feat: add team-lifecycle-v5 with unified team-worker agent architecture

Replace v4's per-role boilerplate (7 role.md files sharing 60% code) with a single team-worker agent that handles Phase 1/5, message bus, consensus, and inner loop. Role-specific Phase 2-4 logic lives in lightweight role-spec files. Workers spawn as team-worker agents directly instead of general-purpose + Skill indirection, reducing total worker content by ~64%.
2026-03-01 15:03:57 +08:00 · 2026-02-27 19:02:22 +08:00
parent 017b258223
commit 47fe0d3bec
15 changed files with 3170 additions and 0 deletions
--- a/.claude/skills/team-lifecycle-v5/subagents/discuss-subagent.md
+++ b/.claude/skills/team-lifecycle-v5/subagents/discuss-subagent.md
@@ -0,0 +1,169 @@
+# 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:
+
+```
+Task({
+  subagent_type: "cli-discuss-agent",
+  run_in_background: false,
+  description: "Discuss <round-id>",
+  prompt: `## Multi-Perspective Critique: <round-id>
+
+### Input
+- Artifact: <artifact-path>
+- Round: <round-id>
+- Perspectives: <perspective-list>
+- Session: <session-folder>
+- Discovery Context: <session-folder>/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 <artifact-path>
+2. For each perspective, launch CLI analysis in background:
+   Bash(command="ccw cli -p 'PURPOSE: Analyze from <role> perspective for <round-id>
+   TASK: <focus-areas>
+   MODE: analysis
+   CONTEXT: Artifact content below
+   EXPECTED: JSON with strengths[], weaknesses[], suggestions[], rating (1-5)
+   CONSTRAINTS: Output valid JSON only
+
+   Artifact:
+   <artifact-content>' --tool <cli-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: <session-folder>/discussions/<round-id>-discussion.md
+
+### Discussion Record Format
+# Discussion Record: <round-id>
+
+**Artifact**: <artifact-path>
+**Perspectives**: <list>
+**Consensus**: reached / blocked
+**Average Rating**: <avg>/5
+
+## Convergent Themes
+- <theme>
+
+## Divergent Views
+- **<topic>** (<severity>): <description>
+
+## Action Items
+1. <item>
+
+## Ratings
+| Perspective | Rating |
+|-------------|--------|
+| <name> | <n>/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)**:
+
+```
+[<role>] <task-id> complete. Discuss <round-id>: consensus_blocked (severity=<severity>)
+Divergences: <top-3-divergent-points>
+Action items: <prioritized-items>
+Recommendation: <revise|proceed-with-caution|escalate>
+Artifact: <artifact-path>
+Discussion: <discussion-record-path>
+```
+
+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 |
--- a/.claude/skills/team-lifecycle-v5/subagents/doc-generation-subagent.md
+++ b/.claude/skills/team-lifecycle-v5/subagents/doc-generation-subagent.md
@@ -0,0 +1,62 @@
+# Doc Generation Subagent
+
+文档生成执行引擎。由 writer 主 agent 通过 Inner Loop 调用。
+负责 CLI 多视角分析 + 模板填充 + 文件写入。
+
+## Design Rationale
+
+从 v4.0 的 writer 内联 CLI 执行，改为 subagent 隔离调用。
+好处：CLI 调用的大量 token 消耗不污染 writer 主 agent 上下文，
+writer 只拿到压缩摘要，可在多任务间保持上下文连续。
+
+## Invocation
+
+```
+Task({
+  subagent_type: "universal-executor",
+  run_in_background: false,
+  description: "Generate <doc-type>",
+  prompt: `## Document Generation: <doc-type>
+
+### Session
+- Folder: <session-folder>
+- Spec config: <spec-config-path>
+
+### Document Config
+- Type: <product-brief | requirements | architecture | epics>
+- Template: <template-path>
+- Output: <output-path>
+- Prior discussion: <discussion-file or "none">
+
+### Writer Accumulator (prior decisions)
+<JSON array of prior task summaries>
+
+### Execution Strategy
+<从 generate-doc.md 对应 doc-type 段落加载>
+
+### Output Requirements
+1. Write document to <output-path> (follow template + document-standards.md)
+2. Return JSON summary:
+{
+  "artifact_path": "<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 决定是否继续 |
--- a/.claude/skills/team-lifecycle-v5/subagents/explore-subagent.md
+++ b/.claude/skills/team-lifecycle-v5/subagents/explore-subagent.md
@@ -0,0 +1,172 @@
+# 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
+
+```
+Task({
+  subagent_type: "cli-explore-agent",
+  run_in_background: false,
+  description: "Explore <angle>",
+  prompt: `Explore codebase for: <query>
+
+Focus angle: <angle>
+Keywords: <keyword-list>
+Session folder: <session-folder>
+
+## Cache Check
+1. Read <session-folder>/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
+<angle-specific-focus-from-table-below>
+
+## Output
+Write JSON to: <session-folder>/explorations/explore-<angle>.json
+Update cache-index.json with new entry
+
+## Output Schema
+{
+  "angle": "<angle>",
+  "query": "<query>",
+  "relevant_files": [
+    { "path": "...", "rationale": "...", "role": "...", "discovery_source": "...", "key_symbols": [] }
+  ],
+  "patterns": [],
+  "dependencies": [],
+  "external_refs": [],
+  "_metadata": { "created_by": "<calling-role>", "timestamp": "...", "cache_key": "..." }
+}
+
+Return summary: file count, pattern count, top 5 files, output path`
+})
+```
+
+## Cache Mechanism
+
+### Cache Index Schema
+
+`<session-folder>/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="<project-root>", query="<query>")
+```
+
+ACE failure fallback: `rg -l '<keywords>' --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
+Task({
+  subagent_type: "cli-explore-agent",
+  description: "Explore general context",
+  prompt: "Explore codebase for: <topic>\nFocus angle: general\n..."
+})
+# Result feeds into discovery-context.json
+```
+
+### planner (PLAN-001)
+
+```
+# Multi-angle exploration before plan generation
+for angle in selected_angles:
+  Task({
+    subagent_type: "cli-explore-agent",
+    description: "Explore <angle>",
+    prompt: "Explore codebase for: <task>\nFocus angle: <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 |