Phase 5: file-based /retro → /kai self-improvement loop - #31
Closed
olehsvyrydov wants to merge 92 commits into
Closed
Phase 5: file-based /retro → /kai self-improvement loop#31olehsvyrydov wants to merge 92 commits into
olehsvyrydov wants to merge 92 commits into
Conversation
A reusable repository of specialized Claude Code skills that work together like a real software development team. Features: - 15 specialized AI agents (management, architecture, development, quality, operations) - Comprehensive skill extension guide for adding new technologies - Ready-to-use templates (sprint, user-story, ADR, code-review) - Team workflow and communication protocol documentation - Enhanced CLAUDE.md for project recognition in new sessions
Created skill files in .claude/skills/ with proper YAML frontmatter: Management: - product-owner: Product vision, backlog management, user stories - scrum-master: Sprint planning, agile coaching, retrospectives - business-analyst: Market research, requirements, competitive analysis Architecture: - solution-architect: System design, patterns (DDD, CQRS, Event Sourcing) Development: - backend-developer: Spring Boot 4, Java 25, WebFlux, R2DBC - frontend-developer: Next.js 15, React 19, React Native, TypeScript 5 Quality: - backend-reviewer: Code review, Checkstyle, SpotBugs, SonarQube - frontend-reviewer: ESLint, Prettier, accessibility, performance - backend-tester: JUnit 6, Testcontainers, StepVerifier - frontend-tester: Jest, React Testing Library, MSW - e2e-tester: Playwright, Detox, Page Object Model Operations: - devops-engineer: Terraform, Kubernetes, GitHub Actions - secops-engineer: JWT, OAuth2, OWASP, rate limiting - mlops-engineer: Spring AI, LLM integration, multi-provider Documentation: - technical-writer: C4 diagrams, Mermaid, API docs, changelogs
New skill: - spring-kafka-integration: Comprehensive Kafka skill covering both blocking Spring Kafka and reactive Reactor Kafka patterns - Includes KafkaTemplate, @KafkaListener, DLT configuration - Reactor Kafka: KafkaSender, KafkaReceiver, backpressure handling - Delivery semantics: at-least-once, at-most-once, exactly-once - Testing patterns with EmbeddedKafka and Testcontainers Updated backend-developer: - Spring Boot 4.0 (December 2025) - Spring Framework 7, Spring Security 7 - Spring Cloud 2025.1.0 (Oakwood) - JUnit 6, Gradle 9.x support - JSpecify null safety annotations
New skills: angular-developer: - Angular 21 with Signals, Zoneless change detection - Signal Forms (experimental), Angular Aria - Standalone components, NgRx SignalStore - Vitest testing, RxJS integration quarkus-developer: - Quarkus 3.30+ with native compilation - RESTEasy Reactive, Panache ORM - WebSocket Next, Mutiny reactive - Dev Services, Kafka messaging cucumber-bdd: - Cucumber-JVM 7.28+ (Java) - Cucumber-JS 10.x (JavaScript/TypeScript) - Gherkin syntax, data tables, scenario outlines - Spring Boot and Playwright integration - Page object pattern, hooks
New skills covering additional technology stacks: - vue-developer: Vue 3.5+, Pinia 3.x, Composition API, Vite - flutter-developer: Flutter 3.27+, Dart 3.6+, Riverpod, go_router - fastapi-developer: FastAPI 0.115+, Pydantic 2.x, SQLAlchemy async - terraform-specialist: Terraform 1.10+, OpenTofu, multi-cloud providers - graphql-developer: Apollo Server 4.x, Federation 2.x, DataLoader
- Add Extended Skills sections to 5 core agents: - frontend-developer → angular, vue, flutter - backend-developer → kafka, quarkus, fastapi - devops-engineer → terraform - e2e-tester → cucumber-bdd - solution-architect → graphql - Update 9 extended skills with [Extends parent] prefix: - angular-developer, vue-developer, flutter-developer - spring-kafka-integration, quarkus-developer, fastapi-developer - terraform-specialist, cucumber-bdd, graphql-developer - Add Related Skills sections to all 15 core agents for cross-skill collaboration and automatic skill chaining This enables hierarchical skill invocation where specialized skills extend base agents while maintaining clear relationships.
- Add Option 1: Global Installation as recommended method - Document how to install skills to ~/.claude/skills/ - Add /agents command skill to list all available agents - Document Extended Skills hierarchy (9 specialized skills) - Add skill hierarchy diagram showing auto-chaining - Update repository URLs to actual GitHub repo - Bump version to 1.1.0
Skills (.claude/skills/) are model-invoked - Claude decides when to use them. Commands (.claude/commands/) are user-invoked - user types /command directly. - Move agents from .claude/skills/ to .claude/commands/ - Update README with correct installation instructions - Add note explaining Skills vs Commands difference
New agent: ui-designer (Aura - Senior UI/UX Design Architect) - React 19, Tailwind CSS 4, Framer Motion expertise - Discovery-First protocol with Plan Mode - Auto-activated skill modules: - BrandSynthesis, ComponentArchitect, ResponsiveEngine - MicroInteractionist, DataVisualLogic, SEO-PerformanceSentinel - Atomic Design principles (Atoms → Molecules → Organisms) - WCAG 2.1 accessibility compliance - Mobile-first responsive design - Production-ready React/Tailwind prototypes Updated /agents command and README to reflect 16 core agents.
Added MCP Browser/Playwright tool documentation to 8 frontend-related agents for visual inspection and screenshot capabilities: Core agents updated: - frontend-developer: Debug UI, responsive testing, component verification - frontend-tester: Screenshot baselines, multi-device testing, console errors - frontend-reviewer: Accessibility audits, semantic HTML analysis - e2e-tester: Visual regression, cross-device validation - ui-designer: Design verification, responsive breakpoint testing Extended skills updated: - angular-developer: Zoneless verification, Angular Material testing - vue-developer: Pinia state verification, Nuxt SSR testing - flutter-developer: Flutter Web inspection, Material 3 theming Each agent now includes: - Available MCP Browser tools table - Device simulation presets (143+ devices) - Framework-specific workflows - Visual Verification checklist items
New extended skill: - kotlin-developer: Senior Kotlin specialist for JVM, Native, and KMP - Coroutines & structured concurrency (Flow, StateFlow, Dispatchers) - Ktor backend framework - Kotlin Multiplatform (KMP) with expect/actual - kotlinx.serialization optimization - Performance audit checklist - "The Kotlin Way" standards (null safety, efficiency, concurrency) Updated skills: - backend-developer: Added kotlin-developer to Extended Skills - backend-reviewer: Added Kotlin Code Review section with The Kotlin Way checks - backend-tester: Added Kotlin Testing section (runTest, Turbine, MockK) Extended skills count: 9 -> 10
New core agent: uk-legal-counsel - Senior UK Legal Counsel with 20+ years English & Welsh Law experience - Auto-triggered skills: - STATUTE_SCANNER: Cites Acts of Parliament with Section numbers - PENALTY_WATCHDOG: Calculates maximum penalties aggressively - CLAUSE_AUDITOR: Reviews contracts for unfair terms - JURISDICTION_TRIAGE: Handles Scotland/NI law differences - DEVILS_ADVOCATE: Analyzes counter-arguments Practice areas: - Corporate & Commercial (Companies Act 2006, Contract Law) - Employment Law (ERA 1996, Equality Act 2010) - Data Protection (UK GDPR, DPA 2018) - Property & Real Estate (Housing Act, Protection from Eviction Act) - Intellectual Property (CDPA 1988, Trade Marks Act) Includes penalty reference table, contract review templates, employment dismissal checklists, and structured response format. Core agents count: 16 -> 17
- Created uk-accountant skill with FCA/CFO expertise - Added /inga command for direct invocation - Auto-triggered skills: TAX_RADAR, SAVINGS_HUNTER, COMPLIANCE_SENTINEL, APP_LOGIC_ARCHITECT - Covers UK tax law, VAT, Corporation Tax, R&D Credits, IR35 - Dual mission: Operational Advisor + Product Consultant for accounting apps - Updated agents.md with Finance & Accounting section - Updated README.md to v1.6.0
- Created accountant.md as alias for easier recall - Updated agents.md with alternate command option
- Updated product-owner skill with Max persona - Added /max command for direct invocation - Updated agents.md and README.md
- Updated scrum-master skill with Luda persona - Added /luda command for direct invocation - Updated agents.md and README.md
- Add LoadTester module with k6 and Artillery templates - Add WebVitalsAnalyzer for Core Web Vitals and Lighthouse CI - Add APIPerformanceTester with latency percentiles and benchmarks - Add PerformanceReporter with GitHub Actions CI/CD workflow - Include load test patterns: smoke, load, stress, spike, soak - Add performance budgets and regression thresholds - Update README with new capabilities
Major changes: - Add James persona to backend-developer (/james command) - Add Adam persona to e2e-tester (/adam command) - Create unified reviewer (Rev) combining backend+frontend review - Create unified tester (Rob) as black-box QA tester - Add comprehensive TDD-based team workflow document Workflow: /max → /luda → /aura → /finn or /james → /rev → /rob → /adam Key principles: - Developers write all tests (TDD): unit + integration - Rev reviews code quality and security (grype, trivy) - Rob validates against acceptance criteria (black-box) - Adam writes E2E and performance tests
Workflow updates: - Add /jorge architectural approval gate (ALWAYS required) - Add /inga finance approval gate (for payment/billing features) - Add /alex legal approval gate (for GDPR/compliance features) - Add /aura design verification phase after implementation - /aura uses Browser MCP to verify UI matches design spec New files: - skills/design/ui-designer.md - UI Designer skill with design QA workflow Workflow sequence: /max → /luda → /jorge → [/inga] → [/alex] → [/aura] → /finn|/james → /rev + [/aura verify] → /rob → /adam
- Rename .claude/ to claude/ for visibility and easy copying - Organize 33 skills by technology category: - management/, architecture/, development/, quality/ - operations/, design/, compliance/, marketing/, specialized/ - Add 9 new slash commands (jorge, finn, james, rev, rob, adam, aura, anna, apex) - Create generic compliance agents (accountant, legal-counsel) with UK regional variants - Add install.sh with merge/replace/link options - Move templates to claude/templates/ - Update README.md with new installation instructions - Remove old duplicate structures (.claude/, skills/, templates/) New structure allows simple deployment: ./install.sh # Interactive ./install.sh --merge # Add to existing ./install.sh --replace # Backup and replace ./install.sh --link # Symlink for development
Standardize all command files and references to use role-based names: - /po (Product Owner), /sm (Scrum Master), /ba (Business Analyst) - /arch (Solution Architect), /fe (Frontend), /be (Backend) - /rev (Code Reviewer), /qa (QA), /e2e (E2E Tester) - /ui (UI Designer), /fin (Finance), /legal (Legal), /mkt (Marketing) Updated files: README.md, CLAUDE.md, TEAM_WORKFLOW.md, agents.md
…yment Feature/restructure for deployment
Critical improvement for team workflow continuity:
- Sprint folder structure: docs/sprints/sprint-{N}-{feature}/
- Subfolders: approvals/, implementation/, reviews/, testing/
- Agent file conventions: each agent saves to designated file
- Auto-save rules: all approvals trigger /sm status update
- Templates for Sprint README.md and Architecture Approval
Ensures context survives across conversation resets.
…#18) * Phase 1: progressive-disclosure refactor of reviewer (829 -> 424 lines) Split into a lean SKILL.md (gate check, trigger, context, doc lookup, role, jira integration, review navigation, architecture verification, AC validation, review principles, comment quality, security checks, anti-patterns, universal principles + references index) and 3 references/ files: review-checklist, feedback-and-reports, process-and-style. Real section boundaries; fences verified balanced/non-nested - the feedback-format examples' outer markdown fences bumped to 4 backticks so their inner code blocks render correctly. No content lost. * Address Copilot review on PR #18: fix stale 'see template below' pointer The review report template moved to references/feedback-and-reports.md; update the Jira-comment body placeholder to point there instead of 'below'. * Address Copilot re-review on PR #18: fix split cross-references - review-checklist.md: repoint 'see detection table' and 'AC Validation above' to the corresponding sections in the main reviewer SKILL. - feedback-and-reports.md: add a 'Static Analysis Results' section to the report template so it matches the process-and-style.md reporting instruction. * Address Copilot re-review on PR #18: link checklist cross-refs to SKILL.md sections Use relative markdown links (../SKILL.md#anchor) for the Code Smells detection table and AC Validation references instead of plain text.
…#19) * Phase 1: progressive-disclosure refactor of hmrc-api (804 -> 188 lines) Split the large Expertise block into 2 references/ files: api-oauth-fraud (endpoints, MTD timeline, OAuth 2.0, fraud-prevention headers) and self-assessment-error-config (Self Assessment integration, error handling, sandbox testing, configuration). Lean SKILL.md keeps trigger, context, doc lookup, standards, checklist, anti-patterns, external-ID management, sandbox-vs-prod. Real section boundaries; fences verified. No content lost. * Address Copilot review on PR #19: fix heading levels in self-assessment-error-config.md Promote the top-level sections from H3 to H2 (and their H4 children to H3) so the reference goes H1 -> H2 -> H3, consistent with the other references.
…0 lines) (#20) * Phase 1: progressive-disclosure refactor of javafx-developer (799 -> 200 lines) Move the ~605-line Expertise block into references/javafx-expertise.md (versions, core concepts: setup/MVVM/FXML/CSS/threading/packaging, GraalVM, project structure). Lean SKILL.md keeps trigger, context, doc lookup, standards, checklist, MVVM gold standard, sizing gotchas, TestFX, anti-patterns. Fences verified. No content lost. * Address Copilot review on PR #20: fix two imported javafx snippet bugs - FXML: Insets uses top/right/bottom/left, not the invalid topRightBottomLeft. - GraalVM reflection config: tag the block as json (it's JSON, not java).
) * Phase 1: progressive-disclosure refactor of tester (720 -> 434 lines) Split into a lean SKILL.md (gate check, trigger, context, doc lookup, role, jira integration, workflow, /e2e review, defect severity, team collab, workflow triggers, checklist, anti-patterns, universal principles + references index) and 2 references/ files: templates (test plan, execution report, defect ticket) and methodology (test design, predictable behavior, manual testing, advanced patterns, cross-reference). Real section boundaries; fences verified. No content lost. * Address Copilot review on PR #21: fix stale 'see template below' pointers Test plan and defect templates moved to references/templates.md; update the Confluence/Jira snippet placeholders to point there instead of 'below'. * Address Copilot re-review on PR #21: align role names in methodology.md Use the role commands /qa (test design/manual) and /e2e (automation) instead of the persona aliases /rob and /adam, consistent with the rest of the skill. * Address Copilot re-review on PR #21: deep-link template references to anchors Add the exact heading anchors (#test-plan-template-confluence, #defect-template-jira-bug-ticket) to the references/templates.md pointers so readers land on the right section. (Refs sit inside code-example blocks, so the anchor is included in the path rather than a rendered markdown link.)
…lines) (#22) * Phase 1: progressive-disclosure refactor of javafx-designer (640 -> 97 lines) Move the ~549-line Expertise block into references/javafx-design-expertise.md (CSS, design system, component library, layout patterns, Scene Builder, accessibility). Lean SKILL.md keeps trigger, context, doc lookup, standards, checklist, anti-patterns. Fences verified. No content lost. * Address Copilot review on PR #22: fix imported JavaFX CSS/FXML errors - CSS selector comparison: JavaFX uses .class/#id (same as web); #id targets the Node id, not fx:id. - Remove unsupported -fx-text-transform (note to uppercase in code/FXML instead). - FXML styleClass is space-separated, not comma (nav-item active; button primary). - Scene Builder tip: style classes set via the styleClass list, not -fx-style-class. - Typo: Self-Employ -> Self-Employed.
…s) (#24) * Consolidate agents: 48 -> 29 (fold tech variants into parent references) Fold the 18 [Extends X] technology/language variants into their parent role's references/, so a role agent self-routes to the matching stack instead of each being a separate always-in-context agent. Two-tier roster: 15-agent core team + optional specialists; tech stacks live as references. - /fe <- angular, vue, flutter, javafx-desktop (+ stack-selection router) - /be <- kotlin, fastapi, laravel, quarkus, spring-kafka, hmrc-api (+ router) - /rev <- backend/frontend/php review - /e2e <- cucumber-bdd ; /arch <- graphql ; /devops <- terraform ; /ui <- javafx-design - compliance: generic /legal + /fin are the roles; uk-legal/uk-accountant/ uk-self-employment become references/uk, selected by jurisdiction. - Each parent: description enumerates stacks (preserves auto-trigger) + a Stack-selection router + references index. - Rewrote agents.md (core 15 + specialists), simplified disambiguation.md to roles only, updated CLAUDE.md/README counts. - Fixed 2 pre-existing nested/dangling fence bugs (technical-writer, ui-designer). Full-tree fence scan clean; relocations preserve git history. * Address Copilot review on PR #24: fix README counts + /be JavaFX note - README: update all stale '40 agents / 40 skill files' mentions to 29 (15-agent core + specialists; stacks as references). - backend-developer: JavaFX desktop is a /fe reference, not /be — remove it from the /be stacks note. * Address Copilot review on PR #24: add the missing /devops command devops-engineer had no slash command. Add claude/commands/devops.md and declare /devops in the skill (description + header) so the /devops references in agents.md and disambiguation.md resolve. * Address Copilot re-review on PR #24: align stack routers with folded references - /fe: add JavaFX desktop to the description + Stack selection router. - /be: add HMRC MTD to the Stack selection router. Keeps each router consistent with its references index. * Address Copilot re-review on PR #24: fix e2e-tester reference direction The Cucumber reference index is below the Specializations note, not above.
…README hero) (#25) * OSS polish + launch hygiene - Jira-decouple 5 skills (tester, e2e-tester, reviewer, backend, frontend): reframe MANDATORY Jira sections to the file-based default; Jira/Confluence is an optional overlay enabled in workflow.yaml. - Emit AGENTS.md (root + claude/) mirroring CLAUDE.md so Cursor/Kiro/VS Code get identical guidance (those editors don't read CLAUDE.md). - Add CONTRIBUTING.md + .github issue templates (bug/feature/new-agent) + PR template. - README: editor badges (Claude Code/Cursor/Kiro/VS Code), 10-second hero, 'process not prompts' + vs-mega-prompt table; fix the Claude-Code-only and Jira-default framing. * Address Copilot review on PR #25: finish the Jira-decoupling + AGENTS/doc fixes - Skills (tester/e2e/reviewer/backend/frontend): add a 'tracker-agnostic' note to each recording section, make the output tables ticket-first (Jira/Confluence as 'if configured'), and genericize the hard-coded 'Read/Post/subtasks in Jira' steps. - claude/CLAUDE.md + claude/AGENTS.md: fix the stale '~48' -> ~29 (15 core + specialists). - AGENTS.md (root): retitle + reframe to be editor-neutral (was a CLAUDE.md copy); claude/AGENTS.md: add a mirror note. - PR template: correct paths to claude/commands/agents.md + claude/skills/disambiguation.md. * Address Copilot re-review on PR #25: finish backend/frontend Jira-decoupling + AGENTS tree - backend/frontend: genericize the remaining 'Jira ticket' / 'comments in Jira' / 'documented in Jira comment' phrases to the tracker-agnostic ticket wording. - AGENTS.md: fix the repo-tree annotation (this file is AGENTS.md, mirrors CLAUDE.md). * Address Copilot re-review on PR #25: conditional Jira subsections + AGENTS/CLAUDE accuracy - tester/e2e/reviewer: make the report-posting and bug-ticket subsections conditional — record in the ticket (Backlog.md) by default; Jira only if the overlay is configured. - AGENTS.md + root CLAUDE.md: workflow diagram now uses role commands + /verify; replace 'all features require /jorge' with the proportional-gates wording; fix stale counts (Skills 33->29, Commands 35->47, Templates 5->6). * Address Copilot re-review on PR #25: thorough Jira/Confluence decoupling + README gates - tester/e2e/reviewer: genericize the remaining process tables, checklists and workflow examples to tracker-agnostic wording (ticket / KB doc / KB ADR / KB Feature Vision). Remaining 'Jira'/'Confluence' mentions are only the tracker-agnostic notes, explicitly-conditional overlay steps, and Atlassian tool-call examples. - CLAUDE.md/AGENTS.md structure block: 35 -> 47 slash commands. - README: Approval Gates table is now proportional (trigger/preset, not 'Always'); Jira & Confluence retitled an optional overlay with a file-based-default lead.
…26) * Phase 2: universal installer (Claude Code, Cursor, Kiro, VS Code) Rewrite install.sh as a vendor-neutral installer that wires up any of the four editors and emits the right config for each (no lock-in): - Claude Code: .claude/skills + .claude/commands + CLAUDE.md - Cursor: .cursor/rules/ai-dev-team.mdc + AGENTS.md - Kiro: .kiro/steering/ai-dev-team.md + AGENTS.md - VS Code (Copilot): .github/copilot-instructions.md + AGENTS.md Flags: --editors=, --scope=project|user, --preset=solo|small-team|regulated, --dry-run, --yes, --link, --uninstall. Applies the chosen preset to workflow.yaml. Preserves the previous Claude advanced-backend setup as scripts/setup-claude-backends.sh. README Quick Start updated; .gitignore guards self-install artifacts (.claude/, .cursor/, .kiro/, .mcp.json). * Address Copilot review on PR #26: fix backends-script paths + installer link/uninstall - scripts/setup-claude-backends.sh: SCRIPT_DIR resolves to the repo root (the script lives in scripts/), fixing the claude/, multi-llm/, rag/ paths used by prerequisites / venvs / rag / multi-llm / hooks. Updated header usage examples. - install.sh: --link now COPIES workflow/ (symlinks the rest) so --preset applies per-project without mutating the source repo; --uninstall no longer prompts for editors (it removes all known configs regardless). * Address Copilot re-review on PR #26: installer robustness - run() executes args directly ("$@"), no eval — safe with quotes/spaces in paths. - Validate --editors; fail fast on unknown names. - Confirm before overwriting existing content unless --yes (guards ~/.claude). - Preset edit replaces only the value, preserving the inline comment in workflow.yaml. - Emit AGENTS.md whenever Cursor/Kiro/VS Code is selected, even in user scope. - Uninstall removes project-level editor configs regardless of scope, and removes AGENTS.md/CLAUDE.md only if they carry our header. - scripts/setup-claude-backends.sh: silent API-key prompts (read -rsp). * Address Copilot re-review on PR #26: help/overwrite/venv/url - show_help prints only the leading comment block (no code lines leaked). - write_instructions won't clobber a pre-existing AGENTS.md/CLAUDE.md that isn't AI Dev Team-managed (prompts unless --yes; skips on no). - scripts/setup-claude-backends.sh: 'setup_venvs || true' so a venv skip doesn't abort under set -e; fix docs URL to olehsvyrydov/AI-development-team. * Address Copilot re-review on PR #26: write preset to the workflow override The active preset resolves from .aidevteam/workflow.yaml (project) or ~/.aidevteam/workflow.yaml (user) before the shipped default, so the installer now writes the chosen preset there (a copy of workflow.yaml) instead of editing the default — which also lets --link symlink all content. Instruction text + the final hint point to the override; --uninstall removes it (and the .aidevteam dir if empty). Also: emit_mcp drops the unused 'ref' + fixes its comment; backends find uses NUL-delimited -print0 / read -d '' for paths with spaces. * Address Copilot re-review on PR #26: prereq check, vscode guard, pip failure handling - install.sh: fail fast with a clear message if the framework content (SOURCE_DIR/claude/{skills,commands,templates,workflow}) is missing. - emit_vscode uses write_instructions so it won't clobber a pre-existing .github/copilot-instructions.md that isn't AI Dev Team-managed. - README: add --yes to the non-interactive example so it truly doesn't prompt. - scripts/setup-claude-backends.sh: pip install '|| return 1' so a venv failure returns to the caller (which tolerates it) instead of aborting under set -e. * Address Copilot re-review on PR #26: uninstall confirmation + guards + backends polish - install.sh: --uninstall confirms before removing anything (unless --yes/--dry-run), and removes .github/copilot-instructions.md only if it carries our header (so it won't delete an unrelated Copilot file the install previously skipped). - scripts/setup-claude-backends.sh: guard the Qdrant health check on curl being present (don't hang/confuse when curl is missing); fix the startup banner to 'AI Dev Team — Backend Setup'.
* Phase 3: pluggable OSS-first adapter framework Make every backend a documented, swappable adapter (zero lock-in): - claude/workflow/adapters/README.md: the adapter contract (capabilities / health-check / fallback / data-residency) + the OSS-first menu per category (tickets, knowledge base, memory, design) and how to enable each overlay. - claude/workflow/adapters/mcp/: ready-to-paste .mcp.json overlays (atlassian, backlog, openmemory, penpot, obsidian). - workflow.yaml: add memory: and design: adapter sections (+ schema entries); point to adapters/README.md. - installer: .mcp.json.example now points at the adapters/mcp/ menu. - workflow/README.md: note backends are pluggable adapters. * Address Copilot review on PR #27: mem0 overlay + fix .mcp.json.example README path - Add adapters/mcp/mem0.json (the hosted mem0 backend advertised in workflow.yaml) + a README table row; label openmemory as the local mem0 server. - installer: the .mcp.json.example note now points to the installed adapters README ($(content_ref)/workflow/adapters/README.md), not a root-relative path. * Address Copilot re-review on PR #27: add figma + canva design overlays design.optional_mcp advertised figma/canva but shipped no overlays. Add adapters/mcp/{figma,canva}.json (Figma Dev Mode local MCP on :3845; Canva hosted MCP) + README rows, so every advertised backend now has a ready-to-use overlay. * Address Copilot re-review on PR #27: schema-validate adapter config + clarify mappings - workflow.schema.json: add a shared 'adapterConfig' definition (requires 'default' string, 'optional_mcp' array-of-strings, no extra keys) and reference it from tickets/knowledge_base/memory/design — so validation catches config mistakes. workflow.yaml validates against it. - adapters/README.md: note that some overlays serve multiple backends (Jira + Confluence both come from atlassian.json). * Address Copilot re-review on PR #27: fix mem0 residency in the menu table OpenMemory (self-hosted mem0) is the local-service overlay; mem0 (hosted) is the cloud option — align the Memory row with the overlay table's API-key note.
* Phase 3: local Hub — a zero-dependency workflow dashboard A read-only dashboard for the proportional workflow: live gate board (gates from the active workflow.yaml with owner / hard|soft / required-by-preset / safety-override, state from the .workflow-state.json ledger), tickets (Backlog.md / .aidevteam/tickets), and knowledge base (docs/). Pure Node (no npm install); live-updates over SSE on file changes. Reads the override cascade (.aidevteam → .claude → framework default). node hub/server.js [projectDir] [--port 4477] - hub/server.js: HTTP + SSE server, tolerant regex/line-based workflow.yaml reader. - hub/public/index.html: single-file 3-pane UI, dark theme. - hub/README.md + a README Quick Start callout. * Address Copilot review on PR #28: align Hub to the canonical ledger + bind localhost - Read the canonical .workflow-state.json (a map keyed by ticket id; each gate is { state: passed|pending|rejected, by, at }) instead of an invented flat shape. The gate board reflects the first not-'done' ticket; every ticket lists in the Tickets pane (ticketCount shown). - UI uses the canonical 'passed' state (CSS + classes); gate cards tooltip by/at. - Bind to 127.0.0.1 by default (serves local paths/state); --host 0.0.0.0 opts into LAN. - findWorkflow follows the full cascade incl. ~/.aidevteam/workflow.yaml. - hub/README: canonical ledger example + accurate ticket-source resolution. * Address Copilot re-review on PR #28: workflow-resolution fidelity + robustness - findWorkflow comment describes the real cascade (project override -> user override -> installed default .claude/workflow -> framework checkout claude/workflow -> Hub copy). - startWatchers also watches ~/.aidevteam, claude/workflow, and the resolved active workflow file, so edits to whichever file is authoritative trigger SSE updates. - buildState tolerates malformed ledger entries: a ticket id mapping to null no longer crashes /api/state; the board picks a valid ticket and surfaces a malformed count via ledgerError. - Exact pathname route matching (/api/stateful no longer collides with /api/state). - hub/README: resolution table includes claude/workflow/workflow.yaml. * Address Copilot re-review on PR #28: watcher reliability, Backlog.md tickets, no path leak - Watch the project root and re-scan on every change (idempotent watcher set), so creating .aidevteam/, docs/, backlog/, or .workflow-state.json AFTER startup now triggers SSE updates (verified live). - Tickets fall back to a root Backlog.md checkbox list when there is no ledger and no backlog/ dir. - /api/state returns only the project directory NAME, not the absolute path — avoids leaking filesystem layout when bound with --host 0.0.0.0 (full path stays on console). * Address Copilot re-review on PR #28: SSE/URL robustness + ticket/doc consistency - broadcast() drops a client from the set when its write throws (no dead-socket leak). - Guard URL parsing in the request handler; return 400 on a malformed target instead of letting it crash the process (relevant under --host 0.0.0.0). - Normalize ticket id/title (de-quote + trim) like status, for quoted frontmatter. - findWorkflow comment documents the Hub's own resolution order (no claimed engine parity). - hub/README: knowledge-base resolution lists docs/ -> kb/ -> .aidevteam/kb/ (bullet + table). * Address Copilot re-review on PR #28: watcher coverage, SSE timeout, IPv6 URL - startWatchers also watches kb/, .aidevteam/tickets/, .aidevteam/kb/, and Backlog.md, so edits to any source the Hub reads trigger SSE updates (verified live). - /api/events disables the request/socket idle timeouts so the SSE stream stays open instead of being dropped by Node's defaults. - Startup URL brackets IPv6 host literals (http://[::1]:PORT). * Address Copilot re-review on PR #28: tolerant workflow parsing + ledger/state/path hardening - Parse quoted OR unquoted values: preset, gate owner, gate refusal. Also handle inline presets (name: { always_required: [...] }) in addition to the multi-line form. - readLedger validates the parsed JSON is a ticket-map object — arrays/primitives now report 'ledger is not a ticket map' instead of yielding bogus ticket ids. - Normalize gate-state synonyms (approved/pass/done -> passed; fail/blocked -> rejected; unknown -> pending) so the UI always renders a styled state. - The workflow label no longer leaks paths outside projectDir (~/.aidevteam shown as ~/..., anything further out as the basename only). * Address Copilot re-review on PR #28: parser tolerance + missing-UI + --host docs - section() tolerates a trailing comment/whitespace on a top-level key line (e.g. 'gates: # ...'), so gates/presets still parse. - always_required list items are de-quoted, so quoted entries (['CODE_REVIEWED']) correctly set the 'required' flag. - Serving the UI returns 500 (not an empty 200) when hub/public/index.html is missing. - READMEs: document --host and --host 0.0.0.0 (dev container / VM / LAN) in the Hub usage examples, with a trusted-network caveat. * Address Copilot re-review on PR #28: tighten resolution order + casing robustness - findWorkflow follows the documented cascade only: .aidevteam -> ~/.aidevteam -> installed .claude/workflow -> the Hub's bundled default. Dropped the undocumented project-local 'claude/workflow' candidate (and its watcher); README table aligned. - Fail fast with a clear message when projectDir is not a directory. - Normalize gate refusal to hard|soft case-insensitively (HARD -> hard). - Treat ticket stage 'done' case-insensitively, so 'Done' counts as done for board selection.
* Phase 4: bundled demo project for an instant Hub preview Add examples/demo/ — a realistic mid-flight snapshot so 'node hub/server.js examples/demo' shows a populated board out of the box: three tickets (done / in-review / in-dev), a regulated-preset gate board for the active ticket (with a *rejected* CODE_REVIEWED — the review caught a token-TTL / rate-limit issue), and two knowledge-base docs. File-based only (.aidevteam/workflow.yaml, .workflow-state.json, docs/). - .gitignore: keep examples/demo/.workflow-state.json tracked (the generated-ledger ignore rule would otherwise exclude the demo fixture). - README + hub/README: point the Hub usage examples at the bundled demo. * Address Copilot review on PR #29: demo fixture consistency - Demo workflow.yaml header now states it is a project OVERRIDE (not the shipped default), clarifying the resolution cascade. - The demo's regulated preset keeps all backends file-based (backlog_md/markdown) so the 'no setup' claim holds even if run through the engine, not just the Hub. - Align the CODE_REVIEWED rejection narrative with the ADR/SECOPS docs: the issue is the missing rate-limit on the reset endpoint (ADT-130 follow-up), not the 15m token TTL (which both docs accept). Fixed in the ledger note + demo README. * Address Copilot re-review on PR #29: clarify demo's pinned preset vs proportionality Annotate the demo's 'preset: regulated' and the proportionality comment to make clear the demo intentionally pins regulated (always_required forces the heavy gates), while the default solo preset forces nothing and lets proportionality classify. * Address Copilot re-review on PR #29: align demo header cascade with the Hub The demo header now lists the Hub's actual 4-step resolution (adds the project-scope .claude/workflow/ install step) and notes how it relates to the engine's documented 1-2 -> shipped-default contract. * Address Copilot re-review on PR #29: SecOps capitalization in prose Use 'SecOps' for the role/team in demo prose (README + ADR), reserving all-caps for the gate name SECOPS_APPROVED. * Demo: SecOps casing in the ledger rejection note too (consistency) * Address Copilot re-review on PR #29: clarify the demo runs from the repo root
* Release 5.0.0: CHANGELOG + version bump Add CHANGELOG.md documenting the OSS-first release (proportional workflow engine, 48->29 roster consolidation, universal multi-editor installer, pluggable adapters, local Hub, file-based defaults). Bump version 4.1.0 -> 5.0.0 in CLAUDE.md, the README version table, and scripts/setup-claude-backends.sh; add editors/backends/Hub lines to the CLAUDE.md version block. * Address Copilot review on PR #30: bump AGENTS.md version block + fix CHANGELOG intro - AGENTS.md version block updated to 5.0.0 (mirrors CLAUDE.md) — was the remaining 4.1.0 reference outside the version-history tables. - CHANGELOG intro reworded to a complete sentence.
…ired) Close the learning loop OSS-first: - New /retro command (scrum-master-led): runs a proportional retrospective and CAPTURES reusable learnings to .aidevteam/learnings/*.md (structured frontmatter: agent / target / type / scope / status). No Jira or RAG required. - Kai reads the file-based learnings store by DEFAULT — cluster by target+theme, promote a cluster at >=3 'scope: universal, status: open' learnings; RAG/Qdrant is now an optional overlay. New references/file-based-learnings.md documents the algorithm, the type->section mapping, and the file format. - /kai command + SKILL reframed file-based-first; agents.md lists /retro and /kai; the retrospective template points at /retro for the lightweight default. - examples/demo: two example learnings so the loop is demoable end-to-end.
There was a problem hiding this comment.
Pull request overview
This PR completes the OSS-first self-improvement loop by introducing a file-based learning capture flow (/retro) and updating Kai (/kai) documentation/skill guidance to treat .aidevteam/learnings/*.md as the default source of truth (with RAG/Qdrant as an optional overlay).
Changes:
- Adds a new
/retrocommand that captures reusable learnings into.aidevteam/learnings/*.mdwith structured frontmatter. - Reframes
/kaiand Kai’s SKILL to be file-based-by-default, and adds a reference doc describing the file format + clustering/promotion algorithm. - Updates templates/docs and demo content to make the loop discoverable and runnable end-to-end.
Reviewed changes
Copilot reviewed 8 out of 8 changed files in this pull request and generated 2 comments.
Show a summary per file
| File | Description |
|---|---|
| examples/demo/.aidevteam/learnings/L-2026-06-04-001.md | Adds a demo learning (review checklist) targeting the reviewer skill. |
| examples/demo/.aidevteam/learnings/L-2026-06-04-002.md | Adds a demo learning (secops gotcha) targeting the secops skill. |
| claude/templates/retrospective-template.md | Points users to /retro for lightweight learning capture and /kai promotion. |
| claude/skills/specialized/kai/SKILL.md | Updates Kai’s guidance to treat file-based learnings as the default source (RAG optional). |
| claude/skills/specialized/kai/references/file-based-learnings.md | New reference documenting the file-based store, clustering, and promotion mapping. |
| claude/commands/retro.md | New /retro command spec for proportional retrospectives + learning-file capture. |
| claude/commands/kai.md | Updates /kai command doc to reflect file-based learnings as the default source. |
| claude/commands/agents.md | Registers /retro and /kai in the commands directory listing. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
… RAG-overlay steps - file-based-learnings.md: 'pattern' routes only to Best Practices, 'gotcha' only to Anti-Patterns (a learning is one or the other) — no overlapping rows. - kai.md: mark every Qdrant/agent-knowledge step as RAG-overlay-only (analyze, apply, re-ingest), consistent with the file-based-by-default lead.
…pplies) + cosine threshold - retro command/description, retrospective template, agents.md: reword 'promote into skills' to 'propose SKILL.md updates (human-approved)', consistent with the never-auto-applies safety model. - kai SKILL: tie the RAG overlay to embedding similarity (cosine >= 0.7) explicitly.
Comment on lines
+27
to
+29
| ### Learnings source — file-based by default (RAG optional) | ||
|
|
||
| By default, read the **file-based** learning store `./.aidevteam/learnings/*.md` (written by `/retro`) — **no Qdrant, no embeddings, no paid accounts**. Cluster by `target` skill + `type`/theme; promote a cluster at **≥ 3** matching `scope: universal`, `status: open` learnings. The RAG `learnings`/`agent-knowledge` collections (Qdrant + embeddings) are an **optional overlay** for fuzzier clustering by embedding similarity (cosine ≥ 0.7, as in Pattern Detection below) when configured. Full algorithm + the learning file format: [`references/file-based-learnings.md`](references/file-based-learnings.md). |
olehsvyrydov
added a commit
that referenced
this pull request
Jun 6, 2026
… RAG-overlay steps - file-based-learnings.md: 'pattern' routes only to Best Practices, 'gotcha' only to Anti-Patterns (a learning is one or the other) — no overlapping rows. - kai.md: mark every Qdrant/agent-knowledge step as RAG-overlay-only (analyze, apply, re-ingest), consistent with the file-based-by-default lead.
olehsvyrydov
added a commit
that referenced
this pull request
Jun 6, 2026
…pplies) + cosine threshold - retro command/description, retrospective template, agents.md: reword 'promote into skills' to 'propose SKILL.md updates (human-approved)', consistent with the never-auto-applies safety model. - kai SKILL: tie the RAG overlay to embedding similarity (cosine >= 0.7) explicitly.
olehsvyrydov
added a commit
that referenced
this pull request
Jun 6, 2026
* Phase 5: file-based /retro -> /kai self-improvement loop (no RAG required) Close the learning loop OSS-first: - New /retro command (scrum-master-led): runs a proportional retrospective and CAPTURES reusable learnings to .aidevteam/learnings/*.md (structured frontmatter: agent / target / type / scope / status). No Jira or RAG required. - Kai reads the file-based learnings store by DEFAULT — cluster by target+theme, promote a cluster at >=3 'scope: universal, status: open' learnings; RAG/Qdrant is now an optional overlay. New references/file-based-learnings.md documents the algorithm, the type->section mapping, and the file format. - /kai command + SKILL reframed file-based-first; agents.md lists /retro and /kai; the retrospective template points at /retro for the lightweight default. - examples/demo: two example learnings so the loop is demoable end-to-end. * Address Copilot review on PR #31: disambiguate type mapping + clarify RAG-overlay steps - file-based-learnings.md: 'pattern' routes only to Best Practices, 'gotcha' only to Anti-Patterns (a learning is one or the other) — no overlapping rows. - kai.md: mark every Qdrant/agent-knowledge step as RAG-overlay-only (analyze, apply, re-ingest), consistent with the file-based-by-default lead. * Address Copilot re-review on PR #31: clarify Kai proposes (not auto-applies) + cosine threshold - retro command/description, retrospective template, agents.md: reword 'promote into skills' to 'propose SKILL.md updates (human-approved)', consistent with the never-auto-applies safety model. - kai SKILL: tie the RAG overlay to embedding similarity (cosine >= 0.7) explicitly. * Address Copilot review on PR #32: Kai RAG-overlay consistency + retro path robustness - kai SKILL: mark embedding clustering, agent-knowledge scan, and Qdrant re-ingest as RAG-overlay-only across Pattern Detection / Proposal Management / Workflow — consistent with the file-based-by-default lead. - retro command: 'mkdir -p .aidevteam/learnings' before writing (dir absent in fresh checkout); point the retro summary at docs/ (suggest creating docs/retros/) instead of a non-existent path. * Address Copilot re-review on PR #32: clarify retro summary mirrors to the tracker/KB Reword so 'mirror the summary' clearly means the configured Jira/Confluence tracker/KB overlay (enabled in workflow.yaml), not writing into workflow.yaml itself. * docs(skills): port retro pattern blocks into source skills Sync universal pattern additions from runtime skills into the source repo's categorized layout. Project-agnostic only — no sprint/ticket nouns. - secops: BOLA/IDOR re-authorization, value-scrub for audit logs, deterministic+advisory signal composition (precedence, untrusted-text-as-data) - backend java-expertise: decide-once optimistic-lock transitions, advisory side-effects degrade gracefully - backend-review: enforced pagination cap, audit/decision-row leak checks - architecture-patterns: SPA-route-vs-proxied-API collision, leaky-port anti-pattern - mlops: full "Benchmark & eval-harness integrity" section (5 blocks) * Address Copilot re-review on PR #32: RAG-overlay collection consistency + frontmatter - kai SKILL frontmatter description: lead with the file-based .aidevteam/learnings/ store (RAG learnings/agent-knowledge collections noted as the optional overlay). - Pattern Detection bullet + /kai command: the RAG overlay scans BOTH the 'learnings' and 'agent-knowledge' Qdrant collections (was only naming agent-knowledge). * Address Copilot re-review on PR #32: align Checklist with RAG-overlay-only re-ingest Checklist re-ingest item is now conditional (RAG overlay only) and adds the file-based step (mark source learnings status: promoted), consistent with the rest of the skill.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
Closes the learning loop OSS-first — knowledge earned once benefits every future session, with no RAG/Qdrant required.
/retrocommand — a scrum-master-led, proportional retrospective that captures reusable learnings to.aidevteam/learnings/*.mdwith structured frontmatter (agent/target/type/scope/status). File-based; no Jira..aidevteam/learnings/, clusters bytargetskill +type/theme, and proposesSKILL.mdupdates when a cluster hits ≥ 3scope: universal, status: openlearnings. RAG/Qdrant (embeddings + re-ingest) is an optional overlay. Newreferences/file-based-learnings.mddocuments the algorithm, thetype→section mapping, and the file format./retro) and propose (/kai) stay separate; Kai never auto-applies — a human approves before anySKILL.mdchange (plain git diff)./kaicommand + SKILL reframed file-based-first;agents.mdlists/retro+/kai; the retrospective template points at/retrofor the lightweight path.examples/demo/.aidevteam/learnings/has two example learnings so the loop is demoable end-to-end.Why
The whole 5.0 release is file-based-by-default; the self-improvement loop was the last piece still assuming RAG. Now it works with zero paid accounts.
Verification