From bbdd1840dee8e4bb7fdd389b5d60793f9ba99737 Mon Sep 17 00:00:00 2001 From: catlog22 Date: Wed, 4 Mar 2026 23:54:20 +0800 Subject: [PATCH] Add document standards, quality gates, and templates for team lifecycle phases - Introduced `document-standards.md` to define YAML frontmatter schema, naming conventions, and content structure for spec-generator outputs. - Created `quality-gates.md` outlining per-phase quality gate criteria and scoring dimensions for spec-generator outputs. - Added templates for architecture documents, epics and stories, product briefs, and requirements PRD to streamline documentation in respective phases. --- .claude/agents/team-worker.md | 12 +- .claude/skills/team-arch-opt/SKILL.md | 14 +- .../team-arch-opt/role-specs/analyzer.md | 4 +- .../team-arch-opt/role-specs/designer.md | 4 +- .../team-arch-opt/role-specs/refactorer.md | 4 +- .../team-arch-opt/role-specs/reviewer.md | 4 +- .../team-arch-opt/specs/team-config.json | 16 +- .../subagents/discuss-subagent.md | 123 --------- .../subagents/explore-subagent.md | 113 -------- .../team-brainstorm/role-specs/challenger.md | 2 +- .../team-brainstorm/role-specs/evaluator.md | 2 +- .../team-brainstorm/role-specs/ideator.md | 2 +- .../team-brainstorm/role-specs/synthesizer.md | 2 +- .claude/skills/team-coordinate/SKILL.md | 20 +- .../coordinator/commands/analyze-task.md | 4 +- .../team-coordinate/roles/coordinator/role.md | 2 +- .../specs/role-spec-template.md | 14 +- .../subagents/discuss-subagent.md | 132 --------- .../subagents/explore-subagent.md | 120 --------- .../team-executor/roles/executor/role.md | 2 +- .../team-executor/specs/session-schema.md | 2 +- .../team-frontend/role-specs/analyst.md | 2 +- .../team-frontend/role-specs/architect.md | 2 +- .../team-frontend/role-specs/developer.md | 2 +- .claude/skills/team-frontend/role-specs/qa.md | 2 +- .../skills/team-issue/role-specs/explorer.md | 6 +- .../team-issue/role-specs/integrator.md | 4 +- .../skills/team-issue/role-specs/planner.md | 4 +- .../team-issue/roles/coordinator/role.md | 2 +- .claude/skills/team-iterdev/SKILL.md | 2 +- .../skills/team-iterdev/role-specs/tester.md | 17 +- .../team-lifecycle-v2/role-specs/architect.md | 76 ++++++ .../team-lifecycle-v2/role-specs/executor.md | 67 +++++ .../role-specs/fe-developer.md | 79 ++++++ .../team-lifecycle-v2/role-specs/fe-qa.md | 79 ++++++ .../team-lifecycle-v2/role-specs/planner.md | 98 +++++++ .../team-lifecycle-v2/role-specs/tester.md | 76 ++++++ .../specs/document-standards.md | 192 +++++++++++++ .../team-lifecycle-v2/specs/quality-gates.md | 207 ++++++++++++++ .../templates/architecture-doc.md | 254 ++++++++++++++++++ .../templates/epics-template.md | 196 ++++++++++++++ .../templates/product-brief.md | 133 +++++++++ .../templates/requirements-prd.md | 224 +++++++++++++++ .claude/skills/team-lifecycle/SKILL.md | 25 +- .../team-lifecycle/role-specs/analyst.md | 6 +- .../team-lifecycle/role-specs/architect.md | 2 +- .../team-lifecycle/role-specs/executor.md | 2 +- .../team-lifecycle/role-specs/fe-developer.md | 2 +- .../skills/team-lifecycle/role-specs/fe-qa.md | 2 +- .../team-lifecycle/role-specs/planner.md | 6 +- .../team-lifecycle/role-specs/reviewer.md | 14 +- .../team-lifecycle/role-specs/tester.md | 2 +- .../team-lifecycle/role-specs/writer.md | 16 +- .../team-lifecycle/roles/coordinator/role.md | 3 +- .../team-lifecycle/specs/team-config.json | 24 +- .../subagents/discuss-subagent.md | 169 ------------ .../subagents/doc-generation-subagent.md | 62 ----- .../subagents/explore-subagent.md | 174 ------------ .claude/skills/team-perf-opt/SKILL.md | 12 +- .../team-perf-opt/role-specs/optimizer.md | 4 +- .../team-perf-opt/role-specs/profiler.md | 4 +- .../team-perf-opt/role-specs/reviewer.md | 4 +- .../team-perf-opt/role-specs/strategist.md | 4 +- .../subagents/discuss-subagent.md | 89 ------ .../subagents/explore-subagent.md | 108 -------- .claude/skills/team-planex/SKILL.md | 2 +- .../skills/team-planex/role-specs/executor.md | 2 +- .../roles/coordinator/commands/monitor.md | 2 +- .../team-planex/roles/coordinator/role.md | 2 +- .../skills/team-quality-assurance/SKILL.md | 4 +- .../role-specs/analyst.md | 2 +- .../role-specs/executor.md | 4 +- .../role-specs/generator.md | 4 +- .../role-specs/scout.md | 2 +- .../role-specs/strategist.md | 2 +- .../roles/coordinator/commands/monitor.md | 2 +- .../roles/coordinator/role.md | 2 +- .../specs/team-config.json | 8 +- .claude/skills/team-review/SKILL.md | 4 +- .../roles/coordinator/commands/monitor.md | 2 +- .../team-review/roles/coordinator/role.md | 2 +- .claude/skills/team-roadmap-dev/SKILL.md | 2 +- .../team-roadmap-dev/role-specs/executor.md | 23 +- .../team-roadmap-dev/role-specs/planner.md | 39 ++- .../team-roadmap-dev/role-specs/verifier.md | 3 +- .../roles/coordinator/commands/monitor.md | 4 +- .../coordinator/commands/roadmap-discuss.md | 4 +- .../roles/coordinator/role.md | 4 +- .../team-roadmap-dev/specs/team-config.json | 5 +- .claude/skills/team-tech-debt/SKILL.md | 2 +- .../team-tech-debt/role-specs/executor.md | 20 +- .../team-tech-debt/role-specs/scanner.md | 7 +- .../team-tech-debt/role-specs/validator.md | 14 +- .../team-tech-debt/roles/coordinator/role.md | 4 +- .../team-tech-debt/specs/team-config.json | 11 +- .../team-testing/role-specs/executor.md | 2 +- .claude/skills/team-uidesign/SKILL.md | 2 +- .../team-uidesign/role-specs/researcher.md | 4 +- .../team-ultra-analyze/role-specs/analyst.md | 2 +- .../role-specs/discussant.md | 6 +- .../team-ultra-analyze/role-specs/explorer.md | 2 +- .../role-specs/synthesizer.md | 2 +- .../team-ultra-analyze/specs/team-config.json | 6 +- 103 files changed, 1959 insertions(+), 1311 deletions(-) delete mode 100644 .claude/skills/team-arch-opt/subagents/discuss-subagent.md delete mode 100644 .claude/skills/team-arch-opt/subagents/explore-subagent.md delete mode 100644 .claude/skills/team-coordinate/subagents/discuss-subagent.md delete mode 100644 .claude/skills/team-coordinate/subagents/explore-subagent.md create mode 100644 .claude/skills/team-lifecycle-v2/role-specs/architect.md create mode 100644 .claude/skills/team-lifecycle-v2/role-specs/executor.md create mode 100644 .claude/skills/team-lifecycle-v2/role-specs/fe-developer.md create mode 100644 .claude/skills/team-lifecycle-v2/role-specs/fe-qa.md create mode 100644 .claude/skills/team-lifecycle-v2/role-specs/planner.md create mode 100644 .claude/skills/team-lifecycle-v2/role-specs/tester.md create mode 100644 .claude/skills/team-lifecycle-v2/specs/document-standards.md create mode 100644 .claude/skills/team-lifecycle-v2/specs/quality-gates.md create mode 100644 .claude/skills/team-lifecycle-v2/templates/architecture-doc.md create mode 100644 .claude/skills/team-lifecycle-v2/templates/epics-template.md create mode 100644 .claude/skills/team-lifecycle-v2/templates/product-brief.md create mode 100644 .claude/skills/team-lifecycle-v2/templates/requirements-prd.md delete mode 100644 .claude/skills/team-lifecycle/subagents/discuss-subagent.md delete mode 100644 .claude/skills/team-lifecycle/subagents/doc-generation-subagent.md delete mode 100644 .claude/skills/team-lifecycle/subagents/explore-subagent.md delete mode 100644 .claude/skills/team-perf-opt/subagents/discuss-subagent.md delete mode 100644 .claude/skills/team-perf-opt/subagents/explore-subagent.md diff --git a/.claude/agents/team-worker.md b/.claude/agents/team-worker.md index b2bcd80d..a3a8a01f 100644 --- a/.claude/agents/team-worker.md +++ b/.claude/agents/team-worker.md @@ -49,7 +49,7 @@ Parse the following fields from your prompt: - `prefix`: Task prefix to filter (e.g., `RESEARCH`, `DRAFT`, `IMPL`) - `inner_loop`: Override from frontmatter if present - `discuss_rounds`: Array of discuss round IDs this role handles - - `subagents`: (DEPRECATED - team workers cannot call subagents) Array for documentation only + - `delegates_to`: (DEPRECATED - team workers cannot delegate to other agents) Array for documentation only - `message_types`: Success/error/fix message type mappings 3. Parse **body** (content after frontmatter) to get Phase 2-4 execution instructions 4. Store parsed metadata and instructions for use in execution phases @@ -123,9 +123,9 @@ After claiming a task, check if output artifacts already exist (indicates resume The role_spec contains Phase 2, Phase 3, and Phase 4 sections with domain-specific logic. Follow those instructions exactly. Key integration points with built-in infrastructure: -## CRITICAL LIMITATION: No Subagent Delegation +## CRITICAL LIMITATION: No Agent Delegation -**Team workers CANNOT call the Agent() tool to spawn subagents.** +**Team workers CANNOT call the Agent() tool to spawn other agents.** Test evidence shows that team members spawned via Agent tool do not have access to the Agent tool themselves. Only the coordinator (main conversation context) can spawn agents. @@ -142,15 +142,15 @@ Bash(`ccw cli -p "..." --tool gemini --mode analysis`, { run_in_background: fals Use Read, Grep, Glob, mcp__ace-tool__search_context directly. **Option C: Request Coordinator Help** -Send message to coordinator requesting subagent delegation: +Send message to coordinator requesting agent delegation: ```javascript mcp__ccw-tools__team_msg({ operation: "log", session_id: sessionId, from: role, to: "coordinator", - type: "subagent_request", - summary: "Request exploration subagent for X", + type: "agent_request", + summary: "Request exploration agent for X", data: { reason: "...", scope: "..." } }) SendMessage({ recipient: "coordinator", content: "..." }) diff --git a/.claude/skills/team-arch-opt/SKILL.md b/.claude/skills/team-arch-opt/SKILL.md index 0921f9b1..bf3f7ea0 100644 --- a/.claude/skills/team-arch-opt/SKILL.md +++ b/.claude/skills/team-arch-opt/SKILL.md @@ -27,7 +27,7 @@ Unified team skill: Analyze codebase architecture, identify structural issues (d analyzer desig- refact- valid- review- ner orer ator er - Subagents (callable by workers, not team members): + CLI Tools (callable by workers inline): [explore] [discuss] (tw) = team-worker agent @@ -52,12 +52,12 @@ Parse `$ARGUMENTS`. No `--role` needed -- always routes to coordinator. | validator | [role-specs/validator.md](role-specs/validator.md) | VALIDATE-* | validation | false | | reviewer | [role-specs/reviewer.md](role-specs/reviewer.md) | REVIEW-* / QUALITY-* | read_only_analysis | false | -### Subagent Registry +### CLI Tool Registry -| Subagent | Spec | Callable By | Purpose | -|----------|------|-------------|---------| -| explore | [subagents/explore-subagent.md](subagents/explore-subagent.md) | analyzer, refactorer | Shared codebase exploration for architecture-critical structures and dependency graphs | -| discuss | [subagents/discuss-subagent.md](subagents/discuss-subagent.md) | designer, reviewer | Multi-perspective discussion for refactoring approaches and review findings | +| Tool | Spec | Used By | Purpose | +|------|------|---------|---------| +| explore | [cli-tools/explore.md](cli-tools/explore.md) | analyzer, refactorer | Shared codebase exploration for architecture-critical structures and dependency graphs | +| discuss | [cli-tools/discuss.md](cli-tools/discuss.md) | designer, reviewer | Multi-perspective discussion for refactoring approaches and review findings | ### Dispatch @@ -460,7 +460,7 @@ Coordinator supports `--resume` / `--continue` for interrupted sessions: |----------|------------| | Role spec file not found | Error with expected path (role-specs/.md) | | Command file not found | Fallback to inline execution in coordinator role.md | -| Subagent spec not found | Error with expected path (subagents/-subagent.md) | +| CLI tool spec not found | Error with expected path (cli-tools/.md) | | Fast-advance orphan detected | Coordinator resets task to pending on next check | | consensus_blocked HIGH | Coordinator creates revision task or pauses pipeline | | team-worker agent unavailable | Error: requires .claude/agents/team-worker.md | diff --git a/.claude/skills/team-arch-opt/role-specs/analyzer.md b/.claude/skills/team-arch-opt/role-specs/analyzer.md index 49fb58de..e5a72062 100644 --- a/.claude/skills/team-arch-opt/role-specs/analyzer.md +++ b/.claude/skills/team-arch-opt/role-specs/analyzer.md @@ -1,7 +1,7 @@ --- prefix: ANALYZE inner_loop: false -subagents: [explore] +cli_tools: [explore] message_types: success: analyze_complete error: error @@ -31,7 +31,7 @@ Analyze codebase architecture to identify structural issues: dependency cycles, | CLI entry / bin/ directory | CLI Tool | Command structure, plugin architecture, configuration layering | | No detection | Generic | All architecture dimensions | -3. Use `explore` subagent to map module structure, dependency graph, and layer boundaries within target scope +3. Use `explore` CLI tool to map module structure, dependency graph, and layer boundaries within target scope 4. Detect available analysis tools (linters, dependency analyzers, build tools) ## Phase 3: Architecture Analysis diff --git a/.claude/skills/team-arch-opt/role-specs/designer.md b/.claude/skills/team-arch-opt/role-specs/designer.md index ede2d042..d82596d6 100644 --- a/.claude/skills/team-arch-opt/role-specs/designer.md +++ b/.claude/skills/team-arch-opt/role-specs/designer.md @@ -2,7 +2,7 @@ prefix: DESIGN inner_loop: false discuss_rounds: [DISCUSS-REFACTOR] -subagents: [discuss] +cli_tools: [discuss] message_types: success: design_complete error: error @@ -57,7 +57,7 @@ Prioritize refactorings by impact/effort ratio: | P2 (Medium) | Medium impact + Low effort (duplication extraction) | | P3 (Low) | Low impact or High effort -- defer (large God Class decomposition) | -If complexity is High, invoke `discuss` subagent (DISCUSS-REFACTOR round) to evaluate trade-offs between competing strategies before finalizing the plan. +If complexity is High, invoke `discuss` CLI tool (DISCUSS-REFACTOR round) to evaluate trade-offs between competing strategies before finalizing the plan. Define measurable success criteria per refactoring (target metric improvement or structural change). diff --git a/.claude/skills/team-arch-opt/role-specs/refactorer.md b/.claude/skills/team-arch-opt/role-specs/refactorer.md index a0701c01..ca6e8fa8 100644 --- a/.claude/skills/team-arch-opt/role-specs/refactorer.md +++ b/.claude/skills/team-arch-opt/role-specs/refactorer.md @@ -2,7 +2,7 @@ prefix: REFACTOR inner_loop: true additional_prefixes: [FIX] -subagents: [explore] +cli_tools: [explore] message_types: success: refactor_complete error: error @@ -47,7 +47,7 @@ Implement architecture refactoring changes following the design plan. For FIX ta - **Independent pipeline**: Read `/artifacts/pipelines/{P}/refactoring-plan.md` -- extract this pipeline's plan 4. For FIX: parse review/validation feedback for specific issues to address -5. Use `explore` subagent to load implementation context for target files +5. Use `explore` CLI tool to load implementation context for target files 6. For inner loop (single mode only): load context_accumulator from prior REFACTOR/FIX tasks **Meta.json namespace**: diff --git a/.claude/skills/team-arch-opt/role-specs/reviewer.md b/.claude/skills/team-arch-opt/role-specs/reviewer.md index 86244065..631a2988 100644 --- a/.claude/skills/team-arch-opt/role-specs/reviewer.md +++ b/.claude/skills/team-arch-opt/role-specs/reviewer.md @@ -3,7 +3,7 @@ prefix: REVIEW inner_loop: false additional_prefixes: [QUALITY] discuss_rounds: [DISCUSS-REVIEW] -subagents: [discuss] +cli_tools: [discuss] message_types: success: review_complete error: error @@ -90,7 +90,7 @@ Per-dimension review process: - Dependency direction follows layer conventions (dependencies flow inward) - Appropriate abstraction level (not over-engineered, not under-abstracted) -If any Critical findings detected, invoke `discuss` subagent (DISCUSS-REVIEW round) to validate the assessment before issuing verdict. +If any Critical findings detected, invoke `discuss` CLI tool (DISCUSS-REVIEW round) to validate the assessment before issuing verdict. ## Phase 4: Verdict & Feedback diff --git a/.claude/skills/team-arch-opt/specs/team-config.json b/.claude/skills/team-arch-opt/specs/team-config.json index a2f4c21c..82ca6878 100644 --- a/.claude/skills/team-arch-opt/specs/team-config.json +++ b/.claude/skills/team-arch-opt/specs/team-config.json @@ -31,7 +31,7 @@ "inner_loop": false, "additional_prefixes": [], "discuss_rounds": [], - "subagents": ["explore"], + "cli_tools": ["explore"], "message_types": { "success": "analyze_complete", "error": "error" @@ -51,7 +51,7 @@ "inner_loop": false, "additional_prefixes": [], "discuss_rounds": ["DISCUSS-REFACTOR"], - "subagents": ["discuss"], + "cli_tools": ["discuss"], "message_types": { "success": "design_complete", "error": "error" @@ -71,7 +71,7 @@ "inner_loop": true, "additional_prefixes": ["FIX"], "discuss_rounds": [], - "subagents": ["explore"], + "cli_tools": ["explore"], "message_types": { "success": "refactor_complete", "error": "error", @@ -92,7 +92,7 @@ "inner_loop": false, "additional_prefixes": [], "discuss_rounds": [], - "subagents": [], + "cli_tools": [], "message_types": { "success": "validate_complete", "error": "error", @@ -113,7 +113,7 @@ "inner_loop": false, "additional_prefixes": ["QUALITY"], "discuss_rounds": ["DISCUSS-REVIEW"], - "subagents": ["discuss"], + "cli_tools": ["discuss"], "message_types": { "success": "review_complete", "error": "error", @@ -193,10 +193,10 @@ "diagram": "See pipeline-diagram section" }, - "subagents": [ + "cli_tools": [ { "name": "explore", - "agent_type": "cli-explore-agent", + "implementation": "ccw cli with analysis mode", "callable_by": ["analyzer", "refactorer"], "purpose": "Shared codebase exploration for architecture-critical structures, dependency graphs, and module boundaries", "has_cache": true, @@ -204,7 +204,7 @@ }, { "name": "discuss", - "agent_type": "cli-discuss-agent", + "implementation": "ccw cli with analysis mode", "callable_by": ["designer", "reviewer"], "purpose": "Multi-perspective discussion for refactoring approaches and review findings", "has_cache": false diff --git a/.claude/skills/team-arch-opt/subagents/discuss-subagent.md b/.claude/skills/team-arch-opt/subagents/discuss-subagent.md deleted file mode 100644 index 340b721d..00000000 --- a/.claude/skills/team-arch-opt/subagents/discuss-subagent.md +++ /dev/null @@ -1,123 +0,0 @@ -# Discuss Subagent - -Multi-perspective discussion for evaluating refactoring strategies and reviewing code change quality. Used by designer (DISCUSS-REFACTOR) and reviewer (DISCUSS-REVIEW) when complex trade-offs require multi-angle analysis. - -## Design Rationale - -Complex refactoring decisions (e.g., choosing between dependency inversion vs mediator pattern to break a cycle) and nuanced code review findings (e.g., evaluating whether a temporary coupling increase is acceptable) benefit from structured multi-perspective analysis. This subagent provides that analysis inline without spawning additional team members. - -## Invocation - -Called by designer, reviewer after their primary analysis when complexity warrants multi-perspective evaluation: - -```javascript -// Multi-perspective discussion using CLI tools -Bash({ - command: `ccw cli -p "PURPOSE: Conduct multi-perspective discussion on for architecture optimization -TASK: • Evaluate architecture impact • Assess risks and trade-offs • Consider maintainability • Explore alternatives -MODE: analysis -CONTEXT: @/discussions/.md | Memory: -EXPECTED: Structured recommendation with consensus verdict (proceed/revise/escalate), confidence level, key trade-offs, recommended approach with rationale, dissenting perspectives -CONSTRAINTS: Focus on topic - -Round: -Topic: -Session: - -Context: - - -Perspectives to consider: -- Architecture impact: Will this actually improve the target structural metric? -- Risk assessment: What could break? Dangling references? Behavioral changes? Migration risk? -- Maintainability: Is the refactored code more understandable and maintainable? -- Alternative approaches: Are there simpler or safer ways to achieve the same structural improvement? - -Evaluate trade-offs and provide a structured recommendation with: -- Consensus verdict: proceed / revise / escalate -- Confidence level: high / medium / low -- Key trade-offs identified -- Recommended approach with rationale -- Dissenting perspectives (if any)" --tool gemini --mode analysis`, - run_in_background: false -}) -``` - -**Alternative: Direct multi-perspective analysis** - -For simpler discussions, call CLI tool directly without wrapper: - -```javascript -Bash({ - command: `ccw cli -p "Conduct a multi-perspective discussion on the following topic. - -Round: -Topic: -Session: - -Context: - - -Perspectives to consider: -- Architecture impact: Will this actually improve the target structural metric? -- Risk assessment: What could break? Dangling references? Behavioral changes? Migration risk? -- Maintainability: Is the refactored code more understandable and maintainable? -- Alternative approaches: Are there simpler or safer ways to achieve the same structural improvement? - -Evaluate trade-offs and provide a structured recommendation with: -- Consensus verdict: proceed / revise / escalate -- Confidence level: high / medium / low -- Key trade-offs identified -- Recommended approach with rationale -- Dissenting perspectives (if any)` -}) -``` - -## Round Configuration - -| Round | Artifact | Parameters | Calling Role | -|-------|----------|------------|-------------| -| DISCUSS-REFACTOR | /discussions/DISCUSS-REFACTOR.md | Refactoring strategy trade-offs | designer | -| DISCUSS-REVIEW | /discussions/DISCUSS-REVIEW.md | Code review finding validation | reviewer | - -## Integration with Calling Role - -The calling role is responsible for: - -1. **Before calling**: Complete primary analysis, identify the specific trade-off or finding needing discussion -2. **Calling**: Invoke subagent with round ID, topic, and relevant context -3. **After calling**: - -| Result | Action | -|--------|--------| -| consensus_reached (proceed) | Incorporate recommendation into output, continue | -| consensus_reached (revise) | Adjust findings/strategy based on discussion insights | -| consensus_blocked (HIGH) | Report to coordinator via message with severity | -| consensus_blocked (MEDIUM) | Include in output with recommendation for revision | -| consensus_blocked (LOW) | Note in output, proceed with original assessment | - -## Output Schema - -```json -{ - "round_id": "", - "topic": "", - "verdict": "", - "confidence": "", - "trade_offs": [ - { "dimension": "", "pro": "", "con": "" } - ], - "recommendation": "", - "rationale": "", - "dissenting_views": [""] -} -``` - -## Error Handling - -| Scenario | Resolution | -|----------|------------| -| Single perspective analysis fails | Continue with partial perspectives | -| All analyses fail | Return basic recommendation from calling role's primary analysis | -| Artifact not found | Return error immediately | -| Discussion inconclusive | Return "revise" verdict with low confidence | diff --git a/.claude/skills/team-arch-opt/subagents/explore-subagent.md b/.claude/skills/team-arch-opt/subagents/explore-subagent.md deleted file mode 100644 index 27e63d54..00000000 --- a/.claude/skills/team-arch-opt/subagents/explore-subagent.md +++ /dev/null @@ -1,113 +0,0 @@ -# Explore Subagent - -Shared codebase exploration for discovering architecture-critical structures, dependency graphs, module boundaries, and layer organization. Results are cached to avoid redundant exploration across analyzer and refactorer roles. - -## Design Rationale - -Codebase exploration is a read-only operation shared between analyzer (mapping structural issues) and refactorer (understanding implementation context). Caching explorations avoids redundant work when refactorer re-explores structures the analyzer already mapped. - -## Invocation - -Called by analyzer, refactorer after needing codebase context for architecture analysis or implementation: - -``` -Agent({ - subagent_type: "Explore", - run_in_background: false, - description: "Explore codebase for architecture-critical structures in ", - prompt: `Explore the codebase to identify architecture-critical structures. - -Target scope: -Session: -Focus: - -Tasks: -1. Map the module structure, entry points, and layer boundaries within scope -2. Build dependency graph (import/require relationships between modules) -3. Identify architectural patterns (layering, dependency injection, event-driven, plugin architecture) -4. Note any existing abstractions, interfaces, and module boundaries -5. List key files with their roles, layer assignment, and dependency relationships - -Output a structured exploration report with: -- Module map (key files, their relationships, and layer assignments) -- Dependency graph (directed edges between modules, cycle indicators) -- Layer structure (identified layers and their boundaries) -- Existing architectural patterns found -- Architecture-relevant configuration (path aliases, barrel exports, module boundaries)` -}) -``` - -## Cache Mechanism - -### Cache Index Schema - -`/explorations/cache-index.json`: - -```json -{ - "entries": [ - { - "key": "", - "scope": "", - "focus": "", - "timestamp": "", - "result_file": ".md" - } - ] -} -``` - -### Cache Lookup Rules - -| Condition | Action | -|-----------|--------| -| Exact scope+focus match exists | Return cached result from .md | -| No match | Execute subagent, cache result to .md, update index | -| Cache file missing but index has entry | Remove stale entry, re-execute | -| Cache older than current session | Use cached (explorations are stable within session) | - -## Integration with Calling Role - -The calling role is responsible for: - -1. **Before calling**: Determine target scope and exploration focus -2. **Calling**: Check cache first, invoke subagent only on cache miss -3. **After calling**: - -| Result | Action | -|--------|--------| -| Exploration successful | Use findings to inform analysis/implementation | -| Exploration partial | Use available findings, note gaps | -| Exploration failed | Proceed without exploration context, use direct file reading | - -## Output Schema - -```json -{ - "scope": "", - "module_map": [ - { "file": "", "role": "", "layer": "", "dependency_graph": { "imports": [""], "imported_by": [""] } } - ], - "dependency_graph": { - "nodes": [""], - "edges": [{ "from": "", "to": "", "type": "" }], - "cycles": [["", "", ""]] - }, - "layer_structure": [ - { "layer": "", "modules": [""], "violations": [""] } - ], - "existing_patterns": [ - { "type": "", "location": "", "description": "" } - ], - "investigation_targets": [""] -} -``` - -## Error Handling - -| Scenario | Resolution | -|----------|------------| -| Single exploration angle fails | Continue with partial results | -| All exploration fails | Return basic result from direct file listing | -| Target scope not found | Return error immediately | -| Cache corrupt | Clear cache-index.json, re-execute | diff --git a/.claude/skills/team-brainstorm/role-specs/challenger.md b/.claude/skills/team-brainstorm/role-specs/challenger.md index 5506c3e2..e63137bb 100644 --- a/.claude/skills/team-brainstorm/role-specs/challenger.md +++ b/.claude/skills/team-brainstorm/role-specs/challenger.md @@ -1,7 +1,7 @@ --- prefix: CHALLENGE inner_loop: false -subagents: [] +delegates_to: [] message_types: success: critique_ready error: error diff --git a/.claude/skills/team-brainstorm/role-specs/evaluator.md b/.claude/skills/team-brainstorm/role-specs/evaluator.md index 2479bc7b..83382c5d 100644 --- a/.claude/skills/team-brainstorm/role-specs/evaluator.md +++ b/.claude/skills/team-brainstorm/role-specs/evaluator.md @@ -1,7 +1,7 @@ --- prefix: EVAL inner_loop: false -subagents: [] +delegates_to: [] message_types: success: evaluation_ready error: error diff --git a/.claude/skills/team-brainstorm/role-specs/ideator.md b/.claude/skills/team-brainstorm/role-specs/ideator.md index d6522adf..d6366106 100644 --- a/.claude/skills/team-brainstorm/role-specs/ideator.md +++ b/.claude/skills/team-brainstorm/role-specs/ideator.md @@ -1,7 +1,7 @@ --- prefix: IDEA inner_loop: false -subagents: [] +delegates_to: [] message_types: success: ideas_ready error: error diff --git a/.claude/skills/team-brainstorm/role-specs/synthesizer.md b/.claude/skills/team-brainstorm/role-specs/synthesizer.md index 48ff2bdd..8b6714cb 100644 --- a/.claude/skills/team-brainstorm/role-specs/synthesizer.md +++ b/.claude/skills/team-brainstorm/role-specs/synthesizer.md @@ -1,7 +1,7 @@ --- prefix: SYNTH inner_loop: false -subagents: [] +delegates_to: [] message_types: success: synthesis_ready error: error diff --git a/.claude/skills/team-coordinate/SKILL.md b/.claude/skills/team-coordinate/SKILL.md index aea69cb4..0304a209 100644 --- a/.claude/skills/team-coordinate/SKILL.md +++ b/.claude/skills/team-coordinate/SKILL.md @@ -27,9 +27,9 @@ Universal team coordination skill: analyze task -> generate role-specs -> dispat [team-worker agents, each loaded with a dynamic role-spec] (roles generated at runtime from task analysis) - Subagents (callable by any worker, not team members): - [discuss-subagent] - multi-perspective critique (dynamic perspectives) - [explore-subagent] - codebase exploration with cache + CLI Tools (callable by any worker): + ccw cli --mode analysis - analysis and exploration + ccw cli --mode write - code generation and modification ``` ## Role Router @@ -49,12 +49,14 @@ Only coordinator is statically registered. All other roles are dynamic, stored a | coordinator | [roles/coordinator/role.md](roles/coordinator/role.md) | built-in orchestrator | | (dynamic) | `/role-specs/.md` | runtime-generated role-spec | -### Subagent Registry +### CLI Tool Usage -| Subagent | Spec | Callable By | Purpose | -|----------|------|-------------|---------| -| discuss | [subagents/discuss-subagent.md](subagents/discuss-subagent.md) | any role | Multi-perspective critique (dynamic perspectives) | -| explore | [subagents/explore-subagent.md](subagents/explore-subagent.md) | any role | Codebase exploration with cache | +Workers can use CLI tools for analysis and code operations: + +| Tool | Purpose | +|------|---------| +| ccw cli --mode analysis | Analysis, exploration, pattern discovery | +| ccw cli --mode write | Code generation, modification, refactoring | ### Dispatch @@ -259,7 +261,7 @@ Coordinator supports `resume` / `continue` for interrupted sessions: | Unknown command | Error with available command list | | Dynamic role-spec not found | Error, coordinator may need to regenerate | | Command file not found | Fallback to inline execution | -| Discuss subagent fails | Worker proceeds without discuss, logs warning | +| CLI tool fails | Worker proceeds with direct implementation, logs warning | | Explore cache corrupt | Clear cache, re-explore | | Fast-advance spawns wrong task | Coordinator reconciles on next callback | | capability_gap reported | Coordinator generates new role-spec via handleAdapt | diff --git a/.claude/skills/team-coordinate/roles/coordinator/commands/analyze-task.md b/.claude/skills/team-coordinate/roles/coordinator/commands/analyze-task.md index af7b6d3a..2b76fc6f 100644 --- a/.claude/skills/team-coordinate/roles/coordinator/commands/analyze-task.md +++ b/.claude/skills/team-coordinate/roles/coordinator/commands/analyze-task.md @@ -117,7 +117,7 @@ For each role, determine frontmatter and generation hints: |-------|------------| | `prefix` | From capability prefix (e.g., RESEARCH, DRAFT, IMPL) | | `inner_loop` | `true` if role has 2+ serial same-prefix tasks | -| `subagents` | Suggested, not mandatory — coordinator may adjust based on task needs | +| `CLI tools` | Suggested, not mandatory — coordinator may adjust based on task needs | | `pattern_hint` | Reference pattern name from role-spec-template (research/document/code/analysis/validation) — guides coordinator's Phase 2-4 composition, NOT a rigid template selector | | `output_type` | `artifact` (new files in session/artifacts/) / `codebase` (modify existing project files) / `mixed` (both) — determines verification strategy in Behavioral Traits | | `message_types.success` | `_complete` | @@ -177,7 +177,7 @@ Write `/task-analysis.json`: "task_count": 1, "inner_loop": false, "role_spec_metadata": { - "subagents": ["explore"], + "CLI tools": ["explore"], "pattern_hint": "research", "output_type": "artifact", "message_types": { diff --git a/.claude/skills/team-coordinate/roles/coordinator/role.md b/.claude/skills/team-coordinate/roles/coordinator/role.md index 65888eac..6ce2eaab 100644 --- a/.claude/skills/team-coordinate/roles/coordinator/role.md +++ b/.claude/skills/team-coordinate/roles/coordinator/role.md @@ -25,7 +25,7 @@ Orchestrate the team-coordinate workflow: task analysis, dynamic role-spec gener - **Read source code or perform codebase exploration** (delegate to worker roles) - Execute task work directly (delegate to workers) - Modify task output artifacts (workers own their deliverables) -- Call implementation subagents (code-developer, etc.) directly +- Call implementation agents (code-developer, etc.) directly - Skip dependency validation when creating task chains - Generate more than 5 worker roles (merge if exceeded) - Override consensus_blocked HIGH without user confirmation diff --git a/.claude/skills/team-coordinate/specs/role-spec-template.md b/.claude/skills/team-coordinate/specs/role-spec-template.md index 815a44c8..ff271f9d 100644 --- a/.claude/skills/team-coordinate/specs/role-spec-template.md +++ b/.claude/skills/team-coordinate/specs/role-spec-template.md @@ -11,7 +11,7 @@ Template used by coordinator to generate lightweight worker role-spec files at r role: prefix: inner_loop: -subagents: [] +CLI tools: [] message_types: success: _complete error: error @@ -45,7 +45,7 @@ message_types: | `role` | Yes | Role name matching session registry | | `prefix` | Yes | Task prefix to filter (e.g., RESEARCH, DRAFT, IMPL) | | `inner_loop` | Yes | Whether team-worker loops through same-prefix tasks | -| `subagents` | No | Array of subagent types this role may call | +| `CLI tools` | No | Array of CLI tool types this role may call | | `message_types` | Yes | Message type mapping for team_msg | | `message_types.success` | Yes | Type string for successful completion | | `message_types.error` | Yes | Type string for errors (usually "error") | @@ -61,13 +61,13 @@ message_types: | ~80 lines target | Lightweight, domain-focused | | No pseudocode | Decision tables + text + tool calls only | | `` notation | Use angle brackets for variable substitution | -| Reference subagents by name | team-worker resolves invocation from its delegation templates | +| Reference CLI tools by name | team-worker resolves invocation from its delegation templates | ## Behavioral Traits All dynamically generated role-specs MUST embed these traits into Phase 4. Coordinator copies this section verbatim into every generated role-spec as a Phase 4 appendix. -**Design principle**: Constrain behavioral characteristics (accuracy, feedback, quality gates), NOT specific actions (which tool, which subagent, which path). Tasks are diverse — the coordinator composes task-specific Phase 2-3 instructions, while these traits ensure execution quality regardless of task type. +**Design principle**: Constrain behavioral characteristics (accuracy, feedback, quality gates), NOT specific actions (which tool, which CLI tool, which path). Tasks are diverse — the coordinator composes task-specific Phase 2-3 instructions, while these traits ensure execution quality regardless of task type. ### Accuracy — outputs must be verifiable @@ -95,7 +95,7 @@ Phase 4 must produce a verification summary with these fields: ### Error Protocol -- Primary approach fails → try alternative (different subagent / different tool) +- Primary approach fails → try alternative (different CLI tool / different tool) - 2 retries exhausted → escalate to coordinator with failure details - NEVER: skip verification and report completed @@ -108,7 +108,7 @@ Coordinator MAY reference these patterns when composing Phase 2-4 content for a ### Research / Exploration - Phase 2: Define exploration scope + load prior knowledge from shared state and wisdom -- Phase 3: Explore via subagents, direct tool calls, or codebase search — approach chosen by agent +- Phase 3: Explore via CLI tools, direct tool calls, or codebase search — approach chosen by agent - Phase 4: Verify findings documented (Behavioral Traits) + update shared state ### Document / Content @@ -120,7 +120,7 @@ Coordinator MAY reference these patterns when composing Phase 2-4 content for a ### Code Implementation - Phase 2: Load design/spec artifacts from upstream -- Phase 3: Implement code changes — subagent choice and approach determined by task complexity +- Phase 3: Implement code changes — CLI tool choice and approach determined by task complexity - Phase 4: Syntax check + file verification (Behavioral Traits) + update shared state ### Analysis / Audit diff --git a/.claude/skills/team-coordinate/subagents/discuss-subagent.md b/.claude/skills/team-coordinate/subagents/discuss-subagent.md deleted file mode 100644 index 06b42848..00000000 --- a/.claude/skills/team-coordinate/subagents/discuss-subagent.md +++ /dev/null @@ -1,132 +0,0 @@ -# Discuss Subagent - -Lightweight multi-perspective critique engine. Called inline by any role needing peer review. Perspectives are dynamic -- specified by the calling role, not pre-defined. - -## Design - -Unlike team-lifecycle-v4's fixed perspective definitions (product, technical, quality, risk, coverage), team-coordinate uses **dynamic perspectives** passed in the prompt. The calling role decides what viewpoints matter for its artifact. - -## Invocation - -Called by roles after artifact creation: - -```javascript -// Multi-perspective critique using CLI tools -// The coordinator reads the artifact and launches parallel CLI analyses for each perspective -Bash({ - command: `ccw cli -p "## Multi-Perspective Critique: - -### Input -- Artifact: -- Round: -- Session: - -### Perspectives - - -Example: -| Perspective | CLI Tool | Role | Focus Areas | -|-------------|----------|------|-------------| -| Feasibility | gemini | Engineer | Implementation complexity, technical risks, resource needs | -| Clarity | codex | Editor | Readability, logical flow, completeness of explanation | -| Accuracy | gemini | Domain Expert | Factual correctness, source reliability, claim verification | - -### Execution Steps -1. Read artifact from -2. For each perspective, launch CLI analysis in background: - Bash(command="ccw cli -p 'PURPOSE: Analyze from perspective for - TASK: - MODE: analysis - CONTEXT: Artifact content below - EXPECTED: JSON with strengths[], weaknesses[], suggestions[], rating (1-5) - CONSTRAINTS: Output valid JSON only - - Artifact: - ' --tool --mode analysis", run_in_background=true) -3. Wait for all CLI results -4. Divergence detection: - - High severity: any rating <= 2, critical issue identified - - Medium severity: rating spread (max - min) >= 3, or single perspective rated <= 2 with others >= 3 - - Low severity: minor suggestions only, all ratings >= 3 -5. Consensus determination: - - No high-severity divergences AND average rating >= 3.0 -> consensus_reached - - Otherwise -> consensus_blocked -6. Synthesize: - - Convergent themes (agreed by 2+ perspectives) - - Divergent views (conflicting assessments) - - Action items from suggestions -7. Write discussion record to: /discussions/-discussion.md - -### Discussion Record Format -# Discussion Record: - -**Artifact**: -**Perspectives**: -**Consensus**: reached / blocked -**Average Rating**: /5 - -## Convergent Themes -- - -## Divergent Views -- **** (): - -## Action Items -1. - -## Ratings -| Perspective | Rating | -|-------------|--------| -| | /5 | - -### Return Value - -**When consensus_reached**: -Return a summary string with: -- Verdict: consensus_reached -- Average rating -- Key action items (top 3) -- Discussion record path - -**When consensus_blocked**: -Return a structured summary with: -- Verdict: consensus_blocked -- Severity: HIGH | MEDIUM | LOW -- Average rating -- Divergence summary: top 3 divergent points with perspective attribution -- Action items: prioritized list of required changes -- Recommendation: revise | proceed-with-caution | escalate -- Discussion record path - -### Error Handling -- Single CLI fails -> fallback to direct Claude analysis for that perspective -- All CLI fail -> generate basic discussion from direct artifact reading -- Artifact not found -> return error immediately` -}) -``` - -## Integration with Calling Role - -The calling role is responsible for: - -1. **Before calling**: Complete primary artifact output -2. **Calling**: Invoke discuss subagent with appropriate dynamic perspectives -3. **After calling**: - -| Verdict | Severity | Role Action | -|---------|----------|-------------| -| consensus_reached | - | Include action items in Phase 5 report, proceed normally | -| consensus_blocked | HIGH | Include divergence details in Phase 5 SendMessage. Do NOT self-revise -- coordinator decides. | -| consensus_blocked | MEDIUM | Include warning in Phase 5 SendMessage. Proceed normally. | -| consensus_blocked | LOW | Treat as consensus_reached with notes. Proceed normally. | - -**SendMessage format for consensus_blocked (HIGH or MEDIUM)**: - -``` -[] complete. Discuss : consensus_blocked (severity=) -Divergences: -Action items: -Recommendation: -Artifact: -Discussion: -``` diff --git a/.claude/skills/team-coordinate/subagents/explore-subagent.md b/.claude/skills/team-coordinate/subagents/explore-subagent.md deleted file mode 100644 index 95fddd8f..00000000 --- a/.claude/skills/team-coordinate/subagents/explore-subagent.md +++ /dev/null @@ -1,120 +0,0 @@ -# Explore Subagent - -Shared codebase exploration utility with centralized caching. Callable by any role needing code context. - -## Invocation - -``` -Agent({ - subagent_type: "Explore", - run_in_background: false, - description: "Explore ", - prompt: `Explore codebase for: - -Focus angle: -Keywords: -Session folder: - -## Cache Check -1. Read /explorations/cache-index.json (if exists) -2. Look for entry with matching angle -3. If found AND file exists -> read cached result, return summary -4. If not found -> proceed to exploration - -## Exploration - - -## Output -Write JSON to: /explorations/explore-.json -Update cache-index.json with new entry - -## Output Schema -{ - "angle": "", - "query": "", - "relevant_files": [ - { "path": "...", "rationale": "...", "role": "...", "discovery_source": "...", "key_symbols": [] } - ], - "patterns": [], - "dependencies": [], - "external_refs": [], - "_metadata": { "created_by": "", "timestamp": "...", "cache_key": "..." } -} - -Return summary: file count, pattern count, top 5 files, output path` -}) -``` - -## Cache Mechanism - -### Cache Index Schema - -`/explorations/cache-index.json`: - -```json -{ - "entries": [ - { - "angle": "architecture", - "keywords": ["auth", "middleware"], - "file": "explore-architecture.json", - "created_by": "analyst", - "created_at": "2026-02-27T10:00:00Z", - "file_count": 15 - } - ] -} -``` - -### Cache Lookup Rules - -| Condition | Action | -|-----------|--------| -| Exact angle match exists | Return cached result | -| No match | Execute exploration, cache result | -| Cache file missing but index has entry | Remove stale entry, re-explore | - -### Cache Invalidation - -Cache is session-scoped. No explicit invalidation needed -- each session starts fresh. If a role suspects stale data, it can pass `force_refresh: true` in the prompt to bypass cache. - -## Angle Focus Guide - -| Angle | Focus Points | Typical Caller | -|-------|-------------|----------------| -| architecture | Layer boundaries, design patterns, component responsibilities, ADRs | any | -| dependencies | Import chains, external libraries, circular dependencies, shared utilities | any | -| modularity | Module interfaces, separation of concerns, extraction opportunities | any | -| integration-points | API endpoints, data flow between modules, event systems | any | -| security | Auth/authz logic, input validation, sensitive data handling, middleware | any | -| dataflow | Data transformations, state propagation, validation points | any | -| performance | Bottlenecks, N+1 queries, blocking operations, algorithm complexity | any | -| error-handling | Try-catch blocks, error propagation, recovery strategies, logging | any | -| patterns | Code conventions, design patterns, naming conventions, best practices | any | -| testing | Test files, coverage gaps, test patterns, mocking strategies | any | -| general | Broad semantic search for topic-related code | any | - -## Exploration Strategies - -### Low Complexity (direct search) - -For simple queries, use ACE semantic search: - -``` -mcp__ace-tool__search_context(project_root_path="", query="") -``` - -ACE failure fallback: `rg -l '' --type ts` - -### Medium/High Complexity (multi-angle) - -For complex queries, call cli-explore-agent per angle. The calling role determines complexity and selects angles. - -## Search Tool Priority - -| Tool | Priority | Use Case | -|------|----------|----------| -| mcp__ace-tool__search_context | P0 | Semantic search | -| Grep / Glob | P1 | Pattern matching | -| cli-explore-agent | Deep | Multi-angle exploration | -| WebSearch | P3 | External docs | diff --git a/.claude/skills/team-executor/roles/executor/role.md b/.claude/skills/team-executor/roles/executor/role.md index 630dc47a..ff5c8dd6 100644 --- a/.claude/skills/team-executor/roles/executor/role.md +++ b/.claude/skills/team-executor/roles/executor/role.md @@ -23,7 +23,7 @@ Orchestrate the team-executor workflow: session validation, state reconciliation ### MUST NOT - Execute task work directly (delegate to workers) - Modify task output artifacts (workers own their deliverables) -- Call implementation subagents (code-developer, etc.) directly +- Call CLI tools or spawn utility members directly for implementation (code-developer, etc.) - Generate new role-specs (use existing session role-specs only) - Skip session validation - Override consensus_blocked HIGH without user confirmation diff --git a/.claude/skills/team-executor/specs/session-schema.md b/.claude/skills/team-executor/specs/session-schema.md index 323b7925..7a4b0d1c 100644 --- a/.claude/skills/team-executor/specs/session-schema.md +++ b/.claude/skills/team-executor/specs/session-schema.md @@ -163,7 +163,7 @@ team-executor validates the following before execution: "responsibility_type": "", "inner_loop": false, "role_spec_metadata": { - "subagents": [], + "additional_members": [], "message_types": { "success": "_complete", "error": "error" diff --git a/.claude/skills/team-frontend/role-specs/analyst.md b/.claude/skills/team-frontend/role-specs/analyst.md index e31e7cbe..d1efd994 100644 --- a/.claude/skills/team-frontend/role-specs/analyst.md +++ b/.claude/skills/team-frontend/role-specs/analyst.md @@ -1,7 +1,7 @@ --- prefix: ANALYZE inner_loop: false -subagents: [] +additional_members: [] message_types: success: analyze_ready error: error diff --git a/.claude/skills/team-frontend/role-specs/architect.md b/.claude/skills/team-frontend/role-specs/architect.md index 89583dbb..4fad522f 100644 --- a/.claude/skills/team-frontend/role-specs/architect.md +++ b/.claude/skills/team-frontend/role-specs/architect.md @@ -1,7 +1,7 @@ --- prefix: ARCH inner_loop: false -subagents: [] +additional_members: [] message_types: success: arch_ready error: error diff --git a/.claude/skills/team-frontend/role-specs/developer.md b/.claude/skills/team-frontend/role-specs/developer.md index d2e9ddf9..3764c770 100644 --- a/.claude/skills/team-frontend/role-specs/developer.md +++ b/.claude/skills/team-frontend/role-specs/developer.md @@ -1,7 +1,7 @@ --- prefix: DEV inner_loop: true -subagents: [] +additional_members: [] message_types: success: dev_complete error: error diff --git a/.claude/skills/team-frontend/role-specs/qa.md b/.claude/skills/team-frontend/role-specs/qa.md index e4b00a8e..172c78d6 100644 --- a/.claude/skills/team-frontend/role-specs/qa.md +++ b/.claude/skills/team-frontend/role-specs/qa.md @@ -1,7 +1,7 @@ --- prefix: QA inner_loop: false -subagents: [] +additional_members: [] message_types: success: qa_passed error: error diff --git a/.claude/skills/team-issue/role-specs/explorer.md b/.claude/skills/team-issue/role-specs/explorer.md index d15a3528..1687fe4c 100644 --- a/.claude/skills/team-issue/role-specs/explorer.md +++ b/.claude/skills/team-issue/role-specs/explorer.md @@ -1,7 +1,7 @@ --- prefix: EXPLORE inner_loop: false -subagents: [cli-explore-agent] +additional_members: [] message_types: success: context_ready error: error @@ -44,8 +44,8 @@ Bash("ccw issue status --json") | Score | Complexity | Strategy | |-------|------------|----------| -| >= 4 | High | Deep exploration via cli-explore-agent | -| 2-3 | Medium | Hybrid: ACE search + selective agent | +| >= 4 | High | Deep exploration via CLI tool | +| 2-3 | Medium | Hybrid: ACE search + selective CLI | | 0-1 | Low | Direct ACE search only | **Exploration execution**: diff --git a/.claude/skills/team-issue/role-specs/integrator.md b/.claude/skills/team-issue/role-specs/integrator.md index 2e38f023..41307774 100644 --- a/.claude/skills/team-issue/role-specs/integrator.md +++ b/.claude/skills/team-issue/role-specs/integrator.md @@ -1,7 +1,7 @@ --- prefix: MARSHAL inner_loop: false -subagents: [issue-queue-agent] +additional_members: [] message_types: success: queue_ready conflict: conflict_found @@ -10,7 +10,7 @@ message_types: # Issue Integrator -Queue orchestration, conflict detection, and execution order optimization. Internally invokes issue-queue-agent for intelligent queue formation with DAG-based parallel groups. +Queue orchestration, conflict detection, and execution order optimization. Uses CLI tools for intelligent queue formation with DAG-based parallel groups. ## Phase 2: Collect Bound Solutions diff --git a/.claude/skills/team-issue/role-specs/planner.md b/.claude/skills/team-issue/role-specs/planner.md index b92fa436..e77ac3ca 100644 --- a/.claude/skills/team-issue/role-specs/planner.md +++ b/.claude/skills/team-issue/role-specs/planner.md @@ -2,7 +2,7 @@ prefix: SOLVE inner_loop: false additional_prefixes: [SOLVE-fix] -subagents: [issue-plan-agent] +additional_members: [] message_types: success: solution_ready multi: multi_solution @@ -11,7 +11,7 @@ message_types: # Issue Planner -Design solutions and decompose into implementation tasks. Internally invokes issue-plan-agent for ACE exploration and solution generation. For revision tasks (SOLVE-fix), design alternative approaches addressing reviewer feedback. +Design solutions and decompose into implementation tasks. Uses CLI tools for ACE exploration and solution generation. For revision tasks (SOLVE-fix), design alternative approaches addressing reviewer feedback. ## Phase 2: Context Loading diff --git a/.claude/skills/team-issue/roles/coordinator/role.md b/.claude/skills/team-issue/roles/coordinator/role.md index 191ca38b..ac10ad81 100644 --- a/.claude/skills/team-issue/roles/coordinator/role.md +++ b/.claude/skills/team-issue/roles/coordinator/role.md @@ -24,7 +24,7 @@ Orchestrates the issue resolution pipeline: manages task chains, spawns team-wor - Skip review gate in full/batch modes - Force-advance pipeline past failed review - Modify source code directly -- delegate to implementer worker -- Call implementation subagents directly (issue-plan-agent, issue-queue-agent, code-developer) +- Call CLI tools or spawn utility members directly for implementation (issue-plan-agent, issue-queue-agent, code-developer) --- diff --git a/.claude/skills/team-iterdev/SKILL.md b/.claude/skills/team-iterdev/SKILL.md index 2071b4d6..f65b353b 100644 --- a/.claude/skills/team-iterdev/SKILL.md +++ b/.claude/skills/team-iterdev/SKILL.md @@ -116,7 +116,7 @@ Standard report flow after task completion: | Share state via team_msg(type='state_update') | Create tasks for other roles | | SendMessage to coordinator | Communicate directly with other workers | -**Coordinator additional restrictions**: No direct code writing, no calling implementation-type subagents, no directly executing analysis/testing/review. +**Coordinator additional restrictions**: No direct code writing, no directly executing analysis/testing/review. ### Message Bus diff --git a/.claude/skills/team-iterdev/role-specs/tester.md b/.claude/skills/team-iterdev/role-specs/tester.md index 21eb7a76..cccd94b9 100644 --- a/.claude/skills/team-iterdev/role-specs/tester.md +++ b/.claude/skills/team-iterdev/role-specs/tester.md @@ -43,12 +43,25 @@ Common commands: npm test, pytest, go test ./..., cargo test | 2 | Parse results, check pass rate | | 3 | Pass rate >= 95% -> exit loop (success) | | 4 | Extract failing test details | -| 5 | Delegate fix to code-developer subagent | +| 5 | Apply fix using CLI tool | | 6 | Increment iteration counter | | 7 | iteration >= MAX (5) -> exit loop (report failures) | | 8 | Go to Step 1 | -**Fix delegation**: Spawn code-developer subagent with test output and changed file list. Run synchronously (run_in_background: false). +**Fix delegation**: Use CLI tool to fix failing tests: + +```bash +ccw cli -p "PURPOSE: Fix failing tests; success = all listed tests pass +TASK: • Analyze test failure output • Identify root cause in changed files • Apply minimal fix +MODE: write +CONTEXT: @ | Memory: Test output from current iteration +EXPECTED: Code fixes that make failing tests pass without breaking other tests +CONSTRAINTS: Only modify files in changed list | Minimal changes +Test output: +Changed files: " --tool gemini --mode write --rule development-debug-runtime-issues +``` + +Wait for CLI completion before re-running tests. ## Phase 4: Regression Check + Report diff --git a/.claude/skills/team-lifecycle-v2/role-specs/architect.md b/.claude/skills/team-lifecycle-v2/role-specs/architect.md new file mode 100644 index 00000000..ab06df4c --- /dev/null +++ b/.claude/skills/team-lifecycle-v2/role-specs/architect.md @@ -0,0 +1,76 @@ +--- +role: architect +prefix: ARCH +inner_loop: false +discuss_rounds: [] +subagents: [explore] +message_types: + success: arch_ready + concern: arch_concern + error: error +--- + +# Architect — Phase 2-4 + +## Consultation Modes + +| Task Pattern | Mode | Focus | +|-------------|------|-------| +| ARCH-SPEC-* | spec-review | Review architecture docs | +| ARCH-PLAN-* | plan-review | Review plan soundness | +| ARCH-CODE-* | code-review | Assess code change impact | +| ARCH-CONSULT-* | consult | Answer architecture questions | +| ARCH-FEASIBILITY-* | feasibility | Technical feasibility | + +## Phase 2: Context Loading + +**Common**: session folder, wisdom, project-tech.json, explorations + +**Mode-specific**: + +| Mode | Additional Context | +|------|-------------------| +| spec-review | architecture/_index.md, ADR-*.md | +| plan-review | plan/plan.json | +| code-review | git diff, changed files | +| consult | Question from task description | +| feasibility | Requirements + codebase | + +## Phase 3: Assessment + +Analyze using mode-specific criteria. Output: mode, verdict (APPROVE/CONCERN/BLOCK), dimensions[], concerns[], recommendations[]. + +For complex questions → Gemini CLI with architecture review rule: + +``` +Bash({ + command: `ccw cli -p "..." --tool gemini --mode analysis --rule analysis-review-architecture`, + run_in_background: true +}) +``` + +## Phase 4: Report + +Output to `/architecture/arch-.json`. Contribute decisions to wisdom/decisions.md. + +**Frontend project outputs** (when frontend tech stack detected): +- `/architecture/design-tokens.json` — color, spacing, typography, shadow tokens +- `/architecture/component-specs/*.md` — per-component design spec + +**Report**: mode, verdict, concern count, recommendations, output path(s). + +### Coordinator Integration + +| Timing | Task | +|--------|------| +| After DRAFT-003 | ARCH-SPEC-001: architecture doc review | +| After PLAN-001 | ARCH-PLAN-001: plan architecture review | +| On-demand | ARCH-CONSULT-001: architecture consultation | + +## Error Handling + +| Scenario | Resolution | +|----------|------------| +| Docs not found | Assess from available context | +| CLI timeout | Partial assessment | +| Insufficient context | Request explorer via coordinator | diff --git a/.claude/skills/team-lifecycle-v2/role-specs/executor.md b/.claude/skills/team-lifecycle-v2/role-specs/executor.md new file mode 100644 index 00000000..2bde3195 --- /dev/null +++ b/.claude/skills/team-lifecycle-v2/role-specs/executor.md @@ -0,0 +1,67 @@ +--- +role: executor +prefix: IMPL +inner_loop: true +discuss_rounds: [] +subagents: [] +message_types: + success: impl_complete + progress: impl_progress + error: error +--- + +# Executor — Phase 2-4 + +## Phase 2: Task & Plan Loading + +**Objective**: Load plan and determine execution strategy. + +1. Load plan.json and .task/TASK-*.json from `/plan/` + +**Backend selection** (priority order): + +| Priority | Source | Method | +|----------|--------|--------| +| 1 | Task metadata | task.metadata.executor field | +| 2 | Plan default | "Execution Backend:" in plan | +| 3 | Auto-select | Simple (< 200 chars, no refactor) → agent; Complex → codex | + +**Code review selection**: + +| Priority | Source | Method | +|----------|--------|--------| +| 1 | Task metadata | task.metadata.code_review field | +| 2 | Plan default | "Code Review:" in plan | +| 3 | Auto-select | Critical keywords (auth, security, payment) → enabled | + +## Phase 3: Code Implementation + +**Objective**: Execute implementation across batches. + +**Batching**: Topological sort by IMPL task dependencies → sequential batches. + +| Backend | Invocation | Use Case | +|---------|-----------|----------| +| gemini | `ccw cli --tool gemini --mode write` (foreground) | Simple, direct edits | +| codex | `ccw cli --tool codex --mode write` (foreground) | Complex, architecture | +| qwen | `ccw cli --tool qwen --mode write` (foreground) | Alternative backend | + +## Phase 4: Self-Validation + +| Step | Method | Pass Criteria | +|------|--------|--------------| +| Syntax check | `tsc --noEmit` (30s) | Exit code 0 | +| Acceptance criteria | Match criteria keywords vs implementation | All addressed | +| Test detection | Find .test.ts/.spec.ts for modified files | Tests identified | +| Code review (optional) | gemini analysis or codex review | No blocking issues | + +**Report**: task ID, status, files modified, validation results, backend used. + +## Error Handling + +| Scenario | Resolution | +|----------|------------| +| Syntax errors | Retry with error context (max 3) | +| Missing dependencies | Request from coordinator | +| Backend unavailable | Fallback to alternative tool | +| Circular dependencies | Abort, report graph | diff --git a/.claude/skills/team-lifecycle-v2/role-specs/fe-developer.md b/.claude/skills/team-lifecycle-v2/role-specs/fe-developer.md new file mode 100644 index 00000000..6bc6811d --- /dev/null +++ b/.claude/skills/team-lifecycle-v2/role-specs/fe-developer.md @@ -0,0 +1,79 @@ +--- +role: fe-developer +prefix: DEV-FE +inner_loop: false +discuss_rounds: [] +subagents: [] +message_types: + success: dev_fe_complete + progress: dev_fe_progress + error: error +--- + +# FE Developer — Phase 2-4 + +## Phase 2: Context Loading + +**Inputs to load**: +- Plan: `/plan/plan.json` +- Design tokens: `/architecture/design-tokens.json` (optional) +- Design intelligence: `/analysis/design-intelligence.json` (optional) +- Component specs: `/architecture/component-specs/*.md` (optional) +- Shared memory, wisdom + +**Tech stack detection**: + +| Signal | Framework | Styling | +|--------|-----------|---------| +| react/react-dom in deps | react | - | +| vue in deps | vue | - | +| next in deps | nextjs | - | +| tailwindcss in deps | - | tailwind | +| @shadcn/ui in deps | - | shadcn | + +## Phase 3: Frontend Implementation + +**Step 1**: Generate design token CSS (if tokens available) +- Convert design-tokens.json → CSS custom properties (`:root { --color-*, --space-*, --text-* }`) +- Include dark mode overrides via `@media (prefers-color-scheme: dark)` +- Write to `src/styles/tokens.css` + +**Step 2**: Implement components + +| Task Size | Strategy | +|-----------|----------| +| Simple (<= 3 files, single component) | `ccw cli --tool gemini --mode write` (foreground) | +| Complex (system, multi-component) | `ccw cli --tool codex --mode write` (foreground) | + +**Coding standards** (include in agent/CLI prompt): +- Use design token CSS variables, never hardcode colors/spacing +- Interactive elements: cursor: pointer +- Transitions: 150-300ms +- Text contrast: minimum 4.5:1 +- Include focus-visible styles +- Support prefers-reduced-motion +- Responsive: mobile-first +- No emoji as functional icons + +## Phase 4: Self-Validation + +| Check | What | +|-------|------| +| hardcoded-color | No #hex outside tokens.css | +| cursor-pointer | Interactive elements have cursor: pointer | +| focus-styles | Interactive elements have focus styles | +| responsive | Has responsive breakpoints | +| reduced-motion | Animations respect prefers-reduced-motion | +| emoji-icon | No emoji as functional icons | + +Contribute to wisdom/conventions.md. Update shared-memory.json with component inventory. + +**Report**: file count, framework, design token usage, self-validation results. + +## Error Handling + +| Scenario | Resolution | +|----------|------------| +| Design tokens not found | Use project defaults | +| Tech stack undetected | Default HTML + CSS | +| CLI failure | Retry with alternative tool | diff --git a/.claude/skills/team-lifecycle-v2/role-specs/fe-qa.md b/.claude/skills/team-lifecycle-v2/role-specs/fe-qa.md new file mode 100644 index 00000000..b28d1c8a --- /dev/null +++ b/.claude/skills/team-lifecycle-v2/role-specs/fe-qa.md @@ -0,0 +1,79 @@ +--- +role: fe-qa +prefix: QA-FE +inner_loop: false +discuss_rounds: [] +subagents: [] +message_types: + success: qa_fe_passed + result: qa_fe_result + fix: fix_required + error: error +--- + +# FE QA — Phase 2-4 + +## Review Dimensions + +| Dimension | Weight | Focus | +|-----------|--------|-------| +| Code Quality | 25% | TypeScript types, component structure, error handling | +| Accessibility | 25% | Semantic HTML, ARIA, keyboard nav, contrast, focus-visible | +| Design Compliance | 20% | Token usage, no hardcoded colors, no emoji icons | +| UX Best Practices | 15% | Loading/error/empty states, cursor-pointer, responsive | +| Pre-Delivery | 15% | No console.log, dark mode, i18n readiness | + +## Phase 2: Context Loading + +**Inputs**: design tokens, design intelligence, shared memory, previous QA results (for GC round tracking), changed frontend files via git diff. + +Determine GC round from previous QA results count. Max 2 rounds. + +## Phase 3: 5-Dimension Review + +For each changed frontend file, check against all 5 dimensions. Score each dimension 0-10, deducting for issues found. + +**Scoring deductions**: + +| Severity | Deduction | +|----------|-----------| +| High | -2 to -3 | +| Medium | -1 to -1.5 | +| Low | -0.5 | + +**Overall score** = weighted sum of dimension scores. + +**Verdict routing**: + +| Condition | Verdict | +|-----------|---------| +| Score >= 8 AND no critical issues | PASS | +| GC round >= max AND score >= 6 | PASS_WITH_WARNINGS | +| GC round >= max AND score < 6 | FAIL | +| Otherwise | NEEDS_FIX | + +## Phase 4: Report + +Write audit to `/qa/audit-fe--r.json`. Update wisdom and shared memory. + +**Report**: round, verdict, overall score, dimension scores, critical issues with Do/Don't format, action required (if NEEDS_FIX). + +### Generator-Critic Loop + +Orchestrated by coordinator: +``` +Round 1: DEV-FE-001 → QA-FE-001 + if NEEDS_FIX → coordinator creates DEV-FE-002 + QA-FE-002 +Round 2: DEV-FE-002 → QA-FE-002 + if still NEEDS_FIX → PASS_WITH_WARNINGS or FAIL (max 2) +``` + +**Convergence**: score >= 8 AND critical_count = 0 + +## Error Handling + +| Scenario | Resolution | +|----------|------------| +| No changed files | Report empty, score N/A | +| Design tokens not found | Skip design compliance, adjust weights | +| Max GC rounds exceeded | Force verdict | diff --git a/.claude/skills/team-lifecycle-v2/role-specs/planner.md b/.claude/skills/team-lifecycle-v2/role-specs/planner.md new file mode 100644 index 00000000..0514691e --- /dev/null +++ b/.claude/skills/team-lifecycle-v2/role-specs/planner.md @@ -0,0 +1,98 @@ +--- +role: planner +prefix: PLAN +inner_loop: true +discuss_rounds: [] +subagents: [] +message_types: + success: plan_ready + revision: plan_revision + error: error +--- + +# Planner — Phase 2-4 + +## Phase 1.5: Load Spec Context (Full-Lifecycle) + +If `/spec/` exists → load requirements/_index.md, architecture/_index.md, epics/_index.md, spec-config.json. Otherwise → impl-only mode. + +**Check shared explorations**: Read `/explorations/cache-index.json` to see if analyst already cached useful explorations. Reuse rather than re-explore. + +## Phase 2: Multi-Angle Exploration + +**Objective**: Explore codebase to inform planning. + +**Complexity routing**: + +| Complexity | Criteria | Strategy | +|------------|----------|----------| +| Low | < 200 chars, no refactor/architecture keywords | ACE semantic search only | +| Medium | 200-500 chars or moderate scope | 2-3 angle explore subagent | +| High | > 500 chars, refactor/architecture, multi-module | 3-5 angle explore subagent | + +For each angle, use CLI exploration (cache-aware — check cache-index.json before each call): + +``` +Bash({ + command: `ccw cli -p "PURPOSE: Explore codebase from perspective to inform planning +TASK: • Search for -specific patterns • Identify relevant files • Document integration points +MODE: analysis +CONTEXT: @**/* | Memory: Task keywords: +EXPECTED: JSON with: relevant_files[], patterns[], integration_points[], recommendations[] +CONSTRAINTS: Focus on perspective" --tool gemini --mode analysis --rule analysis-analyze-code-patterns`, + run_in_background: false +}) +``` + +## Phase 3: Plan Generation + +**Objective**: Generate structured implementation plan. + +| Complexity | Strategy | +|------------|----------| +| Low | Direct planning → single TASK-001 with plan.json | +| Medium/High | cli-lite-planning-agent with exploration results | + +**CLI call** (Medium/High): + +``` +Bash({ + command: `ccw cli -p "PURPOSE: Generate structured implementation plan from exploration results +TASK: • Create plan.json with overview • Generate TASK-*.json files (2-7 tasks) • Define dependencies • Set convergence criteria +MODE: write +CONTEXT: @/explorations/*.json | Memory: Complexity: +EXPECTED: Files: plan.json + .task/TASK-*.json. Schema: ~/.ccw/workflows/cli-templates/schemas/plan-overview-base-schema.json +CONSTRAINTS: 2-7 tasks, include id/title/files[].change/convergence.criteria/depends_on" --tool gemini --mode write --rule planning-breakdown-task-steps`, + run_in_background: false +}) +``` + +**Spec context** (full-lifecycle): Reference REQ-* IDs, follow ADR decisions, reuse Epic/Story decomposition. + +## Phase 4: Submit for Approval + +1. Read plan.json and TASK-*.json +2. Report to coordinator: complexity, task count, task list, approach, plan location +3. Wait for response: approved → complete; revision → update and resubmit + +**Session files**: +``` +/explorations/ (shared cache) ++-- cache-index.json ++-- explore-.json + +/plan/ ++-- explorations-manifest.json ++-- plan.json ++-- .task/TASK-*.json +``` + +## Error Handling + +| Scenario | Resolution | +|----------|------------| +| CLI exploration failure | Plan from description only | +| CLI planning failure | Fallback to direct planning | +| Plan rejected 3+ times | Notify coordinator, suggest alternative | +| Schema not found | Use basic structure | +| Cache index corrupt | Clear cache, re-explore all angles | diff --git a/.claude/skills/team-lifecycle-v2/role-specs/tester.md b/.claude/skills/team-lifecycle-v2/role-specs/tester.md new file mode 100644 index 00000000..3b60e434 --- /dev/null +++ b/.claude/skills/team-lifecycle-v2/role-specs/tester.md @@ -0,0 +1,76 @@ +--- +role: tester +prefix: TEST +inner_loop: false +discuss_rounds: [] +subagents: [] +message_types: + success: test_result + fix: fix_required + error: error +--- + +# Tester — Phase 2-4 + +## Phase 2: Framework Detection & Test Discovery + +**Framework detection** (priority order): + +| Priority | Method | Frameworks | +|----------|--------|-----------| +| 1 | package.json devDependencies | vitest, jest, mocha, pytest | +| 2 | package.json scripts.test | vitest, jest, mocha, pytest | +| 3 | Config files | vitest.config.*, jest.config.*, pytest.ini | + +**Affected test discovery** from executor's modified files: +- Search variants: `.test.ts`, `.spec.ts`, `tests/.test.ts`, `__tests__/.test.ts` + +## Phase 3: Test Execution & Fix Cycle + +**Config**: MAX_ITERATIONS=10, PASS_RATE_TARGET=95%, AFFECTED_TESTS_FIRST=true + +1. Run affected tests → parse results +2. Pass rate met → run full suite +3. Failures → select strategy → fix → re-run → repeat + +**Strategy selection**: + +| Condition | Strategy | Behavior | +|-----------|----------|----------| +| Iteration <= 3 or pass >= 80% | Conservative | Fix one critical failure at a time | +| Critical failures < 5 | Surgical | Fix specific pattern everywhere | +| Pass < 50% or iteration > 7 | Aggressive | Fix all failures in batch | + +**Test commands**: + +| Framework | Affected | Full Suite | +|-----------|---------|------------| +| vitest | `vitest run ` | `vitest run` | +| jest | `jest --no-coverage` | `jest --no-coverage` | +| pytest | `pytest -v` | `pytest -v` | + +## Phase 4: Result Analysis + +**Failure classification**: + +| Severity | Patterns | +|----------|----------| +| Critical | SyntaxError, cannot find module, undefined | +| High | Assertion failures, toBe/toEqual | +| Medium | Timeout, async errors | +| Low | Warnings, deprecations | + +**Report routing**: + +| Condition | Type | +|-----------|------| +| Pass rate >= target | test_result (success) | +| Pass rate < target after max iterations | fix_required | + +## Error Handling + +| Scenario | Resolution | +|----------|------------| +| Framework not detected | Prompt user | +| No tests found | Report to coordinator | +| Infinite fix loop | Abort after MAX_ITERATIONS | diff --git a/.claude/skills/team-lifecycle-v2/specs/document-standards.md b/.claude/skills/team-lifecycle-v2/specs/document-standards.md new file mode 100644 index 00000000..2820cd98 --- /dev/null +++ b/.claude/skills/team-lifecycle-v2/specs/document-standards.md @@ -0,0 +1,192 @@ +# Document Standards + +Defines format conventions, YAML frontmatter schema, naming rules, and content structure for all spec-generator outputs. + +## When to Use + +| Phase | Usage | Section | +|-------|-------|---------| +| All Phases | Frontmatter format | YAML Frontmatter Schema | +| All Phases | File naming | Naming Conventions | +| Phase 2-5 | Document structure | Content Structure | +| Phase 6 | Validation reference | All sections | + +--- + +## YAML Frontmatter Schema + +Every generated document MUST begin with YAML frontmatter: + +```yaml +--- +session_id: SPEC-{slug}-{YYYY-MM-DD} +phase: {1-6} +document_type: {product-brief|requirements|architecture|epics|readiness-report|spec-summary} +status: draft|review|complete +generated_at: {ISO8601 timestamp} +stepsCompleted: [] +version: 1 +dependencies: + - {list of input documents used} +--- +``` + +### Field Definitions + +| Field | Type | Required | Description | +|-------|------|----------|-------------| +| `session_id` | string | Yes | Session identifier matching spec-config.json | +| `phase` | number | Yes | Phase number that generated this document (1-6) | +| `document_type` | string | Yes | One of: product-brief, requirements, architecture, epics, readiness-report, spec-summary | +| `status` | enum | Yes | draft (initial), review (user reviewed), complete (finalized) | +| `generated_at` | string | Yes | ISO8601 timestamp of generation | +| `stepsCompleted` | array | Yes | List of step IDs completed during generation | +| `version` | number | Yes | Document version, incremented on re-generation | +| `dependencies` | array | No | List of input files this document depends on | + +### Status Transitions + +``` +draft -> review -> complete + | ^ + +-------------------+ (direct promotion in auto mode) +``` + +- **draft**: Initial generation, not yet user-reviewed +- **review**: User has reviewed and provided feedback +- **complete**: Finalized, ready for downstream consumption + +In auto mode (`-y`), documents are promoted directly from `draft` to `complete`. + +--- + +## Naming Conventions + +### Session ID Format + +``` +SPEC-{slug}-{YYYY-MM-DD} +``` + +- **slug**: Lowercase, alphanumeric + Chinese characters, hyphens as separators, max 40 chars +- **date**: UTC+8 date in YYYY-MM-DD format + +Examples: +- `SPEC-task-management-system-2026-02-11` +- `SPEC-user-auth-oauth-2026-02-11` + +### Output Files + +| File | Phase | Description | +|------|-------|-------------| +| `spec-config.json` | 1 | Session configuration and state | +| `discovery-context.json` | 1 | Codebase exploration results (optional) | +| `product-brief.md` | 2 | Product brief document | +| `requirements.md` | 3 | PRD document | +| `architecture.md` | 4 | Architecture decisions document | +| `epics.md` | 5 | Epic/Story breakdown document | +| `readiness-report.md` | 6 | Quality validation report | +| `spec-summary.md` | 6 | One-page executive summary | + +### Output Directory + +``` +.workflow/.spec/{session-id}/ +``` + +--- + +## Content Structure + +### Heading Hierarchy + +- `#` (H1): Document title only (one per document) +- `##` (H2): Major sections +- `###` (H3): Subsections +- `####` (H4): Detail items (use sparingly) + +Maximum depth: 4 levels. Prefer flat structures. + +### Section Ordering + +Every document follows this general pattern: + +1. **YAML Frontmatter** (mandatory) +2. **Title** (H1) +3. **Executive Summary** (2-3 sentences) +4. **Core Content Sections** (H2, document-specific) +5. **Open Questions / Risks** (if applicable) +6. **References / Traceability** (links to upstream/downstream docs) + +### Formatting Rules + +| Element | Format | Example | +|---------|--------|---------| +| Requirements | `REQ-{NNN}` prefix | REQ-001: User login | +| Acceptance criteria | Checkbox list | `- [ ] User can log in with email` | +| Architecture decisions | `ADR-{NNN}` prefix | ADR-001: Use PostgreSQL | +| Epics | `EPIC-{NNN}` prefix | EPIC-001: Authentication | +| Stories | `STORY-{EPIC}-{NNN}` prefix | STORY-001-001: Login form | +| Priority tags | MoSCoW labels | `[Must]`, `[Should]`, `[Could]`, `[Won't]` | +| Mermaid diagrams | Fenced code blocks | ````mermaid ... ``` `` | +| Code examples | Language-tagged blocks | ````typescript ... ``` `` | + +### Cross-Reference Format + +Use relative references between documents: + +```markdown +See [Product Brief](product-brief.md#section-name) for details. +Derived from [REQ-001](requirements.md#req-001). +``` + +### Language + +- Document body: Follow user's input language (Chinese or English) +- Technical identifiers: Always English (REQ-001, ADR-001, EPIC-001) +- YAML frontmatter keys: Always English + +--- + +## spec-config.json Schema + +```json +{ + "session_id": "string (required)", + "seed_input": "string (required) - original user input", + "input_type": "text|file (required)", + "timestamp": "ISO8601 (required)", + "mode": "interactive|auto (required)", + "complexity": "simple|moderate|complex (required)", + "depth": "light|standard|comprehensive (required)", + "focus_areas": ["string array"], + "seed_analysis": { + "problem_statement": "string", + "target_users": ["string array"], + "domain": "string", + "constraints": ["string array"], + "dimensions": ["string array - 3-5 exploration dimensions"] + }, + "has_codebase": "boolean", + "phasesCompleted": [ + { + "phase": "number (1-6)", + "name": "string (phase name)", + "output_file": "string (primary output file)", + "completed_at": "ISO8601" + } + ] +} +``` + +--- + +## Validation Checklist + +- [ ] Every document starts with valid YAML frontmatter +- [ ] `session_id` matches across all documents in a session +- [ ] `status` field reflects current document state +- [ ] All cross-references resolve to valid targets +- [ ] Heading hierarchy is correct (no skipped levels) +- [ ] Technical identifiers use correct prefixes +- [ ] Output files are in the correct directory diff --git a/.claude/skills/team-lifecycle-v2/specs/quality-gates.md b/.claude/skills/team-lifecycle-v2/specs/quality-gates.md new file mode 100644 index 00000000..ae968436 --- /dev/null +++ b/.claude/skills/team-lifecycle-v2/specs/quality-gates.md @@ -0,0 +1,207 @@ +# Quality Gates + +Per-phase quality gate criteria and scoring dimensions for spec-generator outputs. + +## When to Use + +| Phase | Usage | Section | +|-------|-------|---------| +| Phase 2-5 | Post-generation self-check | Per-Phase Gates | +| Phase 6 | Cross-document validation | Cross-Document Validation | +| Phase 6 | Final scoring | Scoring Dimensions | + +--- + +## Quality Thresholds + +| Gate | Score | Action | +|------|-------|--------| +| **Pass** | >= 80% | Continue to next phase | +| **Review** | 60-79% | Log warnings, continue with caveats | +| **Fail** | < 60% | Must address issues before continuing | + +In auto mode (`-y`), Review-level issues are logged but do not block progress. + +--- + +## Scoring Dimensions + +### 1. Completeness (25%) + +All required sections present with substantive content. + +| Score | Criteria | +|-------|----------| +| 100% | All template sections filled with detailed content | +| 75% | All sections present, some lack detail | +| 50% | Major sections present but minor sections missing | +| 25% | Multiple major sections missing or empty | +| 0% | Document is a skeleton only | + +### 2. Consistency (25%) + +Terminology, formatting, and references are uniform across documents. + +| Score | Criteria | +|-------|----------| +| 100% | All terms consistent, all references valid, formatting uniform | +| 75% | Minor terminology variations, all references valid | +| 50% | Some inconsistent terms, 1-2 broken references | +| 25% | Frequent inconsistencies, multiple broken references | +| 0% | Documents contradict each other | + +### 3. Traceability (25%) + +Requirements, architecture decisions, and stories trace back to goals. + +| Score | Criteria | +|-------|----------| +| 100% | Every story traces to a requirement, every requirement traces to a goal | +| 75% | Most items traceable, few orphans | +| 50% | Partial traceability, some disconnected items | +| 25% | Weak traceability, many orphan items | +| 0% | No traceability between documents | + +### 4. Depth (25%) + +Content provides sufficient detail for execution teams. + +| Score | Criteria | +|-------|----------| +| 100% | Acceptance criteria specific and testable, architecture decisions justified, stories estimable | +| 75% | Most items detailed enough, few vague areas | +| 50% | Mix of detailed and vague content | +| 25% | Mostly high-level, lacking actionable detail | +| 0% | Too abstract for execution | + +--- + +## Per-Phase Quality Gates + +### Phase 1: Discovery + +| Check | Criteria | Severity | +|-------|----------|----------| +| Session ID valid | Matches `SPEC-{slug}-{date}` format | Error | +| Problem statement exists | Non-empty, >= 20 characters | Error | +| Target users identified | >= 1 user group | Error | +| Dimensions generated | 3-5 exploration dimensions | Warning | +| Constraints listed | >= 0 (can be empty with justification) | Info | + +### Phase 2: Product Brief + +| Check | Criteria | Severity | +|-------|----------|----------| +| Vision statement | Clear, 1-3 sentences | Error | +| Problem statement | Specific and measurable | Error | +| Target users | >= 1 persona with needs described | Error | +| Goals defined | >= 2 measurable goals | Error | +| Success metrics | >= 2 quantifiable metrics | Warning | +| Scope boundaries | In-scope and out-of-scope listed | Warning | +| Multi-perspective | >= 2 CLI perspectives synthesized | Info | + +### Phase 3: Requirements (PRD) + +| Check | Criteria | Severity | +|-------|----------|----------| +| Functional requirements | >= 3 with REQ-NNN IDs | Error | +| Acceptance criteria | Every requirement has >= 1 criterion | Error | +| MoSCoW priority | Every requirement tagged | Error | +| Non-functional requirements | >= 1 (performance, security, etc.) | Warning | +| User stories | >= 1 per Must-have requirement | Warning | +| Traceability | Requirements trace to product brief goals | Warning | + +### Phase 4: Architecture + +| Check | Criteria | Severity | +|-------|----------|----------| +| Component diagram | Present (Mermaid or ASCII) | Error | +| Tech stack specified | Languages, frameworks, key libraries | Error | +| ADR present | >= 1 Architecture Decision Record | Error | +| ADR has alternatives | Each ADR lists >= 2 options considered | Warning | +| Integration points | External systems/APIs identified | Warning | +| Data model | Key entities and relationships described | Warning | +| Codebase mapping | Mapped to existing code (if has_codebase) | Info | + +### Phase 5: Epics & Stories + +| Check | Criteria | Severity | +|-------|----------|----------| +| Epics defined | 3-7 epics with EPIC-NNN IDs | Error | +| MVP subset | >= 1 epic tagged as MVP | Error | +| Stories per epic | 2-5 stories per epic | Error | +| Story format | "As a...I want...So that..." pattern | Warning | +| Dependency map | Cross-epic dependencies documented | Warning | +| Estimation hints | Relative sizing (S/M/L/XL) per story | Info | +| Traceability | Stories trace to requirements | Warning | + +### Phase 6: Readiness Check + +| Check | Criteria | Severity | +|-------|----------|----------| +| All documents exist | product-brief, requirements, architecture, epics | Error | +| Frontmatter valid | All YAML frontmatter parseable and correct | Error | +| Cross-references valid | All document links resolve | Error | +| Overall score >= 60% | Weighted average across 4 dimensions | Error | +| No unresolved Errors | All Error-severity issues addressed | Error | +| Summary generated | spec-summary.md created | Warning | + +--- + +## Cross-Document Validation + +Checks performed during Phase 6 across all documents: + +### Completeness Matrix + +``` +Product Brief goals -> Requirements (each goal has >= 1 requirement) +Requirements -> Architecture (each Must requirement has design coverage) +Requirements -> Epics (each Must requirement appears in >= 1 story) +Architecture ADRs -> Epics (tech choices reflected in implementation stories) +``` + +### Consistency Checks + +| Check | Documents | Rule | +|-------|-----------|------| +| Terminology | All | Same term used consistently (no synonyms for same concept) | +| User personas | Brief + PRD + Epics | Same user names/roles throughout | +| Scope | Brief + PRD | PRD scope does not exceed brief scope | +| Tech stack | Architecture + Epics | Stories reference correct technologies | + +### Traceability Matrix Format + +```markdown +| Goal | Requirements | Architecture | Epics | +|------|-------------|--------------|-------| +| G-001: ... | REQ-001, REQ-002 | ADR-001 | EPIC-001 | +| G-002: ... | REQ-003 | ADR-002 | EPIC-002, EPIC-003 | +``` + +--- + +## Issue Classification + +### Error (Must Fix) + +- Missing required document or section +- Broken cross-references +- Contradictory information between documents +- Empty acceptance criteria on Must-have requirements +- No MVP subset defined in epics + +### Warning (Should Fix) + +- Vague acceptance criteria +- Missing non-functional requirements +- No success metrics defined +- Incomplete traceability +- Missing architecture review notes + +### Info (Nice to Have) + +- Could add more detailed personas +- Consider additional ADR alternatives +- Story estimation hints missing +- Mermaid diagrams could be more detailed diff --git a/.claude/skills/team-lifecycle-v2/templates/architecture-doc.md b/.claude/skills/team-lifecycle-v2/templates/architecture-doc.md new file mode 100644 index 00000000..5106de03 --- /dev/null +++ b/.claude/skills/team-lifecycle-v2/templates/architecture-doc.md @@ -0,0 +1,254 @@ +# Architecture Document Template (Directory Structure) + +Template for generating architecture decision documents as a directory of individual ADR files in Phase 4. + +## Usage Context + +| Phase | Usage | +|-------|-------| +| Phase 4 (Architecture) | Generate `architecture/` directory from requirements analysis | +| Output Location | `{workDir}/architecture/` | + +## Output Structure + +``` +{workDir}/architecture/ +├── _index.md # Overview, components, tech stack, data model, security +├── ADR-001-{slug}.md # Individual Architecture Decision Record +├── ADR-002-{slug}.md +└── ... +``` + +--- + +## Template: _index.md + +```markdown +--- +session_id: {session_id} +phase: 4 +document_type: architecture-index +status: draft +generated_at: {timestamp} +version: 1 +dependencies: + - ../spec-config.json + - ../product-brief.md + - ../requirements/_index.md +--- + +# Architecture: {product_name} + +{executive_summary - high-level architecture approach and key decisions} + +## System Overview + +### Architecture Style +{description of chosen architecture style: microservices, monolith, serverless, etc.} + +### System Context Diagram + +```mermaid +C4Context + title System Context Diagram + Person(user, "User", "Primary user") + System(system, "{product_name}", "Core system") + System_Ext(ext1, "{external_system}", "{description}") + Rel(user, system, "Uses") + Rel(system, ext1, "Integrates with") +``` + +## Component Architecture + +### Component Diagram + +```mermaid +graph TD + subgraph "{product_name}" + A[Component A] --> B[Component B] + B --> C[Component C] + A --> D[Component D] + end + B --> E[External Service] +``` + +### Component Descriptions + +| Component | Responsibility | Technology | Dependencies | +|-----------|---------------|------------|--------------| +| {component_name} | {what it does} | {tech stack} | {depends on} | + +## Technology Stack + +### Core Technologies + +| Layer | Technology | Version | Rationale | +|-------|-----------|---------|-----------| +| Frontend | {technology} | {version} | {why chosen} | +| Backend | {technology} | {version} | {why chosen} | +| Database | {technology} | {version} | {why chosen} | +| Infrastructure | {technology} | {version} | {why chosen} | + +### Key Libraries & Frameworks + +| Library | Purpose | License | +|---------|---------|---------| +| {library_name} | {purpose} | {license} | + +## Architecture Decision Records + +| ADR | Title | Status | Key Choice | +|-----|-------|--------|------------| +| [ADR-001](ADR-001-{slug}.md) | {title} | Accepted | {one-line summary} | +| [ADR-002](ADR-002-{slug}.md) | {title} | Accepted | {one-line summary} | +| [ADR-003](ADR-003-{slug}.md) | {title} | Proposed | {one-line summary} | + +## Data Architecture + +### Data Model + +```mermaid +erDiagram + ENTITY_A ||--o{ ENTITY_B : "has many" + ENTITY_A { + string id PK + string name + datetime created_at + } + ENTITY_B { + string id PK + string entity_a_id FK + string value + } +``` + +### Data Storage Strategy + +| Data Type | Storage | Retention | Backup | +|-----------|---------|-----------|--------| +| {type} | {storage solution} | {retention policy} | {backup strategy} | + +## API Design + +### API Overview + +| Endpoint | Method | Purpose | Auth | +|----------|--------|---------|------| +| {/api/resource} | {GET/POST/etc} | {purpose} | {auth type} | + +## Security Architecture + +### Security Controls + +| Control | Implementation | Requirement | +|---------|---------------|-------------| +| Authentication | {approach} | [NFR-S-{NNN}](../requirements/NFR-S-{NNN}-{slug}.md) | +| Authorization | {approach} | [NFR-S-{NNN}](../requirements/NFR-S-{NNN}-{slug}.md) | +| Data Protection | {approach} | [NFR-S-{NNN}](../requirements/NFR-S-{NNN}-{slug}.md) | + +## Infrastructure & Deployment + +### Deployment Architecture + +{description of deployment model: containers, serverless, VMs, etc.} + +### Environment Strategy + +| Environment | Purpose | Configuration | +|-------------|---------|---------------| +| Development | Local development | {config} | +| Staging | Pre-production testing | {config} | +| Production | Live system | {config} | + +## Codebase Integration + +{if has_codebase is true:} + +### Existing Code Mapping + +| New Component | Existing Module | Integration Type | Notes | +|--------------|----------------|------------------|-------| +| {component} | {existing module path} | Extend/Replace/New | {notes} | + +### Migration Notes +{any migration considerations for existing code} + +## Quality Attributes + +| Attribute | Target | Measurement | ADR Reference | +|-----------|--------|-------------|---------------| +| Performance | {target} | {how measured} | [ADR-{NNN}](ADR-{NNN}-{slug}.md) | +| Scalability | {target} | {how measured} | [ADR-{NNN}](ADR-{NNN}-{slug}.md) | +| Reliability | {target} | {how measured} | [ADR-{NNN}](ADR-{NNN}-{slug}.md) | + +## Risks & Mitigations + +| Risk | Impact | Probability | Mitigation | +|------|--------|-------------|------------| +| {risk} | High/Medium/Low | High/Medium/Low | {mitigation approach} | + +## Open Questions + +- [ ] {architectural question 1} +- [ ] {architectural question 2} + +## References + +- Derived from: [Requirements](../requirements/_index.md), [Product Brief](../product-brief.md) +- Next: [Epics & Stories](../epics/_index.md) +``` + +--- + +## Template: ADR-NNN-{slug}.md (Individual Architecture Decision Record) + +```markdown +--- +id: ADR-{NNN} +status: Accepted +traces_to: [{REQ-NNN}, {NFR-X-NNN}] +date: {timestamp} +--- + +# ADR-{NNN}: {decision_title} + +## Context + +{what is the situation that motivates this decision} + +## Decision + +{what is the chosen approach} + +## Alternatives Considered + +| Option | Pros | Cons | +|--------|------|------| +| {option_1 - chosen} | {pros} | {cons} | +| {option_2} | {pros} | {cons} | +| {option_3} | {pros} | {cons} | + +## Consequences + +- **Positive**: {positive outcomes} +- **Negative**: {tradeoffs accepted} +- **Risks**: {risks to monitor} + +## Traces + +- **Requirements**: [REQ-{NNN}](../requirements/REQ-{NNN}-{slug}.md), [NFR-X-{NNN}](../requirements/NFR-X-{NNN}-{slug}.md) +- **Implemented by**: [EPIC-{NNN}](../epics/EPIC-{NNN}-{slug}.md) (added in Phase 5) +``` + +--- + +## Variable Descriptions + +| Variable | Source | Description | +|----------|--------|-------------| +| `{session_id}` | spec-config.json | Session identifier | +| `{timestamp}` | Runtime | ISO8601 generation timestamp | +| `{product_name}` | product-brief.md | Product/feature name | +| `{NNN}` | Auto-increment | ADR/requirement number | +| `{slug}` | Auto-generated | Kebab-case from decision title | +| `{has_codebase}` | spec-config.json | Whether existing codebase exists | diff --git a/.claude/skills/team-lifecycle-v2/templates/epics-template.md b/.claude/skills/team-lifecycle-v2/templates/epics-template.md new file mode 100644 index 00000000..939d933c --- /dev/null +++ b/.claude/skills/team-lifecycle-v2/templates/epics-template.md @@ -0,0 +1,196 @@ +# Epics & Stories Template (Directory Structure) + +Template for generating epic/story breakdown as a directory of individual Epic files in Phase 5. + +## Usage Context + +| Phase | Usage | +|-------|-------| +| Phase 5 (Epics & Stories) | Generate `epics/` directory from requirements decomposition | +| Output Location | `{workDir}/epics/` | + +## Output Structure + +``` +{workDir}/epics/ +├── _index.md # Overview table + dependency map + MVP scope + execution order +├── EPIC-001-{slug}.md # Individual Epic with its Stories +├── EPIC-002-{slug}.md +└── ... +``` + +--- + +## Template: _index.md + +```markdown +--- +session_id: {session_id} +phase: 5 +document_type: epics-index +status: draft +generated_at: {timestamp} +version: 1 +dependencies: + - ../spec-config.json + - ../product-brief.md + - ../requirements/_index.md + - ../architecture/_index.md +--- + +# Epics & Stories: {product_name} + +{executive_summary - overview of epic structure and MVP scope} + +## Epic Overview + +| Epic ID | Title | Priority | MVP | Stories | Est. Size | +|---------|-------|----------|-----|---------|-----------| +| [EPIC-001](EPIC-001-{slug}.md) | {title} | Must | Yes | {n} | {S/M/L/XL} | +| [EPIC-002](EPIC-002-{slug}.md) | {title} | Must | Yes | {n} | {S/M/L/XL} | +| [EPIC-003](EPIC-003-{slug}.md) | {title} | Should | No | {n} | {S/M/L/XL} | + +## Dependency Map + +```mermaid +graph LR + EPIC-001 --> EPIC-002 + EPIC-001 --> EPIC-003 + EPIC-002 --> EPIC-004 + EPIC-003 --> EPIC-005 +``` + +### Dependency Notes +{explanation of why these dependencies exist and suggested execution order} + +### Recommended Execution Order +1. [EPIC-{NNN}](EPIC-{NNN}-{slug}.md): {reason - foundational} +2. [EPIC-{NNN}](EPIC-{NNN}-{slug}.md): {reason - depends on #1} +3. ... + +## MVP Scope + +### MVP Epics +{list of epics included in MVP with justification, linking to each} + +### MVP Definition of Done +- [ ] {MVP completion criterion 1} +- [ ] {MVP completion criterion 2} +- [ ] {MVP completion criterion 3} + +## Traceability Matrix + +| Requirement | Epic | Stories | Architecture | +|-------------|------|---------|--------------| +| [REQ-001](../requirements/REQ-001-{slug}.md) | [EPIC-001](EPIC-001-{slug}.md) | STORY-001-001, STORY-001-002 | [ADR-001](../architecture/ADR-001-{slug}.md) | +| [REQ-002](../requirements/REQ-002-{slug}.md) | [EPIC-001](EPIC-001-{slug}.md) | STORY-001-003 | Component B | +| [REQ-003](../requirements/REQ-003-{slug}.md) | [EPIC-002](EPIC-002-{slug}.md) | STORY-002-001 | [ADR-002](../architecture/ADR-002-{slug}.md) | + +## Estimation Summary + +| Size | Meaning | Count | +|------|---------|-------| +| S | Small - well-understood, minimal risk | {n} | +| M | Medium - some complexity, moderate risk | {n} | +| L | Large - significant complexity, should consider splitting | {n} | +| XL | Extra Large - high complexity, must split before implementation | {n} | + +## Risks & Considerations + +| Risk | Affected Epics | Mitigation | +|------|---------------|------------| +| {risk description} | [EPIC-{NNN}](EPIC-{NNN}-{slug}.md) | {mitigation} | + +## Open Questions + +- [ ] {question about scope or implementation 1} +- [ ] {question about scope or implementation 2} + +## References + +- Derived from: [Requirements](../requirements/_index.md), [Architecture](../architecture/_index.md) +- Handoff to: execution workflows (lite-plan, plan, req-plan) +``` + +--- + +## Template: EPIC-NNN-{slug}.md (Individual Epic) + +```markdown +--- +id: EPIC-{NNN} +priority: {Must|Should|Could} +mvp: {true|false} +size: {S|M|L|XL} +requirements: [REQ-{NNN}] +architecture: [ADR-{NNN}] +dependencies: [EPIC-{NNN}] +status: draft +--- + +# EPIC-{NNN}: {epic_title} + +**Priority**: {Must|Should|Could} +**MVP**: {Yes|No} +**Estimated Size**: {S|M|L|XL} + +## Description + +{detailed epic description} + +## Requirements + +- [REQ-{NNN}](../requirements/REQ-{NNN}-{slug}.md): {title} +- [REQ-{NNN}](../requirements/REQ-{NNN}-{slug}.md): {title} + +## Architecture + +- [ADR-{NNN}](../architecture/ADR-{NNN}-{slug}.md): {title} +- Component: {component_name} + +## Dependencies + +- [EPIC-{NNN}](EPIC-{NNN}-{slug}.md) (blocking): {reason} +- [EPIC-{NNN}](EPIC-{NNN}-{slug}.md) (soft): {reason} + +## Stories + +### STORY-{EPIC}-001: {story_title} + +**User Story**: As a {persona}, I want to {action} so that {benefit}. + +**Acceptance Criteria**: +- [ ] {criterion 1} +- [ ] {criterion 2} +- [ ] {criterion 3} + +**Size**: {S|M|L|XL} +**Traces to**: [REQ-{NNN}](../requirements/REQ-{NNN}-{slug}.md) + +--- + +### STORY-{EPIC}-002: {story_title} + +**User Story**: As a {persona}, I want to {action} so that {benefit}. + +**Acceptance Criteria**: +- [ ] {criterion 1} +- [ ] {criterion 2} + +**Size**: {S|M|L|XL} +**Traces to**: [REQ-{NNN}](../requirements/REQ-{NNN}-{slug}.md) +``` + +--- + +## Variable Descriptions + +| Variable | Source | Description | +|----------|--------|-------------| +| `{session_id}` | spec-config.json | Session identifier | +| `{timestamp}` | Runtime | ISO8601 generation timestamp | +| `{product_name}` | product-brief.md | Product/feature name | +| `{EPIC}` | Auto-increment | Epic number (3 digits) | +| `{NNN}` | Auto-increment | Story/requirement number | +| `{slug}` | Auto-generated | Kebab-case from epic/story title | +| `{S\|M\|L\|XL}` | CLI analysis | Relative size estimate | diff --git a/.claude/skills/team-lifecycle-v2/templates/product-brief.md b/.claude/skills/team-lifecycle-v2/templates/product-brief.md new file mode 100644 index 00000000..ffbdf437 --- /dev/null +++ b/.claude/skills/team-lifecycle-v2/templates/product-brief.md @@ -0,0 +1,133 @@ +# Product Brief Template + +Template for generating product brief documents in Phase 2. + +## Usage Context + +| Phase | Usage | +|-------|-------| +| Phase 2 (Product Brief) | Generate product-brief.md from multi-CLI analysis | +| Output Location | `{workDir}/product-brief.md` | + +--- + +## Template + +```markdown +--- +session_id: {session_id} +phase: 2 +document_type: product-brief +status: draft +generated_at: {timestamp} +stepsCompleted: [] +version: 1 +dependencies: + - spec-config.json +--- + +# Product Brief: {product_name} + +{executive_summary - 2-3 sentences capturing the essence of the product/feature} + +## Vision + +{vision_statement - clear, aspirational 1-3 sentence statement of what success looks like} + +## Problem Statement + +### Current Situation +{description of the current state and pain points} + +### Impact +{quantified impact of the problem - who is affected, how much, how often} + +## Target Users + +{for each user persona:} + +### {Persona Name} +- **Role**: {user's role/context} +- **Needs**: {primary needs related to this product} +- **Pain Points**: {current frustrations} +- **Success Criteria**: {what success looks like for this user} + +## Goals & Success Metrics + +| Goal ID | Goal | Success Metric | Target | +|---------|------|----------------|--------| +| G-001 | {goal description} | {measurable metric} | {specific target} | +| G-002 | {goal description} | {measurable metric} | {specific target} | + +## Scope + +### In Scope +- {feature/capability 1} +- {feature/capability 2} +- {feature/capability 3} + +### Out of Scope +- {explicitly excluded item 1} +- {explicitly excluded item 2} + +### Assumptions +- {key assumption 1} +- {key assumption 2} + +## Competitive Landscape + +| Aspect | Current State | Proposed Solution | Advantage | +|--------|--------------|-------------------|-----------| +| {aspect} | {how it's done now} | {our approach} | {differentiator} | + +## Constraints & Dependencies + +### Technical Constraints +- {constraint 1} +- {constraint 2} + +### Business Constraints +- {constraint 1} + +### Dependencies +- {external dependency 1} +- {external dependency 2} + +## Multi-Perspective Synthesis + +### Product Perspective +{summary of product/market analysis findings} + +### Technical Perspective +{summary of technical feasibility and constraints} + +### User Perspective +{summary of user journey and UX considerations} + +### Convergent Themes +{themes where all perspectives agree} + +### Conflicting Views +{areas where perspectives differ, with notes on resolution approach} + +## Open Questions + +- [ ] {unresolved question 1} +- [ ] {unresolved question 2} + +## References + +- Derived from: [spec-config.json](spec-config.json) +- Next: [Requirements PRD](requirements.md) +``` + +## Variable Descriptions + +| Variable | Source | Description | +|----------|--------|-------------| +| `{session_id}` | spec-config.json | Session identifier | +| `{timestamp}` | Runtime | ISO8601 generation timestamp | +| `{product_name}` | Seed analysis | Product/feature name | +| `{executive_summary}` | CLI synthesis | 2-3 sentence summary | +| `{vision_statement}` | CLI product perspective | Aspirational vision | +| All `{...}` fields | CLI analysis outputs | Filled from multi-perspective analysis | diff --git a/.claude/skills/team-lifecycle-v2/templates/requirements-prd.md b/.claude/skills/team-lifecycle-v2/templates/requirements-prd.md new file mode 100644 index 00000000..0b1dbf28 --- /dev/null +++ b/.claude/skills/team-lifecycle-v2/templates/requirements-prd.md @@ -0,0 +1,224 @@ +# Requirements PRD Template (Directory Structure) + +Template for generating Product Requirements Document as a directory of individual requirement files in Phase 3. + +## Usage Context + +| Phase | Usage | +|-------|-------| +| Phase 3 (Requirements) | Generate `requirements/` directory from product brief expansion | +| Output Location | `{workDir}/requirements/` | + +## Output Structure + +``` +{workDir}/requirements/ +├── _index.md # Summary + MoSCoW table + traceability matrix + links +├── REQ-001-{slug}.md # Individual functional requirement +├── REQ-002-{slug}.md +├── NFR-P-001-{slug}.md # Non-functional: Performance +├── NFR-S-001-{slug}.md # Non-functional: Security +├── NFR-SC-001-{slug}.md # Non-functional: Scalability +├── NFR-U-001-{slug}.md # Non-functional: Usability +└── ... +``` + +--- + +## Template: _index.md + +```markdown +--- +session_id: {session_id} +phase: 3 +document_type: requirements-index +status: draft +generated_at: {timestamp} +version: 1 +dependencies: + - ../spec-config.json + - ../product-brief.md +--- + +# Requirements: {product_name} + +{executive_summary - brief overview of what this PRD covers and key decisions} + +## Requirement Summary + +| Priority | Count | Coverage | +|----------|-------|----------| +| Must Have | {n} | {description of must-have scope} | +| Should Have | {n} | {description of should-have scope} | +| Could Have | {n} | {description of could-have scope} | +| Won't Have | {n} | {description of explicitly excluded} | + +## Functional Requirements + +| ID | Title | Priority | Traces To | +|----|-------|----------|-----------| +| [REQ-001](REQ-001-{slug}.md) | {title} | Must | [G-001](../product-brief.md#goals--success-metrics) | +| [REQ-002](REQ-002-{slug}.md) | {title} | Must | [G-001](../product-brief.md#goals--success-metrics) | +| [REQ-003](REQ-003-{slug}.md) | {title} | Should | [G-002](../product-brief.md#goals--success-metrics) | + +## Non-Functional Requirements + +### Performance + +| ID | Title | Target | +|----|-------|--------| +| [NFR-P-001](NFR-P-001-{slug}.md) | {title} | {target value} | + +### Security + +| ID | Title | Standard | +|----|-------|----------| +| [NFR-S-001](NFR-S-001-{slug}.md) | {title} | {standard/framework} | + +### Scalability + +| ID | Title | Target | +|----|-------|--------| +| [NFR-SC-001](NFR-SC-001-{slug}.md) | {title} | {target value} | + +### Usability + +| ID | Title | Target | +|----|-------|--------| +| [NFR-U-001](NFR-U-001-{slug}.md) | {title} | {target value} | + +## Data Requirements + +### Data Entities + +| Entity | Description | Key Attributes | +|--------|-------------|----------------| +| {entity_name} | {description} | {attr1, attr2, attr3} | + +### Data Flows + +{description of key data flows, optionally with Mermaid diagram} + +## Integration Requirements + +| System | Direction | Protocol | Data Format | Notes | +|--------|-----------|----------|-------------|-------| +| {system_name} | Inbound/Outbound/Both | {REST/gRPC/etc} | {JSON/XML/etc} | {notes} | + +## Constraints & Assumptions + +### Constraints +- {technical or business constraint 1} +- {technical or business constraint 2} + +### Assumptions +- {assumption 1 - must be validated} +- {assumption 2 - must be validated} + +## Priority Rationale + +{explanation of MoSCoW prioritization decisions, especially for Should/Could boundaries} + +## Traceability Matrix + +| Goal | Requirements | +|------|-------------| +| G-001 | [REQ-001](REQ-001-{slug}.md), [REQ-002](REQ-002-{slug}.md), [NFR-P-001](NFR-P-001-{slug}.md) | +| G-002 | [REQ-003](REQ-003-{slug}.md), [NFR-S-001](NFR-S-001-{slug}.md) | + +## Open Questions + +- [ ] {unresolved question 1} +- [ ] {unresolved question 2} + +## References + +- Derived from: [Product Brief](../product-brief.md) +- Next: [Architecture](../architecture/_index.md) +``` + +--- + +## Template: REQ-NNN-{slug}.md (Individual Functional Requirement) + +```markdown +--- +id: REQ-{NNN} +type: functional +priority: {Must|Should|Could|Won't} +traces_to: [G-{NNN}] +status: draft +--- + +# REQ-{NNN}: {requirement_title} + +**Priority**: {Must|Should|Could|Won't} + +## Description + +{detailed requirement description} + +## User Story + +As a {persona}, I want to {action} so that {benefit}. + +## Acceptance Criteria + +- [ ] {specific, testable criterion 1} +- [ ] {specific, testable criterion 2} +- [ ] {specific, testable criterion 3} + +## Traces + +- **Goal**: [G-{NNN}](../product-brief.md#goals--success-metrics) +- **Architecture**: [ADR-{NNN}](../architecture/ADR-{NNN}-{slug}.md) (if applicable) +- **Implemented by**: [EPIC-{NNN}](../epics/EPIC-{NNN}-{slug}.md) (added in Phase 5) +``` + +--- + +## Template: NFR-{type}-NNN-{slug}.md (Individual Non-Functional Requirement) + +```markdown +--- +id: NFR-{type}-{NNN} +type: non-functional +category: {Performance|Security|Scalability|Usability} +priority: {Must|Should|Could} +status: draft +--- + +# NFR-{type}-{NNN}: {requirement_title} + +**Category**: {Performance|Security|Scalability|Usability} +**Priority**: {Must|Should|Could} + +## Requirement + +{detailed requirement description} + +## Metric & Target + +| Metric | Target | Measurement Method | +|--------|--------|--------------------| +| {metric} | {target value} | {how measured} | + +## Traces + +- **Goal**: [G-{NNN}](../product-brief.md#goals--success-metrics) +- **Architecture**: [ADR-{NNN}](../architecture/ADR-{NNN}-{slug}.md) (if applicable) +``` + +--- + +## Variable Descriptions + +| Variable | Source | Description | +|----------|--------|-------------| +| `{session_id}` | spec-config.json | Session identifier | +| `{timestamp}` | Runtime | ISO8601 generation timestamp | +| `{product_name}` | product-brief.md | Product/feature name | +| `{NNN}` | Auto-increment | Requirement number (zero-padded 3 digits) | +| `{slug}` | Auto-generated | Kebab-case from requirement title | +| `{type}` | Category | P (Performance), S (Security), SC (Scalability), U (Usability) | +| `{Must\|Should\|Could\|Won't}` | User input / auto | MoSCoW priority tag | diff --git a/.claude/skills/team-lifecycle/SKILL.md b/.claude/skills/team-lifecycle/SKILL.md index 8b35d38c..62248c5e 100644 --- a/.claude/skills/team-lifecycle/SKILL.md +++ b/.claude/skills/team-lifecycle/SKILL.md @@ -34,10 +34,10 @@ Unified team skill: specification -> implementation -> testing -> review. Built | fe-qa | +--------+ - Subagents (callable by any worker, not team members): - [discuss-subagent] - multi-perspective critique - [explore-subagent] - codebase exploration with cache - [doc-generation] - document generation (CLI execution) + Utility Functions (callable by workers): + [multi-perspective discussion] - CLI tools for critique + [codebase exploration] - Explore agent with cache + [document generation] - CLI execution ``` ## Role Router @@ -63,13 +63,13 @@ Parse `$ARGUMENTS`. No `--role` needed — always routes to coordinator. | fe-developer | [role-specs/fe-developer.md](role-specs/fe-developer.md) | DEV-FE-* | frontend | false | | fe-qa | [role-specs/fe-qa.md](role-specs/fe-qa.md) | QA-FE-* | frontend | false | -### Subagent Registry +### Utility Functions -| Subagent | Spec | Callable By | Purpose | -|----------|------|-------------|---------| -| discuss | [subagents/discuss-subagent.md](subagents/discuss-subagent.md) | analyst, writer, reviewer | Multi-perspective critique | -| explore | [subagents/explore-subagent.md](subagents/explore-subagent.md) | analyst, planner, any role | Codebase exploration with cache | -| doc-generation | [subagents/doc-generation-subagent.md](subagents/doc-generation-subagent.md) | writer | Document generation (CLI execution) | +| Function | Implementation | Callable By | Purpose | +|----------|----------------|-------------|---------| +| Multi-perspective discussion | CLI tools (ccw cli --mode analysis) | analyst, writer, reviewer | Multi-perspective critique | +| Codebase exploration | Explore agent | analyst, planner, any role | Codebase exploration with cache | +| Document generation | CLI tools (ccw cli --mode write) | writer | Document generation | ### Dispatch @@ -306,9 +306,6 @@ Coordinator supports `--resume` / `--continue` for interrupted sessions: | Requirements Template | [templates/requirements-prd.md](templates/requirements-prd.md) | DRAFT-002 | | Architecture Template | [templates/architecture-doc.md](templates/architecture-doc.md) | DRAFT-003 | | Epics Template | [templates/epics-template.md](templates/epics-template.md) | DRAFT-004 | -| Discuss Subagent | [subagents/discuss-subagent.md](subagents/discuss-subagent.md) | Inline discuss protocol | -| Explore Subagent | [subagents/explore-subagent.md](subagents/explore-subagent.md) | Shared exploration utility | -| Doc-Gen Subagent | [subagents/doc-generation-subagent.md](subagents/doc-generation-subagent.md) | Document generation engine | ## Error Handling @@ -317,6 +314,6 @@ Coordinator supports `--resume` / `--continue` for interrupted sessions: | Unknown command | Error with available command list | | Role spec file not found | Error with expected path | | Command file not found | Fallback to inline execution | -| Discuss subagent fails | Worker proceeds without discuss, logs warning | +| Multi-perspective discussion fails | Worker proceeds without discuss, logs warning | | Explore cache corrupt | Clear cache, re-explore | | Fast-advance spawns wrong task | Coordinator reconciles on next callback | diff --git a/.claude/skills/team-lifecycle/role-specs/analyst.md b/.claude/skills/team-lifecycle/role-specs/analyst.md index 95f2e710..3ca73d08 100644 --- a/.claude/skills/team-lifecycle/role-specs/analyst.md +++ b/.claude/skills/team-lifecycle/role-specs/analyst.md @@ -3,7 +3,7 @@ role: analyst prefix: RESEARCH inner_loop: false discuss_rounds: [DISCUSS-001] -subagents: [discuss] +cli_tools: [discuss] message_types: success: research_ready progress: research_progress @@ -76,7 +76,7 @@ Parse CLI output to build codebase context: tech_stack, architecture_patterns, c ### 4b: Inline Discuss (DISCUSS-001) -Call discuss subagent with: +Invoke multi-perspective discussion using CLI tools: - Artifact: `/spec/discovery-context.json` - Round: DISCUSS-001 - Perspectives: product, risk, coverage @@ -93,4 +93,4 @@ Handle discuss verdict per team-worker consensus handling protocol. | Codebase detection failed | Continue as new project | | Topic too vague | Report with clarification questions | | CLI exploration fails | Continue without codebase context | -| Discuss subagent fails | Proceed without discuss, log warning | +| Multi-perspective discussion fails | Proceed without discuss, log warning | diff --git a/.claude/skills/team-lifecycle/role-specs/architect.md b/.claude/skills/team-lifecycle/role-specs/architect.md index ab06df4c..83949645 100644 --- a/.claude/skills/team-lifecycle/role-specs/architect.md +++ b/.claude/skills/team-lifecycle/role-specs/architect.md @@ -3,7 +3,7 @@ role: architect prefix: ARCH inner_loop: false discuss_rounds: [] -subagents: [explore] +cli_tools: [explore] message_types: success: arch_ready concern: arch_concern diff --git a/.claude/skills/team-lifecycle/role-specs/executor.md b/.claude/skills/team-lifecycle/role-specs/executor.md index 2bde3195..57e5c2ca 100644 --- a/.claude/skills/team-lifecycle/role-specs/executor.md +++ b/.claude/skills/team-lifecycle/role-specs/executor.md @@ -3,7 +3,7 @@ role: executor prefix: IMPL inner_loop: true discuss_rounds: [] -subagents: [] +cli_tools: [] message_types: success: impl_complete progress: impl_progress diff --git a/.claude/skills/team-lifecycle/role-specs/fe-developer.md b/.claude/skills/team-lifecycle/role-specs/fe-developer.md index 6bc6811d..e90ed42c 100644 --- a/.claude/skills/team-lifecycle/role-specs/fe-developer.md +++ b/.claude/skills/team-lifecycle/role-specs/fe-developer.md @@ -3,7 +3,7 @@ role: fe-developer prefix: DEV-FE inner_loop: false discuss_rounds: [] -subagents: [] +cli_tools: [] message_types: success: dev_fe_complete progress: dev_fe_progress diff --git a/.claude/skills/team-lifecycle/role-specs/fe-qa.md b/.claude/skills/team-lifecycle/role-specs/fe-qa.md index b28d1c8a..f4deda1f 100644 --- a/.claude/skills/team-lifecycle/role-specs/fe-qa.md +++ b/.claude/skills/team-lifecycle/role-specs/fe-qa.md @@ -3,7 +3,7 @@ role: fe-qa prefix: QA-FE inner_loop: false discuss_rounds: [] -subagents: [] +cli_tools: [] message_types: success: qa_fe_passed result: qa_fe_result diff --git a/.claude/skills/team-lifecycle/role-specs/planner.md b/.claude/skills/team-lifecycle/role-specs/planner.md index 0514691e..3012c863 100644 --- a/.claude/skills/team-lifecycle/role-specs/planner.md +++ b/.claude/skills/team-lifecycle/role-specs/planner.md @@ -3,7 +3,7 @@ role: planner prefix: PLAN inner_loop: true discuss_rounds: [] -subagents: [] +cli_tools: [explore] message_types: success: plan_ready revision: plan_revision @@ -27,8 +27,8 @@ If `/spec/` exists → load requirements/_index.md, architecture | Complexity | Criteria | Strategy | |------------|----------|----------| | Low | < 200 chars, no refactor/architecture keywords | ACE semantic search only | -| Medium | 200-500 chars or moderate scope | 2-3 angle explore subagent | -| High | > 500 chars, refactor/architecture, multi-module | 3-5 angle explore subagent | +| Medium | 200-500 chars or moderate scope | 2-3 angle CLI explore | +| High | > 500 chars, refactor/architecture, multi-module | 3-5 angle CLI explore | For each angle, use CLI exploration (cache-aware — check cache-index.json before each call): diff --git a/.claude/skills/team-lifecycle/role-specs/reviewer.md b/.claude/skills/team-lifecycle/role-specs/reviewer.md index 82090783..498e4a60 100644 --- a/.claude/skills/team-lifecycle/role-specs/reviewer.md +++ b/.claude/skills/team-lifecycle/role-specs/reviewer.md @@ -4,7 +4,7 @@ prefix: REVIEW additional_prefixes: [QUALITY, IMPROVE] inner_loop: false discuss_rounds: [DISCUSS-006] -subagents: [discuss] +cli_tools: [discuss] message_types: success_review: review_result success_quality: quality_result @@ -73,11 +73,19 @@ message_types: ### Spec Quality Inline Discuss (DISCUSS-006) -After generating readiness-report.md, call discuss subagent: +After generating readiness-report.md, call CLI discuss tool: - Artifact: `/spec/readiness-report.md` - Round: DISCUSS-006 - Perspectives: product, technical, quality, risk, coverage (all 5) +```bash +ccw cli -p "PURPOSE: Multi-perspective critique of spec readiness +TASK: Review from product, technical, quality, risk, coverage perspectives +ARTIFACT: @/spec/readiness-report.md +MODE: analysis +EXPECTED: JSON with perspectives[], consensus, severity, recommendations[]" --tool gemini --mode analysis +``` + Handle discuss verdict per team-worker consensus handling protocol. > **Note**: DISCUSS-006 HIGH always triggers user pause (final sign-off gate), regardless of revision count. @@ -91,4 +99,4 @@ Handle discuss verdict per team-worker consensus handling protocol. | Missing context | Request from coordinator | | Invalid mode | Abort with error | | Analysis failure | Retry, then fallback template | -| Discuss subagent fails | Proceed without final discuss, log warning | +| CLI discuss fails | Proceed without final discuss, log warning | diff --git a/.claude/skills/team-lifecycle/role-specs/tester.md b/.claude/skills/team-lifecycle/role-specs/tester.md index 3b60e434..34fae37a 100644 --- a/.claude/skills/team-lifecycle/role-specs/tester.md +++ b/.claude/skills/team-lifecycle/role-specs/tester.md @@ -3,7 +3,7 @@ role: tester prefix: TEST inner_loop: false discuss_rounds: [] -subagents: [] +cli_tools: [] message_types: success: test_result fix: fix_required diff --git a/.claude/skills/team-lifecycle/role-specs/writer.md b/.claude/skills/team-lifecycle/role-specs/writer.md index 22452e3c..b52379c5 100644 --- a/.claude/skills/team-lifecycle/role-specs/writer.md +++ b/.claude/skills/team-lifecycle/role-specs/writer.md @@ -3,7 +3,7 @@ role: writer prefix: DRAFT inner_loop: true discuss_rounds: [DISCUSS-002, DISCUSS-003, DISCUSS-004, DISCUSS-005] -subagents: [discuss] +cli_tools: [discuss] message_types: success: draft_ready revision: draft_revision @@ -54,7 +54,7 @@ message_types: | Discussion feedback | `/discussions/` | If exists | | Prior decisions | context_accumulator (in-memory) | If prior tasks exist | -## Phase 3: Subagent Document Generation +## Phase 3: CLI Document Generation **Objective**: Generate document using CLI tool. @@ -87,11 +87,19 @@ Parse CLI output for artifact path and summary. Document is written to disk by C ### 4b: Inline Discuss -Call discuss subagent for this task's discuss round: +Call CLI discuss tool for this task's discuss round: - Artifact: `` (the generated document) - Round: `` from mapping table - Perspectives: from mapping table +```bash +ccw cli -p "PURPOSE: Multi-perspective critique of +TASK: Review from +ARTIFACT: @ +MODE: analysis +EXPECTED: JSON with perspectives[], consensus, severity, recommendations[]" --tool gemini --mode analysis +``` + Handle discuss verdict per team-worker consensus handling protocol. **Report**: doc type, validation status, discuss verdict + severity, average rating, summary, output path. @@ -101,7 +109,7 @@ Handle discuss verdict per team-worker consensus handling protocol. | Scenario | Resolution | |----------|------------| | CLI failure | Retry once with alternative tool. Still fails → log error, continue next task | -| Discuss subagent fails | Skip discuss, log warning | +| CLI discuss fails | Skip discuss, log warning | | Cumulative 3 task failures | SendMessage to coordinator, STOP | | Prior doc not found | Notify coordinator, request prerequisite | | Discussion contradicts prior docs | Note conflict, flag for coordinator | diff --git a/.claude/skills/team-lifecycle/roles/coordinator/role.md b/.claude/skills/team-lifecycle/roles/coordinator/role.md index a59acbec..7bebabaa 100644 --- a/.claude/skills/team-lifecycle/roles/coordinator/role.md +++ b/.claude/skills/team-lifecycle/roles/coordinator/role.md @@ -11,7 +11,7 @@ Orchestrate the team-lifecycle workflow: team creation, task dispatching, progre ### MUST - Parse user requirements and clarify ambiguous inputs via AskUserQuestion -- Create team and spawn worker subagents in background using **team-worker** agent type +- Create team and spawn worker agents in background using **team-worker** agent type - Dispatch tasks with proper dependency chains (see SKILL.md Task Metadata Registry) - Monitor progress via worker callbacks and route messages - Maintain session state persistence (team-session.json) @@ -19,7 +19,6 @@ Orchestrate the team-lifecycle workflow: team creation, task dispatching, progre ### MUST NOT - Execute spec/impl/research work directly (delegate to workers) - Modify task outputs (workers own their deliverables) -- Call implementation subagents (code-developer, etc.) directly - Skip dependency validation when creating task chains --- diff --git a/.claude/skills/team-lifecycle/specs/team-config.json b/.claude/skills/team-lifecycle/specs/team-config.json index 19a791a2..a3fa22a8 100644 --- a/.claude/skills/team-lifecycle/specs/team-config.json +++ b/.claude/skills/team-lifecycle/specs/team-config.json @@ -6,7 +6,6 @@ "architecture": "team-worker agent + role-specs", "role_structure": "role-specs/{name}.md (Phase 2-4 only)", "worker_agent": "team-worker", - "subagent_structure": "subagents/{name}-subagent.md", "roles": { "coordinator": { @@ -27,7 +26,6 @@ "role_spec": "role-specs/writer.md", "responsibility": "Product Brief / PRD / Architecture / Epics document generation + inline discuss", "inner_loop": true, - "subagent_type": "universal-executor", "inline_discuss": ["DISCUSS-002", "DISCUSS-003", "DISCUSS-004", "DISCUSS-005"], "message_types": ["draft_ready", "draft_revision", "error"] }, @@ -88,24 +86,24 @@ } }, - "subagents": { + "utility_functions": { "discuss": { - "spec": "subagents/discuss-subagent.md", - "type": "cli-discuss-agent", + "type": "cli-tool", "callable_by": ["analyst", "writer", "reviewer"], - "purpose": "Multi-perspective critique with CLI tools, consensus synthesis" + "purpose": "Multi-perspective critique with CLI tools, consensus synthesis", + "implementation": "Bash with ccw cli --mode analysis" }, "explore": { - "spec": "subagents/explore-subagent.md", - "type": "cli-explore-agent", + "type": "explore-agent", "callable_by": ["analyst", "planner", "any"], - "purpose": "Codebase exploration with centralized cache" + "purpose": "Codebase exploration with centralized cache", + "implementation": "Agent with subagent_type: Explore" }, "doc-generation": { - "spec": "subagents/doc-generation-subagent.md", - "type": "universal-executor", + "type": "cli-tool", "callable_by": ["writer"], - "purpose": "Document generation engine (CLI execution)" + "purpose": "Document generation engine (CLI execution)", + "implementation": "Bash with ccw cli --mode write" } }, @@ -199,7 +197,7 @@ "style_decisions": "Accumulated design decisions", "qa_history": "From fe-qa, audit trail", "industry_context": "Industry + strictness config", - "exploration_cache": "From explore subagent, shared by all roles" + "exploration_cache": "From exploration utility (Explore agent), shared by all roles" } }, diff --git a/.claude/skills/team-lifecycle/subagents/discuss-subagent.md b/.claude/skills/team-lifecycle/subagents/discuss-subagent.md deleted file mode 100644 index 9334a614..00000000 --- a/.claude/skills/team-lifecycle/subagents/discuss-subagent.md +++ /dev/null @@ -1,169 +0,0 @@ -# Discuss Subagent - -Lightweight multi-perspective critique engine. Called inline by produce roles (analyst, writer, reviewer) instead of as a separate team member. Eliminates spawn overhead while preserving multi-CLI analysis quality. - -## Design Rationale - -In v3, `discussant` was a full team role requiring: agent spawn -> Skill load -> Phase 1 task discovery -> Phase 2-4 work -> Phase 5 report + callback. For what is essentially "run CLI analyses + synthesize", the framework overhead exceeded actual work time. - -In v4, discuss is a **subagent call** from within the producing role, reducing each discuss round from ~60-90s overhead to ~5s overhead. - -## Invocation - -Called by produce roles after artifact creation: - -``` -Agent({ - subagent_type: "cli-discuss-agent", - run_in_background: false, - description: "Discuss ", - prompt: `## Multi-Perspective Critique: - -### Input -- Artifact: -- Round: -- Perspectives: -- Session: -- Discovery Context: /spec/discovery-context.json (for coverage perspective) - -### Perspective Routing - -| Perspective | CLI Tool | Role | Focus Areas | -|-------------|----------|------|-------------| -| Product | gemini | Product Manager | Market fit, user value, business viability | -| Technical | codex | Tech Lead | Feasibility, tech debt, performance, security | -| Quality | claude | QA Lead | Completeness, testability, consistency | -| Risk | gemini | Risk Analyst | Risk identification, dependencies, failure modes | -| Coverage | gemini | Requirements Analyst | Requirement completeness vs discovery-context | - -### Execution Steps -1. Read artifact from -2. For each perspective, launch CLI analysis in background: - Bash(command="ccw cli -p 'PURPOSE: Analyze from perspective for - TASK: - MODE: analysis - CONTEXT: Artifact content below - EXPECTED: JSON with strengths[], weaknesses[], suggestions[], rating (1-5) - CONSTRAINTS: Output valid JSON only - - Artifact: - ' --tool --mode analysis", run_in_background=true) -3. Wait for all CLI results -4. Divergence detection: - - Coverage gap: missing_requirements non-empty -> High severity - - High risk: risk_level is high or critical -> High severity - - Low rating: any perspective rating <= 2 -> Medium severity - - Rating spread: max - min >= 3 -> Medium severity -5. Consensus determination: - - No high-severity divergences AND average rating >= 3.0 -> consensus_reached - - Otherwise -> consensus_blocked -6. Synthesize: - - Convergent themes (agreed by 2+ perspectives) - - Divergent views (conflicting assessments) - - Coverage gaps - - Action items from suggestions -7. Write discussion record to: /discussions/-discussion.md - -### Discussion Record Format -# Discussion Record: - -**Artifact**: -**Perspectives**: -**Consensus**: reached / blocked -**Average Rating**: /5 - -## Convergent Themes -- - -## Divergent Views -- **** (): - -## Action Items -1. - -## Ratings -| Perspective | Rating | -|-------------|--------| -| | /5 | - -### Return Value - -**When consensus_reached**: -Return a summary string with: -- Verdict: consensus_reached -- Average rating -- Key action items (top 3) -- Discussion record path - -**When consensus_blocked**: -Return a structured summary with: -- Verdict: consensus_blocked -- Severity: HIGH | MEDIUM | LOW - - HIGH: any rating <= 2, critical risk identified, or missing_requirements non-empty - - MEDIUM: rating spread >= 3, or single perspective rated <= 2 with others >= 3 - - LOW: minor suggestions only, all ratings >= 3 but divergent views exist -- Average rating -- Divergence summary: top 3 divergent points with perspective attribution -- Action items: prioritized list of required changes -- Recommendation: revise | proceed-with-caution | escalate -- Discussion record path - -### Error Handling -- Single CLI fails -> fallback to direct Claude analysis for that perspective -- All CLI fail -> generate basic discussion from direct artifact reading -- Artifact not found -> return error immediately` -}) -``` - -## Round Configuration - -| Round | Artifact | Perspectives | Calling Role | -|-------|----------|-------------|-------------| -| DISCUSS-001 | spec/discovery-context.json | product, risk, coverage | analyst | -| DISCUSS-002 | spec/product-brief.md | product, technical, quality, coverage | writer | -| DISCUSS-003 | spec/requirements/_index.md | quality, product, coverage | writer | -| DISCUSS-004 | spec/architecture/_index.md | technical, risk | writer | -| DISCUSS-005 | spec/epics/_index.md | product, technical, quality, coverage | writer | -| DISCUSS-006 | spec/readiness-report.md | all 5 | reviewer | - -## Integration with Calling Role - -The calling role is responsible for: - -1. **Before calling**: Complete primary artifact output -2. **Calling**: Invoke discuss subagent with correct round config -3. **After calling**: - -| Verdict | Severity | Role Action | -|---------|----------|-------------| -| consensus_reached | - | Include action items in Phase 5 report, proceed normally | -| consensus_blocked | HIGH | Include divergence details in Phase 5 SendMessage with structured format (see below). **Do NOT self-revise** -- coordinator decides. | -| consensus_blocked | MEDIUM | Include warning in Phase 5 SendMessage. Proceed to Phase 5 normally. | -| consensus_blocked | LOW | Treat as consensus_reached with notes. Proceed normally. | - -**SendMessage format for consensus_blocked (HIGH or MEDIUM)**: - -``` -[] complete. Discuss : consensus_blocked (severity=) -Divergences: -Action items: -Recommendation: -Artifact: -Discussion: -``` - -The coordinator receives this and routes per severity (see monitor.md Consensus-Blocked Handling): -- HIGH -> creates revision task (max 1) or pauses for user -- MEDIUM -> proceeds with warning logged to wisdom/issues.md -- DISCUSS-006 HIGH -> always pauses for user decision (final sign-off gate) - -## Comparison with v3 - -| Aspect | v3 (discussant role) | v4 (discuss subagent) | -|--------|---------------------|----------------------| -| Spawn | Full general-purpose agent | Inline subagent call | -| Skill load | Reads SKILL.md + role.md | None (prompt contains all logic) | -| Task discovery | TaskList + TaskGet + TaskUpdate | None (called with context) | -| Report overhead | team_msg + SendMessage + TaskUpdate | Return value to caller | -| Total overhead | ~25-45s framework | ~5s call overhead | -| Pipeline beat | 1 beat per discuss round | 0 additional beats | diff --git a/.claude/skills/team-lifecycle/subagents/doc-generation-subagent.md b/.claude/skills/team-lifecycle/subagents/doc-generation-subagent.md deleted file mode 100644 index ed55ac33..00000000 --- a/.claude/skills/team-lifecycle/subagents/doc-generation-subagent.md +++ /dev/null @@ -1,62 +0,0 @@ -# Doc Generation Subagent - -文档生成执行引擎。由 writer 主 agent 通过 Inner Loop 调用。 -负责 CLI 多视角分析 + 模板填充 + 文件写入。 - -## Design Rationale - -从 v4.0 的 writer 内联 CLI 执行，改为 subagent 隔离调用。 -好处：CLI 调用的大量 token 消耗不污染 writer 主 agent 上下文， -writer 只拿到压缩摘要，可在多任务间保持上下文连续。 - -## Invocation - -``` -Agent({ - subagent_type: "universal-executor", - run_in_background: false, - description: "Generate ", - prompt: `## Document Generation: - -### Session -- Folder: -- Spec config: - -### Document Config -- Type: -- Template: -- Output: -- Prior discussion: - -### Writer Accumulator (prior decisions) - - -### Execution Strategy -<从 generate-doc.md 对应 doc-type 段落加载> - -### Output Requirements -1. Write document to (follow template + document-standards.md) -2. Return JSON summary: -{ - "artifact_path": "", - "summary": "<100-200字>", - "key_decisions": [], - "sections_generated": [], - "cross_references": [], - "warnings": [] -}` -}) -``` - -## Doc Type Strategies - -(直接引用 generate-doc.md 的 DRAFT-001/002/003/004 策略，不重复) -See: roles/writer/commands/generate-doc.md - -## Error Handling - -| Scenario | Resolution | -|----------|------------| -| CLI 工具失败 | fallback chain: gemini → codex → claude | -| Template 不存在 | 返回错误 JSON | -| Prior doc 不存在 | 返回错误 JSON，writer 决定是否继续 | diff --git a/.claude/skills/team-lifecycle/subagents/explore-subagent.md b/.claude/skills/team-lifecycle/subagents/explore-subagent.md deleted file mode 100644 index c3952cf3..00000000 --- a/.claude/skills/team-lifecycle/subagents/explore-subagent.md +++ /dev/null @@ -1,174 +0,0 @@ -# Explore Subagent - -Shared codebase exploration utility with centralized caching. Callable by any role needing code context. Replaces v3's standalone explorer role. - -## Design Rationale - -In v3, exploration happened in 3 separate places: -- `analyst` Phase 3: ACE semantic search for architecture patterns -- `planner` Phase 2: multi-angle cli-explore-agent -- `explorer` role: standalone service with full spawn cycle - -Results were scattered across different directories and never shared. In v4, all exploration routes through this subagent with a **unified cache** in `explorations/`. - -## Invocation - -``` -Agent({ - subagent_type: "cli-explore-agent", - run_in_background: false, - description: "Explore ", - prompt: `Explore codebase for: - -Focus angle: -Keywords: -Session folder: - -## Cache Check -1. Read /explorations/cache-index.json (if exists) -2. Look for entry with matching angle -3. If found AND file exists -> read cached result, return summary -4. If not found -> proceed to exploration - -## Exploration - - -## Output -Write JSON to: /explorations/explore-.json -Update cache-index.json with new entry - -## Output Schema -{ - "angle": "", - "query": "", - "relevant_files": [ - { "path": "...", "rationale": "...", "role": "...", "discovery_source": "...", "key_symbols": [] } - ], - "patterns": [], - "dependencies": [], - "external_refs": [], - "_metadata": { "created_by": "", "timestamp": "...", "cache_key": "..." } -} - -Return summary: file count, pattern count, top 5 files, output path` -}) -``` - -## Cache Mechanism - -### Cache Index Schema - -`/explorations/cache-index.json`: - -```json -{ - "entries": [ - { - "angle": "architecture", - "keywords": ["auth", "middleware"], - "file": "explore-architecture.json", - "created_by": "analyst", - "created_at": "2026-02-27T10:00:00Z", - "file_count": 15 - } - ] -} -``` - -### Cache Lookup Rules - -| Condition | Action | -|-----------|--------| -| Exact angle match exists | Return cached result | -| No match | Execute exploration, cache result | -| Cache file missing but index has entry | Remove stale entry, re-explore | - -### Cache Invalidation - -Cache is session-scoped. No explicit invalidation needed -- each session starts fresh. If a role suspects stale data, it can pass `force_refresh: true` in the prompt to bypass cache. - -## Angle Focus Guide - -| Angle | Focus Points | Typical Caller | -|-------|-------------|----------------| -| architecture | Layer boundaries, design patterns, component responsibilities, ADRs | analyst, planner | -| dependencies | Import chains, external libraries, circular dependencies, shared utilities | planner | -| modularity | Module interfaces, separation of concerns, extraction opportunities | planner | -| integration-points | API endpoints, data flow between modules, event systems | analyst, planner | -| security | Auth/authz logic, input validation, sensitive data handling, middleware | planner | -| auth-patterns | Auth flows, session management, token validation, permissions | planner | -| dataflow | Data transformations, state propagation, validation points | planner | -| performance | Bottlenecks, N+1 queries, blocking operations, algorithm complexity | planner | -| error-handling | Try-catch blocks, error propagation, recovery strategies, logging | planner | -| patterns | Code conventions, design patterns, naming conventions, best practices | analyst, planner | -| testing | Test files, coverage gaps, test patterns, mocking strategies | planner | -| general | Broad semantic search for topic-related code | analyst | - -## Exploration Strategies - -### Low Complexity (direct search) - -For simple queries, use ACE semantic search: - -``` -mcp__ace-tool__search_context(project_root_path="", query="") -``` - -ACE failure fallback: `rg -l '' --type ts` - -### Medium/High Complexity (multi-angle) - -For complex queries, call cli-explore-agent per angle. The calling role determines complexity and selects angles (see planner's `commands/explore.md`). - -## Search Tool Priority - -| Tool | Priority | Use Case | -|------|----------|----------| -| mcp__ace-tool__search_context | P0 | Semantic search | -| Grep / Glob | P1 | Pattern matching | -| cli-explore-agent | Deep | Multi-angle exploration | -| WebSearch | P3 | External docs | - -## Integration with Roles - -### analyst (RESEARCH-001) - -``` -# After seed analysis, explore codebase context -Agent({ - subagent_type: "cli-explore-agent", - description: "Explore general context", - run_in_background: false, - prompt: "Explore codebase for: \nFocus angle: general\n..." -}) -# Result feeds into discovery-context.json -``` - -### planner (PLAN-001) - -``` -# Multi-angle exploration before plan generation -for angle in selected_angles: - Agent({ - subagent_type: "cli-explore-agent", - description: "Explore ", - run_in_background: false, - prompt: "Explore codebase for: \nFocus angle: \n..." - }) -# Explorations manifest built from cache-index.json -``` - -### Any role needing context - -Any role can call explore subagent when needing codebase context for better decisions. - -## Comparison with v3 - -| Aspect | v3 (explorer role) | v4 (explore subagent) | -|--------|-------------------|----------------------| -| Identity | Full team member | Utility subagent | -| Task creation | Coordinator creates EXPLORE-* tasks | No tasks, direct call | -| Spawn overhead | Full agent lifecycle | Subagent call (~5s) | -| Result sharing | Isolated in explorations/ | Shared cache with index | -| Caller | Only via coordinator dispatch | Any role directly | -| Duplication | analyst + planner + explorer all explore | Single cached path | diff --git a/.claude/skills/team-perf-opt/SKILL.md b/.claude/skills/team-perf-opt/SKILL.md index 8c02d557..6c991fd9 100644 --- a/.claude/skills/team-perf-opt/SKILL.md +++ b/.claude/skills/team-perf-opt/SKILL.md @@ -27,9 +27,6 @@ Unified team skill: Profile application performance, identify bottlenecks, desig profiler strate- optim- bench- review- gist izer marker er - Subagents (callable by workers, not team members): - [explore] [discuss] - (tw) = team-worker agent ``` @@ -52,13 +49,6 @@ Parse `$ARGUMENTS`. No `--role` needed -- always routes to coordinator. | benchmarker | [role-specs/benchmarker.md](role-specs/benchmarker.md) | BENCH-* | validation | false | | reviewer | [role-specs/reviewer.md](role-specs/reviewer.md) | REVIEW-* / QUALITY-* | read_only_analysis | false | -### Subagent Registry - -| Subagent | Spec | Callable By | Purpose | -|----------|------|-------------|---------| -| explore | [subagents/explore-subagent.md](subagents/explore-subagent.md) | profiler, optimizer | Shared codebase exploration for performance-critical code paths | -| discuss | [subagents/discuss-subagent.md](subagents/discuss-subagent.md) | strategist, reviewer | Multi-perspective discussion for optimization approaches and review findings | - ### Dispatch Always route to coordinator. Coordinator reads `roles/coordinator/role.md` and executes its phases. @@ -459,7 +449,7 @@ Coordinator supports `--resume` / `--continue` for interrupted sessions: |----------|------------| | Role spec file not found | Error with expected path (role-specs/.md) | | Command file not found | Fallback to inline execution in coordinator role.md | -| Subagent spec not found | Error with expected path (subagents/-subagent.md) | +| Role file not found | Error with expected path (role-specs/.md) | | Fast-advance orphan detected | Coordinator resets task to pending on next check | | consensus_blocked HIGH | Coordinator creates revision task or pauses pipeline | | team-worker agent unavailable | Error: requires .claude/agents/team-worker.md | diff --git a/.claude/skills/team-perf-opt/role-specs/optimizer.md b/.claude/skills/team-perf-opt/role-specs/optimizer.md index fa279f14..b7df525a 100644 --- a/.claude/skills/team-perf-opt/role-specs/optimizer.md +++ b/.claude/skills/team-perf-opt/role-specs/optimizer.md @@ -2,7 +2,7 @@ prefix: IMPL inner_loop: true additional_prefixes: [FIX] -subagents: [explore] +delegates_to: [] message_types: success: impl_complete error: error @@ -47,7 +47,7 @@ Implement optimization changes following the strategy plan. For FIX tasks, apply - **Independent pipeline**: Read `/artifacts/pipelines/{P}/optimization-plan.md` -- extract this pipeline's plan 4. For FIX: parse review/benchmark feedback for specific issues to address -5. Use `explore` subagent to load implementation context for target files +5. Use ACE search or CLI tools to load implementation context for target files 6. For inner loop (single mode only): load context_accumulator from prior IMPL/FIX tasks **Shared-memory namespace**: diff --git a/.claude/skills/team-perf-opt/role-specs/profiler.md b/.claude/skills/team-perf-opt/role-specs/profiler.md index af7c775f..5046ec59 100644 --- a/.claude/skills/team-perf-opt/role-specs/profiler.md +++ b/.claude/skills/team-perf-opt/role-specs/profiler.md @@ -1,7 +1,7 @@ --- prefix: PROFILE inner_loop: false -subagents: [explore] +delegates_to: [] message_types: success: profile_complete error: error @@ -31,7 +31,7 @@ Profile application performance to identify CPU, memory, I/O, network, and rende | CLI entry / bin/ directory | CLI Tool | Startup time, throughput, memory peak | | No detection | Generic | All profiling dimensions | -3. Use `explore` subagent to map performance-critical code paths within target scope +3. Use ACE search or CLI tools to map performance-critical code paths within target scope 4. Detect available profiling tools (test runners, benchmark harnesses, linting tools) ## Phase 3: Performance Profiling diff --git a/.claude/skills/team-perf-opt/role-specs/reviewer.md b/.claude/skills/team-perf-opt/role-specs/reviewer.md index 21f7337e..7de0b459 100644 --- a/.claude/skills/team-perf-opt/role-specs/reviewer.md +++ b/.claude/skills/team-perf-opt/role-specs/reviewer.md @@ -3,7 +3,7 @@ prefix: REVIEW inner_loop: false additional_prefixes: [QUALITY] discuss_rounds: [DISCUSS-REVIEW] -subagents: [discuss] +delegates_to: [] message_types: success: review_complete error: error @@ -65,7 +65,7 @@ Per-dimension review process: - Record findings with severity (Critical / High / Medium / Low) - Include specific file:line references and suggested fixes -If any Critical findings detected, invoke `discuss` subagent (DISCUSS-REVIEW round) to validate the assessment before issuing verdict. +If any Critical findings detected, use CLI tools for multi-perspective validation (DISCUSS-REVIEW round) to validate the assessment before issuing verdict. ## Phase 4: Verdict & Feedback diff --git a/.claude/skills/team-perf-opt/role-specs/strategist.md b/.claude/skills/team-perf-opt/role-specs/strategist.md index 263586a8..67b60a6c 100644 --- a/.claude/skills/team-perf-opt/role-specs/strategist.md +++ b/.claude/skills/team-perf-opt/role-specs/strategist.md @@ -2,7 +2,7 @@ prefix: STRATEGY inner_loop: false discuss_rounds: [DISCUSS-OPT] -subagents: [discuss] +delegates_to: [] message_types: success: strategy_complete error: error @@ -55,7 +55,7 @@ Prioritize optimizations by impact/effort ratio: | P2 (Medium) | Medium impact + Low effort | | P3 (Low) | Low impact or High effort -- defer | -If complexity is High, invoke `discuss` subagent (DISCUSS-OPT round) to evaluate trade-offs between competing strategies before finalizing the plan. +If complexity is High, use CLI tools for multi-perspective analysis (DISCUSS-OPT round) to evaluate trade-offs between competing strategies before finalizing the plan. Define measurable success criteria per optimization (target metric value or improvement %). diff --git a/.claude/skills/team-perf-opt/subagents/discuss-subagent.md b/.claude/skills/team-perf-opt/subagents/discuss-subagent.md deleted file mode 100644 index 10a8070c..00000000 --- a/.claude/skills/team-perf-opt/subagents/discuss-subagent.md +++ /dev/null @@ -1,89 +0,0 @@ -# Discuss Subagent - -Multi-perspective discussion for evaluating optimization strategies and reviewing code change quality. Used by strategist (DISCUSS-OPT) and reviewer (DISCUSS-REVIEW) when complex trade-offs require multi-angle analysis. - -## Design Rationale - -Complex optimization decisions (e.g., choosing between algorithmic change vs caching layer) and nuanced code review findings (e.g., evaluating whether a side effect is acceptable) benefit from structured multi-perspective analysis. This subagent provides that analysis inline without spawning additional team members. - -## Invocation - -Called by strategist, reviewer after their primary analysis when complexity warrants multi-perspective evaluation: - -``` -Agent({ - subagent_type: "cli-discuss-agent", - run_in_background: false, - description: "Discuss : for performance optimization", - prompt: `Conduct a multi-perspective discussion on the following topic. - -Round: -Topic: -Session: - -Context: - - -Perspectives to consider: -- Performance impact: Will this actually improve the target metric? -- Risk assessment: What could go wrong? Side effects? Regressions? -- Maintainability: Is the optimized code still understandable and maintainable? -- Alternative approaches: Are there simpler or safer ways to achieve the same goal? - -Evaluate trade-offs and provide a structured recommendation with: -- Consensus verdict: proceed / revise / escalate -- Confidence level: high / medium / low -- Key trade-offs identified -- Recommended approach with rationale -- Dissenting perspectives (if any)` -}) -``` - -## Round Configuration - -| Round | Artifact | Parameters | Calling Role | -|-------|----------|------------|-------------| -| DISCUSS-OPT | /discussions/DISCUSS-OPT.md | Optimization strategy trade-offs | strategist | -| DISCUSS-REVIEW | /discussions/DISCUSS-REVIEW.md | Code review finding validation | reviewer | - -## Integration with Calling Role - -The calling role is responsible for: - -1. **Before calling**: Complete primary analysis, identify the specific trade-off or finding needing discussion -2. **Calling**: Invoke subagent with round ID, topic, and relevant context -3. **After calling**: - -| Result | Action | -|--------|--------| -| consensus_reached (proceed) | Incorporate recommendation into output, continue | -| consensus_reached (revise) | Adjust findings/strategy based on discussion insights | -| consensus_blocked (HIGH) | Report to coordinator via message with severity | -| consensus_blocked (MEDIUM) | Include in output with recommendation for revision | -| consensus_blocked (LOW) | Note in output, proceed with original assessment | - -## Output Schema - -```json -{ - "round_id": "", - "topic": "", - "verdict": "", - "confidence": "", - "trade_offs": [ - { "dimension": "", "pro": "", "con": "" } - ], - "recommendation": "", - "rationale": "", - "dissenting_views": [""] -} -``` - -## Error Handling - -| Scenario | Resolution | -|----------|------------| -| Single perspective analysis fails | Continue with partial perspectives | -| All analyses fail | Return basic recommendation from calling role's primary analysis | -| Artifact not found | Return error immediately | -| Discussion inconclusive | Return "revise" verdict with low confidence | diff --git a/.claude/skills/team-perf-opt/subagents/explore-subagent.md b/.claude/skills/team-perf-opt/subagents/explore-subagent.md deleted file mode 100644 index 44347614..00000000 --- a/.claude/skills/team-perf-opt/subagents/explore-subagent.md +++ /dev/null @@ -1,108 +0,0 @@ -# Explore Subagent - -Shared codebase exploration for discovering performance-critical code paths, module structures, and optimization opportunities. Results are cached to avoid redundant exploration across profiler and optimizer roles. - -## Design Rationale - -Codebase exploration is a read-only operation shared between profiler (mapping bottlenecks) and optimizer (understanding implementation context). Caching explorations avoids redundant work when optimizer re-explores paths the profiler already mapped. - -## Invocation - -Called by profiler, optimizer after needing codebase context for performance analysis or implementation: - -``` -Agent({ - subagent_type: "cli-explore-agent", - run_in_background: false, - description: "Explore codebase for performance-critical paths in ", - prompt: `Explore the codebase to identify performance-critical code paths. - -Target scope: -Session: -Focus: - -Tasks: -1. Map the module structure and entry points within scope -2. Identify hot code paths (frequently called functions, critical loops) -3. Find performance-relevant patterns (caching, lazy loading, async, pooling) -4. Note any existing performance optimizations or benchmark harnesses -5. List key files with their roles in the performance-critical path - -Output a structured exploration report with: -- Module map (key files and their relationships) -- Hot path analysis (call chains, loop nests, recursive patterns) -- Existing optimization patterns found -- Performance-relevant configuration (caching, pooling, batching settings) -- Recommended investigation targets for profiling` -}) -``` - -## Cache Mechanism - -### Cache Index Schema - -`/explorations/cache-index.json`: - -```json -{ - "entries": [ - { - "key": "", - "scope": "", - "focus": "", - "timestamp": "", - "result_file": ".md" - } - ] -} -``` - -### Cache Lookup Rules - -| Condition | Action | -|-----------|--------| -| Exact scope+focus match exists | Return cached result from .md | -| No match | Execute subagent, cache result to .md, update index | -| Cache file missing but index has entry | Remove stale entry, re-execute | -| Cache older than current session | Use cached (explorations are stable within session) | - -## Integration with Calling Role - -The calling role is responsible for: - -1. **Before calling**: Determine target scope and exploration focus -2. **Calling**: Check cache first, invoke subagent only on cache miss -3. **After calling**: - -| Result | Action | -|--------|--------| -| Exploration successful | Use findings to inform profiling/implementation | -| Exploration partial | Use available findings, note gaps | -| Exploration failed | Proceed without exploration context, use direct file reading | - -## Output Schema - -```json -{ - "scope": "", - "module_map": [ - { "file": "", "role": "", "hot_path": true } - ], - "hot_paths": [ - { "chain": "", "frequency": "", "files": [""] } - ], - "existing_optimizations": [ - { "type": "", "location": "", "description": "" } - ], - "investigation_targets": [""] -} -``` - -## Error Handling - -| Scenario | Resolution | -|----------|------------| -| Single exploration angle fails | Continue with partial results | -| All exploration fails | Return basic result from direct file listing | -| Target scope not found | Return error immediately | -| Cache corrupt | Clear cache-index.json, re-execute | diff --git a/.claude/skills/team-planex/SKILL.md b/.claude/skills/team-planex/SKILL.md index 1acf304b..1979879e 100644 --- a/.claude/skills/team-planex/SKILL.md +++ b/.claude/skills/team-planex/SKILL.md @@ -127,7 +127,7 @@ When coordinator spawns workers, use `team-worker` agent with role-spec path: ``` Agent({ - subagent_type: "team-worker", + agent_type: "team-worker", description: "Spawn worker", team_name: , name: "", diff --git a/.claude/skills/team-planex/role-specs/executor.md b/.claude/skills/team-planex/role-specs/executor.md index 4af565ac..90be7b5f 100644 --- a/.claude/skills/team-planex/role-specs/executor.md +++ b/.claude/skills/team-planex/role-specs/executor.md @@ -85,6 +85,6 @@ Send `impl_complete` message to coordinator via team_msg + SendMessage. |---------|-----------| | Load solution from file | Create or modify issues | | Implement via CLI tools (Codex/Gemini) | Modify solution artifacts | -| Run tests | Spawn subagents (use CLI tools instead) | +| Run tests | Spawn additional agents (use CLI tools instead) | | git commit | Direct user interaction | | Update issue status | Create tasks for other roles | diff --git a/.claude/skills/team-planex/roles/coordinator/commands/monitor.md b/.claude/skills/team-planex/roles/coordinator/commands/monitor.md index d00d3493..4e6ad4f5 100644 --- a/.claude/skills/team-planex/roles/coordinator/commands/monitor.md +++ b/.claude/skills/team-planex/roles/coordinator/commands/monitor.md @@ -118,7 +118,7 @@ Collect task states from TaskList() | +- EXEC-* -> executor +- Spawn team-worker: Agent({ - subagent_type: "team-worker", + agent_type: "team-worker", description: "Spawn worker for ", team_name: , name: "", diff --git a/.claude/skills/team-planex/roles/coordinator/role.md b/.claude/skills/team-planex/roles/coordinator/role.md index 2c2419c8..0c2aab14 100644 --- a/.claude/skills/team-planex/roles/coordinator/role.md +++ b/.claude/skills/team-planex/roles/coordinator/role.md @@ -19,7 +19,7 @@ Orchestrate the team-planex pipeline: parse input, create team, dispatch tasks, ### MUST NOT - Execute planning or implementation work directly (delegate to workers) - Modify solution artifacts or code (workers own their deliverables) -- Call implementation subagents (code-developer, etc.) directly +- Call implementation CLI tools (code-developer, etc.) directly - Skip dependency validation when creating task chains --- diff --git a/.claude/skills/team-quality-assurance/SKILL.md b/.claude/skills/team-quality-assurance/SKILL.md index 272b1ebf..5fd45d14 100644 --- a/.claude/skills/team-quality-assurance/SKILL.md +++ b/.claude/skills/team-quality-assurance/SKILL.md @@ -360,7 +360,7 @@ When coordinator spawns workers, use `team-worker` agent with role-spec path: ``` Agent({ - subagent_type: "team-worker", + agent_type: "team-worker", description: "Spawn worker", team_name: "quality-assurance", name: "", @@ -398,7 +398,7 @@ Execute built-in Phase 1 (task discovery) -> role-spec Phase 2-4 -> built-in Pha ``` Agent({ - subagent_type: "team-worker", + agent_type: "team-worker", description: "Spawn - worker", team_name: "quality-assurance", name: "-", diff --git a/.claude/skills/team-quality-assurance/role-specs/analyst.md b/.claude/skills/team-quality-assurance/role-specs/analyst.md index f77437fc..160d2e42 100644 --- a/.claude/skills/team-quality-assurance/role-specs/analyst.md +++ b/.claude/skills/team-quality-assurance/role-specs/analyst.md @@ -1,7 +1,7 @@ --- prefix: QAANA inner_loop: false -subagents: [] +additional_members: [] message_types: success: analysis_ready report: quality_report diff --git a/.claude/skills/team-quality-assurance/role-specs/executor.md b/.claude/skills/team-quality-assurance/role-specs/executor.md index c26a8a35..9059d5da 100644 --- a/.claude/skills/team-quality-assurance/role-specs/executor.md +++ b/.claude/skills/team-quality-assurance/role-specs/executor.md @@ -2,7 +2,7 @@ prefix: QARUN inner_loop: true additional_prefixes: [QARUN-gc] -subagents: [] +additional_members: [] message_types: success: tests_passed failure: tests_failed @@ -50,7 +50,7 @@ Per iteration: 4. If pass rate >= 95% and iteration >= 2 -> exit loop (good enough) 5. If iteration >= MAX -> exit loop (report current state) 6. Extract failure details (error lines, assertion failures) -7. Delegate fix to code-developer subagent with constraints: +7. Delegate fix via CLI tool with constraints: - ONLY modify test files, NEVER modify source code - Fix: incorrect assertions, missing imports, wrong mocks, setup issues - Do NOT: skip tests, add `@ts-ignore`, use `as any` diff --git a/.claude/skills/team-quality-assurance/role-specs/generator.md b/.claude/skills/team-quality-assurance/role-specs/generator.md index 114992f3..8ad02aef 100644 --- a/.claude/skills/team-quality-assurance/role-specs/generator.md +++ b/.claude/skills/team-quality-assurance/role-specs/generator.md @@ -2,7 +2,7 @@ prefix: QAGEN inner_loop: false additional_prefixes: [QAGEN-fix] -subagents: [] +additional_members: [] message_types: success: tests_generated revised: tests_revised @@ -38,7 +38,7 @@ Generate test code according to strategist's strategy and layers. Support L1 uni |-----------|------| | GC fix task | Read failure info from `/results/run-.json`, fix failing tests only | | <= 3 focus files | Direct: inline Read source -> Write test file | -| > 3 focus files | Batch by module, delegate to code-developer subagent | +| > 3 focus files | Batch by module, delegate via CLI tool | **Direct generation flow** (per source file): 1. Read source file content, extract exports diff --git a/.claude/skills/team-quality-assurance/role-specs/scout.md b/.claude/skills/team-quality-assurance/role-specs/scout.md index 9bd77f4e..96c74b8f 100644 --- a/.claude/skills/team-quality-assurance/role-specs/scout.md +++ b/.claude/skills/team-quality-assurance/role-specs/scout.md @@ -1,7 +1,7 @@ --- prefix: SCOUT inner_loop: false -subagents: [] +additional_members: [] message_types: success: scan_ready error: error diff --git a/.claude/skills/team-quality-assurance/role-specs/strategist.md b/.claude/skills/team-quality-assurance/role-specs/strategist.md index f617983f..abb58886 100644 --- a/.claude/skills/team-quality-assurance/role-specs/strategist.md +++ b/.claude/skills/team-quality-assurance/role-specs/strategist.md @@ -1,7 +1,7 @@ --- prefix: QASTRAT inner_loop: false -subagents: [] +additional_members: [] message_types: success: strategy_ready error: error diff --git a/.claude/skills/team-quality-assurance/roles/coordinator/commands/monitor.md b/.claude/skills/team-quality-assurance/roles/coordinator/commands/monitor.md index af344221..ee73bc13 100644 --- a/.claude/skills/team-quality-assurance/roles/coordinator/commands/monitor.md +++ b/.claude/skills/team-quality-assurance/roles/coordinator/commands/monitor.md @@ -132,7 +132,7 @@ const STAGE_WORKER_MAP = { ``` Agent({ - subagent_type: "team-worker", + agent_type: "team-worker", description: "Spawn worker for ", team_name: "quality-assurance", name: "", diff --git a/.claude/skills/team-quality-assurance/roles/coordinator/role.md b/.claude/skills/team-quality-assurance/roles/coordinator/role.md index b35598f9..506608f0 100644 --- a/.claude/skills/team-quality-assurance/roles/coordinator/role.md +++ b/.claude/skills/team-quality-assurance/roles/coordinator/role.md @@ -17,7 +17,7 @@ Orchestrate the Quality Assurance workflow: requirement clarification, mode sele ### MUST NOT - Directly execute any business tasks (scanning, testing, analysis, etc.) -- Directly invoke implementation subagents (cli-explore-agent, code-developer, etc.) +- Directly invoke implementation CLI tools (cli-explore-agent, code-developer, etc.) - Directly modify source code or generated artifact files - Bypass worker roles to complete delegated work - Omit `[coordinator]` identifier in any output diff --git a/.claude/skills/team-quality-assurance/specs/team-config.json b/.claude/skills/team-quality-assurance/specs/team-config.json index 98f22511..50db404b 100644 --- a/.claude/skills/team-quality-assurance/specs/team-config.json +++ b/.claude/skills/team-quality-assurance/specs/team-config.json @@ -24,7 +24,7 @@ "message_types_received": [], "commands": ["scan"], "cli_tools": ["gemini"], - "subagents": ["cli-explore-agent"] + "cli_tools": ["gemini"] }, "strategist": { "name": "strategist", @@ -35,7 +35,7 @@ "message_types_received": [], "commands": ["analyze-scope"], "cli_tools": ["gemini"], - "subagents": ["cli-explore-agent"] + "cli_tools": ["gemini"] }, "generator": { "name": "generator", @@ -46,7 +46,7 @@ "message_types_received": [], "commands": ["generate-tests"], "cli_tools": ["gemini"], - "subagents": ["code-developer"] + "cli_tools": ["gemini"] }, "executor": { "name": "executor", @@ -56,7 +56,7 @@ "message_types_sent": ["tests_passed", "tests_failed", "coverage_report", "error"], "message_types_received": [], "commands": ["run-fix-cycle"], - "subagents": ["code-developer"] + "cli_tools": ["gemini"] }, "analyst": { "name": "analyst", diff --git a/.claude/skills/team-review/SKILL.md b/.claude/skills/team-review/SKILL.md index ab43148e..c2803d00 100644 --- a/.claude/skills/team-review/SKILL.md +++ b/.claude/skills/team-review/SKILL.md @@ -202,7 +202,7 @@ Cross-task knowledge accumulation. Coordinator creates `wisdom/` directory at se | Use tools declared in Toolbox | Create tasks for other roles | | Delegate to commands/ files | Modify resources outside own responsibility | -Coordinator additional restrictions: Do not write/modify code directly, do not call implementation subagents, do not execute analysis/test/review directly. +Coordinator additional restrictions: Do not write/modify code directly, do not call implementation CLI tools, do not execute analysis/test/review directly. ### Team Configuration @@ -225,7 +225,7 @@ When coordinator spawns workers, use `team-worker` agent with role-spec path: ``` Agent({ - subagent_type: "team-worker", + agent_type: "team-worker", description: "Spawn worker", team_name: "review", name: "", diff --git a/.claude/skills/team-review/roles/coordinator/commands/monitor.md b/.claude/skills/team-review/roles/coordinator/commands/monitor.md index d40a66f2..3a4888f2 100644 --- a/.claude/skills/team-review/roles/coordinator/commands/monitor.md +++ b/.claude/skills/team-review/roles/coordinator/commands/monitor.md @@ -144,7 +144,7 @@ Ready tasks found? ``` Agent({ - subagent_type: "team-worker", + agent_type: "team-worker", description: "Spawn worker for ", team_name: "review", name: "", diff --git a/.claude/skills/team-review/roles/coordinator/role.md b/.claude/skills/team-review/roles/coordinator/role.md index f531f842..cde363c4 100644 --- a/.claude/skills/team-review/roles/coordinator/role.md +++ b/.claude/skills/team-review/roles/coordinator/role.md @@ -26,7 +26,7 @@ Code review team coordinator. Orchestrates the scan-review-fix pipeline (CP-1 Li - Perform code review analysis - Bypass worker roles to do delegated work - Omit `[coordinator]` prefix on any output -- Call implementation subagents directly +- Call implementation CLI tools directly > **Core principle**: coordinator is the orchestrator, not the executor. All actual work delegated to scanner/reviewer/fixer via task chain. diff --git a/.claude/skills/team-roadmap-dev/SKILL.md b/.claude/skills/team-roadmap-dev/SKILL.md index d61115e9..af2c7f40 100644 --- a/.claude/skills/team-roadmap-dev/SKILL.md +++ b/.claude/skills/team-roadmap-dev/SKILL.md @@ -192,7 +192,7 @@ All outputs must carry `[role_name]` prefix. | Allowed | Forbidden | |---------|-----------| | Discuss roadmap with user (AskUserQuestion) | Direct code writing/modification | -| Create task chain (TaskCreate) | Calling implementation subagents | +| Create task chain (TaskCreate) | Calling CLI tools for implementation | | Dispatch tasks to workers | Direct analysis/testing/verification | | Monitor progress (message bus) | Bypassing workers | | Report results to user | Modifying source code | diff --git a/.claude/skills/team-roadmap-dev/role-specs/executor.md b/.claude/skills/team-roadmap-dev/role-specs/executor.md index 0abca649..06dae694 100644 --- a/.claude/skills/team-roadmap-dev/role-specs/executor.md +++ b/.claude/skills/team-roadmap-dev/role-specs/executor.md @@ -1,8 +1,8 @@ --- prefix: EXEC inner_loop: true -subagents: - - code-developer +cli_tools: + - gemini --mode write message_types: success: exec_complete progress: exec_progress @@ -11,7 +11,7 @@ message_types: # Executor -Wave-based code implementation per phase. Reads IMPL-*.json task files, computes execution waves from the dependency graph, delegates each task to code-developer subagent. Produces summary-{IMPL-ID}.md per task. +Wave-based code implementation per phase. Reads IMPL-*.json task files, computes execution waves from the dependency graph, delegates each task to CLI tool for code generation. Produces summary-{IMPL-ID}.md per task. ## Phase 2: Context Loading @@ -38,13 +38,24 @@ Execute waves sequentially, tasks within each wave can be parallel. | Task Count | Strategy | |------------|----------| | <= 2 | Direct: inline Edit/Write | -| 3-5 | Single code-developer for all | -| > 5 | Batch: one code-developer per module group | +| 3-5 | Single CLI tool call for all | +| > 5 | Batch: one CLI tool call per module group | **Per task**: 1. Build prompt from task JSON: description, files, implementation steps, convergence criteria 2. Include prior summaries and wisdom as context -3. Delegate to code-developer subagent (`run_in_background: false`) +3. Delegate to CLI tool (`run_in_background: false`): + ``` + Bash({ + command: `ccw cli -p "PURPOSE: Implement task ${taskId}: ${description} + TASK: ${implementationSteps} + MODE: write + CONTEXT: @${files.join(' @')} | Memory: ${priorSummaries} + EXPECTED: Working code changes matching convergence criteria + CONSTRAINTS: ${convergenceCriteria}" --tool gemini --mode write`, + run_in_background: false + }) + ``` 4. Write `/phase-{N}/summary-{IMPL-ID}.md` with: task ID, affected files, changes made, status **Between waves**: report wave progress via team_msg (type: exec_progress) diff --git a/.claude/skills/team-roadmap-dev/role-specs/planner.md b/.claude/skills/team-roadmap-dev/role-specs/planner.md index 7ae1353b..3aa37cd2 100644 --- a/.claude/skills/team-roadmap-dev/role-specs/planner.md +++ b/.claude/skills/team-roadmap-dev/role-specs/planner.md @@ -1,9 +1,8 @@ --- prefix: PLAN inner_loop: true -subagents: - - cli-explore-agent - - action-planning-agent +cli_tools: + - gemini --mode analysis message_types: success: plan_ready progress: plan_progress @@ -12,7 +11,7 @@ message_types: # Planner -Research and plan creation per roadmap phase. Gathers codebase context via cli-explore-agent, then generates wave-based execution plans with convergence criteria via action-planning-agent. +Research and plan creation per roadmap phase. Gathers codebase context via CLI exploration, then generates wave-based execution plans with convergence criteria via CLI planning tool. ## Phase 2: Context Loading + Research @@ -27,7 +26,18 @@ Research and plan creation per roadmap phase. Gathers codebase context via cli-e 2. Read config.json for depth setting (quick/standard/comprehensive) 3. Load prior phase summaries for dependency context 4. Detect gap closure mode (task description contains "Gap closure") -5. Launch cli-explore-agent with phase requirements as exploration query: +5. Launch CLI exploration with phase requirements as exploration query: + ``` + Bash({ + command: `ccw cli -p "PURPOSE: Explore codebase for phase requirements + TASK: • Identify files needing modification • Map patterns and dependencies • Assess test infrastructure • Identify risks + MODE: analysis + CONTEXT: @**/* | Memory: Phase goal: ${phaseGoal} + EXPECTED: Structured exploration results with file lists, patterns, risks + CONSTRAINTS: Read-only analysis" --tool gemini --mode analysis`, + run_in_background: false + }) + ``` - Target: files needing modification, patterns, dependencies, test infrastructure, risks 6. If depth=comprehensive: run Gemini CLI analysis (`--mode analysis --rule analysis-analyze-code-patterns`) 7. Write `/phase-{N}/context.md` combining roadmap requirements + exploration results @@ -36,12 +46,19 @@ Research and plan creation per roadmap phase. Gathers codebase context via cli-e 1. Load context.md from Phase 2 2. Create output directory: `/phase-{N}/.task/` -3. Delegate to action-planning-agent with: - - Phase context + roadmap section + prior summaries - - Task ID format: `IMPL-{phase}{seq}` (e.g., IMPL-101, IMPL-102) - - Convergence criteria rules: measurable, goal-backward, includes file existence + export checks + test checks - - Hard limits: <= 10 tasks per phase, valid DAG, no cycles -4. Agent produces: `IMPL_PLAN.md`, `.task/IMPL-*.json`, `TODO_LIST.md` +3. Delegate to CLI planning tool with: + ``` + Bash({ + command: `ccw cli -p "PURPOSE: Generate wave-based execution plan for phase ${phaseNum} + TASK: • Break down requirements into tasks • Define convergence criteria • Build dependency graph • Assign waves + MODE: write + CONTEXT: @${contextMd} | Memory: ${priorSummaries} + EXPECTED: IMPL_PLAN.md + IMPL-*.json files + TODO_LIST.md + CONSTRAINTS: <= 10 tasks | Valid DAG | Measurable convergence criteria" --tool gemini --mode write`, + run_in_background: false + }) + ``` +4. CLI tool produces: `IMPL_PLAN.md`, `.task/IMPL-*.json`, `TODO_LIST.md` 5. If gap closure: only create tasks for gaps, starting from next available ID ## Phase 4: Self-Validation diff --git a/.claude/skills/team-roadmap-dev/role-specs/verifier.md b/.claude/skills/team-roadmap-dev/role-specs/verifier.md index 192291d9..af40a941 100644 --- a/.claude/skills/team-roadmap-dev/role-specs/verifier.md +++ b/.claude/skills/team-roadmap-dev/role-specs/verifier.md @@ -1,7 +1,8 @@ --- prefix: VERIFY inner_loop: true -subagents: [] +cli_tools: + - gemini --mode analysis message_types: success: verify_passed failure: gaps_found diff --git a/.claude/skills/team-roadmap-dev/roles/coordinator/commands/monitor.md b/.claude/skills/team-roadmap-dev/roles/coordinator/commands/monitor.md index 7bed1275..53c56800 100644 --- a/.claude/skills/team-roadmap-dev/roles/coordinator/commands/monitor.md +++ b/.claude/skills/team-roadmap-dev/roles/coordinator/commands/monitor.md @@ -15,8 +15,8 @@ Handle all coordinator monitoring events for the roadmap-dev pipeline using the | Prefix | Role | Role Spec | inner_loop | |--------|------|-----------|------------| -| PLAN | planner | `.claude/skills/team-roadmap-dev/role-specs/planner.md` | true (subagents: cli-explore-agent, action-planning-agent) | -| EXEC | executor | `.claude/skills/team-roadmap-dev/role-specs/executor.md` | true (subagents: code-developer) | +| PLAN | planner | `.claude/skills/team-roadmap-dev/role-specs/planner.md` | true (cli_tools: gemini --mode analysis) | +| EXEC | executor | `.claude/skills/team-roadmap-dev/role-specs/executor.md` | true (cli_tools: gemini --mode write) | | VERIFY | verifier | `.claude/skills/team-roadmap-dev/role-specs/verifier.md` | true | ### Pipeline Structure diff --git a/.claude/skills/team-roadmap-dev/roles/coordinator/commands/roadmap-discuss.md b/.claude/skills/team-roadmap-dev/roles/coordinator/commands/roadmap-discuss.md index 88341e67..7aa566c9 100644 --- a/.claude/skills/team-roadmap-dev/roles/coordinator/commands/roadmap-discuss.md +++ b/.claude/skills/team-roadmap-dev/roles/coordinator/commands/roadmap-discuss.md @@ -13,7 +13,7 @@ Discuss project roadmap with the user using project-tech.json + specs/*.md as co ## Strategy -Direct interaction via AskUserQuestion. No delegation to workers or subagents. Coordinator handles this entirely. +Direct interaction via AskUserQuestion. No delegation to workers or CLI tools. Coordinator handles this entirely. ## Parameters @@ -130,7 +130,7 @@ if (!autoYes) { ### Step 6: Analyze Codebase and Generate Phased Roadmap ```javascript -// Use Gemini CLI (or cli-explore-agent) to analyze the codebase +// Use Gemini CLI (or CLI exploration tool) to analyze the codebase // and generate a phased breakdown based on goal + project context Bash({ command: `ccw cli -p "PURPOSE: Analyze codebase and generate phased execution roadmap for: ${projectGoal} diff --git a/.claude/skills/team-roadmap-dev/roles/coordinator/role.md b/.claude/skills/team-roadmap-dev/roles/coordinator/role.md index b9c28329..22f3b665 100644 --- a/.claude/skills/team-roadmap-dev/roles/coordinator/role.md +++ b/.claude/skills/team-roadmap-dev/roles/coordinator/role.md @@ -18,7 +18,7 @@ Orchestrate the roadmap-driven development workflow: init prerequisites -> roadm - Manage state.md updates at every phase transition - Route verifier gap results to planner for closure - Parse user requirements and clarify ambiguous inputs via AskUserQuestion -- Create team and spawn worker subagents in background +- Create team and spawn worker team members in background - Dispatch tasks with proper dependency chains - Monitor progress via worker callbacks and route messages - Maintain session state persistence @@ -26,7 +26,7 @@ Orchestrate the roadmap-driven development workflow: init prerequisites -> roadm ### MUST NOT - Execute any business tasks (code, analysis, testing, verification) -- Call code-developer, cli-explore-agent, or other implementation subagents +- Call CLI tools for code generation, exploration, or planning - Modify source code or generate implementation artifacts - Bypass worker roles to do work directly - Skip roadmap discussion phase diff --git a/.claude/skills/team-roadmap-dev/specs/team-config.json b/.claude/skills/team-roadmap-dev/specs/team-config.json index 823689b1..2970744f 100644 --- a/.claude/skills/team-roadmap-dev/specs/team-config.json +++ b/.claude/skills/team-roadmap-dev/specs/team-config.json @@ -29,9 +29,8 @@ "display_name": "RD Planner", "responsibility_type": "Orchestration", "task_prefix": "PLAN", - "description": "Research, context gathering, task JSON generation via action-planning-agent", + "description": "Research, context gathering, task JSON generation via CLI planning tool", "commands": ["research", "create-plans"], - "subagents": ["cli-explore-agent", "action-planning-agent"], "cli_tools": [{"tool": "gemini", "mode": "analysis"}], "message_types": ["plan_ready", "plan_progress", "error"] }, @@ -42,7 +41,7 @@ "task_prefix": "EXEC", "description": "Code implementation from IMPL-*.json tasks, wave-based parallel execution", "commands": ["implement"], - "subagents": ["code-developer"], + "cli_tools": [{"tool": "gemini", "mode": "write"}], "message_types": ["exec_complete", "exec_progress", "error"] }, { diff --git a/.claude/skills/team-tech-debt/SKILL.md b/.claude/skills/team-tech-debt/SKILL.md index b91d8b29..c956ee73 100644 --- a/.claude/skills/team-tech-debt/SKILL.md +++ b/.claude/skills/team-tech-debt/SKILL.md @@ -224,7 +224,7 @@ TDSCAN-001 内部并行架构: ┌────────────────────────────────────────────────────┐ │ Scanner Worker │ │ │ - │ Fan-out A: Subagent Exploration (并行 cli-explore) │ + │ Fan-out A: CLI Exploration (parallel CLI explore) │ │ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ │ │structure │ │patterns │ │deps │ │ │ │角度 │ │角度 │ │角度 │ │ diff --git a/.claude/skills/team-tech-debt/role-specs/executor.md b/.claude/skills/team-tech-debt/role-specs/executor.md index b413c351..8441b1f3 100644 --- a/.claude/skills/team-tech-debt/role-specs/executor.md +++ b/.claude/skills/team-tech-debt/role-specs/executor.md @@ -9,7 +9,7 @@ message_types: # Tech Debt Executor -Debt cleanup executor. Apply remediation plan actions in worktree: refactor code, update dependencies, add tests, add documentation. Batch-delegate to code-developer subagent, self-validate after each batch. +Debt cleanup executor. Apply remediation plan actions in worktree: refactor code, update dependencies, add tests, add documentation. Batch-delegate to CLI tools, self-validate after each batch. ## Phase 2: Load Remediation Plan @@ -32,14 +32,24 @@ Debt cleanup executor. Apply remediation plan actions in worktree: refactor code ## Phase 3: Execute Fixes -For each batch, delegate to `code-developer` subagent (synchronous, `run_in_background: false`): +For each batch, use CLI tool for implementation: **Worktree constraint**: ALL file operations and commands must execute within worktree path. Use `cd "" && ...` prefix for all Bash commands. **Per-batch delegation**: -- Provide batch type prompt (refactor/update-deps/add-tests/add-docs/restructure) -- List all items with file paths, descriptions, and fix steps -- Enforce: read files before modifying, minimal changes, backward compatibility, no new features, no suppressions + +```bash +ccw cli -p "PURPOSE: Apply tech debt fixes in batch; success = all items fixed without breaking changes +TASK: +MODE: write +CONTEXT: @/**/* | Memory: Remediation plan context +EXPECTED: Code changes that fix debt items, maintain backward compatibility, pass existing tests +CONSTRAINTS: Minimal changes only | No new features | No suppressions | Read files before modifying +Batch type: +Items: " --tool gemini --mode write --cd "" +``` + +Wait for CLI completion before proceeding to next batch. **Fix Results Tracking**: diff --git a/.claude/skills/team-tech-debt/role-specs/scanner.md b/.claude/skills/team-tech-debt/role-specs/scanner.md index d2b6aebd..709d8485 100644 --- a/.claude/skills/team-tech-debt/role-specs/scanner.md +++ b/.claude/skills/team-tech-debt/role-specs/scanner.md @@ -1,7 +1,6 @@ --- prefix: TDSCAN inner_loop: false -subagents: [] message_types: success: scan_complete error: error @@ -47,8 +46,8 @@ Multi-dimension tech debt scanner. Scan codebase across 5 dimensions (code, arch | Score | Complexity | Strategy | |-------|------------|----------| -| >= 4 | High | Triple Fan-out: subagent explore + CLI 5 dimensions + multi-perspective Gemini | -| 2-3 | Medium | Dual Fan-out: subagent explore + CLI 3 dimensions | +| >= 4 | High | Triple Fan-out: CLI explore + CLI 5 dimensions + multi-perspective Gemini | +| 2-3 | Medium | Dual Fan-out: CLI explore + CLI 3 dimensions | | 0-1 | Low | Inline: ACE search + Grep | ## Phase 3: Multi-Dimension Scan @@ -58,7 +57,7 @@ Multi-dimension tech debt scanner. Scan codebase across 5 dimensions (code, arch - Classify findings into dimensions **Medium/High Complexity** (Fan-out): -- Fan-out A: Subagent exploration (structure, patterns, dependencies angles) via `cli-explore-agent` +- Fan-out A: CLI exploration (structure, patterns, dependencies angles) via `ccw cli --tool gemini --mode analysis` - Fan-out B: CLI dimension analysis (parallel gemini per dimension -- code, architecture, testing, dependency, documentation) - Fan-out C (High only): Multi-perspective Gemini analysis (security, performance, code-quality, architecture) - Fan-in: Merge results, cross-deduplicate by file:line, boost severity for multi-source findings diff --git a/.claude/skills/team-tech-debt/role-specs/validator.md b/.claude/skills/team-tech-debt/role-specs/validator.md index 38b6468c..d96c969f 100644 --- a/.claude/skills/team-tech-debt/role-specs/validator.md +++ b/.claude/skills/team-tech-debt/role-specs/validator.md @@ -58,8 +58,18 @@ Execute 4-layer validation (all commands in worktree): - improvement_percentage = ((before - after) / before) * 100 **Auto-fix attempt** (when total_regressions <= 3): -- Spawn code-developer subagent to fix regressions in worktree -- Constraints: fix only regressions, preserve debt cleanup changes, no suppressions +- Use CLI tool to fix regressions in worktree: + ``` + Bash({ + command: `cd "${worktreePath}" && ccw cli -p "PURPOSE: Fix regressions found in validation + TASK: ${regressionDetails} + MODE: write + CONTEXT: @${modifiedFiles.join(' @')} + EXPECTED: Fixed regressions + CONSTRAINTS: Fix only regressions | Preserve debt cleanup changes | No suppressions" --tool gemini --mode write`, + run_in_background: false + }) + ``` - Re-run checks after fix attempt ## Phase 4: Compare & Report diff --git a/.claude/skills/team-tech-debt/roles/coordinator/role.md b/.claude/skills/team-tech-debt/roles/coordinator/role.md index 5b63b956..33b8f53c 100644 --- a/.claude/skills/team-tech-debt/roles/coordinator/role.md +++ b/.claude/skills/team-tech-debt/roles/coordinator/role.md @@ -19,7 +19,7 @@ ### MUST NOT - Execute tech debt work directly (delegate to workers) - Modify task outputs (workers own their deliverables) -- Call implementation subagents directly (cli-explore-agent, code-developer, etc.) +- Call CLI tools for analysis, exploration, or code generation - Modify source code or generate artifact files directly - Bypass worker roles to complete delegated work - Skip dependency validation when creating task chains @@ -100,7 +100,7 @@ For callback/check/resume/complete: load `commands/monitor.md` and execute match | `Task` | Tool | Phase 4 | Worker spawning | | `AskUserQuestion` | Tool | Phase 1 | Requirement clarification | -> Coordinator does not directly use CLI analysis tools or implementation subagents +> Coordinator does not directly use CLI analysis tools or CLI code generation --- diff --git a/.claude/skills/team-tech-debt/specs/team-config.json b/.claude/skills/team-tech-debt/specs/team-config.json index 0de6ce83..4350134c 100644 --- a/.claude/skills/team-tech-debt/specs/team-config.json +++ b/.claude/skills/team-tech-debt/specs/team-config.json @@ -23,8 +23,7 @@ "message_types_sent": ["scan_complete", "debt_items_found", "error"], "message_types_received": [], "commands": ["scan-debt"], - "cli_tools": ["gemini"], - "subagents": ["cli-explore-agent"] + "cli_tools": ["gemini"] }, "assessor": { "name": "assessor", @@ -44,8 +43,7 @@ "message_types_sent": ["plan_ready", "plan_revision", "error"], "message_types_received": [], "commands": ["create-plan"], - "cli_tools": ["gemini"], - "subagents": ["cli-explore-agent"] + "cli_tools": ["gemini"] }, "executor": { "name": "executor", @@ -55,7 +53,7 @@ "message_types_sent": ["fix_complete", "fix_progress", "error"], "message_types_received": [], "commands": ["remediate"], - "subagents": ["code-developer"] + "cli_tools": [{"tool": "gemini", "mode": "write"}] }, "validator": { "name": "validator", @@ -65,8 +63,7 @@ "message_types_sent": ["validation_complete", "regression_found", "error"], "message_types_received": [], "commands": ["verify"], - "subagents": ["code-developer"], - "cli_tools": ["gemini"] + "cli_tools": [{"tool": "gemini", "mode": "write"}] } }, diff --git a/.claude/skills/team-testing/role-specs/executor.md b/.claude/skills/team-testing/role-specs/executor.md index c22829d1..f65d3642 100644 --- a/.claude/skills/team-testing/role-specs/executor.md +++ b/.claude/skills/team-testing/role-specs/executor.md @@ -49,7 +49,7 @@ Glob("//**/*") | 2 | Parse results: pass rate + coverage | | 3 | pass_rate >= 0.95 AND coverage >= target -> success, exit | | 4 | Extract failing test details | -| 5 | Delegate fix to code-developer subagent | +| 5 | Delegate fix to CLI tool (gemini write mode) | | 6 | Increment iteration; >= 3 -> exit with failures | ``` diff --git a/.claude/skills/team-uidesign/SKILL.md b/.claude/skills/team-uidesign/SKILL.md index ff34b43f..2373a413 100644 --- a/.claude/skills/team-uidesign/SKILL.md +++ b/.claude/skills/team-uidesign/SKILL.md @@ -142,7 +142,7 @@ Cross-task knowledge accumulation. Coordinator creates `wisdom/` directory at se | Share state via team_msg(type='state_update') | Create tasks for other roles | | Delegate to commands/ files | Modify resources outside own responsibility | -Coordinator additional restrictions: Do not write/modify code directly, do not call implementation subagents, do not execute analysis/audits, do not bypass workers. +Coordinator additional restrictions: Do not write/modify code directly, do not spawn implementation workers directly, do not execute analysis/audits, do not bypass workers. ### Output Tagging diff --git a/.claude/skills/team-uidesign/role-specs/researcher.md b/.claude/skills/team-uidesign/role-specs/researcher.md index 14073429..35594dd0 100644 --- a/.claude/skills/team-uidesign/role-specs/researcher.md +++ b/.claude/skills/team-uidesign/role-specs/researcher.md @@ -1,7 +1,7 @@ --- prefix: RESEARCH inner_loop: false -subagents: [explore] +additional_members: [explore] message_types: success: research_ready progress: research_progress @@ -32,7 +32,7 @@ Analyze existing design system, build component inventory, assess accessibility | @shadcn/ui | shadcn | | (default) | html-tailwind | -3. Use `explore` subagent to scan for existing design tokens, component files, styling patterns +3. Use CLI tools (e.g., `ccw cli -p "..." --tool gemini --mode analysis`) or direct tools (Glob, Grep, mcp__ace-tool__search_context) to scan for existing design tokens, component files, styling patterns 4. Read industry context from session config (industry, strictness, must-have features) ## Phase 3: Research Execution diff --git a/.claude/skills/team-ultra-analyze/role-specs/analyst.md b/.claude/skills/team-ultra-analyze/role-specs/analyst.md index 44b74c1f..0f1d222b 100644 --- a/.claude/skills/team-ultra-analyze/role-specs/analyst.md +++ b/.claude/skills/team-ultra-analyze/role-specs/analyst.md @@ -2,7 +2,7 @@ prefix: ANALYZE inner_loop: false additional_prefixes: [ANALYZE-fix] -subagents: [] +additional_members: [] message_types: success: analysis_ready error: error diff --git a/.claude/skills/team-ultra-analyze/role-specs/discussant.md b/.claude/skills/team-ultra-analyze/role-specs/discussant.md index d480dd3a..818602c9 100644 --- a/.claude/skills/team-ultra-analyze/role-specs/discussant.md +++ b/.claude/skills/team-ultra-analyze/role-specs/discussant.md @@ -1,7 +1,7 @@ --- prefix: DISCUSS inner_loop: false -subagents: [] +additional_members: [] message_types: success: discussion_processed error: error @@ -40,9 +40,9 @@ Select strategy by discussion type: | Type | Mode | Description | |------|------|-------------| | initial | inline | Aggregate all analyses: convergent themes, conflicts, top discussion points | -| deepen | subagent | Spawn cli-explore-agent to investigate open questions deeper | +| deepen | cli | Use CLI tool to investigate open questions deeper | | direction-adjusted | cli | Re-analyze via `ccw cli` from adjusted perspective | -| specific-questions | subagent | Targeted exploration answering user questions | +| specific-questions | cli | Targeted exploration answering user questions | **initial**: Cross-perspective summary -- identify convergent themes, conflicting views, top 5 discussion points and open questions from all analyses. diff --git a/.claude/skills/team-ultra-analyze/role-specs/explorer.md b/.claude/skills/team-ultra-analyze/role-specs/explorer.md index e42d9e8f..ea432417 100644 --- a/.claude/skills/team-ultra-analyze/role-specs/explorer.md +++ b/.claude/skills/team-ultra-analyze/role-specs/explorer.md @@ -1,7 +1,7 @@ --- prefix: EXPLORE inner_loop: false -subagents: [] +additional_members: [] message_types: success: exploration_ready error: error diff --git a/.claude/skills/team-ultra-analyze/role-specs/synthesizer.md b/.claude/skills/team-ultra-analyze/role-specs/synthesizer.md index 5a114430..5690e3bf 100644 --- a/.claude/skills/team-ultra-analyze/role-specs/synthesizer.md +++ b/.claude/skills/team-ultra-analyze/role-specs/synthesizer.md @@ -1,7 +1,7 @@ --- prefix: SYNTH inner_loop: false -subagents: [] +additional_members: [] message_types: success: synthesis_ready error: error diff --git a/.claude/skills/team-ultra-analyze/specs/team-config.json b/.claude/skills/team-ultra-analyze/specs/team-config.json index 5fb7f468..4d5d7745 100644 --- a/.claude/skills/team-ultra-analyze/specs/team-config.json +++ b/.claude/skills/team-ultra-analyze/specs/team-config.json @@ -23,8 +23,7 @@ "message_types_sent": ["exploration_ready", "error"], "message_types_received": [], "commands": ["explore"], - "subagents": ["cli-explore-agent"] - }, + "cli_tools": ["gemini"] }, "analyst": { "name": "analyst", "responsibility": "Read-only analysis (深度分析)", @@ -44,8 +43,7 @@ "message_types_received": [], "commands": ["deepen"], "cli_tools": ["gemini"], - "subagents": ["cli-explore-agent"] - }, + "cli_tools": ["gemini"] }, "synthesizer": { "name": "synthesizer", "responsibility": "Read-only analysis (综合结论)",