mirror of
https://github.com/catlog22/Claude-Code-Workflow.git
synced 2026-03-05 16:13:08 +08:00
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.
This commit is contained in:
catlog22
@@ -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 |
|
||||
|
||||
@@ -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: `<session-folder>/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 |
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -3,7 +3,7 @@ role: executor
|
||||
prefix: IMPL
|
||||
inner_loop: true
|
||||
discuss_rounds: []
|
||||
subagents: []
|
||||
cli_tools: []
|
||||
message_types:
|
||||
success: impl_complete
|
||||
progress: impl_progress
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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 `<session-folder>/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):
|
||||
|
||||
|
||||
@@ -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: `<session-folder>/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: @<session-folder>/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 |
|
||||
|
||||
@@ -3,7 +3,7 @@ role: tester
|
||||
prefix: TEST
|
||||
inner_loop: false
|
||||
discuss_rounds: []
|
||||
subagents: []
|
||||
cli_tools: []
|
||||
message_types:
|
||||
success: test_result
|
||||
fix: fix_required
|
||||
|
||||
@@ -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 | `<session-folder>/discussions/<discuss-file>` | 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: `<output-path>` (the generated document)
|
||||
- Round: `<DISCUSS-NNN>` from mapping table
|
||||
- Perspectives: from mapping table
|
||||
|
||||
```bash
|
||||
ccw cli -p "PURPOSE: Multi-perspective critique of <doc-type>
|
||||
TASK: Review from <perspectives>
|
||||
ARTIFACT: @<output-path>
|
||||
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 |
|
||||
|
||||
@@ -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
|
||||
|
||||
---
|
||||
|
||||
@@ -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"
|
||||
}
|
||||
},
|
||||
|
||||
|
||||
@@ -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 <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 |
|
||||
@@ -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 <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 决定是否继续 |
|
||||
@@ -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 <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
|
||||
Agent({
|
||||
subagent_type: "cli-explore-agent",
|
||||
description: "Explore general context",
|
||||
run_in_background: false,
|
||||
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:
|
||||
Agent({
|
||||
subagent_type: "cli-explore-agent",
|
||||
description: "Explore <angle>",
|
||||
run_in_background: false,
|
||||
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 |
|
||||
Reference in New Issue
Block a user