catlog22/Claude-Code-Workflow
1
0
Fork 0
mirror of https://github.com/catlog22/Claude-Code-Workflow.git synced 2026-03-05 16:13:08 +08:00
Code Issues Packages Projects Releases Wiki Activity

Add document standards, quality gates, and templates for team lifecycle phases

Browse Source 
- 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
2026-03-04 23:54:20 +08:00
parent fd0c9efa4d
commit bbdd1840de
103 changed files with 1959 additions and 1311 deletions
Download Patch File Download Diff File Expand all files Collapse all files

12
.claude/agents/team-worker.md
View File

@@ -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: "..." })

14
.claude/skills/team-arch-opt/SKILL.md
View File

@@ -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/<name>.md) |
| Command file not found | Fallback to inline execution in coordinator role.md |
| Subagent spec not found | Error with expected path (subagents/<name>-subagent.md) |
| CLI tool spec not found | Error with expected path (cli-tools/<name>.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 |

4
.claude/skills/team-arch-opt/role-specs/analyzer.md
View File

@@ -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

4
.claude/skills/team-arch-opt/role-specs/designer.md
View File

@@ -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).

4
.claude/skills/team-arch-opt/role-specs/refactorer.md
View File

@@ -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 `<session>/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**:

4
.claude/skills/team-arch-opt/role-specs/reviewer.md
View File

@@ -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

16
.claude/skills/team-arch-opt/specs/team-config.json
View File

@@ -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

123
.claude/skills/team-arch-opt/subagents/discuss-subagent.md
View File

@@ -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 <topic> for architecture optimization
TASK: • Evaluate architecture impact • Assess risks and trade-offs • Consider maintainability • Explore alternatives
MODE: analysis
CONTEXT: @<session-folder>/discussions/<round-id>.md | Memory: <relevant-context-from-calling-role>
EXPECTED: Structured recommendation with consensus verdict (proceed/revise/escalate), confidence level, key trade-offs, recommended approach with rationale, dissenting perspectives
CONSTRAINTS: Focus on <round-id> topic
Round: <round-id>
Topic: <discussion-topic>
Session: <session-folder>
Context:
<relevant-context-from-calling-role>
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: <round-id>
Topic: <discussion-topic>
Session: <session-folder>
Context:
<relevant-context-from-calling-role>
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 | <session>/discussions/DISCUSS-REFACTOR.md | Refactoring strategy trade-offs | designer |
| DISCUSS-REVIEW | <session>/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": "<DISCUSS-REFACTOR|DISCUSS-REVIEW>",
"topic": "<discussion-topic>",
"verdict": "<proceed|revise|escalate>",
"confidence": "<high|medium|low>",
"trade_offs": [
{ "dimension": "<architecture|risk|maintainability>", "pro": "<benefit>", "con": "<cost>" }
],
"recommendation": "<recommended-approach>",
"rationale": "<reasoning>",
"dissenting_views": ["<alternative-perspective>"]
}
```
## 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 |

113
.claude/skills/team-arch-opt/subagents/explore-subagent.md
View File

@@ -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 <target-scope>",
prompt: `Explore the codebase to identify architecture-critical structures.
Target scope: <target-scope>
Session: <session-folder>
Focus: <exploration-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
`<session-folder>/explorations/cache-index.json`:
```json
{
"entries": [
{
"key": "<scope-hash>",
"scope": "<target-scope>",
"focus": "<exploration-focus>",
"timestamp": "<ISO-8601>",
"result_file": "<hash>.md"
}
]
}
```
### Cache Lookup Rules
| Condition | Action |
|-----------|--------|
| Exact scope+focus match exists | Return cached result from <hash>.md |
| No match | Execute subagent, cache result to <hash>.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": "<target-scope>",
"module_map": [
{ "file": "<path>", "role": "<description>", "layer": "<presentation|domain|data|infra>", "dependency_graph": { "imports": ["<path>"], "imported_by": ["<path>"] } }
],
"dependency_graph": {
"nodes": ["<module-path>"],
"edges": [{ "from": "<path>", "to": "<path>", "type": "<import|re-export|dynamic>" }],
"cycles": [["<path-a>", "<path-b>", "<path-a>"]]
},
"layer_structure": [
{ "layer": "<name>", "modules": ["<path>"], "violations": ["<description>"] }
],
"existing_patterns": [
{ "type": "<pattern>", "location": "<file:line>", "description": "<what>" }
],
"investigation_targets": ["<file-or-pattern>"]
}
```
## 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 |

2
.claude/skills/team-brainstorm/role-specs/challenger.md
View File

@@ -1,7 +1,7 @@
---
prefix: CHALLENGE
inner_loop: false
subagents: []
delegates_to: []
message_types:
success: critique_ready
error: error

2
.claude/skills/team-brainstorm/role-specs/evaluator.md
View File

@@ -1,7 +1,7 @@
---
prefix: EVAL
inner_loop: false
subagents: []
delegates_to: []
message_types:
success: evaluation_ready
error: error

2
.claude/skills/team-brainstorm/role-specs/ideator.md
View File

@@ -1,7 +1,7 @@
---
prefix: IDEA
inner_loop: false
subagents: []
delegates_to: []
message_types:
success: ideas_ready
error: error

2
.claude/skills/team-brainstorm/role-specs/synthesizer.md
View File

@@ -1,7 +1,7 @@
---
prefix: SYNTH
inner_loop: false
subagents: []
delegates_to: []
message_types:
success: synthesis_ready
error: error

20
.claude/skills/team-coordinate/SKILL.md
View File

@@ -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) | `<session>/role-specs/<role-name>.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 |

4
.claude/skills/team-coordinate/roles/coordinator/commands/analyze-task.md
View File

@@ -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` | `<prefix>_complete` |
@@ -177,7 +177,7 @@ Write `<session-folder>/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": {

2
.claude/skills/team-coordinate/roles/coordinator/role.md
View File

@@ -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

14
.claude/skills/team-coordinate/specs/role-spec-template.md
View File

@@ -11,7 +11,7 @@ Template used by coordinator to generate lightweight worker role-spec files at r
role: <role_name>
prefix: <PREFIX>
inner_loop: <true|false>
subagents: [<subagent-names>]
CLI tools: [<CLI tool-names>]
message_types:
success: <prefix>_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 |
| `<placeholder>` 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

132
.claude/skills/team-coordinate/subagents/discuss-subagent.md
View File

@@ -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: <round-id>
### Input
- Artifact: <artifact-path>
- Round: <round-id>
- Session: <session-folder>
### Perspectives
<Dynamic perspective list -- each entry defines: name, cli_tool, role_label, focus_areas>
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 <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:
- 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: <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
- 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)**:
```
[<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>
```

120
.claude/skills/team-coordinate/subagents/explore-subagent.md
View File

@@ -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 <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 | 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="<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.
## 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 |

2
.claude/skills/team-executor/roles/executor/role.md
View File

@@ -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

2
.claude/skills/team-executor/specs/session-schema.md
View File

@@ -163,7 +163,7 @@ team-executor validates the following before execution:
"responsibility_type": "<type>",
"inner_loop": false,
"role_spec_metadata": {
"subagents": [],
"additional_members": [],
"message_types": {
"success": "<prefix>_complete",
"error": "error"

2
.claude/skills/team-frontend/role-specs/analyst.md
View File

@@ -1,7 +1,7 @@
---
prefix: ANALYZE
inner_loop: false
subagents: []
additional_members: []
message_types:
success: analyze_ready
error: error

2
.claude/skills/team-frontend/role-specs/architect.md
View File

@@ -1,7 +1,7 @@
---
prefix: ARCH
inner_loop: false
subagents: []
additional_members: []
message_types:
success: arch_ready
error: error

2
.claude/skills/team-frontend/role-specs/developer.md
View File

@@ -1,7 +1,7 @@
---
prefix: DEV
inner_loop: true
subagents: []
additional_members: []
message_types:
success: dev_complete
error: error

2
.claude/skills/team-frontend/role-specs/qa.md
View File

@@ -1,7 +1,7 @@
---
prefix: QA
inner_loop: false
subagents: []
additional_members: []
message_types:
success: qa_passed
error: error

6
.claude/skills/team-issue/role-specs/explorer.md
View File

@@ -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 <issueId> --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**:

4
.claude/skills/team-issue/role-specs/integrator.md
View File

@@ -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

4
.claude/skills/team-issue/role-specs/planner.md
View File

@@ -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

2
.claude/skills/team-issue/roles/coordinator/role.md
View File

@@ -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)
---

2
.claude/skills/team-iterdev/SKILL.md
View File

@@ -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

17
.claude/skills/team-iterdev/role-specs/tester.md
View File

@@ -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: @<changed-files> | 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: <test-failure-details>
Changed files: <file-list>" --tool gemini --mode write --rule development-debug-runtime-issues
```
Wait for CLI completion before re-running tests.
## Phase 4: Regression Check + Report

76
.claude/skills/team-lifecycle-v2/role-specs/architect.md Normal file
View File

@@ -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 `<session-folder>/architecture/arch-<slug>.json`. Contribute decisions to wisdom/decisions.md.
**Frontend project outputs** (when frontend tech stack detected):
- `<session-folder>/architecture/design-tokens.json` — color, spacing, typography, shadow tokens
- `<session-folder>/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 |

67
.claude/skills/team-lifecycle-v2/role-specs/executor.md Normal file
View File

@@ -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 `<session-folder>/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 |

79
.claude/skills/team-lifecycle-v2/role-specs/fe-developer.md Normal file
View File

@@ -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: `<session-folder>/plan/plan.json`
- Design tokens: `<session-folder>/architecture/design-tokens.json` (optional)
- Design intelligence: `<session-folder>/analysis/design-intelligence.json` (optional)
- Component specs: `<session-folder>/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 |

79
.claude/skills/team-lifecycle-v2/role-specs/fe-qa.md Normal file
View File

@@ -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 `<session-folder>/qa/audit-fe-<task>-r<round>.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 |

98
.claude/skills/team-lifecycle-v2/role-specs/planner.md Normal file
View File

@@ -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 `<session-folder>/spec/` exists → load requirements/_index.md, architecture/_index.md, epics/_index.md, spec-config.json. Otherwise → impl-only mode.
**Check shared explorations**: Read `<session-folder>/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 <angle> perspective to inform planning
TASK: • Search for <angle>-specific patterns • Identify relevant files • Document integration points
MODE: analysis
CONTEXT: @**/* | Memory: Task keywords: <keywords>
EXPECTED: JSON with: relevant_files[], patterns[], integration_points[], recommendations[]
CONSTRAINTS: Focus on <angle> 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: @<session-folder>/explorations/*.json | Memory: Complexity: <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**:
```
<session-folder>/explorations/ (shared cache)
+-- cache-index.json
+-- explore-<angle>.json
<session-folder>/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 |

76
.claude/skills/team-lifecycle-v2/role-specs/tester.md Normal file
View File

@@ -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: `<name>.test.ts`, `<name>.spec.ts`, `tests/<name>.test.ts`, `__tests__/<name>.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 <files>` | `vitest run` |
| jest | `jest <files> --no-coverage` | `jest --no-coverage` |
| pytest | `pytest <files> -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 |

192
.claude/skills/team-lifecycle-v2/specs/document-standards.md Normal file
View File

@@ -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

207
.claude/skills/team-lifecycle-v2/specs/quality-gates.md Normal file
View File

@@ -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

254
.claude/skills/team-lifecycle-v2/templates/architecture-doc.md Normal file
View File

@@ -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 |

196
.claude/skills/team-lifecycle-v2/templates/epics-template.md Normal file
View File

@@ -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 |

133
.claude/skills/team-lifecycle-v2/templates/product-brief.md Normal file
View File

@@ -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 |

224
.claude/skills/team-lifecycle-v2/templates/requirements-prd.md Normal file
View File

@@ -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 |

25
.claude/skills/team-lifecycle/SKILL.md
View File

@@ -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 |

6
.claude/skills/team-lifecycle/role-specs/analyst.md
View File

@@ -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 |

2
.claude/skills/team-lifecycle/role-specs/architect.md
View File

@@ -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

2
.claude/skills/team-lifecycle/role-specs/executor.md
View File

@@ -3,7 +3,7 @@ role: executor
prefix: IMPL
inner_loop: true
discuss_rounds: []
subagents: []
cli_tools: []
message_types:
success: impl_complete
progress: impl_progress

2
.claude/skills/team-lifecycle/role-specs/fe-developer.md
View File

@@ -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

2
.claude/skills/team-lifecycle/role-specs/fe-qa.md
View File

@@ -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

6
.claude/skills/team-lifecycle/role-specs/planner.md
View File

@@ -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):

14
.claude/skills/team-lifecycle/role-specs/reviewer.md
View File

@@ -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 |

2
.claude/skills/team-lifecycle/role-specs/tester.md
View File

@@ -3,7 +3,7 @@ role: tester
prefix: TEST
inner_loop: false
discuss_rounds: []
subagents: []
cli_tools: []
message_types:
success: test_result
fix: fix_required

16
.claude/skills/team-lifecycle/role-specs/writer.md
View File

@@ -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 |

3
.claude/skills/team-lifecycle/roles/coordinator/role.md
View File

@@ -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
---

24
.claude/skills/team-lifecycle/specs/team-config.json
View File

@@ -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"
}
},

169
.claude/skills/team-lifecycle/subagents/discuss-subagent.md
View File

@@ -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 |

62
.claude/skills/team-lifecycle/subagents/doc-generation-subagent.md
View File

@@ -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 决定是否继续 |

174
.claude/skills/team-lifecycle/subagents/explore-subagent.md
View File

@@ -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 |

12
.claude/skills/team-perf-opt/SKILL.md
View File

@@ -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/<name>.md) |
| Command file not found | Fallback to inline execution in coordinator role.md |
| Subagent spec not found | Error with expected path (subagents/<name>-subagent.md) |
| Role file not found | Error with expected path (role-specs/<name>.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 |

4
.claude/skills/team-perf-opt/role-specs/optimizer.md
View File

@@ -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 `<session>/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**:

4
.claude/skills/team-perf-opt/role-specs/profiler.md
View File

@@ -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

4
.claude/skills/team-perf-opt/role-specs/reviewer.md
View File

@@ -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

4
.claude/skills/team-perf-opt/role-specs/strategist.md
View File

@@ -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 %).

89
.claude/skills/team-perf-opt/subagents/discuss-subagent.md
View File

@@ -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 <round-id>: <topic> for performance optimization",
prompt: `Conduct a multi-perspective discussion on the following topic.
Round: <round-id>
Topic: <discussion-topic>
Session: <session-folder>
Context:
<relevant-context-from-calling-role>
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 | <session>/discussions/DISCUSS-OPT.md | Optimization strategy trade-offs | strategist |
| DISCUSS-REVIEW | <session>/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": "<DISCUSS-OPT|DISCUSS-REVIEW>",
"topic": "<discussion-topic>",
"verdict": "<proceed|revise|escalate>",
"confidence": "<high|medium|low>",
"trade_offs": [
{ "dimension": "<performance|risk|maintainability>", "pro": "<benefit>", "con": "<cost>" }
],
"recommendation": "<recommended-approach>",
"rationale": "<reasoning>",
"dissenting_views": ["<alternative-perspective>"]
}
```
## 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 |

108
.claude/skills/team-perf-opt/subagents/explore-subagent.md
View File

@@ -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 <target-scope>",
prompt: `Explore the codebase to identify performance-critical code paths.
Target scope: <target-scope>
Session: <session-folder>
Focus: <exploration-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
`<session-folder>/explorations/cache-index.json`:
```json
{
"entries": [
{
"key": "<scope-hash>",
"scope": "<target-scope>",
"focus": "<exploration-focus>",
"timestamp": "<ISO-8601>",
"result_file": "<hash>.md"
}
]
}
```
### Cache Lookup Rules
| Condition | Action |
|-----------|--------|
| Exact scope+focus match exists | Return cached result from <hash>.md |
| No match | Execute subagent, cache result to <hash>.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": "<target-scope>",
"module_map": [
{ "file": "<path>", "role": "<description>", "hot_path": true }
],
"hot_paths": [
{ "chain": "<call-chain>", "frequency": "<high|medium|low>", "files": ["<path>"] }
],
"existing_optimizations": [
{ "type": "<pattern>", "location": "<file:line>", "description": "<what>" }
],
"investigation_targets": ["<file-or-pattern>"]
}
```
## 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 |

2
.claude/skills/team-planex/SKILL.md
View File

@@ -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 <role> worker",
team_name: <team-name>,
name: "<role>",

2
.claude/skills/team-planex/role-specs/executor.md
View File

@@ -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 |

2
.claude/skills/team-planex/roles/coordinator/commands/monitor.md
View File

@@ -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 <role> worker for <subject>",
team_name: <team-name>,
name: "<role>",

2
.claude/skills/team-planex/roles/coordinator/role.md
View File

@@ -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
---

4
.claude/skills/team-quality-assurance/SKILL.md
View File

@@ -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 <role> worker",
team_name: "quality-assurance",
name: "<role>",
@@ -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 <role>-<N> worker",
team_name: "quality-assurance",
name: "<role>-<N>",

2
.claude/skills/team-quality-assurance/role-specs/analyst.md
View File

@@ -1,7 +1,7 @@
---
prefix: QAANA
inner_loop: false
subagents: []
additional_members: []
message_types:
success: analysis_ready
report: quality_report

4
.claude/skills/team-quality-assurance/role-specs/executor.md
View File

@@ -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`

4
.claude/skills/team-quality-assurance/role-specs/generator.md
View File

@@ -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 `<session>/results/run-<layer>.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

2
.claude/skills/team-quality-assurance/role-specs/scout.md
View File

@@ -1,7 +1,7 @@
---
prefix: SCOUT
inner_loop: false
subagents: []
additional_members: []
message_types:
success: scan_ready
error: error

2
.claude/skills/team-quality-assurance/role-specs/strategist.md
View File

@@ -1,7 +1,7 @@
---
prefix: QASTRAT
inner_loop: false
subagents: []
additional_members: []
message_types:
success: strategy_ready
error: error

2
.claude/skills/team-quality-assurance/roles/coordinator/commands/monitor.md
View File

@@ -132,7 +132,7 @@ const STAGE_WORKER_MAP = {
```
Agent({
subagent_type: "team-worker",
agent_type: "team-worker",
description: "Spawn <role> worker for <task-id>",
team_name: "quality-assurance",
name: "<role>",

2
.claude/skills/team-quality-assurance/roles/coordinator/role.md
View File

@@ -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

8
.claude/skills/team-quality-assurance/specs/team-config.json
View File

@@ -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",

4
.claude/skills/team-review/SKILL.md
View File

@@ -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 <role> worker",
team_name: "review",
name: "<role>",

2
.claude/skills/team-review/roles/coordinator/commands/monitor.md
View File

@@ -144,7 +144,7 @@ Ready tasks found?
```
Agent({
subagent_type: "team-worker",
agent_type: "team-worker",
description: "Spawn <role> worker for <subject>",
team_name: "review",
name: "<role>",

2
.claude/skills/team-review/roles/coordinator/role.md
View File

@@ -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.

2
.claude/skills/team-roadmap-dev/SKILL.md
View File

@@ -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 |

23
.claude/skills/team-roadmap-dev/role-specs/executor.md
View File

@@ -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 `<session>/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)

39
.claude/skills/team-roadmap-dev/role-specs/planner.md
View File

@@ -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 `<session>/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: `<session>/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

3
.claude/skills/team-roadmap-dev/role-specs/verifier.md
View File

@@ -1,7 +1,8 @@
---
prefix: VERIFY
inner_loop: true
subagents: []
cli_tools:
- gemini --mode analysis
message_types:
success: verify_passed
failure: gaps_found

4
.claude/skills/team-roadmap-dev/roles/coordinator/commands/monitor.md
View File

@@ -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

4
.claude/skills/team-roadmap-dev/roles/coordinator/commands/roadmap-discuss.md
View File

@@ -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}

4
.claude/skills/team-roadmap-dev/roles/coordinator/role.md
View File

@@ -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

5
.claude/skills/team-roadmap-dev/specs/team-config.json
View File

@@ -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"]
},
{

2
.claude/skills/team-tech-debt/SKILL.md
View File

@@ -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 │ │
│ │角度 │ │角度 │ │角度 │ │

20
.claude/skills/team-tech-debt/role-specs/executor.md
View File

@@ -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 "<worktree-path>" && ...` 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: <batch-type-specific-tasks>
MODE: write
CONTEXT: @<worktree-path>/**/* | 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: <refactor|update-deps|add-tests|add-docs|restructure>
Items: <list-of-items-with-file-paths-and-descriptions>" --tool gemini --mode write --cd "<worktree-path>"
```
Wait for CLI completion before proceeding to next batch.
**Fix Results Tracking**:

7
.claude/skills/team-tech-debt/role-specs/scanner.md
View File

@@ -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

14
.claude/skills/team-tech-debt/role-specs/validator.md
View File

@@ -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

4
.claude/skills/team-tech-debt/roles/coordinator/role.md
View File

@@ -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
---

11
.claude/skills/team-tech-debt/specs/team-config.json
View File

@@ -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"}]
}
},

2
.claude/skills/team-testing/role-specs/executor.md
View File

@@ -49,7 +49,7 @@ Glob("<session>/<test-dir>/**/*")
| 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 |
```

2
.claude/skills/team-uidesign/SKILL.md
View File

@@ -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

4
.claude/skills/team-uidesign/role-specs/researcher.md
View File

@@ -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

2
.claude/skills/team-ultra-analyze/role-specs/analyst.md
View File

@@ -2,7 +2,7 @@
prefix: ANALYZE
inner_loop: false
additional_prefixes: [ANALYZE-fix]
subagents: []
additional_members: []
message_types:
success: analysis_ready
error: error

6
.claude/skills/team-ultra-analyze/role-specs/discussant.md
View File

@@ -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.

Some files were not shown because too many files have changed in this diff Show More