compound-agent 1.2.6 → 1.2.8

package/CHANGELOG.md

@@ -9,6 +9,18 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.2.7] - 2026-02-17
+
+### Changed
+
+- **Explicit agent mechanism language in phase skills**: Each phase now clearly distinguishes subagents (Task tool, lightweight research) from AgentTeam teammates (TeamCreate + Task with `team_name`, dedicated role skills). Relative paths to agent definitions and role skill files included in every step.
+  - Brainstorm/Plan: "Spawn **subagents** via Task tool" referencing `.claude/agents/compound/*.md`
+  - Work/Review/Compound: "Deploy an **AgentTeam** (TeamCreate + Task with `team_name`)" referencing `.claude/skills/compound/agents/*/SKILL.md`
+
+### Fixed
+
+- **`verify-gates` JSON array unwrap**: `bd show --json` returns an array, not an object. `parseDepsJson()` now unwraps the first element before reading `depends_on`. Previously caused false gate failures on valid epics.
+
 ## [1.2.6] - 2026-02-16
 
 ### Changed
@@ -493,7 +505,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   - Vitest test suite
   - tsup build configuration
 
-[Unreleased]: https://github.com/Nathandela/learning_agent/compare/v1.2.6...HEAD
+[Unreleased]: https://github.com/Nathandela/learning_agent/compare/v1.2.7...HEAD
+[1.2.7]: https://github.com/Nathandela/learning_agent/compare/v1.2.6...v1.2.7
 [1.2.6]: https://github.com/Nathandela/learning_agent/compare/v1.2.5...v1.2.6
 [1.2.5]: https://github.com/Nathandela/learning_agent/compare/v1.2.4...v1.2.5
 [1.2.4]: https://github.com/Nathandela/learning_agent/compare/v1.2.1...v1.2.4

package/dist/cli.js

@@ -2926,13 +2926,7 @@ $ARGUMENTS
 
 # Brainstorm
 
-Run the **brainstorm** phase. Follow the brainstorm skill for full instructions.
-
-Key steps:
-- Search memory and explore docs for prior context
-- Clarify scope and constraints via AskUserQuestion
-- Propose 2-3 approaches with tradeoffs
-- Create a beads epic from conclusions
+**MANDATORY FIRST STEP -- NON-NEGOTIABLE**: Use the Read tool to open and read \`.claude/skills/compound/brainstorm/SKILL.md\` NOW. Do NOT proceed until you have read the complete skill file. It contains the full workflow you must follow.
 `,
   "plan.md": `---
 name: compound:plan
@@ -2943,13 +2937,7 @@ $ARGUMENTS
 
 # Plan
 
-Run the **plan** phase. Follow the plan skill for full instructions.
-
-Key steps:
-- Spawn subagents to research constraints and patterns
-- Decompose into tasks with acceptance criteria
-- Create review and compound blocking tasks
-- Verify POST-PLAN gates
+**MANDATORY FIRST STEP -- NON-NEGOTIABLE**: Use the Read tool to open and read \`.claude/skills/compound/plan/SKILL.md\` NOW. Do NOT proceed until you have read the complete skill file. It contains the full workflow you must follow.
 `,
   "work.md": `---
 name: compound:work
@@ -2960,13 +2948,7 @@ $ARGUMENTS
 
 # Work
 
-Run the **work** phase. Follow the work skill for full instructions.
-
-Key steps:
-- Deploy AgentTeam with test-writers and implementers
-- Lead coordinates, delegates, does not code directly
-- Commit incrementally as tests pass
-- Run verification gates before closing tasks
+**MANDATORY FIRST STEP -- NON-NEGOTIABLE**: Use the Read tool to open and read \`.claude/skills/compound/work/SKILL.md\` NOW. Do NOT proceed until you have read the complete skill file. It contains the full workflow you must follow.
 `,
   "review.md": `---
 name: compound:review
@@ -2977,13 +2959,7 @@ $ARGUMENTS
 
 # Review
 
-Run the **review** phase. Follow the review skill for full instructions.
-
-Key steps:
-- Run quality gates, then spawn reviewers in parallel
-- Classify findings as P1/P2/P3
-- Fix all P1 findings before proceeding
-- Submit to /implementation-reviewer as mandatory gate
+**MANDATORY FIRST STEP -- NON-NEGOTIABLE**: Use the Read tool to open and read \`.claude/skills/compound/review/SKILL.md\` NOW. Do NOT proceed until you have read the complete skill file. It contains the full workflow you must follow.
 `,
   "compound.md": `---
 name: compound:compound
@@ -2994,13 +2970,7 @@ $ARGUMENTS
 
 # Compound
 
-Run the **compound** phase. Follow the compound skill for full instructions.
-
-Key steps:
-- Spawn analysis agents in an AgentTeam
-- Apply quality filters, then store via npx ca learn
-- Delegate CCT synthesis to compounding agent
-- Verify FINAL GATE before closing epic
+**MANDATORY FIRST STEP -- NON-NEGOTIABLE**: Use the Read tool to open and read \`.claude/skills/compound/compound/SKILL.md\` NOW. Do NOT proceed until you have read the complete skill file. It contains the full workflow you must follow.
 `,
   "lfg.md": `---
 name: compound:lfg
@@ -3012,13 +2982,7 @@ $ARGUMENTS
 
 # LFG
 
-Run all 5 phases. Follow each phase skill for full instructions.
-
-- Brainstorm: explore and define the problem
-- Plan: decompose into tasks with dependencies
-- Work: delegate to AgentTeam for TDD
-- Review: multi-agent review with severity classification
-- Compound: capture lessons via npx ca learn
+**MANDATORY FIRST STEP -- NON-NEGOTIABLE**: Use the Read tool to open and read \`.claude/skills/compound/lfg/SKILL.md\` NOW. Do NOT proceed until you have read the complete skill file. It contains the full orchestration workflow you must follow.
 `,
   // =========================================================================
   // Utility commands (CLI wrappers)
@@ -3131,10 +3095,10 @@ Explore the problem space before committing to a solution. This phase produces a
 ## Methodology
 1. Ask "why" before "how" -- understand the real problem
 2. Search memory with \`npx ca search\` for similar past features and known constraints
-3. Spawn research subagents in parallel -- use MULTIPLE when the topic spans several domains:
-   - Deploy docs-explorer(s) and code-explorer(s) as opus subagents for broad coverage
-   - Scale subagent count to the number of distinct domains being researched
-   - Synthesize all findings before moving to divergent phase
+3. Spawn **subagents** via Task tool in parallel for research (lightweight, no inter-agent coordination):
+   - Available agents: \`.claude/agents/compound/repo-analyst.md\`, \`memory-analyst.md\`
+   - Or use \`subagent_type: Explore\` for ad-hoc research
+   - Deploy MULTIPLE when topic spans several domains; synthesize all findings before proceeding
 4. Use \`AskUserQuestion\` to clarify scope, constraints, and preferences
 5. Divergent phase: generate multiple approaches without filtering
 6. Identify constraints and non-functional requirements (performance, security, etc.)
@@ -3185,9 +3149,9 @@ Create a concrete implementation plan by decomposing work into small, testable t
 ## Methodology
 1. Review brainstorm output for decisions and open questions
 2. Search memory with \`npx ca search\` for architectural patterns and past mistakes
-3. Spawn research subagents in parallel for maximum coverage:
-   - Deploy docs-analyst, repo-analyst, and memory-analyst as opus subagents
-   - For complex features spanning multiple domains, deploy MULTIPLE analysts per type
+3. Spawn **subagents** via Task tool in parallel for research (lightweight, no inter-agent coordination):
+   - Available agents: \`.claude/agents/compound/repo-analyst.md\`, \`memory-analyst.md\`
+   - For complex features, deploy MULTIPLE analysts per domain area
    - Synthesize all findings before decomposing into tasks
 4. Synthesize research findings into a coherent approach. Flag conflicts between ADRs and proposed plan.
 5. Use \`AskUserQuestion\` to resolve ambiguities, conflicting constraints, or priority trade-offs before decomposing
@@ -3244,9 +3208,9 @@ Execute implementation through an AgentTeam using adaptive TDD. The lead coordin
 2. Mark tasks in progress: \`bd update <id> --status=in_progress\`
 3. Run \`npx ca search\` per agent/subtask for targeted context. Display results.
 4. Assess parallelization: identify independent tasks that can be worked simultaneously
-5. Deploy an AgentTeam with MULTIPLE test-writers and implementers scaled to workload:
-   - Scale teammate count to the number of independent tasks -- never a single pair for many tasks
-   - Each pair works on a subset of tasks; pairs coordinate via SendMessage on shared interfaces
+5. Deploy an **AgentTeam** (TeamCreate + Task with \`team_name\`) with MULTIPLE test-writers and implementers:
+   - Role skills: \`.claude/skills/compound/agents/{test-writer,implementer}/SKILL.md\`
+   - Scale teammate count to independent tasks; pairs coordinate via SendMessage on shared interfaces
 6. Agents communicate via SendMessage when working on overlapping areas.
 7. Lead coordinates: review agent outputs, resolve conflicts, verify tests pass. Do not write code directly.
 8. If blocked, use AskUserQuestion to get user direction.
@@ -3317,9 +3281,9 @@ Perform thorough code review by spawning specialized reviewers in parallel, cons
    - **Small** (<100 lines): 4 core -- security, test-coverage, simplicity, cct-reviewer
    - **Medium** (100-500): add architecture, performance, edge-case (7 total)
    - **Large** (500+): all 11 reviewers including docs, consistency, error-handling, pattern-matcher
-4. Spawn selected reviewers in an AgentTeam. For large diffs (500+ lines), deploy MULTIPLE instances of high-value reviewers:
-   - Split files/modules across reviewer instances for security and test-coverage reviewers
-   - Each instance reviews a subset; instances coordinate via SendMessage to avoid duplicate findings
+4. Spawn reviewers in an **AgentTeam** (TeamCreate + Task with \`team_name\`):
+   - Role skills: \`.claude/skills/compound/agents/{security-reviewer,architecture-reviewer,performance-reviewer,test-coverage-reviewer,simplicity-reviewer}/SKILL.md\`
+   - For large diffs (500+), deploy MULTIPLE instances; split files across instances, coordinate via SendMessage
 5. Reviewers communicate findings to each other via \`SendMessage\`
 6. Collect, consolidate, and deduplicate all findings
 7. Classify by severity: P1 (critical/blocking), P2 (important), P3 (minor)
@@ -3380,15 +3344,11 @@ Lessons go to \`.claude/lessons/index.jsonl\` through the CLI. MEMORY.md is a di
 
 ## Methodology
 1. Review what happened during this cycle (git diff, test results, plan context)
-2. Spawn the analysis pipeline in an AgentTeam. Scale agents to the volume of changes:
-   - For large diffs, deploy multiple context-analyzers (one per major changed module) and multiple lesson-extractors
-   - All agents coordinate via SendMessage: context-analyzers feed lesson-extractors, which feed pattern-matcher and solution-writer
-   - context-analyzer: gathers cycle context (diffs, test output)
-   - lesson-extractor: identifies corrections, surprises, discoveries
-   - docs-reviewer: scans \`docs/\` for outdated content and ADRs that need updating
-   - pattern-matcher: checks \`npx ca search\` for duplicates and related items
-   - solution-writer: drafts final memory items
-   - compounding: synthesizes accumulated lessons into CCT patterns
+2. Spawn the analysis pipeline in an **AgentTeam** (TeamCreate + Task with \`team_name\`):
+   - Role skills: \`.claude/skills/compound/agents/{context-analyzer,lesson-extractor,pattern-matcher,solution-writer,compounding}/SKILL.md\`
+   - For large diffs, deploy MULTIPLE context-analyzers and lesson-extractors
+   - Pipeline: context-analyzers -> lesson-extractors -> pattern-matcher + solution-writer -> compounding
+   - Agents coordinate via SendMessage throughout the pipeline
 3. Agents pass results through the pipeline via \`SendMessage\`. The lead coordinates: context-analyzer and lesson-extractor feed pattern-matcher and solution-writer, which feed compounding.
 4. Apply quality filters: novelty check (>0.85 similarity = skip), specificity check
 5. Classify each item by type: lesson, solution, pattern, or preference
@@ -3430,6 +3390,73 @@ Before closing the epic:
 - Run \`pnpm test\` and \`pnpm lint\` -- must pass
 If verify-gates fails, the missing phase was SKIPPED. Go back and complete it.
 CRITICAL: 3/5 phases is NOT success. All 5 phases are required.
+`,
+  lfg: `---
+name: LFG
+description: Full-cycle orchestrator chaining all five phases with gates and controls
+---
+
+# LFG Skill
+
+## Overview
+Chain all 5 phases end-to-end: Brainstorm, Plan, Work, Review, Compound. This skill governs the orchestration -- phase sequencing, gates, progress tracking, and error recovery.
+
+## CRITICAL RULE -- READ BEFORE EXECUTE
+Before starting EACH phase, you MUST use the Read tool to open its skill file:
+- .claude/skills/compound/brainstorm/SKILL.md
+- .claude/skills/compound/plan/SKILL.md
+- .claude/skills/compound/work/SKILL.md
+- .claude/skills/compound/review/SKILL.md
+- .claude/skills/compound/compound/SKILL.md
+
+Do NOT proceed from memory. Read the skill, then follow it exactly.
+
+## Phase Execution Protocol
+For each phase:
+1. Announce: "[Phase N/5] PHASE_NAME"
+2. Read the phase skill file (see above)
+3. Run \`npx ca search\` with the current goal -- display results before proceeding
+4. Execute the phase following the skill instructions
+5. Update epic state: \`bd update <epic-id> --notes="Phase: NAME COMPLETE | Next: NEXT"\`
+6. Verify phase gate before proceeding to the next phase
+
+## Phase Gates (MANDATORY)
+- **After Plan**: Run \`bd list --status=open\` -- verify Review and Compound blocking tasks exist
+- **After Work (GATE 3)**: \`bd list --status=in_progress\` must be empty. Only Review + Compound tasks remain open
+- **After Review (GATE 4)**: /implementation-reviewer must have returned APPROVED. All P1 findings resolved
+- **After Compound (FINAL GATE)**: Run \`npx ca verify-gates <epic-id>\` -- must PASS. Run \`pnpm test\` and \`pnpm lint\`
+
+If a gate fails, DO NOT proceed. Fix the issue first.
+
+## Phase Control
+- **Skip phases**: Parse arguments for "from PHASE" (e.g., "from plan"). Skip earlier phases.
+- **Resume**: After interruption, run \`bd show <epic-id>\` and read notes for phase state. Resume from that phase.
+- **Retry**: If a phase fails, report and ask user to retry, skip, or abort via AskUserQuestion.
+- **Progress**: Always announce current phase number before starting.
+
+## Stop Conditions
+- Brainstorm reveals goal is unclear -- stop, ask user
+- Tests produce unresolvable failures -- stop, report
+- Review finds critical security issues -- stop, report
+
+## Common Pitfalls
+- Skipping the Read step for a phase skill (NON-NEGOTIABLE)
+- Not running phase gates between phases
+- Not announcing progress ("[Phase N/5]")
+- Proceeding after a failed gate
+- Not updating epic notes with phase state (loses resume ability)
+- Batching all commits to the end instead of committing incrementally
+
+## Quality Criteria
+- All 5 phases were executed (3/5 is NOT success)
+- Each phase skill was Read before execution
+- Phase gates verified between each transition
+- Epic notes updated after each phase
+- Memory searched at the start of each phase
+- \`npx ca verify-gates\` passed at the end
+
+## SESSION CLOSE -- INVIOLABLE
+Before saying "done": git status, git add, bd sync, git commit, bd sync, git push.
 `
 };