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

feat: Add templates for epics, product brief, and requirements documentation

Browse Source 
- Introduced a comprehensive template for generating epics and stories in Phase 5, including an index and individual epic files.
- Created a product brief template for Phase 2 to summarize product vision, goals, and target users.
- Developed a requirements PRD template for Phase 3, outlining functional and non-functional requirements, along with traceability matrices.

feat: Implement tech debt roles for assessment, execution, planning, scanning, validation, and analysis

- Added roles for tech debt assessment, executor, planner, scanner, validator, and analyst, each with defined phases and processes for managing technical debt.
- Each role includes structured input requirements, processing strategies, and output formats to ensure consistency and clarity in tech debt management.
This commit is contained in:
catlog22
2026-03-07 13:32:04 +08:00
parent 7ee9b579fa
commit 29a1fea467
255 changed files with 14407 additions and 21120 deletions
Download Patch File Download Diff File Expand all files Collapse all files

11
.claude/commands/ddd/execute.md
View File

@@ -64,6 +64,7 @@ For each task with `doc_context`:
- Load referenced `component_docs` (tech-registry/{slug}.md)
- Load ADR excerpts from doc-index `architectureDecisions[]`
- Extract requirement acceptance criteria from doc-index `requirements[]`
- Load `doc_context.symbol_docs[]` documentation content (if present)
### 1.4 Echo Strategy
@@ -131,6 +132,16 @@ ${feature-map content excerpt — overview + requirements section}
${for each component in task.doc_context.component_ids:
tech-registry excerpt — responsibility + code locations + key patterns}
### Symbol Documentation
${if doc_context.symbol_docs is non-empty:
for each component in doc_context.component_ids:
#### ${component.name} Symbols (Top-5)
${for each symbol in component.symbol_docs.slice(0, 5):
- **${symbol.name}** (${symbol.type}): ${symbol.doc_summary}
Source: `${symbol.source_path}` | Freshness: ${symbol.freshness}
}
}
### Architecture Constraints
${for each ADR in task.doc_context.adr_ids:
ADR title + decision + rationale from doc-index}

37
.claude/commands/ddd/plan.md
View File

@@ -142,6 +142,17 @@ Assemble all found references into a structured impact map:
Save as `planning-context.md` (legacy format for backward compatibility).
### Phase 1.7: Symbol Query (DeepWiki Bridge)
If DeepWiki is available (`deepwiki_feature_to_symbol_index` exists in doc-index.json):
1. Collect all `codeLocations[].path` from matched `technicalComponents[]`
2. Query DeepWiki: `POST /api/deepwiki/symbols-for-paths { paths: unique_paths }`
3. Build symbol_docs by component, sorted by type priority (class > function > method)
4. Populate `doc_context.symbol_docs[]` with Top-5 symbols per component
**Graceful degradation**: If DeepWiki unavailable → log warning → skip symbol injection → continue flow.
---
## Phase 2: Doc-Index-Guided Exploration (NEW)
@@ -323,7 +334,18 @@ Follows `plan-overview-base-schema` with ddd-specific `doc_context` extension:
"affected_requirements": ["REQ-001", "REQ-002"],
"affected_components": ["tech-auth-service"],
"architecture_constraints": ["ADR-001"],
"index_path": ".workflow/.doc-index/doc-index.json"
"index_path": ".workflow/.doc-index/doc-index.json",
"symbol_docs": [
{
"symbol_urn": "deepwiki:symbol:<path>#L<start>-L<end>",
"name": "SymbolName",
"type": "class|function|method",
"doc_summary": "Generated documentation summary...",
"source_path": "src/path/to/file.ts",
"doc_path": ".deepwiki/file.md",
"freshness": "fresh|stale|unknown"
}
]
},
"_metadata": {
"timestamp": "ISO8601",
@@ -356,7 +378,18 @@ Follows `task-schema` with ddd-specific `doc_context` extension:
"component_ids": ["tech-auth-service"],
"adr_ids": ["ADR-001"],
"feature_docs": ["feature-maps/auth.md"],
"component_docs": ["tech-registry/auth-service.md"]
"component_docs": ["tech-registry/auth-service.md"],
"symbol_docs": [
{
"symbol_urn": "deepwiki:symbol:<path>#L<start>-L<end>",
"name": "SymbolName",
"type": "class|function|method",
"doc_summary": "Generated documentation summary...",
"source_path": "src/path/to/file.ts",
"doc_path": ".deepwiki/file.md",
"freshness": "fresh|stale|unknown"
}
]
},
"files": [...],
"implementation": [...]

31
.claude/commands/ddd/scan.md
View File

@@ -266,10 +266,39 @@ Write the index with code-first markers:
"affectedComponents": ["tech-{slug}"],
"relatedCommit": "full-hash",
"timestamp": "ISO8601"
}]
}],
"freshness": {
"thresholds": { "warning": 0.3, "stale": 0.7 },
"weights": { "time": 0.1, "churn": 0.4, "symbol": 0.5 },
"time_decay_k": 0.05,
"auto_regenerate": false
},
"deepwiki_feature_to_symbol_index": {}
}
```
## Phase 6.5: Build DeepWiki Feature-to-Symbol Index
If DeepWiki is available (`.codexlens/deepwiki_index.db` exists):
1. Collect all `codeLocations[].path` from `technicalComponents[]`
2. Query DeepWiki: `POST /api/deepwiki/symbols-for-paths { paths: [...] }`
3. Build `deepwiki_feature_to_symbol_index` by traversing:
`feature → requirementIds → techComponentIds → codeLocations → symbols`
```json
"deepwiki_feature_to_symbol_index": {
"feat-auth": [
"deepwiki:symbol:src/auth/jwt.ts#L30-L55",
"deepwiki:symbol:src/models/user.ts#L12-L40"
]
}
```
**Symbol URN format**: `deepwiki:symbol:<file_path>#L<start>-L<end>`
**Graceful degradation**: If DeepWiki is unavailable, set `deepwiki_feature_to_symbol_index: {}` and log warning.
## Phase 7: Generate Documents
### 7.1 Feature Maps

49
.claude/commands/ddd/sync.md
View File

@@ -118,6 +118,47 @@ If changed files don't match any existing component:
- REQ-002: JWT token generation (implementation updated)
```
## Phase 2.4: DeepWiki Freshness Check
If DeepWiki integration is configured (`doc-index.json.freshness` exists):
### 2.4.1 Identify Modified Files
From `execution-manifest.json` or git diff, collect `files_modified[]` with `action == "modified"`.
### 2.4.2 Check Staleness
Query DeepWiki: `POST /api/deepwiki/stale-files { files: [{path, hash}] }`
For each stale file's symbols, calculate staleness score:
```
S(symbol) = min(1.0, w_t × T + w_c × C + w_s × M)
```
Where weights come from `doc-index.json.freshness.weights`.
### 2.4.3 Score Propagation (max aggregation)
```
S_file = max(S_symbol_1, S_symbol_2, ...)
S_component = max(S_file_1, S_file_2, ...)
S_feature = max(S_component_1, S_component_2, ...)
```
### 2.4.4 Status Assignment
Using thresholds from `doc-index.json.freshness.thresholds`:
- `fresh`: score in [0, warning_threshold)
- `warning`: score in [warning_threshold, stale_threshold)
- `stale`: score in [stale_threshold, 1.0]
### 2.4.5 Update Records
- Update `deepwiki_symbols.staleness_score` and `deepwiki_files.staleness_score` in DeepWiki SQLite
- Update `tech-registry/{slug}.md` YAML frontmatter with freshness block
- Update `feature-maps/{slug}.md` YAML frontmatter with freshness block
- Update `deepwiki_feature_to_symbol_index` in doc-index.json
### 2.4.6 Staleness Report
Add to action-log:
- Number of stale symbols/files/components
- Top-5 most stale items with scores
- Auto-regeneration candidates (if `auto_regenerate: true` and score >= stale threshold)
## Phase 3: Update Index
### 3.0 Dry-Run Gate
@@ -229,6 +270,14 @@ timestamp: ISO8601
- Features affected: feat-auth
- Requirements addressed: REQ-001, REQ-002
## Staleness (if DeepWiki freshness enabled)
| Item | Type | Score | Status |
|------|------|-------|--------|
| {symbol/file/component} | {type} | {score} | {fresh/warning/stale} |
- Stale counts: {N} symbols, {N} files, {N} components
- Auto-regeneration candidates: {list of items with auto_regenerate and score >= stale}
## Notes
{any user-provided notes}
```

57
.claude/commands/workflow/analyze-with-file.md
View File

@@ -81,6 +81,18 @@ All `AskUserQuestion` calls MUST comply:
4. Parse options: `-c`/`--continue` for continuation, `-y`/`--yes` for auto-approval
5. Auto-detect: If session folder + discussion.md exist → continue mode
6. Create directory structure
7. **Create Progress Tracking** (TodoWrite — MANDATORY):
```
TodoWrite([
{ id: "phase-1", title: "Phase 1: Topic Understanding", status: "in_progress" },
{ id: "phase-2", title: "Phase 2: CLI Exploration", status: "pending" },
{ id: "phase-3", title: "Phase 3: Interactive Discussion", status: "pending" },
{ id: "phase-4", title: "Phase 4: Synthesis & Conclusion", status: "pending" },
{ id: "next-step", title: "GATE: Post-Completion Next Step", status: "pending" }
])
```
- Update status to `"in_progress"` when entering each phase, `"completed"` when done
- **`next-step` is a terminal gate** — workflow is NOT complete until this todo is `"completed"`
**Session Variables**: `sessionId`, `sessionFolder`, `autoMode` (boolean), `mode` (new|continue)
@@ -98,6 +110,7 @@ All `AskUserQuestion` calls MUST comply:
4. **Record Phase 1 Decisions** — Dimension selection reasoning, depth rationale, any user adjustments
**Success**: Session folder + discussion.md created, dimensions identified, preferences captured, decisions recorded
**TodoWrite**: Update `phase-1` → `"completed"`, `phase-2` → `"in_progress"`
### Phase 2: CLI Exploration
@@ -218,6 +231,7 @@ CONSTRAINTS: Focus on ${dimensions.join(', ')}
- code_anchors/call_chains include `perspective` field
**Success**: Exploration + CLI artifacts created, discussion.md Round 1, key findings and exploration decisions recorded
**TodoWrite**: Update `phase-2` → `"completed"`, `phase-3` → `"in_progress"`
### Phase 3: Interactive Discussion
@@ -280,6 +294,7 @@ CONSTRAINTS: Focus on ${dimensions.join(', ')}
- If ❌ or ⚠️ items exist → **proactively surface** to user at start of next round: "以下原始意图尚未充分覆盖：[list]。是否需要调整优先级？"
**Success**: All rounds documented with narrative synthesis, assumptions corrected, all decisions recorded with rejection reasoning, direction changes with before/after
**TodoWrite**: Update `phase-3` → `"completed"`, `phase-4` → `"in_progress"`
### Phase 4: Synthesis & Conclusion
@@ -335,30 +350,38 @@ CONSTRAINTS: Focus on ${dimensions.join(', ')}
- Accepted: N items | Modified: N items | Rejected: N items
- Only accepted/modified recommendations proceed to next step
6. **Post-Completion Options** (analyze-with-file transitions based on user selection):
6. **MANDATORY GATE: Next Step Selection** — workflow MUST NOT end without executing this step.
> **WORKFLOW TRANSITION**: "执行任务" MUST invoke `Skill(skill="workflow-lite-plan")` — do NOT end without calling it.
**TodoWrite**: Update `phase-4` → `"completed"`, `next-step` → `"in_progress"`
AskUserQuestion (single-select, header: "Next Step"):
- **执行任务** (Recommended if high/medium priority recs exist): Launch workflow-lite-plan
- **产出Issue**: Convert recommendations to issues via /issue:new
- **完成**: No further action
> **CRITICAL**: This AskUserQuestion is a **terminal gate**. The workflow is INCOMPLETE if this question is not asked. After displaying conclusions (step 4) and recommendation review (step 5), you MUST immediately proceed here.
**Handle "产出Issue"**:
Call AskUserQuestion (single-select, header: "Next Step"):
- **执行任务** (Recommended if high/medium priority recs exist): "基于分析结论启动 workflow-lite-plan 制定执行计划"
- **产出Issue**: "将建议转化为 issue 进行跟踪管理"
- **完成**: "分析已足够，无需进一步操作"
**Handle user selection**:
**"执行任务"** → MUST invoke Skill tool (do NOT just display a summary and stop):
1. Build `taskDescription` from high/medium priority recommendations (fallback: summary)
2. Assemble context: `## Prior Analysis ({sessionId})` + summary + key files (up to 8) + key findings (up to 5) from exploration-codebase.json
3. **Invoke Skill tool immediately**:
```javascript
Skill({ skill: "workflow-lite-plan", args: `${taskDescription}\n\n${contextLines}` })
```
If Skill invocation is omitted, the workflow is BROKEN.
4. After Skill invocation, analyze-with-file is complete — do not output any additional content
**"产出Issue"** → Convert recommendations to issues:
1. For each recommendation in conclusions.recommendations (priority high/medium):
- Build issue JSON: `{title, context: rec.action + rec.rationale, priority: rec.priority == 'high' ? 2 : 3, source: 'discovery', labels: dimensions}`
- Create via pipe: `echo '<issue-json>' | ccw issue create`
2. Display created issue IDs with next step hint: `/issue:plan <id>`
**Handle "执行任务"** — MUST invoke Skill tool (do NOT just display a summary and stop):
1. Build `taskDescription` from high/medium priority recommendations (fallback: summary)
2. Assemble context: `## Prior Analysis ({sessionId})` + summary + key files (up to 8) + key findings (up to 5) from exploration-codebase.json
3. **MANDATORY — Invoke Skill tool immediately** (this is the ONLY correct action, do NOT skip):
```javascript
Skill({ skill: "workflow-lite-plan", args: `${taskDescription}\n\n${contextLines}` })
```
If Skill invocation is omitted, the workflow is BROKEN — user selected "执行任务" specifically to launch lite-plan.
4. After Skill invocation, analyze-with-file is complete — do not output any additional content
**"完成"** → No further action needed.
**TodoWrite**: Update `next-step` → `"completed"` after user selection is handled
**conclusions.json Schema**:
- `session_id`, `topic`, `completed`, `total_rounds`, `summary`
@@ -370,7 +393,7 @@ CONSTRAINTS: Focus on ${dimensions.join(', ')}
- `narrative_trail[]`: {round, starting_point, key_progress, hypothesis_impact, updated_understanding, remaining_questions}
- `intent_coverage[]`: {intent, status, where_addressed, notes}
**Success**: conclusions.json created, discussion.md finalized, Intent Coverage Matrix verified, complete decision trail documented
**Success**: conclusions.json created, discussion.md finalized, Intent Coverage Matrix verified, complete decision trail documented, `next-step` gate completed
## Configuration

64
.claude/commands/workflow/brainstorm-with-file.md
View File

@@ -107,6 +107,19 @@ When `--yes` or `-y`: Auto-confirm decisions, use recommended roles, balanced ex
5. Auto-detect mode: If session folder + brainstorm.md exist → continue mode
6. Create directory structure: `{session-folder}/ideas/`
7. **Create Progress Tracking** (TodoWrite — MANDATORY):
```
TodoWrite([
{ id: "phase-1", title: "Phase 1: Seed Understanding", status: "in_progress" },
{ id: "phase-2", title: "Phase 2: Divergent Exploration", status: "pending" },
{ id: "phase-3", title: "Phase 3: Interactive Refinement", status: "pending" },
{ id: "phase-4", title: "Phase 4: Convergence & Crystallization", status: "pending" },
{ id: "next-step", title: "GATE: Post-Completion Next Step", status: "pending" }
])
```
- Update status to `"in_progress"` when entering each phase, `"completed"` when done
- **`next-step` is a terminal gate** — workflow is NOT complete until this todo is `"completed"`
**Session Variables**: `sessionId`, `sessionFolder`, `brainstormMode` (creative|structured|balanced), `autoMode` (boolean), `mode` (new|continue)
### Phase 1: Seed Understanding
@@ -153,6 +166,8 @@ Output as structured exploration vectors for multi-perspective analysis.
5. **Initialize brainstorm.md** with session metadata, initial context (user focus, depth, constraints), seed expansion (original idea + exploration vectors), empty thought evolution timeline sections
**TodoWrite**: Update `phase-1` → `"completed"`, `phase-2` → `"in_progress"`
### Phase 2: Divergent Exploration
1. **Primary Codebase Exploration via cli-explore-agent** (⚠️ FIRST)
@@ -353,6 +368,9 @@ CONSTRAINTS: Don't force incompatible ideas together
4. **Update brainstorm.md** with Round N findings
5. **Repeat or Converge**: Continue loop (max 6 rounds) or exit to Phase 4
**TodoWrite**: Update `phase-2` → `"completed"` (after first round enters Phase 3), `phase-3` → `"in_progress"`
**TodoWrite** (on exit loop): Update `phase-3` → `"completed"`, `phase-4` → `"in_progress"`
### Phase 4: Convergence & Crystallization
1. **Generate Final Synthesis** → Write to synthesis.json
@@ -366,12 +384,46 @@ CONSTRAINTS: Don't force incompatible ideas together
2. **Final brainstorm.md Update**: Executive summary, top ideas ranked, primary recommendation with rationale, alternative approaches, parked ideas, key insights, session statistics (rounds, ideas generated/survived, duration)
3. **Post-Completion Options** (AskUserQuestion)
- **创建实施计划**: Launch workflow-plan with top idea
- **创建Issue**: Launch issue-discover for top 3 ideas
- **深入分析**: Launch workflow:analyze-with-file for top idea
- **导出分享**: Generate shareable report
- **完成**: No further action
3. **MANDATORY GATE: Next Step Selection** — workflow MUST NOT end without executing this step.
**TodoWrite**: Update `phase-4` → `"completed"`, `next-step` → `"in_progress"`
> **CRITICAL**: This AskUserQuestion is a **terminal gate**. The workflow is INCOMPLETE if this question is not asked. After displaying synthesis (step 2), you MUST immediately proceed here.
Call AskUserQuestion (single-select, header: "Next Step"):
- **创建实施计划** (Recommended if top idea has high feasibility): "基于最佳创意启动 workflow-plan 制定实施计划"
- **创建Issue**: "将 Top 3 创意转化为 issue 进行跟踪管理"
- **深入分析**: "对最佳创意启动 analyze-with-file 深入技术分析"
- **完成**: "头脑风暴已足够，无需进一步操作"
**Handle user selection**:
**"创建实施计划"** → MUST invoke Skill tool:
1. Build `taskDescription` from top idea in synthesis.json (title + description + next_steps)
2. Assemble context: `## Prior Brainstorm ({sessionId})` + summary + top idea details + key insights (up to 5)
3. **Invoke Skill tool immediately**:
```javascript
Skill({ skill: "workflow-plan", args: `${taskDescription}\n\n${contextLines}` })
```
If Skill invocation is omitted, the workflow is BROKEN.
4. After Skill invocation, brainstorm-with-file is complete
**"创建Issue"** → Convert top ideas to issues:
1. For each idea in synthesis.top_ideas (top 3):
- Build issue JSON: `{title: idea.title, context: idea.description + '\n' + idea.next_steps.join('\n'), priority: idea.score >= 8 ? 2 : 3, source: 'brainstorm', labels: dimensions}`
- Create via: `Skill({ skill: "issue:from-brainstorm", args: "${sessionFolder}/synthesis.json" })`
2. Display created issue IDs
**"深入分析"** → Launch analysis on top idea:
1. Build analysis topic from top idea title + description
2. **Invoke Skill tool immediately**:
```javascript
Skill({ skill: "workflow:analyze-with-file", args: `${topIdea.title}: ${topIdea.description}` })
```
**"完成"** → No further action needed.
**TodoWrite**: Update `next-step` → `"completed"` after user selection is handled
## Configuration

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

@@ -1,476 +1,144 @@
---
name: team-arch-opt
description: Unified team skill for architecture optimization. Uses team-worker agent architecture with role-spec files for domain logic. Coordinator orchestrates pipeline, workers are team-worker agents. Triggers on "team arch-opt".
description: Unified team skill for architecture optimization. Uses team-worker agent architecture with role directories for domain logic. Coordinator orchestrates pipeline, workers are team-worker agents. Triggers on "team arch-opt".
allowed-tools: Agent, TaskCreate, TaskList, TaskGet, TaskUpdate, TeamCreate, TeamDelete, SendMessage, AskUserQuestion, Read, Write, Edit, Bash, Glob, Grep, mcp__ace-tool__search_context
---
# Team Architecture Optimization
Unified team skill: Analyze codebase architecture, identify structural issues (dependency cycles, coupling/cohesion, layering violations, God Classes, dead code), design refactoring strategies, implement changes, validate improvements, and review code quality. Built on **team-worker agent architecture** -- all worker roles share a single agent definition with role-specific Phase 2-4 loaded from markdown specs.
Orchestrate multi-agent architecture optimization: analyze codebase → design refactoring plan → implement changes → validate improvements → review code quality.
## Architecture
```
+---------------------------------------------------+
| Skill(skill="team-arch-opt") |
| args="<task-description>" |
+-------------------+-------------------------------+
Skill(skill="team-arch-opt", args="task description")
|
Orchestration Mode (auto -> coordinator)
SKILL.md (this file) = Router
|
Coordinator (inline)
Phase 0-5 orchestration
+--------------+--------------+
| |
no --role flag --role <name>
| |
Coordinator Worker
roles/coordinator/role.md roles/<name>/role.md
|
+-------+-------+-------+-------+-------+
+-- analyze → dispatch → spawn workers → STOP
|
+-------+-------+-------+-------+
v v v v v
[tw] [tw] [tw] [tw] [tw]
analyzer desig- refact- valid- review-
ner orer ator er
CLI Tools (callable by workers inline):
[explore] [discuss]
(tw) = team-worker agent
[analyzer][designer][refactorer][validator][reviewer]
```
## Role Registry
| Role | Path | Prefix | Inner Loop |
|------|------|--------|------------|
| coordinator | [roles/coordinator/role.md](roles/coordinator/role.md) | — | — |
| analyzer | [roles/analyzer/role.md](roles/analyzer/role.md) | ANALYZE-* | false |
| designer | [roles/designer/role.md](roles/designer/role.md) | DESIGN-* | false |
| refactorer | [roles/refactorer/role.md](roles/refactorer/role.md) | REFACTOR-*, FIX-* | true |
| validator | [roles/validator/role.md](roles/validator/role.md) | VALIDATE-* | false |
| reviewer | [roles/reviewer/role.md](roles/reviewer/role.md) | REVIEW-*, QUALITY-* | false |
## Role Router
This skill is **coordinator-only**. Workers do NOT invoke this skill -- they are spawned as `team-worker` agents directly.
Parse `$ARGUMENTS`:
- Has `--role <name>` → Read `roles/<name>/role.md`, execute Phase 2-4
- No `--role` → Read `roles/coordinator/role.md`, execute entry router
### Input Parsing
## Shared Constants
Parse `$ARGUMENTS`. No `--role` needed -- always routes to coordinator.
- **Session prefix**: `TAO`
- **Session path**: `.workflow/.team/TAO-<slug>-<date>/`
- **CLI tools**: `ccw cli --mode analysis` (read-only), `ccw cli --mode write` (modifications)
- **Message bus**: `mcp__ccw-tools__team_msg(session_id=<session-id>, ...)`
### Role Registry
## Worker Spawn Template
| Role | Spec | Task Prefix | Type | Inner Loop |
|------|------|-------------|------|------------|
| coordinator | [roles/coordinator/role.md](roles/coordinator/role.md) | (none) | orchestrator | - |
| analyzer | [role-specs/analyzer.md](role-specs/analyzer.md) | ANALYZE-* | orchestration | false |
| designer | [role-specs/designer.md](role-specs/designer.md) | DESIGN-* | orchestration | false |
| refactorer | [role-specs/refactorer.md](role-specs/refactorer.md) | REFACTOR-* / FIX-* | code_generation | true |
| 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 |
### CLI Tool Registry
| 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
Always route to coordinator. Coordinator reads `roles/coordinator/role.md` and executes its phases.
### Orchestration Mode
User just provides task description.
**Invocation**:
```bash
Skill(skill="team-arch-opt", args="<task-description>") # auto mode
Skill(skill="team-arch-opt", args="--parallel-mode=fan-out <task-description>") # force fan-out
Skill(skill="team-arch-opt", args='--parallel-mode=independent "target1" "target2"') # independent
Skill(skill="team-arch-opt", args="--max-branches=3 <task-description>") # limit branches
```
**Parallel Modes**:
| Mode | Description | When to Use |
|------|-------------|------------|
| `auto` (default) | count <= 2 -> single, count >= 3 -> fan-out | General refactoring requests |
| `single` | Linear pipeline, no branching | Simple or tightly coupled refactorings |
| `fan-out` | Shared ANALYZE+DESIGN, then N parallel REFACTOR->VALIDATE+REVIEW branches | Multiple independent architecture issues |
| `independent` | M fully independent pipelines from analysis to review | Separate refactoring targets |
**Lifecycle**:
```
User provides task description + optional --parallel-mode / --max-branches
-> coordinator Phase 1-3: Parse flags -> TeamCreate -> Create task chain (mode-aware)
-> coordinator Phase 4: spawn first batch workers (background) -> STOP
-> Worker (team-worker agent) executes -> SendMessage callback -> coordinator advances
-> [auto/fan-out] CP-2.5: Design complete -> create N branch tasks -> spawn all REFACTOR-B* in parallel
-> [independent] All pipelines run in parallel from the start
-> Per-branch/pipeline fix cycles run independently
-> All branches/pipelines complete -> AGGREGATE -> Phase 5 report + completion action
```
**User Commands** (wake paused coordinator):
| Command | Action |
|---------|--------|
| `check` / `status` | Output execution status graph (branch-grouped), no advancement |
| `resume` / `continue` | Check worker states, advance next step |
| `revise <TASK-ID> [feedback]` | Create revision task + cascade downstream (scoped to branch) |
| `feedback <text>` | Analyze feedback impact, create targeted revision chain |
| `recheck` | Re-run quality check |
| `improve [dimension]` | Auto-improve weakest dimension |
---
## Command Execution Protocol
When coordinator needs to execute a command (dispatch, monitor):
1. **Read the command file**: `roles/coordinator/commands/<command-name>.md`
2. **Follow the workflow** defined in the command file (Phase 2-4 structure)
3. **Commands are inline execution guides** -- NOT separate agents or subprocesses
4. **Execute synchronously** -- complete the command workflow before proceeding
Example:
```
Phase 3 needs task dispatch
-> Read roles/coordinator/commands/dispatch.md
-> Execute Phase 2 (Context Loading)
-> Execute Phase 3 (Task Chain Creation)
-> Execute Phase 4 (Validation)
-> Continue to Phase 4
```
---
## Coordinator Spawn Template
### v5 Worker Spawn (all roles)
When coordinator spawns workers, use `team-worker` agent with role-spec path:
Coordinator spawns workers using this template:
```
Agent({
subagent_type: "team-worker",
description: "Spawn <role> worker",
team_name: <team-name>,
team_name: "arch-opt",
name: "<role>",
run_in_background: true,
prompt: `## Role Assignment
role: <role>
role_spec: .claude/skills/team-arch-opt/role-specs/<role>.md
role_spec: .claude/skills/team-arch-opt/roles/<role>/role.md
session: <session-folder>
session_id: <session-id>
team_name: <team-name>
team_name: arch-opt
requirement: <task-description>
inner_loop: <true|false>
Read role_spec file to load Phase 2-4 domain instructions.
Execute built-in Phase 1 (task discovery) -> role-spec Phase 2-4 -> built-in Phase 5 (report).`
Execute built-in Phase 1 (task discovery) -> role Phase 2-4 -> built-in Phase 5 (report).`
})
```
**Inner Loop roles** (refactorer): Set `inner_loop: true`. The team-worker agent handles the loop internally.
**Inner Loop roles** (refactorer): Set `inner_loop: true`.
**Single-task roles** (analyzer, designer, validator, reviewer): Set `inner_loop: false`.
---
## User Commands
## Pipeline Definitions
### Pipeline Diagrams
**Single Mode** (linear, backward compatible):
```
Pipeline: Single (Linear with Review-Fix Cycle)
=====================================================================
Stage 1 Stage 2 Stage 3 Stage 4
ANALYZE-001 --> DESIGN-001 --> REFACTOR-001 --> VALIDATE-001
[analyzer] [designer] [refactorer] [validator]
^ |
+<--FIX-001---->+
| REVIEW-001
+<--------> [reviewer]
(max 3 iterations) |
COMPLETE
=====================================================================
```
**Fan-out Mode** (shared stages 1-2, parallel branches 3-4):
```
Pipeline: Fan-out (N parallel refactoring branches)
=====================================================================
Stage 1 Stage 2 CP-2.5 Stage 3+4 (per branch)
(branch creation)
ANALYZE-001 --> DESIGN-001 --+-> REFACTOR-B01 --> VALIDATE-B01 + REVIEW-B01 (fix cycle)
[analyzer] [designer] | [refactorer] [validator] [reviewer]
+-> REFACTOR-B02 --> VALIDATE-B02 + REVIEW-B02 (fix cycle)
| [refactorer] [validator] [reviewer]
+-> REFACTOR-B0N --> VALIDATE-B0N + REVIEW-B0N (fix cycle)
|
AGGREGATE -> Phase 5
=====================================================================
```
**Independent Mode** (M fully independent pipelines):
```
Pipeline: Independent (M complete pipelines)
=====================================================================
Pipeline A: ANALYZE-A01 --> DESIGN-A01 --> REFACTOR-A01 --> VALIDATE-A01 + REVIEW-A01
Pipeline B: ANALYZE-B01 --> DESIGN-B01 --> REFACTOR-B01 --> VALIDATE-B01 + REVIEW-B01
Pipeline C: ANALYZE-C01 --> DESIGN-C01 --> REFACTOR-C01 --> VALIDATE-C01 + REVIEW-C01
|
AGGREGATE -> Phase 5
=====================================================================
```
### Cadence Control
**Beat model**: Event-driven, each beat = coordinator wake -> process -> spawn -> STOP.
```
Beat Cycle (single beat)
======================================================================
Event Coordinator Workers
----------------------------------------------------------------------
callback/resume --> +- handleCallback -+
| mark completed |
| check pipeline |
+- handleSpawnNext -+
| find ready tasks |
| spawn workers ---+--> [team-worker A] Phase 1-5
| (parallel OK) --+--> [team-worker B] Phase 1-5
+- STOP (idle) -----+ |
|
callback <-----------------------------------------+
(next beat) SendMessage + TaskUpdate(completed)
======================================================================
Fast-Advance (skips coordinator for simple linear successors)
======================================================================
[Worker A] Phase 5 complete
+- 1 ready task? simple successor?
| --> spawn team-worker B directly
| --> log fast_advance to message bus (coordinator syncs on next wake)
+- complex case? --> SendMessage to coordinator
======================================================================
```
```
Beat View: Architecture Optimization Pipeline
======================================================================
Event Coordinator Workers
----------------------------------------------------------------------
new task --> +- Phase 1-3: clarify -+
| TeamCreate |
| create ANALYZE-001 |
+- Phase 4: spawn ------+--> [analyzer] Phase 1-5
+- STOP (idle) ---------+ |
|
callback <----------------------------------------------+
(analyzer done) --> +- handleCallback ------+ analyze_complete
| mark ANALYZE done |
| spawn designer ------+--> [designer] Phase 1-5
+- STOP ----------------+ |
|
callback <----------------------------------------------+
(designer done) --> +- handleCallback ------+ design_complete
| mark DESIGN done |
| spawn refactorer ----+--> [refactorer] Phase 1-5
+- STOP ----------------+ |
|
callback <----------------------------------------------+
(refactorer done)--> +- handleCallback ------+ refactor_complete
| mark REFACTOR done |
| spawn valid+reviewer-+--> [validator] Phase 1-5
| (parallel) -------+--> [reviewer] Phase 1-5
+- STOP ----------------+ | |
| |
callback x2 <--------------------------------------+-----------+
--> +- handleCallback ------+
| both done? |
| YES + pass -> Phase 5|
| NO / fail -> FIX task|
| spawn refactorer ----+--> [refactorer] FIX-001
+- STOP or Phase 5 -----+
======================================================================
```
**Checkpoints**:
| Checkpoint | Trigger | Location | Behavior |
|------------|---------|----------|----------|
| CP-1 | ANALYZE-001 complete | After Stage 1 | User reviews architecture report, can refine scope |
| CP-2 | DESIGN-001 complete | After Stage 2 | User reviews refactoring plan, can adjust priorities |
| CP-2.5 | DESIGN-001 complete (auto/fan-out) | After Stage 2 | Auto-create N branch tasks from refactoring plan, spawn all REFACTOR-B* in parallel |
| CP-3 | REVIEW/VALIDATE fail | Stage 4 (per-branch) | Auto-create FIX task for that branch only (max 3x per branch) |
| CP-4 | All tasks/branches complete | Phase 5 | Aggregate results, interactive completion action |
### Task Metadata Registry
**Single mode** (backward compatible):
| Task ID | Role | Phase | Dependencies | Description |
|---------|------|-------|-------------|-------------|
| ANALYZE-001 | analyzer | Stage 1 | (none) | Analyze architecture, identify structural issues |
| DESIGN-001 | designer | Stage 2 | ANALYZE-001 | Design refactoring plan from architecture report |
| REFACTOR-001 | refactorer | Stage 3 | DESIGN-001 | Implement highest-priority refactorings |
| VALIDATE-001 | validator | Stage 4 | REFACTOR-001 | Validate build, tests, metrics, API compatibility |
| REVIEW-001 | reviewer | Stage 4 | REFACTOR-001 | Review refactoring code for correctness |
| FIX-001 | refactorer | Stage 3 (cycle) | REVIEW-001 or VALIDATE-001 | Fix issues found in review/validation |
**Fan-out mode** (branch tasks created at CP-2.5):
| Task ID | Role | Phase | Dependencies | Description |
|---------|------|-------|-------------|-------------|
| ANALYZE-001 | analyzer | Stage 1 (shared) | (none) | Analyze architecture |
| DESIGN-001 | designer | Stage 2 (shared) | ANALYZE-001 | Design plan with discrete REFACTOR-IDs |
| REFACTOR-B{NN} | refactorer | Stage 3 (branch) | DESIGN-001 | Implement REFACTOR-{NNN} only |
| VALIDATE-B{NN} | validator | Stage 4 (branch) | REFACTOR-B{NN} | Validate branch B{NN} |
| REVIEW-B{NN} | reviewer | Stage 4 (branch) | REFACTOR-B{NN} | Review branch B{NN} |
| FIX-B{NN}-{cycle} | refactorer | Fix (branch) | (none) | Fix issues in branch B{NN} |
| VALIDATE-B{NN}-R{cycle} | validator | Retry (branch) | FIX-B{NN}-{cycle} | Re-validate after fix |
| REVIEW-B{NN}-R{cycle} | reviewer | Retry (branch) | FIX-B{NN}-{cycle} | Re-review after fix |
**Independent mode**:
| Task ID | Role | Phase | Dependencies | Description |
|---------|------|-------|-------------|-------------|
| ANALYZE-{P}01 | analyzer | Stage 1 | (none) | Analyze for pipeline {P} target |
| DESIGN-{P}01 | designer | Stage 2 | ANALYZE-{P}01 | Design for pipeline {P} |
| REFACTOR-{P}01 | refactorer | Stage 3 | DESIGN-{P}01 | Implement pipeline {P} refactorings |
| VALIDATE-{P}01 | validator | Stage 4 | REFACTOR-{P}01 | Validate pipeline {P} |
| REVIEW-{P}01 | reviewer | Stage 4 | REFACTOR-{P}01 | Review pipeline {P} |
| FIX-{P}01-{cycle} | refactorer | Fix | (none) | Fix issues in pipeline {P} |
### Task Naming Rules
| Mode | Stage 3 | Stage 4 | Fix | Retry |
|------|---------|---------|-----|-------|
| Single | REFACTOR-001 | VALIDATE-001, REVIEW-001 | FIX-001 | VALIDATE-001-R1, REVIEW-001-R1 |
| Fan-out | REFACTOR-B01 | VALIDATE-B01, REVIEW-B01 | FIX-B01-1 | VALIDATE-B01-R1, REVIEW-B01-R1 |
| Independent | REFACTOR-A01 | VALIDATE-A01, REVIEW-A01 | FIX-A01-1 | VALIDATE-A01-R1, REVIEW-A01-R1 |
---
## Completion Action
When the pipeline completes (all tasks done, coordinator Phase 5):
```
AskUserQuestion({
questions: [{
question: "Team pipeline complete. What would you like to do?",
header: "Completion",
multiSelect: false,
options: [
{ label: "Archive & Clean (Recommended)", description: "Archive session, clean up tasks and team resources" },
{ label: "Keep Active", description: "Keep session active for follow-up work or inspection" },
{ label: "Export Results", description: "Export deliverables to a specified location, then clean" }
]
}]
})
```
| Choice | Action |
|--------|--------|
| Archive & Clean | Update session status="completed" -> TeamDelete() -> output final summary |
| Keep Active | Update session status="paused" -> output resume instructions: `Skill(skill="team-arch-opt", args="resume")` |
| Export Results | AskUserQuestion for target path -> copy deliverables -> Archive & Clean |
---
| Command | Action |
|---------|--------|
| `check` / `status` | View execution status graph (branch-grouped), no advancement |
| `resume` / `continue` | Check worker states, advance next step |
| `revise <TASK-ID> [feedback]` | Revise specific task + cascade downstream |
| `feedback <text>` | Analyze feedback impact, create targeted revision chain |
| `recheck` | Re-run quality check |
| `improve [dimension]` | Auto-improve weakest dimension |
## Session Directory
**Single mode**:
```
.workflow/<session-id>/
+-- session.json # Session metadata + status + parallel_mode
+-- artifacts/
| +-- architecture-baseline.json # Analyzer: pre-refactoring metrics
| +-- architecture-report.md # Analyzer: ranked structural issue findings
| +-- refactoring-plan.md # Designer: prioritized refactoring plan
| +-- validation-results.json # Validator: post-refactoring validation
| +-- review-report.md # Reviewer: code review findings
+-- explorations/
| +-- cache-index.json # Shared explore cache
| +-- <hash>.md # Cached exploration results
+-- wisdom/
| +-- patterns.md # Discovered patterns and conventions
+-- .msg/
| +-- messages.jsonl # Message bus log
| +-- meta.json # Session state + cross-role state
+-- discussions/
| +-- DISCUSS-REFACTOR.md # Refactoring design discussion record
| +-- DISCUSS-REVIEW.md # Review discussion record
.workflow/.team/TAO-<slug>-<date>/
├── session.json # Session metadata + status + parallel_mode
├── task-analysis.json # Coordinator analyze output
├── artifacts/
│ ├── architecture-baseline.json # Analyzer: pre-refactoring metrics
│ ├── architecture-report.md # Analyzer: ranked structural issue findings
│ ├── refactoring-plan.md # Designer: prioritized refactoring plan
│ ├── validation-results.json # Validator: post-refactoring validation
│ ├── review-report.md # Reviewer: code review findings
│ ├── aggregate-results.json # Fan-out/independent: aggregated results
│ ├── branches/ # Fan-out mode branch artifacts
│ │ └── B{NN}/
│ │ ├── refactoring-detail.md
│ │ ├── validation-results.json
│ │ └── review-report.md
│ └── pipelines/ # Independent mode pipeline artifacts
│ └── {P}/
│ └── ...
├── explorations/
│ ├── cache-index.json # Shared explore cache
│ └── <hash>.md
├── wisdom/
│ └── patterns.md # Discovered patterns and conventions
├── discussions/
│ ├── DISCUSS-REFACTOR.md
│ └── DISCUSS-REVIEW.md
└── .msg/
├── messages.jsonl # Message bus log
└── meta.json # Session state + cross-role state
```
**Fan-out mode** (adds branches/ directory):
```
.workflow/<session-id>/
+-- session.json # + parallel_mode, branches, fix_cycles
+-- artifacts/
| +-- architecture-baseline.json # Shared baseline (all branches use this)
| +-- architecture-report.md # Shared architecture report
| +-- refactoring-plan.md # Shared plan with discrete REFACTOR-IDs
| +-- aggregate-results.json # Aggregated results from all branches
| +-- branches/
| +-- B01/
| | +-- refactoring-detail.md # Extracted REFACTOR-001 detail
| | +-- validation-results.json # Branch B01 validation
| | +-- review-report.md # Branch B01 review
| +-- B02/
| | +-- refactoring-detail.md
| | +-- validation-results.json
| | +-- review-report.md
| +-- B0N/
+-- explorations/ wisdom/ discussions/ # Same as single
```
## Specs Reference
**Independent mode** (adds pipelines/ directory):
```
.workflow/<session-id>/
+-- session.json # + parallel_mode, independent_targets, fix_cycles
+-- artifacts/
| +-- aggregate-results.json # Aggregated results from all pipelines
| +-- pipelines/
| +-- A/
| | +-- architecture-baseline.json
| | +-- architecture-report.md
| | +-- refactoring-plan.md
| | +-- validation-results.json
| | +-- review-report.md
| +-- B/
| +-- architecture-baseline.json
| +-- ...
+-- explorations/ wisdom/ discussions/ # Same as single
```
## Session Resume
Coordinator supports `--resume` / `--continue` for interrupted sessions:
1. Scan session directory for sessions with status "active" or "paused"
2. Multiple matches -> AskUserQuestion for selection
3. Audit TaskList -> reconcile session state <-> task status
4. Reset in_progress -> pending (interrupted tasks)
5. Rebuild team and spawn needed workers only
6. Create missing tasks with correct blockedBy
7. Kick first executable task -> Phase 4 coordination loop
## Shared Resources
| Resource | Path | Usage |
|----------|------|-------|
| Architecture Baseline | [<session>/artifacts/architecture-baseline.json](<session>/artifacts/architecture-baseline.json) | Pre-refactoring metrics for comparison |
| Architecture Report | [<session>/artifacts/architecture-report.md](<session>/artifacts/architecture-report.md) | Analyzer output consumed by designer |
| Refactoring Plan | [<session>/artifacts/refactoring-plan.md](<session>/artifacts/refactoring-plan.md) | Designer output consumed by refactorer |
| Validation Results | [<session>/artifacts/validation-results.json](<session>/artifacts/validation-results.json) | Validator output consumed by reviewer |
- [specs/pipelines.md](specs/pipelines.md) — Pipeline definitions, task registry, parallel modes
## Error Handling
| Scenario | Resolution |
|----------|------------|
| 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 |
| 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 |
| Unknown command | Error with available command list |
| Role not found | Error with role registry |
| CLI tool fails | Worker fallback to direct implementation |
| Fast-advance conflict | Coordinator reconciles on next callback |
| Completion action fails | Default to Keep Active |
| consensus_blocked HIGH | Coordinator creates revision task or pauses pipeline |
| team-worker agent unavailable | Error: requires .claude/agents/team-worker.md |
| Completion action timeout | Default to Keep Active |
| Analysis tool not available | Fallback to static analysis methods |
| Validation regression detected | Auto-create FIX task with regression details (scoped to branch/pipeline) |
| Review-fix cycle exceeds 3 iterations | Escalate to user with summary of remaining issues (per-branch/pipeline scope) |
| One branch REFACTOR fails | Mark that branch failed, other branches continue to completion |
| Branch scope overlap detected | Designer constrains non-overlapping target files; REFACTOR logs warning on detection |
| Meta.json concurrent writes | Each worker writes only its own namespace key (e.g., `refactorer.B01`) |
| Branch fix cycle >= 3 | Escalate only that branch to user, other branches continue independently |
| max_branches exceeded | Coordinator truncates to top N refactorings by priority at CP-2.5 |
| Independent pipeline partial failure | Failed pipeline marked, others continue; aggregate reports partial results |
| Branch fix cycle >= 3 | Escalate only that branch to user, others continue |
| max_branches exceeded | Coordinator truncates to top N at CP-2.5 |

78
.claude/skills/team-arch-opt/roles/analyzer/role.md Normal file
View File

@@ -0,0 +1,78 @@
---
role: analyzer
prefix: ANALYZE
inner_loop: false
message_types: [state_update]
---
# Architecture Analyzer
Analyze codebase architecture to identify structural issues: dependency cycles, coupling/cohesion problems, layering violations, God Classes, code duplication, dead code, and API surface bloat. Produce quantified baseline metrics and a ranked architecture report.
## Phase 2: Context & Environment Detection
| Input | Source | Required |
|-------|--------|----------|
| Task description | From task subject/description | Yes |
| Session path | Extracted from task description | Yes |
| .msg/meta.json | <session>/wisdom/.msg/meta.json | No |
1. Extract session path and target scope from task description
2. Detect project type by scanning for framework markers:
| Signal File | Project Type | Analysis Focus |
|-------------|-------------|----------------|
| package.json + React/Vue/Angular | Frontend | Component tree, prop drilling, state management, barrel exports |
| package.json + Express/Fastify/NestJS | Backend Node | Service layer boundaries, middleware chains, DB access patterns |
| Cargo.toml / go.mod / pom.xml | Native/JVM Backend | Module boundaries, trait/interface usage, dependency injection |
| Mixed framework markers | Full-stack / Monorepo | Cross-package dependencies, shared types, API contracts |
| CLI entry / bin/ directory | CLI Tool | Command structure, plugin architecture, configuration layering |
| No detection | Generic | All architecture dimensions |
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
Execute analysis based on detected project type:
**Dependency analysis**:
- Build import/require graph across modules
- Detect circular dependencies (direct and transitive cycles)
- Identify layering violations (e.g., UI importing from data layer, utils importing from domain)
- Calculate fan-in/fan-out per module (high fan-out = fragile hub, high fan-in = tightly coupled)
**Structural analysis**:
- Identify God Classes / God Modules (> 500 LOC, > 10 public methods, too many responsibilities)
- Calculate coupling metrics (afferent/efferent coupling per module)
- Calculate cohesion metrics (LCOM -- Lack of Cohesion of Methods)
- Detect code duplication (repeated logic blocks, copy-paste patterns)
- Identify missing abstractions (repeated conditionals, switch-on-type patterns)
**API surface analysis**:
- Count exported symbols per module (export bloat detection)
- Identify dead exports (exported but never imported elsewhere)
- Detect dead code (unreachable functions, unused variables, orphan files)
- Check for pattern inconsistencies (mixed naming conventions, inconsistent error handling)
**All project types**:
- Collect quantified architecture baseline metrics (dependency count, cycle count, coupling scores, LOC distribution)
- Rank top 3-7 architecture issues by severity (Critical / High / Medium)
- Record evidence: file paths, line numbers, measured values
## Phase 4: Report Generation
1. Write architecture baseline to `<session>/artifacts/architecture-baseline.json`:
- Module count, dependency count, cycle count, average coupling, average cohesion
- God Class candidates with LOC and method count
- Dead code file count, dead export count
- Timestamp and project type details
2. Write architecture report to `<session>/artifacts/architecture-report.md`:
- Ranked list of architecture issues with severity, location (file:line or module), measured impact
- Issue categories: CYCLE, COUPLING, COHESION, GOD_CLASS, DUPLICATION, LAYER_VIOLATION, DEAD_CODE, API_BLOAT
- Evidence summary per issue
- Detected project type and analysis methods used
3. Update `<session>/wisdom/.msg/meta.json` under `analyzer` namespace:
- Read existing -> merge `{ "analyzer": { project_type, issue_count, top_issue, scope, categories } }` -> write back

57
.claude/skills/team-arch-opt/roles/coordinator/commands/analyze.md Normal file
View File

@@ -0,0 +1,57 @@
# Analyze Task
Parse user task -> detect architecture capabilities -> build dependency graph -> design roles.
**CONSTRAINT**: Text-level analysis only. NO source code reading, NO codebase exploration.
## Signal Detection
| Keywords | Capability | Prefix |
|----------|------------|--------|
| analyze, scan, audit, map, identify | analyzer | ANALYZE |
| design, plan, strategy, refactoring-plan | designer | DESIGN |
| refactor, implement, fix, apply | refactorer | REFACTOR |
| validate, build, test, verify, compile | validator | VALIDATE |
| review, audit-code, quality, check-code | reviewer | REVIEW |
## Dependency Graph
Natural ordering tiers:
- Tier 0: analyzer (knowledge gathering -- no dependencies)
- Tier 1: designer (requires analyzer output)
- Tier 2: refactorer (requires designer output)
- Tier 3: validator, reviewer (validation requires refactored artifacts, can run in parallel)
## Complexity Scoring
| Factor | Points |
|--------|--------|
| Per capability | +1 |
| Cross-domain refactoring | +2 |
| Parallel branches requested | +1 per branch |
| Serial depth > 3 | +1 |
| Multiple targets (independent mode) | +2 |
Results: 1-3 Low, 4-6 Medium, 7+ High
## Role Minimization
- Cap at 5 roles
- Merge overlapping capabilities
- Absorb trivial single-step roles
## Output
Write <session>/task-analysis.json:
```json
{
"task_description": "<original>",
"pipeline_type": "<single|fan-out|independent|auto>",
"capabilities": [{ "name": "<cap>", "prefix": "<PREFIX>", "keywords": ["..."] }],
"dependency_graph": { "<TASK-ID>": { "role": "<role>", "blockedBy": ["..."], "priority": "P0|P1|P2" } },
"roles": [{ "name": "<role>", "prefix": "<PREFIX>", "inner_loop": false }],
"complexity": { "score": 0, "level": "Low|Medium|High" },
"parallel_mode": "<auto|single|fan-out|independent>",
"max_branches": 5
}
```

342
.claude/skills/team-arch-opt/roles/coordinator/commands/monitor.md
View File

@@ -1,27 +1,33 @@
# Command: Monitor
# Monitor Pipeline
Handle all coordinator monitoring events: worker callbacks, status checks, pipeline advancement, and completion. Supports single, fan-out, and independent parallel modes with per-branch/pipeline tracking.
Event-driven pipeline coordination. Beat model: coordinator wake -> process -> spawn -> STOP.
## Phase 2: Context Loading
## Constants
| Input | Source | Required |
|-------|--------|----------|
| Session state | <session>/session.json | Yes |
| Task list | TaskList() | Yes |
| Trigger event | From Entry Router detection | Yes |
| Pipeline definition | From SKILL.md | Yes |
- SPAWN_MODE: background
- ONE_STEP_PER_INVOCATION: true
- FAST_ADVANCE_AWARE: true
- WORKER_AGENT: team-worker
1. Load session.json for current state, `parallel_mode`, `branches`, `fix_cycles`
2. Run TaskList() to get current task statuses
3. Identify trigger event type from Entry Router
## Handler Router
## Phase 3: Event Handlers
| Source | Handler |
|--------|---------|
| Message contains [analyzer], [designer], [refactorer], [validator], [reviewer] | handleCallback |
| Message contains branch tag [refactorer-B01], etc. | handleCallback (branch-aware) |
| Message contains pipeline tag [analyzer-A], etc. | handleCallback (pipeline-aware) |
| "consensus_blocked" | handleConsensus |
| "capability_gap" | handleAdapt |
| "check" or "status" | handleCheck |
| "resume" or "continue" | handleResume |
| All tasks completed | handleComplete |
| Default | handleSpawnNext |
### handleCallback
## handleCallback
Triggered when a worker sends completion message.
Worker completed. Process and advance.
1. Parse message to identify role, task ID, and **branch/pipeline label**:
1. Parse message to identify role, task ID, and branch/pipeline label:
| Message Pattern | Branch Detection |
|----------------|-----------------|
@@ -29,41 +35,57 @@ Triggered when a worker sends completion message.
| `[analyzer-A]` or task ID `ANALYZE-A01` | Pipeline `A` (independent) |
| `[analyzer]` or task ID `ANALYZE-001` | No branch (single) |
2. Mark task as completed:
```
TaskUpdate({ taskId: "<task-id>", status: "completed" })
```
2. Mark task as completed: `TaskUpdate({ taskId: "<task-id>", status: "completed" })`
3. Record completion in session state
4. **CP-2.5 check** (auto/fan-out mode only):
- If completed task is DESIGN-001 AND `parallel_mode` is `auto` or `fan-out`:
- Execute **CP-2.5 Branch Creation** subroutine from dispatch.md
- If completed task is DESIGN-001 AND parallel_mode is `auto` or `fan-out`:
- Execute CP-2.5 Branch Creation from dispatch.md
- After branch creation, proceed to handleSpawnNext (spawns all REFACTOR-B* in parallel)
- STOP after spawning
5. Check if checkpoint feedback is configured for this stage:
5. Check stage checkpoints:
| Completed Task | Checkpoint | Action |
|---------------|------------|--------|
| ANALYZE-001 / ANALYZE-{P}01 | CP-1 | Notify user: architecture report ready for review |
| DESIGN-001 / DESIGN-{P}01 | CP-2 | Notify user: refactoring plan ready for review |
| DESIGN-001 (auto/fan-out) | CP-2.5 | Execute branch creation, then notify user with branch count |
| VALIDATE-* or REVIEW-* | CP-3 | Check verdicts per branch (see Review-Fix Cycle below) |
| ANALYZE-001 / ANALYZE-{P}01 | CP-1 | Notify user: architecture report ready |
| DESIGN-001 / DESIGN-{P}01 | CP-2 | Notify user: refactoring plan ready |
| DESIGN-001 (auto/fan-out) | CP-2.5 | Execute branch creation, notify with branch count |
| VALIDATE-* or REVIEW-* | CP-3 | Check verdicts per branch (see Review-Fix Cycle) |
6. Proceed to handleSpawnNext
### handleSpawnNext
## handleCheck
Find and spawn the next ready tasks.
Read-only status report, then STOP.
1. Scan task list for tasks where:
- Status is "pending"
- All blockedBy tasks have status "completed"
Output (single mode):
```
[coordinator] Pipeline Status
[coordinator] Progress: <done>/<total> (<pct>%)
[coordinator] Active: <workers with elapsed time>
[coordinator] Ready: <pending tasks with resolved deps>
[coordinator] Commands: 'resume' to advance | 'check' to refresh
```
2. For each ready task, spawn team-worker:
Fan-out mode adds per-branch grouping. Independent mode adds per-pipeline grouping.
## handleResume
1. Audit task list: Tasks stuck in "in_progress" -> reset to "pending"
2. For fan-out/independent: check each branch/pipeline independently
3. Proceed to handleSpawnNext
## handleSpawnNext
Find ready tasks, spawn workers, STOP.
1. Collect: completedSubjects, inProgressSubjects, readySubjects
2. No ready + work in progress -> report waiting, STOP
3. No ready + nothing in progress -> handleComplete
4. Has ready -> for each:
a. Check if inner loop role with active worker -> skip (worker picks up)
b. TaskUpdate -> in_progress
c. team_msg log -> task_unblocked
d. Spawn team-worker (see SKILL.md Spawn Template):
```
Agent({
subagent_type: "team-worker",
@@ -73,7 +95,7 @@ Agent({
run_in_background: true,
prompt: `## Role Assignment
role: <role>
role_spec: .claude/skills/team-arch-opt/role-specs/<role>.md
role_spec: .claude/skills/team-arch-opt/roles/<role>/role.md
session: <session-folder>
session_id: <session-id>
team_name: arch-opt
@@ -81,186 +103,58 @@ requirement: <task-description>
inner_loop: <true|false>
Read role_spec file to load Phase 2-4 domain instructions.
Execute built-in Phase 1 -> role-spec Phase 2-4 -> built-in Phase 5.`
Execute built-in Phase 1 (task discovery) -> role Phase 2-4 -> built-in Phase 5 (report).`
})
```
3. **Parallel spawn rules by mode**:
e. Add to active_workers
5. Parallel spawn rules by mode:
| Mode | Scenario | Spawn Behavior |
|------|----------|---------------|
| Single | Stage 4 ready | Spawn VALIDATE-001 + REVIEW-001 in parallel |
| Fan-out (CP-2.5 done) | All REFACTOR-B* unblocked | Spawn ALL REFACTOR-B* in parallel |
| Fan-out (REFACTOR-B{NN} done) | VALIDATE-B{NN} + REVIEW-B{NN} ready | Spawn both for that branch in parallel |
| Fan-out (REFACTOR-B{NN} done) | VALIDATE + REVIEW ready | Spawn both for that branch in parallel |
| Independent | Any unblocked task | Spawn all ready tasks across all pipelines in parallel |
4. STOP after spawning -- wait for next callback
6. Update session, output summary, STOP
### Review-Fix Cycle (CP-3)
## Review-Fix Cycle (CP-3)
**Per-branch/pipeline scoping**: Each branch/pipeline has its own independent fix cycle.
#### Single Mode (unchanged)
When both VALIDATE-* and REVIEW-* are completed for a branch/pipeline:
When both VALIDATE-001 and REVIEW-001 are completed:
1. Read validation verdict from .msg/meta.json (validator namespace)
2. Read review verdict from .msg/meta.json (reviewer namespace)
1. Read validation verdict from scoped meta.json namespace
2. Read review verdict from scoped meta.json namespace
| Validate Verdict | Review Verdict | Action |
|-----------------|----------------|--------|
| PASS | APPROVE | -> handleComplete |
| PASS | APPROVE | -> handleComplete check |
| PASS | REVISE | Create FIX task with review feedback |
| FAIL | APPROVE | Create FIX task with validation feedback |
| FAIL | REVISE/REJECT | Create FIX task with combined feedback |
| Any | REJECT | Create FIX task + flag for designer re-evaluation |
#### Fan-out Mode (per-branch)
Fix cycle tracking per branch in session.json `fix_cycles`:
- < 3: Create FIX task, increment cycle count
- >= 3: Escalate THIS branch to user. Other branches continue
When both VALIDATE-B{NN} and REVIEW-B{NN} are completed for a specific branch:
## handleComplete
1. Read validation verdict from `validator.B{NN}` namespace
2. Read review verdict from `reviewer.B{NN}` namespace
3. Apply same verdict matrix as single mode, but scoped to this branch only
4. **Other branches are unaffected** -- they continue independently
Pipeline done. Generate report and completion action.
#### Independent Mode (per-pipeline)
Completion check by mode:
| Mode | Completion Condition |
|------|---------------------|
| Single | All 5 tasks (+ any FIX/retry tasks) completed |
| Fan-out | ALL branches have VALIDATE + REVIEW completed (or escalated), shared stages done |
| Independent | ALL pipelines have VALIDATE + REVIEW completed (or escalated) |
When both VALIDATE-{P}01 and REVIEW-{P}01 are completed for a specific pipeline:
1. For fan-out/independent: aggregate per-branch/pipeline results to `<session>/artifacts/aggregate-results.json`
2. If any tasks not completed, return to handleSpawnNext
3. If all completed -> transition to coordinator Phase 5
1. Read verdicts from `validator.{P}` and `reviewer.{P}` namespaces
2. Apply same verdict matrix, scoped to this pipeline only
#### Fix Cycle Count Tracking
Fix cycles are tracked per branch/pipeline in `session.json`:
```json
// Single mode
{ "fix_cycles": { "main": 0 } }
// Fan-out mode
{ "fix_cycles": { "B01": 0, "B02": 1, "B03": 0 } }
// Independent mode
{ "fix_cycles": { "A": 0, "B": 2 } }
```
| Cycle Count | Action |
|-------------|--------|
| < 3 | Create FIX task, increment cycle count for this branch/pipeline |
| >= 3 | Escalate THIS branch/pipeline to user. Other branches continue |
#### FIX Task Creation (branched)
**Fan-out mode**:
```
TaskCreate({
subject: "FIX-B{NN}-{cycle}",
description: "PURPOSE: Fix issues in branch B{NN} from review/validation | Success: All flagged issues resolved
TASK:
- Address review findings: <specific-findings>
- Fix validation failures: <specific-failures>
- Re-validate after fixes
CONTEXT:
- Session: <session-folder>
- Branch: B{NN}
- Upstream artifacts: branches/B{NN}/review-report.md, branches/B{NN}/validation-results.json
- Shared memory: <session>/wisdom/.msg/meta.json (namespace: refactorer.B{NN})
EXPECTED: Fixed source files for B{NN} only
CONSTRAINTS: Targeted fixes only | Do not touch other branches
---
InnerLoop: false
BranchId: B{NN}"
})
TaskUpdate({ taskId: "FIX-B{NN}-{cycle}", owner: "refactorer" })
```
Create new VALIDATE and REVIEW with retry suffix:
- `VALIDATE-B{NN}-R{cycle}` blocked on `FIX-B{NN}-{cycle}`
- `REVIEW-B{NN}-R{cycle}` blocked on `FIX-B{NN}-{cycle}`
**Independent mode**:
```
TaskCreate({
subject: "FIX-{P}01-{cycle}",
...same pattern with pipeline prefix...
})
TaskUpdate({ taskId: "FIX-{P}01-{cycle}", owner: "refactorer" })
```
Create `VALIDATE-{P}01-R{cycle}` and `REVIEW-{P}01-R{cycle}`.
### handleCheck
Output current pipeline status grouped by branch/pipeline.
**Single mode** (unchanged):
```
Pipeline Status:
[DONE] ANALYZE-001 (analyzer) -> architecture-report.md
[DONE] DESIGN-001 (designer) -> refactoring-plan.md
[RUN] REFACTOR-001 (refactorer) -> refactoring...
[WAIT] VALIDATE-001 (validator) -> blocked by REFACTOR-001
[WAIT] REVIEW-001 (reviewer) -> blocked by REFACTOR-001
Fix Cycles: 0/3
Session: <session-id>
```
**Fan-out mode**:
```
Pipeline Status (fan-out, 3 branches):
Shared Stages:
[DONE] ANALYZE-001 (analyzer) -> architecture-report.md
[DONE] DESIGN-001 (designer) -> refactoring-plan.md (4 REFACTOR-IDs)
Branch B01 (REFACTOR-001: <title>):
[RUN] REFACTOR-B01 (refactorer) -> refactoring...
[WAIT] VALIDATE-B01 (validator) -> blocked by REFACTOR-B01
[WAIT] REVIEW-B01 (reviewer) -> blocked by REFACTOR-B01
Fix Cycles: 0/3
Branch B02 (REFACTOR-002: <title>):
[DONE] REFACTOR-B02 (refactorer) -> done
[RUN] VALIDATE-B02 (validator) -> validating...
[RUN] REVIEW-B02 (reviewer) -> reviewing...
Fix Cycles: 0/3
Branch B03 (REFACTOR-003: <title>):
[FAIL] REFACTOR-B03 (refactorer) -> failed
Fix Cycles: 0/3 [BRANCH FAILED]
Session: <session-id>
```
**Independent mode**:
```
Pipeline Status (independent, 2 pipelines):
Pipeline A (target: refactor auth module):
[DONE] ANALYZE-A01 -> [DONE] DESIGN-A01 -> [RUN] REFACTOR-A01 -> ...
Fix Cycles: 0/3
Pipeline B (target: refactor API layer):
[DONE] ANALYZE-B01 -> [DONE] DESIGN-B01 -> [DONE] REFACTOR-B01 -> ...
Fix Cycles: 1/3
Session: <session-id>
```
Output status -- do NOT advance pipeline.
### handleResume
Resume pipeline after user pause or interruption.
1. Audit task list for inconsistencies:
- Tasks stuck in "in_progress" -> reset to "pending"
- Tasks with completed blockers but still "pending" -> include in spawn list
2. For fan-out/independent: check each branch/pipeline independently
3. Proceed to handleSpawnNext
### handleConsensus
## handleConsensus
Handle consensus_blocked signals from discuss rounds.
@@ -270,61 +164,19 @@ Handle consensus_blocked signals from discuss rounds.
| MEDIUM | Create revision task for the blocked role (scoped to branch if applicable) |
| LOW | Log finding, continue pipeline |
### handleComplete
## handleAdapt
Triggered when all pipeline tasks are completed and no fix cycles remain.
Capability gap reported mid-pipeline.
**Completion check varies by mode**:
1. Parse gap description
2. Check if existing role covers it -> redirect
3. Role count < 5 -> generate dynamic role-spec in <session>/role-specs/
4. Create new task, spawn worker
5. Role count >= 5 -> merge or pause
| Mode | Completion Condition |
|------|---------------------|
| Single | All 5 tasks (+ any FIX/retry tasks) have status "completed" |
| Fan-out | ALL branches have VALIDATE + REVIEW completed with PASS/APPROVE (or escalated), shared stages done |
| Independent | ALL pipelines have VALIDATE + REVIEW completed with PASS/APPROVE (or escalated) |
## Fast-Advance Reconciliation
**Aggregate results** before transitioning to Phase 5:
1. For fan-out mode: collect per-branch validation results into `<session>/artifacts/aggregate-results.json`:
```json
{
"branches": {
"B01": { "refactor_id": "REFACTOR-001", "validate_verdict": "PASS", "review_verdict": "APPROVE", "improvement": "..." },
"B02": { "refactor_id": "REFACTOR-002", "validate_verdict": "PASS", "review_verdict": "APPROVE", "improvement": "..." },
"B03": { "status": "failed", "reason": "REFACTOR failed" }
},
"overall": { "total_branches": 3, "passed": 2, "failed": 1 }
}
```
2. For independent mode: collect per-pipeline results similarly
3. If any tasks not completed, return to handleSpawnNext
4. If all completed (allowing for failed branches marked as such), transition to coordinator Phase 5
### handleRevise
Triggered by user "revise <TASK-ID> [feedback]" command.
1. Parse target task ID and optional feedback
2. Detect branch/pipeline from task ID pattern
3. Create revision task with same role but updated requirements, scoped to branch
4. Set blockedBy to empty (immediate execution)
5. Cascade: create new downstream tasks within same branch only
6. Proceed to handleSpawnNext
### handleFeedback
Triggered by user "feedback <text>" command.
1. Analyze feedback text to determine impact scope
2. Identify which pipeline stage, role, and branch/pipeline should handle the feedback
3. Create targeted revision task (scoped to branch if applicable)
4. Proceed to handleSpawnNext
## Phase 4: State Persistence
After every handler execution:
1. Update session.json with current state (active tasks, fix cycle counts per branch, last event, resolved parallel_mode)
2. Verify task list consistency
3. STOP and wait for next event
On every coordinator wake:
1. Read team_msg entries with type="fast_advance"
2. Sync active_workers with spawned successors
3. No duplicate spawns

298
.claude/skills/team-arch-opt/roles/coordinator/role.md
View File

@@ -1,15 +1,14 @@
# Coordinator - Architecture Optimization Team
# Coordinator
**Role**: coordinator
**Type**: Orchestrator
**Team**: arch-opt
Orchestrate team-arch-opt: analyze -> dispatch -> spawn -> monitor -> report.
Orchestrates the architecture optimization pipeline: manages task chains, spawns team-worker agents, handles review-fix cycles, and drives the pipeline to completion.
## Identity
- Name: coordinator | Tag: [coordinator]
- Responsibility: Analyze task -> Create team -> Dispatch tasks -> Monitor progress -> Report results
## Boundaries
### MUST
- Use `team-worker` agent type for all worker spawns (NOT `general-purpose`)
- Follow Command Execution Protocol for dispatch and monitor commands
- Respect pipeline stage dependencies (blockedBy)
@@ -18,113 +17,55 @@ Orchestrates the architecture optimization pipeline: manages task chains, spawns
- Execute completion action in Phase 5
### MUST NOT
- Implement domain logic (analyzing, refactoring, reviewing) -- workers handle this
- Spawn workers without creating tasks first
- Skip checkpoints when configured
- Force-advance pipeline past failed review/validation
- Modify source code directly -- delegate to refactorer worker
---
## Command Execution Protocol
When coordinator needs to execute a command (dispatch, monitor):
1. **Read the command file**: `roles/coordinator/commands/<command-name>.md`
2. **Follow the workflow** defined in the command file (Phase 2-4 structure)
3. **Commands are inline execution guides** -- NOT separate agents or subprocesses
4. **Execute synchronously** -- complete the command workflow before proceeding
Example:
```
Phase 3 needs task dispatch
-> Read roles/coordinator/commands/dispatch.md
-> Execute Phase 2 (Context Loading)
-> Execute Phase 3 (Task Chain Creation)
-> Execute Phase 4 (Validation)
-> Continue to Phase 4
```
---
When coordinator needs to execute a specific phase:
1. Read `commands/<command>.md`
2. Follow the workflow defined in the command
3. Commands are inline execution guides, NOT separate agents
4. Execute synchronously, complete before proceeding
## Entry Router
When coordinator is invoked, detect invocation type:
| Detection | Condition | Handler |
|-----------|-----------|---------|
| Worker callback | Message contains role tag [analyzer], [designer], [refactorer], [validator], [reviewer] | -> handleCallback |
| Branch callback | Message contains branch tag [refactorer-B01], [validator-B02], etc. | -> handleCallback (branch-aware) |
| Pipeline callback | Message contains pipeline tag [analyzer-A], [refactorer-B], etc. | -> handleCallback (pipeline-aware) |
| Consensus blocked | Message contains "consensus_blocked" | -> handleConsensus |
| Status check | Arguments contain "check" or "status" | -> handleCheck |
| Manual resume | Arguments contain "resume" or "continue" | -> handleResume |
| Pipeline complete | All tasks have status "completed" | -> handleComplete |
| Interrupted session | Active/paused session exists | -> Phase 0 (Resume Check) |
| New session | None of above | -> Phase 1 (Requirement Clarification) |
| Worker callback | Message contains [analyzer], [designer], [refactorer], [validator], [reviewer] | -> handleCallback (monitor.md) |
| Branch callback | Message contains [refactorer-B01], [validator-B02], etc. | -> handleCallback branch-aware (monitor.md) |
| Pipeline callback | Message contains [analyzer-A], [refactorer-B], etc. | -> handleCallback pipeline-aware (monitor.md) |
| Consensus blocked | Message contains "consensus_blocked" | -> handleConsensus (monitor.md) |
| Status check | Args contain "check" or "status" | -> handleCheck (monitor.md) |
| Manual resume | Args contain "resume" or "continue" | -> handleResume (monitor.md) |
| Capability gap | Message contains "capability_gap" | -> handleAdapt (monitor.md) |
| Pipeline complete | All tasks completed | -> handleComplete (monitor.md) |
| Interrupted session | Active session in .workflow/.team/TAO-* | -> Phase 0 |
| New session | None of above | -> Phase 1 |
For callback/check/resume/complete: load `commands/monitor.md` and execute matched handler, then STOP.
### Router Implementation
1. **Load session context** (if exists):
- Scan `.workflow/.team/ARCH-OPT-*/.msg/meta.json` for active/paused sessions
- If found, extract session folder path, status, and `parallel_mode`
2. **Parse $ARGUMENTS** for detection keywords:
- Check for role name tags in message content (including branch variants like `[refactorer-B01]`)
- Check for "check", "status", "resume", "continue" keywords
- Check for "consensus_blocked" signal
3. **Route to handler**:
- For monitor handlers: Read `commands/monitor.md`, execute matched handler, STOP
- For Phase 0: Execute Session Resume Check below
- For Phase 1: Execute Requirement Clarification below
---
For callback/check/resume/consensus/adapt/complete: load commands/monitor.md, execute handler, STOP.
## Phase 0: Session Resume Check
Triggered when an active/paused session is detected on coordinator entry.
1. Load session.json from detected session folder
2. Audit task list:
```
TaskList()
```
3. Reconcile session state vs task status:
| Task Status | Session Expects | Action |
|-------------|----------------|--------|
| in_progress | Should be running | Reset to pending (worker was interrupted) |
| completed | Already tracked | Skip |
| pending + unblocked | Ready to run | Include in spawn list |
4. Rebuild team if not active:
```
TeamCreate({ team_name: "arch-opt" })
```
5. Spawn workers for ready tasks -> Phase 4 coordination loop
---
1. Scan `.workflow/.team/TAO-*/session.json` for active/paused sessions
2. No sessions -> Phase 1
3. Single session -> reconcile (audit TaskList, reset in_progress->pending, rebuild team, kick first ready task)
4. Multiple -> AskUserQuestion for selection
## Phase 1: Requirement Clarification
1. Parse user task description from $ARGUMENTS
2. **Parse parallel mode flags**:
TEXT-LEVEL ONLY. No source code reading.
1. Parse task description from $ARGUMENTS
2. Parse parallel mode flags:
| Flag | Value | Default |
|------|-------|---------|
| `--parallel-mode` | `single`, `fan-out`, `independent`, `auto` | `auto` |
| `--max-branches` | integer 1-10 | 5 (from config) |
- For `independent` mode: remaining positional arguments after flags are `independent_targets` array
- Example: `--parallel-mode=independent "refactor auth" "refactor API"` -> targets = ["refactor auth", "refactor API"]
| `--max-branches` | integer 1-10 | 5 |
3. Identify architecture optimization target:
@@ -132,134 +73,43 @@ TeamCreate({ team_name: "arch-opt" })
|--------|--------|
| Specific file/module mentioned | Scoped refactoring |
| "coupling", "dependency", "structure", generic | Full architecture analysis |
| Specific issue mentioned (cycles, God Class, duplication) | Targeted issue resolution |
| Specific issue (cycles, God Class, duplication) | Targeted issue resolution |
| Multiple quoted targets (independent mode) | Per-target scoped refactoring |
4. If target is unclear, ask for clarification:
4. If target is unclear, AskUserQuestion for scope clarification
5. Record requirement with scope, target issues, parallel_mode, max_branches
## Phase 2: Create Team + Initialize Session
1. Generate session ID: `TAO-<slug>-<date>`
2. Create session folder structure
3. TeamCreate with team name `arch-opt`
4. Write session.json with parallel_mode, max_branches, branches, independent_targets, fix_cycles
5. Initialize meta.json via team_msg state_update:
```
AskUserQuestion({
questions: [{
question: "What should I analyze and refactor? Provide a target scope or describe the architecture issue.",
header: "Scope"
}]
})
```
5. Record refactoring requirement with scope, target issues, parallel_mode, and max_branches
---
## Phase 2: Session & Team Setup
1. Create session directory:
```
Bash("mkdir -p .workflow/<session-id>/artifacts .workflow/<session-id>/explorations .workflow/<session-id>/wisdom .workflow/<session-id>/discussions")
```
For independent mode, also create pipeline subdirectories:
```
// For each target in independent_targets
Bash("mkdir -p .workflow/<session-id>/artifacts/pipelines/A .workflow/<session-id>/artifacts/pipelines/B ...")
```
2. Write session.json with extended fields:
```json
{
"status": "active",
"team_name": "arch-opt",
"requirement": "<requirement>",
"timestamp": "<ISO-8601>",
"parallel_mode": "<auto|single|fan-out|independent>",
"max_branches": 5,
"branches": [],
"independent_targets": [],
"fix_cycles": {}
}
```
- `parallel_mode`: from Phase 1 parsing (default: "auto")
- `max_branches`: from Phase 1 parsing (default: 5)
- `branches`: populated at CP-2.5 for fan-out mode (e.g., ["B01", "B02", "B03"])
- `independent_targets`: populated for independent mode (e.g., ["refactor auth", "refactor API"])
- `fix_cycles`: populated per-branch/pipeline as fix cycles occur
4. Initialize meta.json with pipeline metadata:
```typescript
// Use team_msg to write pipeline metadata to .msg/meta.json
mcp__ccw-tools__team_msg({
operation: "log",
session_id: "<session-id>",
from: "coordinator",
type: "state_update",
summary: "Session initialized",
data: {
pipeline_mode: "<parallel_mode>",
pipeline_stages: ["analyzer", "designer", "refactorer", "validator", "reviewer"],
roles: ["coordinator", "analyzer", "designer", "refactorer", "validator", "reviewer"],
team_name: "arch-opt"
}
operation: "log", session_id: "<id>", from: "coordinator",
type: "state_update", summary: "Session initialized",
data: { pipeline_mode: "<mode>", pipeline_stages: ["analyzer","designer","refactorer","validator","reviewer"], team_name: "arch-opt" }
})
```
6. Write session.json
5. Create team:
## Phase 3: Create Task Chain
```
TeamCreate({ team_name: "arch-opt" })
```
Delegate to commands/dispatch.md:
1. Read dependency graph and parallel mode from session.json
2. Topological sort tasks
3. Create tasks via TaskCreate with blockedBy
4. Update session.json with task count
---
## Phase 4: Spawn-and-Stop
## Phase 3: Task Chain Creation
Execute `commands/dispatch.md` inline (Command Execution Protocol):
1. Read `roles/coordinator/commands/dispatch.md`
2. Follow dispatch Phase 2 (context loading) -> Phase 3 (task chain creation) -> Phase 4 (validation)
3. Result: all pipeline tasks created with correct blockedBy dependencies
---
## Phase 4: Spawn & Coordination Loop
### Initial Spawn
Find first unblocked task and spawn its worker:
```
Agent({
subagent_type: "team-worker",
description: "Spawn analyzer worker",
team_name: "arch-opt",
name: "analyzer",
run_in_background: true,
prompt: `## Role Assignment
role: analyzer
role_spec: .claude/skills/team-arch-opt/role-specs/analyzer.md
session: <session-folder>
session_id: <session-id>
team_name: arch-opt
requirement: <requirement>
inner_loop: false
Read role_spec file to load Phase 2-4 domain instructions.
Execute built-in Phase 1 -> role-spec Phase 2-4 -> built-in Phase 5.`
})
```
**STOP** after spawning. Wait for worker callback.
### Coordination (via monitor.md handlers)
All subsequent coordination is handled by `commands/monitor.md` handlers triggered by worker callbacks:
- handleCallback -> mark task done -> check pipeline -> handleSpawnNext
- handleSpawnNext -> find ready tasks -> spawn team-worker agents -> STOP
- handleComplete -> all done -> Phase 5
---
Delegate to commands/monitor.md#handleSpawnNext:
1. Find ready tasks (pending + blockedBy resolved)
2. Spawn team-worker agents (see SKILL.md Spawn Template)
3. Output status summary
4. STOP
## Phase 5: Report + Completion Action
@@ -275,29 +125,19 @@ All subsequent coordination is handled by `commands/monitor.md` handlers trigger
| Review Report | <session>/artifacts/review-report.md |
3. Include discussion summaries if discuss rounds were used
4. Output pipeline summary: task count, duration, improvement metrics from validation results
4. Output pipeline summary: task count, duration, improvement metrics
5. **Completion Action** (interactive):
5. Execute completion action per session.completion_action:
- interactive -> AskUserQuestion (Archive/Keep/Export)
- auto_archive -> Archive & Clean (status=completed, TeamDelete)
- auto_keep -> Keep Active (status=paused)
```
AskUserQuestion({
questions: [{
question: "Team pipeline complete. What would you like to do?",
header: "Completion",
multiSelect: false,
options: [
{ label: "Archive & Clean (Recommended)", description: "Archive session, clean up tasks and team resources" },
{ label: "Keep Active", description: "Keep session active for follow-up work or inspection" },
{ label: "Export Results", description: "Export deliverables to a specified location, then clean" }
]
}]
})
```
## Error Handling
6. Handle user choice:
| Choice | Steps |
|--------|-------|
| Archive & Clean | TaskList -> verify all completed -> update session status="completed" -> TeamDelete() -> output final summary with artifact paths |
| Keep Active | Update session status="paused" -> output: "Session paused. Resume with: Skill(skill='team-arch-opt', args='resume')" |
| Export Results | AskUserQuestion for target directory -> copy all artifacts -> Archive & Clean flow |
| Error | Resolution |
|-------|------------|
| Task too vague | AskUserQuestion for clarification |
| Session corruption | Attempt recovery, fallback to manual |
| Worker crash | Reset task to pending, respawn |
| Dependency cycle | Detect in analysis, halt |
| Role limit exceeded | Merge overlapping roles |

115
.claude/skills/team-arch-opt/roles/designer/role.md Normal file
View File

@@ -0,0 +1,115 @@
---
role: designer
prefix: DESIGN
inner_loop: false
message_types: [state_update]
---
# Refactoring Designer
Analyze architecture reports and baseline metrics to design a prioritized refactoring plan with concrete strategies, expected structural improvements, and risk assessments.
## Phase 2: Analysis Loading
| Input | Source | Required |
|-------|--------|----------|
| Architecture report | <session>/artifacts/architecture-report.md | Yes |
| Architecture baseline | <session>/artifacts/architecture-baseline.json | Yes |
| .msg/meta.json | <session>/wisdom/.msg/meta.json | Yes |
| Wisdom files | <session>/wisdom/patterns.md | No |
1. Extract session path from task description
2. Read architecture report -- extract ranked issue list with severities and categories
3. Read architecture baseline -- extract current structural metrics
4. Load .msg/meta.json for analyzer findings (project_type, scope)
5. Assess overall refactoring complexity:
| Issue Count | Severity Mix | Complexity |
|-------------|-------------|------------|
| 1-2 | All Medium | Low |
| 2-3 | Mix of High/Medium | Medium |
| 3+ or any Critical | Any Critical present | High |
## Phase 3: Strategy Formulation
For each architecture issue, select refactoring approach by type:
| Issue Type | Strategies | Risk Level |
|------------|-----------|------------|
| Circular dependency | Interface extraction, dependency inversion, mediator pattern | High |
| God Class/Module | SRP decomposition, extract class/module, delegate pattern | High |
| Layering violation | Move to correct layer, introduce Facade, add anti-corruption layer | Medium |
| Code duplication | Extract shared utility/base class, template method pattern | Low |
| High coupling | Introduce interface/abstraction, dependency injection, event-driven | Medium |
| API bloat / dead exports | Privatize internals, re-export only public API, barrel file cleanup | Low |
| Dead code | Safe removal with reference verification | Low |
| Missing abstraction | Extract interface/type, introduce strategy/factory pattern | Medium |
Prioritize refactorings by impact/effort ratio:
| Priority | Criteria |
|----------|----------|
| P0 (Critical) | High impact + Low effort -- quick wins (dead code removal, simple moves) |
| P1 (High) | High impact + Medium effort (cycle breaking, layer fixes) |
| 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` 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).
## Phase 4: Plan Output
1. Write refactoring plan to `<session>/artifacts/refactoring-plan.md`:
Each refactoring MUST have a unique REFACTOR-ID and self-contained detail block:
```markdown
### REFACTOR-001: <title>
- Priority: P0
- Target issue: <issue from report>
- Issue type: <CYCLE|COUPLING|GOD_CLASS|DUPLICATION|LAYER_VIOLATION|DEAD_CODE|API_BLOAT>
- Target files: <file-list>
- Strategy: <selected approach>
- Expected improvement: <metric> by <description>
- Risk level: <Low/Medium/High>
- Success criteria: <specific structural change to verify>
- Implementation guidance:
1. <step 1>
2. <step 2>
3. <step 3>
### REFACTOR-002: <title>
...
```
Requirements:
- Each REFACTOR-ID is sequentially numbered (REFACTOR-001, REFACTOR-002, ...)
- Each refactoring must be **non-overlapping** in target files (no two REFACTOR-IDs modify the same file unless explicitly noted with conflict resolution)
- Implementation guidance must be self-contained -- a branch refactorer should be able to work from a single REFACTOR block without reading others
2. Update `<session>/wisdom/.msg/meta.json` under `designer` namespace:
- Read existing -> merge -> write back:
```json
{
"designer": {
"complexity": "<Low|Medium|High>",
"refactoring_count": 4,
"priorities": ["P0", "P0", "P1", "P2"],
"discuss_used": false,
"refactorings": [
{
"id": "REFACTOR-001",
"title": "<title>",
"issue_type": "<CYCLE|COUPLING|...>",
"priority": "P0",
"target_files": ["src/a.ts", "src/b.ts"],
"expected_improvement": "<metric> by <description>",
"success_criteria": "<threshold>"
}
]
}
}
```
3. If DISCUSS-REFACTOR was triggered, record discussion summary in `<session>/discussions/DISCUSS-REFACTOR.md`

102
.claude/skills/team-arch-opt/roles/refactorer/role.md Normal file
View File

@@ -0,0 +1,102 @@
---
role: refactorer
prefix: REFACTOR
inner_loop: true
message_types: [state_update]
---
# Code Refactorer
Implement architecture refactoring changes following the design plan. For FIX tasks, apply targeted corrections based on review/validation feedback.
## Modes
| Mode | Task Prefix | Trigger | Focus |
|------|-------------|---------|-------|
| Refactor | REFACTOR | Design plan ready | Apply refactorings per plan priority |
| Fix | FIX | Review/validation feedback | Targeted fixes for identified issues |
## Phase 2: Plan & Context Loading
| Input | Source | Required |
|-------|--------|----------|
| Refactoring plan | <session>/artifacts/refactoring-plan.md | Yes (REFACTOR, no branch) |
| Branch refactoring detail | <session>/artifacts/branches/B{NN}/refactoring-detail.md | Yes (REFACTOR with branch) |
| Pipeline refactoring plan | <session>/artifacts/pipelines/{P}/refactoring-plan.md | Yes (REFACTOR with pipeline) |
| Review/validation feedback | From task description | Yes (FIX) |
| .msg/meta.json | <session>/wisdom/.msg/meta.json | Yes |
| Wisdom files | <session>/wisdom/patterns.md | No |
| Context accumulator | From prior REFACTOR/FIX tasks | Yes (inner loop) |
1. Extract session path and task mode (REFACTOR or FIX) from task description
2. **Detect branch/pipeline context** from task description:
| Task Description Field | Value | Context |
|----------------------|-------|---------|
| `BranchId: B{NN}` | Present | Fan-out branch -- load single refactoring detail |
| `PipelineId: {P}` | Present | Independent pipeline -- load pipeline-scoped plan |
| Neither present | - | Single mode -- load full refactoring plan |
3. **Load refactoring context by mode**:
- **Single mode (no branch)**: Read `<session>/artifacts/refactoring-plan.md` -- extract ALL priority-ordered changes
- **Fan-out branch**: Read `<session>/artifacts/branches/B{NN}/refactoring-detail.md` -- extract ONLY this branch's refactoring (single REFACTOR-ID)
- **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` 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**:
- Single: write to `refactorer` namespace
- Fan-out: write to `refactorer.B{NN}` namespace
- Independent: write to `refactorer.{P}` namespace
## Phase 3: Code Implementation
Implementation backend selection:
| Backend | Condition | Method |
|---------|-----------|--------|
| CLI | Multi-file refactoring with clear plan | ccw cli --tool gemini --mode write |
| Direct | Single-file changes or targeted fixes | Inline Edit/Write tools |
For REFACTOR tasks:
- **Single mode**: Apply refactorings in plan priority order (P0 first, then P1, etc.)
- **Fan-out branch**: Apply ONLY this branch's single refactoring (from refactoring-detail.md)
- **Independent pipeline**: Apply this pipeline's refactorings in priority order
- Follow implementation guidance from plan (target files, patterns)
- **Preserve existing behavior -- refactoring must not change functionality**
- **Update ALL import references** when moving/renaming modules
- **Update ALL test files** that reference moved/renamed symbols
For FIX tasks:
- Read specific issues from review/validation feedback
- Apply targeted corrections to flagged code locations
- Verify the fix addresses the exact concern raised
General rules:
- Make minimal, focused changes per refactoring
- Add comments only where refactoring logic is non-obvious
- Preserve existing code style and conventions
- Verify no dangling imports after module moves
## Phase 4: Self-Validation
| Check | Method | Pass Criteria |
|-------|--------|---------------|
| Syntax | IDE diagnostics or build check | No new errors |
| File integrity | Verify all planned files exist and are modified | All present |
| Import integrity | Verify no broken imports after moves | All imports resolve |
| Acceptance | Match refactoring plan success criteria | All structural changes applied |
| No regression | Run existing tests if available | No new failures |
If validation fails, attempt auto-fix (max 2 attempts) before reporting error.
Append to context_accumulator for next REFACTOR/FIX task (single/inner-loop mode only):
- Files modified, refactorings applied, validation results
- Any discovered patterns or caveats for subsequent iterations
**Branch output paths**:
- Single: write artifacts to `<session>/artifacts/`
- Fan-out: write artifacts to `<session>/artifacts/branches/B{NN}/`
- Independent: write artifacts to `<session>/artifacts/pipelines/{P}/`

111
.claude/skills/team-arch-opt/roles/reviewer/role.md Normal file
View File

@@ -0,0 +1,111 @@
---
role: reviewer
prefix: REVIEW
inner_loop: false
message_types: [state_update]
---
# Architecture Reviewer
Review refactoring code changes for correctness, pattern consistency, completeness, migration safety, and adherence to best practices. Provide structured verdicts with actionable feedback.
## Phase 2: Context Loading
| Input | Source | Required |
|-------|--------|----------|
| Refactoring code changes | From REFACTOR task artifacts / git diff | Yes |
| Refactoring plan / detail | Varies by mode (see below) | Yes |
| Validation results | Varies by mode (see below) | No |
| .msg/meta.json | <session>/wisdom/.msg/meta.json | Yes |
1. Extract session path from task description
2. **Detect branch/pipeline context** from task description:
| Task Description Field | Value | Context |
|----------------------|-------|---------|
| `BranchId: B{NN}` | Present | Fan-out branch -- review only this branch's changes |
| `PipelineId: {P}` | Present | Independent pipeline -- review pipeline-scoped changes |
| Neither present | - | Single mode -- review all refactoring changes |
3. **Load refactoring context by mode**:
- Single: Read `<session>/artifacts/refactoring-plan.md`
- Fan-out branch: Read `<session>/artifacts/branches/B{NN}/refactoring-detail.md`
- Independent: Read `<session>/artifacts/pipelines/{P}/refactoring-plan.md`
4. Load .msg/meta.json for scoped refactorer namespace:
- Single: `refactorer` namespace
- Fan-out: `refactorer.B{NN}` namespace
- Independent: `refactorer.{P}` namespace
5. Identify changed files from refactorer context -- read ONLY files modified by this branch/pipeline
6. If validation results available, read from scoped path:
- Single: `<session>/artifacts/validation-results.json`
- Fan-out: `<session>/artifacts/branches/B{NN}/validation-results.json`
- Independent: `<session>/artifacts/pipelines/{P}/validation-results.json`
## Phase 3: Multi-Dimension Review
Analyze refactoring changes across five dimensions:
| Dimension | Focus | Severity |
|-----------|-------|----------|
| Correctness | No behavior changes, all references updated, no dangling imports | Critical |
| Pattern consistency | Follows existing patterns, naming consistent, language-idiomatic | High |
| Completeness | All related code updated (imports, tests, config, documentation) | High |
| Migration safety | No dangling references, backward compatible, public API preserved | Critical |
| Best practices | Clean Architecture / SOLID principles, appropriate abstraction level | Medium |
Per-dimension review process:
- Scan modified files for patterns matching each dimension
- Record findings with severity (Critical / High / Medium / Low)
- Include specific file:line references and suggested fixes
**Correctness checks**:
- Verify moved code preserves original behavior (no logic changes mixed with structural changes)
- Check all import/require statements updated to new paths
- Verify no orphaned files left behind after moves
**Pattern consistency checks**:
- New module names follow existing naming conventions
- Extracted interfaces/classes use consistent patterns with existing codebase
- File organization matches project conventions (e.g., index files, barrel exports)
**Completeness checks**:
- All test files updated for moved/renamed modules
- Configuration files updated if needed (e.g., path aliases, build configs)
- Type definitions updated for extracted interfaces
**Migration safety checks**:
- Public API surface unchanged (same exports available to consumers)
- No circular dependencies introduced by the refactoring
- Re-exports in place if module paths changed for backward compatibility
**Best practices checks**:
- Extracted modules have clear single responsibility
- Dependency direction follows layer conventions (dependencies flow inward)
- Appropriate abstraction level (not over-engineered, not under-abstracted)
If any Critical findings detected, invoke `discuss` CLI tool (DISCUSS-REVIEW round) to validate the assessment before issuing verdict.
## Phase 4: Verdict & Feedback
Classify overall verdict based on findings:
| Verdict | Condition | Action |
|---------|-----------|--------|
| APPROVE | No Critical or High findings | Send review_complete |
| REVISE | Has High findings, no Critical | Send fix_required with detailed feedback |
| REJECT | Has Critical findings or fundamental approach flaw | Send fix_required + flag for designer escalation |
1. Write review report to scoped output path:
- Single: `<session>/artifacts/review-report.md`
- Fan-out: `<session>/artifacts/branches/B{NN}/review-report.md`
- Independent: `<session>/artifacts/pipelines/{P}/review-report.md`
- Content: Per-dimension findings with severity, file:line, description; Overall verdict with rationale; Specific fix instructions for REVISE/REJECT verdicts
2. Update `<session>/wisdom/.msg/meta.json` under scoped namespace:
- Single: merge `{ "reviewer": { verdict, finding_count, critical_count, dimensions_reviewed } }`
- Fan-out: merge `{ "reviewer.B{NN}": { verdict, finding_count, critical_count, dimensions_reviewed } }`
- Independent: merge `{ "reviewer.{P}": { verdict, finding_count, critical_count, dimensions_reviewed } }`
3. If DISCUSS-REVIEW was triggered, record discussion summary in `<session>/discussions/DISCUSS-REVIEW.md` (or `DISCUSS-REVIEW-B{NN}.md` for branch-scoped discussions)

115
.claude/skills/team-arch-opt/roles/validator/role.md Normal file
View File

@@ -0,0 +1,115 @@
---
role: validator
prefix: VALIDATE
inner_loop: false
message_types: [state_update]
---
# Architecture Validator
Validate refactoring changes by running build checks, test suites, dependency metric comparisons, and API compatibility verification. Ensure refactoring improves architecture without breaking functionality.
## Phase 2: Environment & Baseline Loading
| Input | Source | Required |
|-------|--------|----------|
| Architecture baseline | <session>/artifacts/architecture-baseline.json (shared) | Yes |
| Refactoring plan / detail | Varies by mode (see below) | Yes |
| .msg/meta.json | <session>/wisdom/.msg/meta.json | Yes |
1. Extract session path from task description
2. **Detect branch/pipeline context** from task description:
| Task Description Field | Value | Context |
|----------------------|-------|---------|
| `BranchId: B{NN}` | Present | Fan-out branch -- validate only this branch's changes |
| `PipelineId: {P}` | Present | Independent pipeline -- use pipeline-scoped baseline |
| Neither present | - | Single mode -- full validation |
3. **Load architecture baseline**:
- Single / Fan-out: Read `<session>/artifacts/architecture-baseline.json` (shared baseline)
- Independent: Read `<session>/artifacts/pipelines/{P}/architecture-baseline.json`
4. **Load refactoring context**:
- Single: Read `<session>/artifacts/refactoring-plan.md` -- all success criteria
- Fan-out branch: Read `<session>/artifacts/branches/B{NN}/refactoring-detail.md` -- only this branch's criteria
- Independent: Read `<session>/artifacts/pipelines/{P}/refactoring-plan.md`
5. Load .msg/meta.json for project type and refactoring scope
6. Detect available validation tools from project:
| Signal | Validation Tool | Method |
|--------|----------------|--------|
| package.json + tsc | TypeScript compiler | Type-check entire project |
| package.json + vitest/jest | Test runner | Run existing test suite |
| package.json + eslint | Linter | Run lint checks for import/export issues |
| Cargo.toml | Rust compiler | cargo check + cargo test |
| go.mod | Go tools | go build + go test |
| Makefile with test target | Custom tests | make test |
| No tooling detected | Manual validation | File existence + import grep checks |
7. Get changed files scope from .msg/meta.json:
- Single: `refactorer` namespace
- Fan-out: `refactorer.B{NN}` namespace
- Independent: `refactorer.{P}` namespace
## Phase 3: Validation Execution
Run validations across four dimensions:
**Build validation**:
- Compile/type-check the project -- zero new errors allowed
- Verify all moved/renamed files are correctly referenced
- Check for missing imports or unresolved modules
**Test validation**:
- Run existing test suite -- all previously passing tests must still pass
- Identify any tests that need updating due to module moves (update, don't skip)
- Check for test file imports that reference old paths
**Dependency metric validation**:
- Recalculate architecture metrics post-refactoring
- Compare coupling scores against baseline (must improve or stay neutral)
- Verify no new circular dependencies introduced
- Check cohesion metrics for affected modules
**API compatibility validation**:
- Verify public API signatures are preserved (exported function/class/type names)
- Check for dangling references (imports pointing to removed/moved files)
- Verify no new dead exports introduced by the refactoring
- Check that re-exports maintain backward compatibility where needed
**Branch-scoped validation** (fan-out mode):
- Only validate metrics relevant to this branch's refactoring (from refactoring-detail.md)
- Still check for regressions across all metrics (not just branch-specific ones)
## Phase 4: Result Analysis
Compare against baseline and plan criteria:
| Metric | Threshold | Verdict |
|--------|-----------|---------|
| Build passes | Zero compilation errors | PASS |
| All tests pass | No new test failures | PASS |
| Coupling improved or neutral | No metric degradation > 5% | PASS |
| No new cycles introduced | Cycle count <= baseline | PASS |
| All plan success criteria met | Every criterion satisfied | PASS |
| Partial improvement | Some metrics improved, none degraded | WARN |
| Build fails | Compilation errors detected | FAIL -> fix_required |
| Test failures | Previously passing tests now fail | FAIL -> fix_required |
| New cycles introduced | Cycle count > baseline | FAIL -> fix_required |
| Dangling references | Unresolved imports detected | FAIL -> fix_required |
1. Write validation results to output path:
- Single: `<session>/artifacts/validation-results.json`
- Fan-out: `<session>/artifacts/branches/B{NN}/validation-results.json`
- Independent: `<session>/artifacts/pipelines/{P}/validation-results.json`
- Content: Per-dimension: name, baseline value, current value, improvement/regression, verdict; Overall verdict: PASS / WARN / FAIL; Failure details (if any)
2. Update `<session>/wisdom/.msg/meta.json` under scoped namespace:
- Single: merge `{ "validator": { verdict, improvements, regressions, build_pass, test_pass } }`
- Fan-out: merge `{ "validator.B{NN}": { verdict, improvements, regressions, build_pass, test_pass } }`
- Independent: merge `{ "validator.{P}": { verdict, improvements, regressions, build_pass, test_pass } }`
3. If verdict is FAIL, include detailed feedback in message for FIX task creation:
- Which validations failed, specific errors, suggested investigation areas

102
.claude/skills/team-arch-opt/specs/pipelines.md Normal file
View File

@@ -0,0 +1,102 @@
# Pipeline Definitions — team-arch-opt
## Available Pipelines
### Single Mode (Linear)
```
ANALYZE-001 → DESIGN-001 → REFACTOR-001 → VALIDATE-001 + REVIEW-001
[analyzer] [designer] [refactorer] [validator] [reviewer]
^ |
+<-- FIX-001 ----+
(max 3 iterations)
```
### Fan-out Mode (Shared Stages + Parallel Branches)
```
ANALYZE-001 → DESIGN-001 --+→ REFACTOR-B01 → VALIDATE-B01 + REVIEW-B01
[analyzer] [designer] | [refactorer] [validator] [reviewer]
+→ REFACTOR-B02 → VALIDATE-B02 + REVIEW-B02
+→ REFACTOR-B0N → VALIDATE-B0N + REVIEW-B0N
|
AGGREGATE → Phase 5
```
Branch tasks created at CP-2.5 after DESIGN-001 completes.
### Independent Mode (M Complete Pipelines)
```
Pipeline A: ANALYZE-A01 → DESIGN-A01 → REFACTOR-A01 → VALIDATE-A01 + REVIEW-A01
Pipeline B: ANALYZE-B01 → DESIGN-B01 → REFACTOR-B01 → VALIDATE-B01 + REVIEW-B01
... |
AGGREGATE → Phase 5
```
### Auto Mode
Auto-detects based on refactoring count at CP-2.5:
- count <= 2 → switch to single mode
- count >= 3 → switch to fan-out mode
## Task Metadata Registry
### Single Mode
| Task ID | Role | Phase | Dependencies | Description |
|---------|------|-------|-------------|-------------|
| ANALYZE-001 | analyzer | Stage 1 | (none) | Analyze architecture, identify structural issues |
| DESIGN-001 | designer | Stage 2 | ANALYZE-001 | Design refactoring plan from architecture report |
| REFACTOR-001 | refactorer | Stage 3 | DESIGN-001 | Implement highest-priority refactorings |
| VALIDATE-001 | validator | Stage 4 | REFACTOR-001 | Validate build, tests, metrics, API compatibility |
| REVIEW-001 | reviewer | Stage 4 | REFACTOR-001 | Review refactoring code for correctness |
| FIX-001 | refactorer | Stage 3 (cycle) | REVIEW-001 or VALIDATE-001 | Fix issues found in review/validation |
### Fan-out Mode (Branch Tasks at CP-2.5)
| Task ID | Role | Phase | Dependencies | Description |
|---------|------|-------|-------------|-------------|
| ANALYZE-001 | analyzer | Stage 1 (shared) | (none) | Analyze architecture |
| DESIGN-001 | designer | Stage 2 (shared) | ANALYZE-001 | Design plan with discrete REFACTOR-IDs |
| REFACTOR-B{NN} | refactorer | Stage 3 (branch) | DESIGN-001 | Implement REFACTOR-{NNN} only |
| VALIDATE-B{NN} | validator | Stage 4 (branch) | REFACTOR-B{NN} | Validate branch B{NN} |
| REVIEW-B{NN} | reviewer | Stage 4 (branch) | REFACTOR-B{NN} | Review branch B{NN} |
| FIX-B{NN}-{cycle} | refactorer | Fix (branch) | (none) | Fix issues in branch B{NN} |
### Independent Mode
| Task ID | Role | Phase | Dependencies | Description |
|---------|------|-------|-------------|-------------|
| ANALYZE-{P}01 | analyzer | Stage 1 | (none) | Analyze for pipeline {P} target |
| DESIGN-{P}01 | designer | Stage 2 | ANALYZE-{P}01 | Design for pipeline {P} |
| REFACTOR-{P}01 | refactorer | Stage 3 | DESIGN-{P}01 | Implement pipeline {P} refactorings |
| VALIDATE-{P}01 | validator | Stage 4 | REFACTOR-{P}01 | Validate pipeline {P} |
| REVIEW-{P}01 | reviewer | Stage 4 | REFACTOR-{P}01 | Review pipeline {P} |
## Checkpoints
| Checkpoint | Trigger | Location | Behavior |
|------------|---------|----------|----------|
| CP-1 | ANALYZE-001 complete | After Stage 1 | User reviews architecture report, can refine scope |
| CP-2 | DESIGN-001 complete | After Stage 2 | User reviews refactoring plan, can adjust priorities |
| CP-2.5 | DESIGN-001 complete (auto/fan-out) | After Stage 2 | Auto-create N branch tasks, spawn all REFACTOR-B* in parallel |
| CP-3 | REVIEW/VALIDATE fail | Stage 4 (per-branch) | Auto-create FIX task for that branch only (max 3x per branch) |
| CP-4 | All tasks/branches complete | Phase 5 | Aggregate results, interactive completion action |
## Task Naming Rules
| Mode | Stage 3 | Stage 4 | Fix | Retry |
|------|---------|---------|-----|-------|
| Single | REFACTOR-001 | VALIDATE-001, REVIEW-001 | FIX-001 | VALIDATE-001-R1, REVIEW-001-R1 |
| Fan-out | REFACTOR-B01 | VALIDATE-B01, REVIEW-B01 | FIX-B01-1 | VALIDATE-B01-R1, REVIEW-B01-R1 |
| Independent | REFACTOR-A01 | VALIDATE-A01, REVIEW-A01 | FIX-A01-1 | VALIDATE-A01-R1, REVIEW-A01-R1 |
## Parallel Mode Invocation
```bash
Skill(skill="team-arch-opt", args="<task-description>") # auto mode
Skill(skill="team-arch-opt", args="--parallel-mode=fan-out <task-description>") # force fan-out
Skill(skill="team-arch-opt", args='--parallel-mode=independent "target1" "target2"') # independent
Skill(skill="team-arch-opt", args="--max-branches=3 <task-description>") # limit branches
```

393
.claude/skills/team-brainstorm/SKILL.md
View File

@@ -1,309 +1,60 @@
---
name: team-brainstorm
description: Unified team skill for brainstorming team. All roles invoke this skill with --role arg for role-specific execution. Triggers on "team brainstorm".
description: Unified team skill for brainstorming team. Uses team-worker agent architecture with role directories for domain logic. Coordinator orchestrates pipeline, workers are team-worker agents. Triggers on "team brainstorm".
allowed-tools: TeamCreate(*), TeamDelete(*), SendMessage(*), TaskCreate(*), TaskUpdate(*), TaskList(*), TaskGet(*), Agent(*), AskUserQuestion(*), Read(*), Write(*), Edit(*), Bash(*), Glob(*), Grep(*)
---
# Team Brainstorm
Unified team skill: multi-angle brainstorming via Generator-Critic loops, shared memory, and dynamic pipeline selection. All team members invoke with `--role=xxx` to route to role-specific execution.
Orchestrate multi-agent brainstorming: generate ideas → challenge assumptions → synthesize → evaluate. Supports Quick, Deep, and Full pipelines with Generator-Critic loop.
## Architecture
```
+---------------------------------------------------+
| Skill(skill="team-brainstorm") |
| args="<topic-description>" |
+-------------------+-------------------------------+
Skill(skill="team-brainstorm", args="topic description")
|
Orchestration Mode (auto -> coordinator)
SKILL.md (this file) = Router
|
Coordinator (inline)
Phase 0-5 orchestration
+--------------+--------------+
| |
no --role flag --role <name>
| |
Coordinator Worker
roles/coordinator/role.md roles/<name>/role.md
|
+-------+-------+-------+-------+
+-- analyze → dispatch → spawn workers → STOP
|
+-------+-------+-------+
v v v v
[tw] [tw] [tw] [tw]
ideator chall- synthe- evalua-
enger sizer tor
(tw) = team-worker agent
[ideator][challenger][synthesizer][evaluator]
```
## Command Execution Protocol
## Role Registry
When coordinator needs to execute a command (dispatch, monitor):
1. **Read the command file**: `roles/coordinator/commands/<command-name>.md`
2. **Follow the workflow** defined in the command file (Phase 2-4 structure)
3. **Commands are inline execution guides** -- NOT separate agents or subprocesses
4. **Execute synchronously** -- complete the command workflow before proceeding
| Role | Path | Prefix | Inner Loop |
|------|------|--------|------------|
| coordinator | [roles/coordinator/role.md](roles/coordinator/role.md) | — | — |
| ideator | [roles/ideator/role.md](roles/ideator/role.md) | IDEA-* | false |
| challenger | [roles/challenger/role.md](roles/challenger/role.md) | CHALLENGE-* | false |
| synthesizer | [roles/synthesizer/role.md](roles/synthesizer/role.md) | SYNTH-* | false |
| evaluator | [roles/evaluator/role.md](roles/evaluator/role.md) | EVAL-* | false |
## Role Router
### Input Parsing
Parse `$ARGUMENTS`:
- Has `--role <name>` → Read `roles/<name>/role.md`, execute Phase 2-4
- No `--role` → Read `roles/coordinator/role.md`, execute entry router
Parse `$ARGUMENTS` to extract `--role`. If absent → Orchestration Mode (auto route to coordinator).
## Shared Constants
### Role Registry
- **Session prefix**: `BRS`
- **Session path**: `.workflow/.team/BRS-<slug>-<date>/`
- **CLI tools**: `ccw cli --mode analysis` (read-only), `ccw cli --mode write` (modifications)
- **Message bus**: `mcp__ccw-tools__team_msg(session_id=<session-id>, ...)`
| Role | Spec | Task Prefix | Inner Loop |
|------|------|-------------|------------|
| coordinator | [roles/coordinator/role.md](roles/coordinator/role.md) | (none) | - |
| ideator | [role-specs/ideator.md](role-specs/ideator.md) | IDEA-* | false |
| challenger | [role-specs/challenger.md](role-specs/challenger.md) | CHALLENGE-* | false |
| synthesizer | [role-specs/synthesizer.md](role-specs/synthesizer.md) | SYNTH-* | false |
| evaluator | [role-specs/evaluator.md](role-specs/evaluator.md) | EVAL-* | false |
## Worker Spawn Template
> **⚠️ COMPACT PROTECTION**: 角色文件是执行文档，不是参考资料。当 context compression 发生后，角色指令仅剩摘要时，**必须立即 `Read` 对应 role.md 重新加载后再继续执行**。不得基于摘要执行任何 Phase。
### Dispatch
1. Extract `--role` from arguments
2. If no `--role` → route to coordinator (Orchestration Mode)
3. Look up role in registry → Read the role file → Execute its phases
### Orchestration Mode
When invoked without `--role`, coordinator auto-starts. User just provides topic description.
**Invocation**: `Skill(skill="team-brainstorm", args="<topic-description>")`
**Lifecycle**:
```
User provides topic description
→ coordinator Phase 1-3: Topic clarification → TeamCreate → Create task chain
→ coordinator Phase 4: spawn first batch workers (background) → STOP
→ Worker executes → SendMessage callback → coordinator advances next step
→ Loop until pipeline complete → Phase 5 report
```
**User Commands** (wake paused coordinator):
| Command | Action |
|---------|--------|
| `check` / `status` | Output execution status graph, no advancement |
| `resume` / `continue` | Check worker states, advance next step |
---
## Shared Infrastructure
The following templates apply to all worker roles. Each role.md only needs to write **Phase 2-4** role-specific logic.
### Worker Phase 1: Task Discovery (shared by all workers)
Every worker executes the same task discovery flow on startup:
1. Call `TaskList()` to get all tasks
2. Filter: subject matches this role's prefix + owner is this role + status is pending + blockedBy is empty
3. No tasks → idle wait
4. Has tasks → `TaskGet` for details → `TaskUpdate` mark in_progress
**Resume Artifact Check** (prevent duplicate output after resume):
- Check whether this task's output artifact already exists
- Artifact complete → skip to Phase 5 report completion
- Artifact incomplete or missing → normal Phase 2-4 execution
### Worker Phase 5: Report (shared by all workers)
Standard reporting flow after task completion:
1. **Message Bus**: Call `mcp__ccw-tools__team_msg` to log message
- Parameters: operation="log", session_id=<session-id>, from=<role>, type=<message-type>, data={ref: "<artifact-path>"}
- `to` and `summary` auto-defaulted -- do NOT specify explicitly
- **CLI fallback**: `ccw team log --session-id <session-id> --from <role> --type <type> --json`
2. **SendMessage**: Send result to coordinator
3. **TaskUpdate**: Mark task completed
4. **Loop**: Return to Phase 1 to check next task
### Wisdom Accumulation (all roles)
Cross-task knowledge accumulation. Coordinator creates `wisdom/` directory at session initialization.
**Directory**:
```
<session-folder>/wisdom/
├── learnings.md # Patterns and insights
├── decisions.md # Architecture and design decisions
├── conventions.md # Codebase conventions
└── issues.md # Known risks and issues
```
**Worker Load** (Phase 2): Extract `Session: <path>` from task description, read wisdom directory files.
**Worker Contribute** (Phase 4/5): Write this task's discoveries to corresponding wisdom files.
### Role Isolation Rules
| Allowed | Forbidden |
|---------|-----------|
| Process tasks with own prefix | Process tasks with other role prefixes |
| SendMessage to coordinator | Communicate directly with other workers |
| 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 generate ideas directly, do not evaluate/challenge ideas, do not execute analysis/synthesis, do not bypass workers.
### Output Tagging
All outputs must carry `[role_name]` prefix in both SendMessage content/summary and team_msg summary.
### Message Bus (All Roles)
Every SendMessage **before**, must call `mcp__ccw-tools__team_msg` to log:
**Parameters**: operation="log", session_id=<session-id>, from=<role>, type=<message-type>, data={ref: "<artifact-path>"}
`to` and `summary` auto-defaulted -- do NOT specify explicitly.
**CLI fallback**: `ccw team log --session-id <session-id> --from <role> --type <type> --json`
**Message types by role**:
| Role | Types |
|------|-------|
| coordinator | `pipeline_selected`, `gc_loop_trigger`, `task_unblocked`, `error`, `shutdown` |
| ideator | `ideas_ready`, `ideas_revised`, `error` |
| challenger | `critique_ready`, `error` |
| synthesizer | `synthesis_ready`, `error` |
| evaluator | `evaluation_ready`, `error` |
### Shared State
Cross-role state is shared via `team_msg(type="state_update")` messages, persisted in `.msg/meta.json`:
| Role | State Key |
|------|-----------|
| ideator | `generated_ideas` |
| challenger | `critique_insights` |
| synthesizer | `synthesis_themes` |
| evaluator | `evaluation_scores` |
### Team Configuration
| Setting | Value |
|---------|-------|
| Team name | brainstorm |
| Session directory | `.workflow/.team/BRS-<slug>-<date>/` |
| Message store | `.msg/messages.jsonl` + `.msg/meta.json` in session dir |
---
## Three-Pipeline Architecture
```
Quick:
IDEA-001 → CHALLENGE-001 → SYNTH-001
Deep (Generator-Critic Loop):
IDEA-001 → CHALLENGE-001 → IDEA-002(fix) → CHALLENGE-002 → SYNTH-001 → EVAL-001
Full (Fan-out + Generator-Critic):
[IDEA-001 + IDEA-002 + IDEA-003](parallel) → CHALLENGE-001(batch) → IDEA-004(fix) → SYNTH-001 → EVAL-001
```
### Generator-Critic Loop
ideator <-> challenger loop, max 2 rounds:
```
IDEA → CHALLENGE → (if critique.severity >= HIGH) → IDEA-fix → CHALLENGE-2 → SYNTH
(if critique.severity < HIGH) → SYNTH
```
### Cadence Control
**Beat model**: Event-driven, each beat = coordinator wake → process → spawn → STOP. Brainstorm beat: generate → challenge → synthesize → evaluate.
```
Beat Cycle (single beat)
═══════════════════════════════════════════════════════════
Event Coordinator Workers
───────────────────────────────────────────────────────────
callback/resume ──→ ┌─ handleCallback ─┐
│ mark completed │
│ check pipeline │
├─ handleSpawnNext ─┤
│ find ready tasks │
│ spawn workers ───┼──→ [Worker A] Phase 1-5
│ (parallel OK) ──┼──→ [Worker B] Phase 1-5
└─ STOP (idle) ─────┘ │
│
callback ←─────────────────────────────────────────┘
(next beat) SendMessage + TaskUpdate(completed)
═══════════════════════════════════════════════════════════
```
**Pipeline beat views**:
```
Quick (3 beats, strictly serial)
──────────────────────────────────────────────────────────
Beat 1 2 3
│ │ │
IDEA → CHALLENGE ──→ SYNTH
▲ ▲
pipeline pipeline
start done
IDEA=ideator CHALLENGE=challenger SYNTH=synthesizer
Deep (5-6 beats, with Generator-Critic loop)
──────────────────────────────────────────────────────────
Beat 1 2 3 4 5 6
│ │ │ │ │ │
IDEA → CHALLENGE → (GC loop?) → IDEA-fix → SYNTH → EVAL
│
severity check
(< HIGH → skip to SYNTH)
Full (4-7 beats, fan-out + Generator-Critic)
──────────────────────────────────────────────────────────
Beat 1 2 3-4 5 6
┌────┴────┐ │ │ │ │
IDEA-1 ∥ IDEA-2 ∥ IDEA-3 → CHALLENGE → (GC loop) → SYNTH → EVAL
▲ ▲
parallel pipeline
window done
```
**Checkpoints**:
| Trigger | Location | Behavior |
|---------|----------|----------|
| Generator-Critic loop | After CHALLENGE-* | If severity >= HIGH → create IDEA-fix task; else proceed to SYNTH |
| GC loop limit | Max 2 rounds | Exceeds limit → force convergence to SYNTH |
| Pipeline stall | No ready + no running | Check missing tasks, report to user |
**Stall Detection** (coordinator `handleCheck` executes):
| Check | Condition | Resolution |
|-------|-----------|------------|
| Worker no response | in_progress task no callback | Report waiting task list, suggest user `resume` |
| Pipeline deadlock | no ready + no running + has pending | Check blockedBy dependency chain, report blocking point |
| GC loop exceeded | ideator/challenger iteration > 2 rounds | Terminate loop, force convergence to synthesizer |
### Task Metadata Registry
| Task ID | Role | Phase | Dependencies | Description |
|---------|------|-------|-------------|-------------|
| IDEA-001 | ideator | generate | (none) | Multi-angle idea generation |
| IDEA-002 | ideator | generate | (none) | Parallel angle (Full pipeline only) |
| IDEA-003 | ideator | generate | (none) | Parallel angle (Full pipeline only) |
| CHALLENGE-001 | challenger | challenge | IDEA-001 (or all IDEA-*) | Devil's advocate critique and feasibility challenge |
| IDEA-004 | ideator | gc-fix | CHALLENGE-001 | Revision based on critique (GC loop, if triggered) |
| CHALLENGE-002 | challenger | gc-fix | IDEA-004 | Re-critique of revised ideas (GC loop round 2) |
| SYNTH-001 | synthesizer | synthesize | last CHALLENGE-* | Cross-idea integration, theme extraction, conflict resolution |
| EVAL-001 | evaluator | evaluate | SYNTH-001 | Scoring, ranking, priority recommendation, final selection |
---
## Coordinator Spawn Template
### v5 Worker Spawn (all roles)
When coordinator spawns workers, use `team-worker` agent with role-spec path:
Coordinator spawns workers using this template:
```
Agent({
@@ -314,39 +65,31 @@ Agent({
run_in_background: true,
prompt: `## Role Assignment
role: <role>
role_spec: .claude/skills/team-brainstorm/role-specs/<role>.md
role_spec: .claude/skills/team-brainstorm/roles/<role>/role.md
session: <session-folder>
session_id: <session-id>
team_name: brainstorm
requirement: <topic-description>
inner_loop: <true|false>
inner_loop: false
Read role_spec file to load Phase 2-4 domain instructions.
Execute built-in Phase 1 (task discovery) -> role-spec Phase 2-4 -> built-in Phase 5 (report).`
Execute built-in Phase 1 (task discovery) -> role Phase 2-4 -> built-in Phase 5 (report).`
})
```
**All roles** (ideator, challenger, synthesizer, evaluator): Set `inner_loop: false`.
**Parallel ideator spawn** (Full pipeline with N angles):
> When Full pipeline has N parallel IDEA tasks assigned to ideator role, spawn N distinct team-worker agents named `ideator-1`, `ideator-2`, etc. Each agent only processes tasks where owner matches its agent name.
| Condition | Action |
|-----------|--------|
| Full pipeline with N idea angles (N > 1) | Spawn N team-worker agents: `ideator-1`, `ideator-2`, ... `ideator-N` with `run_in_background: true` |
| Quick/Deep pipeline (single ideator) | Standard spawn: single `ideator` team-worker agent |
When Full pipeline has N parallel IDEA tasks, spawn N distinct team-worker agents named `ideator-1`, `ideator-2`, etc.
```
Agent({
subagent_type: "team-worker",
description: "Spawn ideator-<N> worker",
team_name: "brainstorm",
name: "ideator-<N>",
team_name: "brainstorm",
run_in_background: true,
prompt: `## Role Assignment
role: ideator
role_spec: .claude/skills/team-brainstorm/role-specs/ideator.md
role_spec: .claude/skills/team-brainstorm/roles/ideator/role.md
session: <session-folder>
session_id: <session-id>
team_name: brainstorm
@@ -355,45 +98,23 @@ agent_name: ideator-<N>
inner_loop: false
Read role_spec file to load Phase 2-4 domain instructions.
Execute built-in Phase 1 (task discovery, owner=ideator-<N>) -> role-spec Phase 2-4 -> built-in Phase 5 (report).`
Execute built-in Phase 1 (task discovery, owner=ideator-<N>) -> role Phase 2-4 -> built-in Phase 5 (report).`
})
```
**Dispatch must match agent names**: When dispatching parallel IDEA tasks, coordinator sets each task's owner to the corresponding instance name (`ideator-1`, `ideator-2`, etc.). In role.md, task discovery uses `--agent-name` for owner matching.
## User Commands
---
| Command | Action |
|---------|--------|
| `check` / `status` | View execution status graph, no advancement |
| `resume` / `continue` | Check worker states, advance next step |
## Completion Action
When the pipeline completes (all tasks done, coordinator Phase 5):
## Session Directory
```
AskUserQuestion({
questions: [{
question: "Brainstorm pipeline complete. What would you like to do?",
header: "Completion",
multiSelect: false,
options: [
{ label: "Archive & Clean (Recommended)", description: "Archive session, clean up tasks and team resources" },
{ label: "Keep Active", description: "Keep session active for follow-up work or inspection" },
{ label: "Export Results", description: "Export deliverables to a specified location, then clean" }
]
}]
})
```
| Choice | Action |
|--------|--------|
| Archive & Clean | Update session status="completed" -> TeamDelete() -> output final summary |
| Keep Active | Update session status="paused" -> output resume instructions: `Skill(skill="team-brainstorm", args="resume")` |
| Export Results | AskUserQuestion for target path -> copy deliverables -> Archive & Clean |
---
## Unified Session Directory
```
.workflow/.team/BRS-<slug>-<YYYY-MM-DD>/
.workflow/.team/BRS-<slug>-<date>/
├── session.json # Session metadata + pipeline + gc_round
├── task-analysis.json # Coordinator analyze output
├── .msg/
│ ├── messages.jsonl # Message bus log
│ └── meta.json # Session state + cross-role state
@@ -404,8 +125,7 @@ AskUserQuestion({
│ └── issues.md
├── ideas/ # Ideator output
│ ├── idea-001.md
│ ├── idea-002.md
│ └── idea-003.md
│ └── idea-002.md
├── critiques/ # Challenger output
│ ├── critique-001.md
│ └── critique-002.md
@@ -415,13 +135,18 @@ AskUserQuestion({
└── evaluation-001.md
```
## Specs Reference
- [specs/pipelines.md](specs/pipelines.md) — Pipeline definitions and task registry
## Error Handling
| Scenario | Resolution |
|----------|------------|
| Unknown --role value | Error with available role list |
| Missing --role arg | Orchestration Mode → auto route to coordinator |
| Role file not found | Error with expected path (roles/<name>.md) |
| Task prefix conflict | Log warning, proceed |
| Generator-Critic loop exceeds 2 rounds | Force convergence → SYNTH |
| Unknown command | Error with available command list |
| Role not found | Error with role registry |
| CLI tool fails | Worker fallback to direct implementation |
| Fast-advance conflict | Coordinator reconciles on next callback |
| Completion action fails | Default to Keep Active |
| Generator-Critic loop exceeds 2 rounds | Force convergence to synthesizer |
| No ideas generated | Coordinator prompts with seed questions |

61
.claude/skills/team-brainstorm/roles/challenger/role.md Normal file
View File

@@ -0,0 +1,61 @@
---
role: challenger
prefix: CHALLENGE
inner_loop: false
message_types: [state_update]
---
# Challenger
Devil's advocate role. Assumption challenging, feasibility questioning, risk identification. Acts as the Critic in the Generator-Critic loop.
## Phase 2: Context Loading
| Input | Source | Required |
|-------|--------|----------|
| Session folder | Task description (Session: line) | Yes |
| Ideas | <session>/ideas/*.md files | Yes |
| Previous critiques | <session>/.msg/meta.json critique_insights | No |
1. Extract session path from task description (match "Session: <path>")
2. Glob idea files from <session>/ideas/
3. Read all idea files for analysis
4. Read .msg/meta.json critique_insights to avoid repeating past challenges
## Phase 3: Critical Analysis
**Challenge Dimensions** (apply to each idea):
| Dimension | Focus |
|-----------|-------|
| Assumption Validity | Does the core assumption hold? Counter-examples? |
| Feasibility | Technical/resource/time feasibility? |
| Risk Assessment | Worst case scenario? Hidden risks? |
| Competitive Analysis | Better alternatives already exist? |
**Severity Classification**:
| Severity | Criteria |
|----------|----------|
| CRITICAL | Fundamental issue, idea may need replacement |
| HIGH | Significant flaw, requires revision |
| MEDIUM | Notable weakness, needs consideration |
| LOW | Minor concern, does not invalidate the idea |
**Generator-Critic Signal**:
| Condition | Signal |
|-----------|--------|
| Any CRITICAL or HIGH severity | REVISION_NEEDED |
| All MEDIUM or lower | CONVERGED |
**Output**: Write to `<session>/critiques/critique-<num>.md`
- Sections: Ideas Reviewed, Per-idea challenges with severity, Summary table with counts, GC Signal
## Phase 4: Severity Summary
1. Count challenges by severity level
2. Determine signal: REVISION_NEEDED if critical+high > 0, else CONVERGED
3. Update shared state:
- Append challenges to .msg/meta.json critique_insights
- Each entry: idea, severity, key_challenge, round

58
.claude/skills/team-brainstorm/roles/coordinator/commands/analyze.md Normal file
View File

@@ -0,0 +1,58 @@
# Analyze Task
Parse user topic -> detect brainstorming capabilities -> assess complexity -> select pipeline.
**CONSTRAINT**: Text-level analysis only. NO source code reading, NO codebase exploration.
## Signal Detection
| Keywords | Capability | Prefix |
|----------|------------|--------|
| generate, create, brainstorm, ideas, explore | ideator | IDEA |
| challenge, critique, argue, devil, risk | challenger | CHALLENGE |
| synthesize, integrate, combine, merge, themes | synthesizer | SYNTH |
| evaluate, score, rank, prioritize, select | evaluator | EVAL |
## Dependency Graph
Natural ordering tiers:
- Tier 0: ideator (divergent generation -- no dependencies)
- Tier 1: challenger (requires ideator output)
- Tier 2: ideator-revision (requires challenger output, GC loop)
- Tier 3: synthesizer (requires last challenger output)
- Tier 4: evaluator (requires synthesizer output, deep/full only)
## Complexity Scoring
| Factor | Points |
|--------|--------|
| Per capability needed | +1 |
| Strategic/systemic topic | +3 |
| Multi-dimensional analysis | +2 |
| Innovation-focused request | +2 |
| Simple/basic topic | -2 |
Results: 0-1 Low (quick), 2-3 Medium (deep), 4+ High (full)
## Pipeline Selection
| Complexity | Pipeline | Tasks |
|------------|----------|-------|
| Low | quick | IDEA → CHALLENGE → SYNTH |
| Medium | deep | IDEA → CHALLENGE → IDEA-fix → CHALLENGE-2 → SYNTH → EVAL |
| High | full | 3x IDEA (parallel) → CHALLENGE → IDEA-fix → SYNTH → EVAL |
## Output
Write <session>/task-analysis.json:
```json
{
"task_description": "<original>",
"pipeline_type": "<quick|deep|full>",
"capabilities": [{ "name": "<cap>", "prefix": "<PREFIX>", "keywords": ["..."] }],
"dependency_graph": { "<TASK-ID>": { "role": "<role>", "blockedBy": ["..."], "priority": "P0|P1|P2" } },
"roles": [{ "name": "<role>", "prefix": "<PREFIX>", "inner_loop": false }],
"complexity": { "score": 0, "level": "Low|Medium|High" },
"angles": ["Technical", "Product", "Innovation", "Risk"]
}
```

164
.claude/skills/team-brainstorm/roles/coordinator/commands/monitor.md
View File

@@ -1,34 +1,30 @@
# Command: Monitor
# Monitor Pipeline
Handle all coordinator monitoring events: worker callbacks, status checks, pipeline advancement, Generator-Critic loop control, and completion.
Event-driven pipeline coordination. Beat model: coordinator wake -> process -> spawn -> STOP.
## Constants
| Key | Value |
|-----|-------|
| SPAWN_MODE | background |
| ONE_STEP_PER_INVOCATION | true |
| WORKER_AGENT | team-worker |
| MAX_GC_ROUNDS | 2 |
- SPAWN_MODE: background
- ONE_STEP_PER_INVOCATION: true
- FAST_ADVANCE_AWARE: true
- WORKER_AGENT: team-worker
- MAX_GC_ROUNDS: 2
## Phase 2: Context Loading
## Handler Router
| Input | Source | Required |
|-------|--------|----------|
| Session state | <session>/session.json | Yes |
| Task list | TaskList() | Yes |
| Trigger event | From Entry Router detection | Yes |
| Meta state | <session>/.msg/meta.json | Yes |
| Source | Handler |
|--------|---------|
| Message contains [ideator], [challenger], [synthesizer], [evaluator] | handleCallback |
| "consensus_blocked" | handleConsensus |
| "capability_gap" | handleAdapt |
| "check" or "status" | handleCheck |
| "resume" or "continue" | handleResume |
| All tasks completed | handleComplete |
| Default | handleSpawnNext |
1. Load session.json for current state, pipeline mode, gc_round
2. Run TaskList() to get current task statuses
3. Identify trigger event type from Entry Router
## handleCallback
## Phase 3: Event Handlers
### handleCallback
Triggered when a worker sends completion message.
Worker completed. Process and advance.
1. Parse message to identify role and task ID:
@@ -39,14 +35,8 @@ Triggered when a worker sends completion message.
| `[synthesizer]` or task ID `SYNTH-*` | synthesizer |
| `[evaluator]` or task ID `EVAL-*` | evaluator |
2. Mark task as completed:
```
TaskUpdate({ taskId: "<task-id>", status: "completed" })
```
2. Mark task as completed: `TaskUpdate({ taskId: "<task-id>", status: "completed" })`
3. Record completion in session state
4. **Generator-Critic check** (when challenger completes):
- If completed task is CHALLENGE-* AND pipeline is deep or full:
- Read critique file for GC signal
@@ -63,16 +53,35 @@ TaskUpdate({ taskId: "<task-id>", status: "completed" })
5. Proceed to handleSpawnNext
### handleSpawnNext
## handleCheck
Find and spawn the next ready tasks.
Read-only status report, then STOP.
1. Scan task list for tasks where:
- Status is "pending"
- All blockedBy tasks have status "completed"
```
[coordinator] Pipeline Status (<pipeline-mode>)
[coordinator] Progress: <done>/<total> (<pct>%)
[coordinator] Active: <workers with elapsed time>
[coordinator] Ready: <pending tasks with resolved deps>
[coordinator] GC Rounds: <gc_round>/<max_gc_rounds>
[coordinator] Commands: 'resume' to advance | 'check' to refresh
```
2. For each ready task, spawn team-worker:
## handleResume
1. Audit task list: Tasks stuck in "in_progress" -> reset to "pending"
2. Proceed to handleSpawnNext
## handleSpawnNext
Find ready tasks, spawn workers, STOP.
1. Collect: completedSubjects, inProgressSubjects, readySubjects
2. No ready + work in progress -> report waiting, STOP
3. No ready + nothing in progress -> handleComplete
4. Has ready -> for each:
a. TaskUpdate -> in_progress
b. team_msg log -> task_unblocked
c. Spawn team-worker (see SKILL.md Spawn Template):
```
Agent({
subagent_type: "team-worker",
@@ -82,7 +91,7 @@ Agent({
run_in_background: true,
prompt: `## Role Assignment
role: <role>
role_spec: .claude/skills/team-brainstorm/role-specs/<role>.md
role_spec: .claude/skills/team-brainstorm/roles/<role>/role.md
session: <session-folder>
session_id: <session-id>
team_name: brainstorm
@@ -90,11 +99,11 @@ requirement: <task-description>
inner_loop: false
Read role_spec file to load Phase 2-4 domain instructions.
Execute built-in Phase 1 -> role-spec Phase 2-4 -> built-in Phase 5.`
Execute built-in Phase 1 (task discovery) -> role Phase 2-4 -> built-in Phase 5 (report).`
})
```
3. **Parallel spawn rules**:
d. Add to active_workers
5. Parallel spawn rules:
| Pipeline | Scenario | Spawn Behavior |
|----------|----------|---------------|
@@ -103,33 +112,34 @@ Execute built-in Phase 1 -> role-spec Phase 2-4 -> built-in Phase 5.`
| Full | IDEA-001/002/003 unblocked | Spawn ALL 3 ideator workers in parallel |
| Full | Other stages | One worker at a time |
4. STOP after spawning -- wait for next callback
### handleCheck
Output current pipeline status. Do NOT advance pipeline.
**Parallel ideator spawn** (Full pipeline):
```
Pipeline Status (<pipeline-mode>):
[DONE] IDEA-001 (ideator) -> ideas/idea-001.md
[DONE] CHALLENGE-001 (challenger) -> critiques/critique-001.md
[RUN] SYNTH-001 (synthesizer) -> synthesizing...
[WAIT] EVAL-001 (evaluator) -> blocked by SYNTH-001
GC Rounds: <gc_round>/<max_gc_rounds>
Session: <session-id>
Agent({
subagent_type: "team-worker",
name: "ideator-<N>",
...
prompt: `...agent_name: ideator-<N>...`
})
```
### handleResume
6. Update session, output summary, STOP
Resume pipeline after user pause or interruption.
## handleComplete
1. Audit task list for inconsistencies:
- Tasks stuck in "in_progress" -> reset to "pending"
- Tasks with completed blockers but still "pending" -> include in spawn list
2. Proceed to handleSpawnNext
Pipeline done. Generate report and completion action.
### handleConsensus
Completion check by mode:
| Mode | Completion Condition |
|------|---------------------|
| quick | All 3 tasks completed |
| deep | All 6 tasks (+ any skipped GC tasks) completed |
| full | All 7 tasks (+ any skipped GC tasks) completed |
1. Verify all tasks completed via TaskList()
2. If any tasks not completed, return to handleSpawnNext
3. If all completed -> transition to coordinator Phase 5
## handleConsensus
Handle consensus_blocked signals.
@@ -139,27 +149,19 @@ Handle consensus_blocked signals.
| MEDIUM | Log finding, attempt to continue |
| LOW | Log finding, continue pipeline |
### handleComplete
## handleAdapt
Triggered when all pipeline tasks are completed.
Capability gap reported mid-pipeline.
**Completion check by mode**:
1. Parse gap description
2. Check if existing role covers it -> redirect
3. Role count < 5 -> generate dynamic role-spec in <session>/role-specs/
4. Create new task, spawn worker
5. Role count >= 5 -> merge or pause
| Mode | Completion Condition |
|------|---------------------|
| quick | All 3 tasks completed |
| deep | All 6 tasks (+ any skipped GC tasks) completed |
| full | All 7 tasks (+ any skipped GC tasks) completed |
## Fast-Advance Reconciliation
1. Verify all tasks completed via TaskList()
2. If any tasks not completed, return to handleSpawnNext
3. If all completed, transition to coordinator Phase 5 (Report + Completion Action)
## Phase 4: State Persistence
After every handler execution:
1. Update session.json with current state (gc_round, last event, active tasks)
2. Update .msg/meta.json gc_round if changed
3. Verify task list consistency
4. STOP and wait for next event
On every coordinator wake:
1. Read team_msg entries with type="fast_advance"
2. Sync active_workers with spawned successors
3. No duplicate spawns

304
.claude/skills/team-brainstorm/roles/coordinator/role.md
View File

@@ -1,15 +1,14 @@
# Coordinator - Brainstorm Team
# Coordinator
**Role**: coordinator
**Type**: Orchestrator
**Team**: brainstorm
Orchestrate team-brainstorm: topic clarify -> dispatch -> spawn -> monitor -> report.
Orchestrates the brainstorming pipeline: topic clarification, complexity assessment, pipeline selection, Generator-Critic loop control, and convergence monitoring. Spawns team-worker agents for all worker roles.
## Identity
- Name: coordinator | Tag: [coordinator]
- Responsibility: Topic clarification -> Create team -> Dispatch tasks -> Monitor progress -> Report results
## Boundaries
### MUST
- Use `team-worker` agent type for all worker spawns (NOT `general-purpose`)
- Follow Command Execution Protocol for dispatch and monitor commands
- Respect pipeline stage dependencies (blockedBy)
@@ -18,105 +17,48 @@ Orchestrates the brainstorming pipeline: topic clarification, complexity assessm
- Execute completion action in Phase 5
### MUST NOT
- Generate ideas, challenge assumptions, synthesize, or evaluate -- workers handle this
- Spawn workers without creating tasks first
- Force-advance pipeline past GC loop decisions
- Modify artifact files (ideas/*.md, critiques/*.md, etc.) -- delegate to workers
- Skip GC severity check when critique arrives
---
## Command Execution Protocol
When coordinator needs to execute a command (dispatch, monitor):
1. **Read the command file**: `roles/coordinator/commands/<command-name>.md`
2. **Follow the workflow** defined in the command file (Phase 2-4 structure)
3. **Commands are inline execution guides** -- NOT separate agents or subprocesses
4. **Execute synchronously** -- complete the command workflow before proceeding
Example:
```
Phase 3 needs task dispatch
-> Read roles/coordinator/commands/dispatch.md
-> Execute Phase 2 (Context Loading)
-> Execute Phase 3 (Task Chain Creation)
-> Execute Phase 4 (Validation)
-> Continue to Phase 4
```
---
When coordinator needs to execute a specific phase:
1. Read `commands/<command>.md`
2. Follow the workflow defined in the command
3. Commands are inline execution guides, NOT separate agents
4. Execute synchronously, complete before proceeding
## Entry Router
When coordinator is invoked, detect invocation type:
| Detection | Condition | Handler |
|-----------|-----------|---------|
| Worker callback | Message contains role tag [ideator], [challenger], [synthesizer], [evaluator] | -> handleCallback |
| Consensus blocked | Message contains "consensus_blocked" | -> handleConsensus |
| Status check | Arguments contain "check" or "status" | -> handleCheck |
| Manual resume | Arguments contain "resume" or "continue" | -> handleResume |
| Pipeline complete | All tasks have status "completed" | -> handleComplete |
| Interrupted session | Active/paused session exists | -> Phase 0 (Resume Check) |
| New session | None of above | -> Phase 1 (Topic Clarification) |
| Worker callback | Message contains [ideator], [challenger], [synthesizer], [evaluator] | -> handleCallback (monitor.md) |
| Consensus blocked | Message contains "consensus_blocked" | -> handleConsensus (monitor.md) |
| Status check | Args contain "check" or "status" | -> handleCheck (monitor.md) |
| Manual resume | Args contain "resume" or "continue" | -> handleResume (monitor.md) |
| Capability gap | Message contains "capability_gap" | -> handleAdapt (monitor.md) |
| Pipeline complete | All tasks completed | -> handleComplete (monitor.md) |
| Interrupted session | Active session in .workflow/.team/BRS-* | -> Phase 0 |
| New session | None of above | -> Phase 1 |
For callback/check/resume/complete: load `commands/monitor.md` and execute matched handler, then STOP.
### Router Implementation
1. **Load session context** (if exists):
- Scan `.workflow/.team/BRS-*/.msg/meta.json` for active/paused sessions
- If found, extract session folder path, status, and pipeline mode
2. **Parse $ARGUMENTS** for detection keywords:
- Check for role name tags in message content
- Check for "check", "status", "resume", "continue" keywords
- Check for "consensus_blocked" signal
3. **Route to handler**:
- For monitor handlers: Read `commands/monitor.md`, execute matched handler, STOP
- For Phase 0: Execute Session Resume Check below
- For Phase 1: Execute Topic Clarification below
---
For callback/check/resume/consensus/adapt/complete: load commands/monitor.md, execute handler, STOP.
## Phase 0: Session Resume Check
Triggered when an active/paused session is detected on coordinator entry.
1. Load session.json from detected session folder
2. Audit task list:
```
TaskList()
```
3. Reconcile session state vs task status:
| Task Status | Session Expects | Action |
|-------------|----------------|--------|
| in_progress | Should be running | Reset to pending (worker was interrupted) |
| completed | Already tracked | Skip |
| pending + unblocked | Ready to run | Include in spawn list |
4. Rebuild team if not active:
```
TeamCreate({ team_name: "brainstorm" })
```
5. Spawn workers for ready tasks -> Phase 4 coordination loop
---
1. Scan `.workflow/.team/BRS-*/session.json` for active/paused sessions
2. No sessions -> Phase 1
3. Single session -> reconcile (audit TaskList, reset in_progress->pending, rebuild team, kick first ready task)
4. Multiple -> AskUserQuestion for selection
## Phase 1: Topic Clarification + Complexity Assessment
1. Parse user task description from $ARGUMENTS
2. Parse optional `--team-name` flag (default: "brainstorm")
TEXT-LEVEL ONLY. No source code reading.
3. Assess topic complexity:
1. Parse topic from $ARGUMENTS
2. Assess topic complexity:
| Signal | Weight | Keywords |
|--------|--------|----------|
@@ -131,155 +73,39 @@ TeamCreate({ team_name: "brainstorm" })
| 2-3 | Medium | deep |
| 0-1 | Low | quick |
4. Ask for missing parameters:
3. AskUserQuestion for pipeline mode and divergence angles
4. Store requirements: mode, scope, angles, constraints
```
AskUserQuestion({
questions: [{
question: "Select brainstorming pipeline mode",
header: "Mode",
multiSelect: false,
options: [
{ label: "quick", description: "3-step: generate -> challenge -> synthesize" },
{ label: "deep", description: "6-step with Generator-Critic loop" },
{ label: "full", description: "7-step parallel ideation + GC + evaluation" }
]
}, {
question: "Select divergence angles",
header: "Angles",
multiSelect: true,
options: [
{ label: "Technical" },
{ label: "Product" },
{ label: "Innovation" },
{ label: "Risk" }
]
}]
})
```
5. Store requirements: mode, scope, angles, constraints
---
## Phase 2: Session & Team Setup
## Phase 2: Create Team + Initialize Session
1. Generate session ID: `BRS-<topic-slug>-<date>`
2. Create session folder structure:
2. Create session folder structure: ideas/, critiques/, synthesis/, evaluation/, wisdom/, .msg/
3. TeamCreate with team name `brainstorm`
4. Write session.json with pipeline, angles, gc_round=0, max_gc_rounds=2
5. Initialize meta.json via team_msg state_update:
```
Bash("mkdir -p .workflow/.team/<session-id>/ideas .workflow/.team/<session-id>/critiques .workflow/.team/<session-id>/synthesis .workflow/.team/<session-id>/evaluation .workflow/.team/<session-id>/wisdom .workflow/.team/<session-id>/.msg")
```
3. Write session.json:
```json
{
"status": "active",
"team_name": "brainstorm",
"topic": "<topic>",
"pipeline": "<quick|deep|full>",
"angles": ["<angle1>", "<angle2>"],
"gc_round": 0,
"max_gc_rounds": 2,
"timestamp": "<ISO-8601>"
}
```
4. Initialize meta.json with pipeline metadata:
```typescript
// Use team_msg to write pipeline metadata to .msg/meta.json
mcp__ccw-tools__team_msg({
operation: "log",
session_id: "<session-id>",
from: "coordinator",
type: "state_update",
summary: "Session initialized",
data: {
pipeline_mode: "<mode>",
pipeline_stages: ["ideator", "challenger", "synthesizer", "evaluator"],
roles: ["coordinator", "ideator", "challenger", "synthesizer", "evaluator"],
team_name: "brainstorm",
topic: "<topic>",
angles: ["<angle1>", "<angle2>"],
gc_round": 0,
status: "active"
}
operation: "log", session_id: "<id>", from: "coordinator",
type: "state_update", summary: "Session initialized",
data: { pipeline_mode: "<mode>", pipeline_stages: ["ideator","challenger","synthesizer","evaluator"], team_name: "brainstorm", topic: "<topic>", angles: [...], gc_round: 0 }
})
```
6. Write session.json
5. Create team:
## Phase 3: Create Task Chain
```
TeamCreate({ team_name: "brainstorm" })
```
Delegate to commands/dispatch.md:
1. Read pipeline mode and angles from session.json
2. Create tasks for selected pipeline with correct blockedBy
3. Update session.json with task count
---
## Phase 4: Spawn-and-Stop
## Phase 3: Task Chain Creation
Execute `commands/dispatch.md` inline (Command Execution Protocol):
1. Read `roles/coordinator/commands/dispatch.md`
2. Follow dispatch Phase 2 (context loading) -> Phase 3 (task chain creation) -> Phase 4 (validation)
3. Result: all pipeline tasks created with correct blockedBy dependencies
---
## Phase 4: Spawn First Batch
Find first unblocked task(s) and spawn worker(s):
```
Agent({
subagent_type: "team-worker",
description: "Spawn ideator worker",
team_name: "brainstorm",
name: "ideator",
run_in_background: true,
prompt: `## Role Assignment
role: ideator
role_spec: .claude/skills/team-brainstorm/role-specs/ideator.md
session: <session-folder>
session_id: <session-id>
team_name: brainstorm
requirement: <topic-description>
inner_loop: false
Read role_spec file to load Phase 2-4 domain instructions.
Execute built-in Phase 1 -> role-spec Phase 2-4 -> built-in Phase 5.`
})
```
For **Full pipeline** with parallel ideators, spawn N team-worker agents:
```
// For each parallel IDEA task (IDEA-001, IDEA-002, IDEA-003)
Agent({
subagent_type: "team-worker",
description: "Spawn ideator worker for IDEA-<N>",
team_name: "brainstorm",
name: "ideator-<N>",
run_in_background: true,
prompt: `## Role Assignment
role: ideator
role_spec: .claude/skills/team-brainstorm/role-specs/ideator.md
session: <session-folder>
session_id: <session-id>
team_name: brainstorm
requirement: <topic-description>
inner_loop: false
Read role_spec file to load Phase 2-4 domain instructions.
Execute built-in Phase 1 -> role-spec Phase 2-4 -> built-in Phase 5.`
})
```
**STOP** after spawning. Wait for worker callback.
All subsequent coordination handled by `commands/monitor.md` handlers.
---
Delegate to commands/monitor.md#handleSpawnNext:
1. Find ready tasks (pending + blockedBy resolved)
2. Spawn team-worker agents (see SKILL.md Spawn Template)
3. Output status summary
4. STOP
## Phase 5: Report + Completion Action
@@ -295,27 +121,17 @@ All subsequent coordination handled by `commands/monitor.md` handlers.
3. Output pipeline summary: topic, pipeline mode, GC rounds, total ideas, key themes
4. **Completion Action** (interactive):
4. Execute completion action per session.completion_action:
- interactive -> AskUserQuestion (Archive/Keep/Export)
- auto_archive -> Archive & Clean (status=completed, TeamDelete)
- auto_keep -> Keep Active (status=paused)
```
AskUserQuestion({
questions: [{
question: "Brainstorm pipeline complete. What would you like to do?",
header: "Completion",
multiSelect: false,
options: [
{ label: "Archive & Clean (Recommended)", description: "Archive session, clean up tasks and team resources" },
{ label: "Keep Active", description: "Keep session active for follow-up brainstorming" },
{ label: "Export Results", description: "Export deliverables to a specified location, then clean" }
]
}]
})
```
## Error Handling
5. Handle user choice:
| Choice | Steps |
|--------|-------|
| Archive & Clean | TaskList -> verify all completed -> update session status="completed" -> TeamDelete() -> output final summary with artifact paths |
| Keep Active | Update session status="paused" -> output: "Session paused. Resume with: Skill(skill='team-brainstorm', args='resume')" |
| Export Results | AskUserQuestion for target directory -> copy all artifacts -> Archive & Clean flow |
| Error | Resolution |
|-------|------------|
| Task too vague | AskUserQuestion for clarification |
| Session corruption | Attempt recovery, fallback to manual |
| Worker crash | Reset task to pending, respawn |
| GC loop exceeded | Force convergence to synthesizer |
| No ideas generated | Coordinator prompts with seed questions |

56
.claude/skills/team-brainstorm/roles/evaluator/role.md Normal file
View File

@@ -0,0 +1,56 @@
---
role: evaluator
prefix: EVAL
inner_loop: false
message_types: [state_update]
---
# Evaluator
Scoring, ranking, and final selection. Multi-dimension evaluation of synthesized proposals with weighted scoring and priority recommendations.
## Phase 2: Context Loading
| Input | Source | Required |
|-------|--------|----------|
| Session folder | Task description (Session: line) | Yes |
| Synthesis results | <session>/synthesis/*.md files | Yes |
| All ideas | <session>/ideas/*.md files | No (for context) |
| All critiques | <session>/critiques/*.md files | No (for context) |
1. Extract session path from task description (match "Session: <path>")
2. Glob synthesis files from <session>/synthesis/
3. Read all synthesis files for evaluation
4. Optionally read ideas and critiques for full context
## Phase 3: Evaluation and Scoring
**Scoring Dimensions**:
| Dimension | Weight | Focus |
|-----------|--------|-------|
| Feasibility | 30% | Technical feasibility, resource needs, timeline |
| Innovation | 25% | Novelty, differentiation, breakthrough potential |
| Impact | 25% | Scope of impact, value creation, problem resolution |
| Cost Efficiency | 20% | Implementation cost, risk cost, opportunity cost |
**Weighted Score**: `(Feasibility * 0.30) + (Innovation * 0.25) + (Impact * 0.25) + (Cost * 0.20)`
**Per-Proposal Evaluation**:
- Score each dimension (1-10) with rationale
- Overall recommendation: Strong Recommend / Recommend / Consider / Pass
**Output**: Write to `<session>/evaluation/evaluation-<num>.md`
- Sections: Input summary, Scoring Matrix (ranked table), Detailed Evaluation per proposal, Final Recommendation, Action Items, Risk Summary
## Phase 4: Consistency Check
| Check | Pass Criteria | Action on Failure |
|-------|---------------|-------------------|
| Score spread | max - min >= 0.5 (with >1 proposal) | Re-evaluate differentiators |
| No perfect scores | Not all 10s | Adjust to reflect critique findings |
| Ranking deterministic | Consistent ranking | Verify calculation |
After passing checks, update shared state:
- Set .msg/meta.json evaluation_scores
- Each entry: title, weighted_score, rank, recommendation

69
.claude/skills/team-brainstorm/roles/ideator/role.md Normal file
View File

@@ -0,0 +1,69 @@
---
role: ideator
prefix: IDEA
inner_loop: false
message_types: [state_update]
---
# Ideator
Multi-angle idea generator. Divergent thinking, concept exploration, and idea revision as the Generator in the Generator-Critic loop.
## Phase 2: Context Loading
| Input | Source | Required |
|-------|--------|----------|
| Session folder | Task description (Session: line) | Yes |
| Topic | <session>/.msg/meta.json | Yes |
| Angles | <session>/.msg/meta.json | Yes |
| GC Round | <session>/.msg/meta.json | Yes |
| Previous critique | <session>/critiques/*.md | For revision tasks only |
| Previous ideas | <session>/.msg/meta.json generated_ideas | No |
1. Extract session path from task description (match "Session: <path>")
2. Read .msg/meta.json for topic, angles, gc_round
3. Detect task mode:
| Condition | Mode |
|-----------|------|
| Task subject contains "revision" or "fix" | GC Revision |
| Otherwise | Initial Generation |
4. If GC Revision mode:
- Glob critique files from <session>/critiques/
- Read latest critique for revision context
5. Read previous ideas from .msg/meta.json generated_ideas state
## Phase 3: Idea Generation
### Mode Router
| Mode | Focus |
|------|-------|
| Initial Generation | Multi-angle divergent thinking, no prior critique |
| GC Revision | Address HIGH/CRITICAL challenges from critique |
**Initial Generation**:
- For each angle, generate 3+ ideas
- Each idea: title, description (2-3 sentences), key assumption, potential impact, implementation hint
**GC Revision**:
- Focus on HIGH/CRITICAL severity challenges from critique
- Retain unchallenged ideas intact
- Revise ideas with revision rationale
- Replace unsalvageable ideas with new alternatives
**Output**: Write to `<session>/ideas/idea-<num>.md`
- Sections: Topic, Angles, Mode, [Revision Context if applicable], Ideas list, Summary
## Phase 4: Self-Review
| Check | Pass Criteria | Action on Failure |
|-------|---------------|-------------------|
| Minimum count | >= 6 (initial) or >= 3 (revision) | Generate additional ideas |
| No duplicates | All titles unique | Replace duplicates |
| Angle coverage | At least 1 idea per angle | Generate missing angle ideas |
After passing checks, update shared state:
- Append new ideas to .msg/meta.json generated_ideas
- Each entry: id, title, round, revised flag

57
.claude/skills/team-brainstorm/roles/synthesizer/role.md Normal file
View File

@@ -0,0 +1,57 @@
---
role: synthesizer
prefix: SYNTH
inner_loop: false
message_types: [state_update]
---
# Synthesizer
Cross-idea integrator. Extracts themes from multiple ideas and challenge feedback, resolves conflicts, generates consolidated proposals.
## Phase 2: Context Loading
| Input | Source | Required |
|-------|--------|----------|
| Session folder | Task description (Session: line) | Yes |
| All ideas | <session>/ideas/*.md files | Yes |
| All critiques | <session>/critiques/*.md files | Yes |
| GC rounds completed | <session>/.msg/meta.json gc_round | Yes |
1. Extract session path from task description (match "Session: <path>")
2. Glob all idea files from <session>/ideas/
3. Glob all critique files from <session>/critiques/
4. Read all idea and critique files for synthesis
5. Read .msg/meta.json for context (topic, gc_round, generated_ideas, critique_insights)
## Phase 3: Synthesis Execution
| Step | Action |
|------|--------|
| 1. Theme Extraction | Identify common themes across ideas, rate strength (1-10), list supporting ideas |
| 2. Conflict Resolution | Identify contradictory ideas, determine resolution approach, document rationale |
| 3. Complementary Grouping | Group complementary ideas together |
| 4. Gap Identification | Discover uncovered perspectives |
| 5. Integrated Proposal | Generate 1-3 consolidated proposals |
**Integrated Proposal Structure**:
- Core concept description
- Source ideas combined
- Addressed challenges from critiques
- Feasibility score (1-10), Innovation score (1-10)
- Key benefits list, Remaining risks list
**Output**: Write to `<session>/synthesis/synthesis-<num>.md`
- Sections: Input summary, Extracted Themes, Conflict Resolution, Integrated Proposals, Coverage Analysis
## Phase 4: Quality Check
| Check | Pass Criteria | Action on Failure |
|-------|---------------|-------------------|
| Proposal count | >= 1 proposal | Generate at least one proposal |
| Theme count | >= 2 themes | Look for more patterns |
| Conflict resolution | All conflicts documented | Address unresolved conflicts |
After passing checks, update shared state:
- Set .msg/meta.json synthesis_themes
- Each entry: name, strength, supporting_ideas

72
.claude/skills/team-brainstorm/specs/pipelines.md Normal file
View File

@@ -0,0 +1,72 @@
# Pipeline Definitions — team-brainstorm
## Available Pipelines
### Quick Pipeline (3 beats, strictly serial)
```
IDEA-001 → CHALLENGE-001 → SYNTH-001
[ideator] [challenger] [synthesizer]
```
### Deep Pipeline (6 beats, Generator-Critic loop)
```
IDEA-001 → CHALLENGE-001 → IDEA-002(fix) → CHALLENGE-002 → SYNTH-001 → EVAL-001
```
GC loop check: if critique.severity >= HIGH → create IDEA-fix → CHALLENGE-2 → SYNTH; else skip to SYNTH
### Full Pipeline (7 tasks, fan-out parallel ideation + GC)
```
[IDEA-001 + IDEA-002 + IDEA-003](parallel) → CHALLENGE-001(batch) → IDEA-004(fix) → SYNTH-001 → EVAL-001
```
## Task Metadata Registry
| Task ID | Role | Phase | Dependencies | Description |
|---------|------|-------|-------------|-------------|
| IDEA-001 | ideator | generate | (none) | Multi-angle idea generation |
| IDEA-002 | ideator | generate | (none) | Parallel angle (Full pipeline only) |
| IDEA-003 | ideator | generate | (none) | Parallel angle (Full pipeline only) |
| CHALLENGE-001 | challenger | challenge | IDEA-001 (or all IDEA-*) | Devil's advocate critique and feasibility challenge |
| IDEA-004 | ideator | gc-fix | CHALLENGE-001 | Revision based on critique (GC loop, if triggered) |
| CHALLENGE-002 | challenger | gc-fix | IDEA-004 | Re-critique of revised ideas (GC loop round 2) |
| SYNTH-001 | synthesizer | synthesize | last CHALLENGE-* | Cross-idea integration, theme extraction, conflict resolution |
| EVAL-001 | evaluator | evaluate | SYNTH-001 | Scoring, ranking, priority recommendation, final selection |
## Checkpoints
| Trigger | Location | Behavior |
|---------|----------|----------|
| Generator-Critic loop | After CHALLENGE-* | If severity >= HIGH → create IDEA-fix task; else proceed to SYNTH |
| GC loop limit | Max 2 rounds | Exceeds limit → force convergence to SYNTH |
| Pipeline stall | No ready + no running | Check missing tasks, report to user |
## Completion Conditions
| Mode | Completion Condition |
|------|---------------------|
| quick | All 3 tasks completed |
| deep | All 6 tasks (+ any skipped GC tasks) completed |
| full | All 7 tasks (+ any skipped GC tasks) completed |
## Shared State (meta.json)
| Role | State Key |
|------|-----------|
| ideator | `generated_ideas` |
| challenger | `critique_insights` |
| synthesizer | `synthesis_themes` |
| evaluator | `evaluation_scores` |
## Message Types
| Role | Types |
|------|-------|
| coordinator | `pipeline_selected`, `gc_loop_trigger`, `task_unblocked`, `error`, `shutdown` |
| ideator | `ideas_ready`, `ideas_revised`, `error` |
| challenger | `critique_ready`, `error` |
| synthesizer | `synthesis_ready`, `error` |
| evaluator | `evaluation_ready`, `error` |

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

@@ -150,40 +150,6 @@ AskUserQuestion({
---
## Cadence Control
**Beat model**: Event-driven, each beat = coordinator wake -> process -> spawn -> STOP.
```
Beat Cycle (single beat)
======================================================================
Event Coordinator Workers
----------------------------------------------------------------------
callback/resume --> +- handleCallback -+
| mark completed |
| check pipeline |
+- handleSpawnNext -+
| find ready tasks |
| spawn workers ---+--> [team-worker A] Phase 1-5
| (parallel OK) --+--> [team-worker B] Phase 1-5
+- STOP (idle) -----+ |
|
callback <-----------------------------------------+
(next beat) SendMessage + TaskUpdate(completed)
======================================================================
Fast-Advance (skips coordinator for simple linear successors)
======================================================================
[Worker A] Phase 5 complete
+- 1 ready task? simple successor? --> spawn team-worker B directly
+- complex case? --> SendMessage to coordinator
======================================================================
```
**Pipelines are dynamic**: Unlike static pipeline definitions, team-coordinate pipelines are generated per-task from the dependency graph.
---
## Session Directory
```

83
.claude/skills/team-coordinate/specs/pipelines.md Normal file
View File

@@ -0,0 +1,83 @@
# Pipeline Definitions — Team Coordinate
## Dynamic Pipeline Model
team-coordinate does NOT have a static pipeline. All pipelines are generated at runtime from task-analysis.json based on the user's task description.
## Pipeline Generation Process
```
Phase 1: analyze-task.md
-> Signal detection -> capability mapping -> dependency graph
-> Output: task-analysis.json
Phase 2: dispatch.md
-> Read task-analysis.json dependency graph
-> Create TaskCreate entries per dependency node
-> Set blockedBy chains from graph edges
-> Output: TaskList with correct DAG
Phase 3-N: monitor.md
-> handleSpawnNext: spawn ready tasks as team-worker agents
-> handleCallback: mark completed, advance pipeline
-> Repeat until all tasks done
```
## Dynamic Task Naming
| Capability | Prefix | Example |
|------------|--------|---------|
| researcher | RESEARCH | RESEARCH-001 |
| developer | IMPL | IMPL-001 |
| analyst | ANALYSIS | ANALYSIS-001 |
| designer | DESIGN | DESIGN-001 |
| tester | TEST | TEST-001 |
| writer | DRAFT | DRAFT-001 |
| planner | PLAN | PLAN-001 |
| (default) | TASK | TASK-001 |
## Dependency Graph Structure
task-analysis.json encodes the pipeline:
```json
{
"dependency_graph": {
"RESEARCH-001": { "role": "researcher", "blockedBy": [], "priority": "P0" },
"IMPL-001": { "role": "developer", "blockedBy": ["RESEARCH-001"], "priority": "P1" },
"TEST-001": { "role": "tester", "blockedBy": ["IMPL-001"], "priority": "P2" }
}
}
```
## Role-Worker Map
Dynamic — loaded from session role-specs at runtime:
```
<session>/role-specs/<role-name>.md -> team-worker agent
```
Role-spec files contain YAML frontmatter:
```yaml
---
role: <role-name>
prefix: <PREFIX>
inner_loop: <true|false>
message_types:
success: <type>
error: error
---
```
## Checkpoint
| Trigger | Behavior |
|---------|----------|
| capability_gap reported | handleAdapt: generate new role-spec, spawn new worker |
| consensus_blocked HIGH | Create REVISION task or pause for user |
| All tasks complete | handleComplete: interactive completion action |
## Specs Reference
- [role-spec-template.md](role-spec-template.md) — Template for generating dynamic role-specs

153
.claude/skills/team-designer/SKILL.md Normal file
View File

@@ -0,0 +1,153 @@
---
name: team-designer
description: Meta-skill for generating team skills following the v4 architecture pattern. Produces complete skill packages with SKILL.md router, coordinator, worker roles, specs, and templates. Triggers on "team-designer", "design team".
allowed-tools: Agent(*), AskUserQuestion(*), Read(*), Write(*), Edit(*), Bash(*), Glob(*), Grep(*)
---
# Team Skill Designer
Generate complete team skills following the team-lifecycle-v4 architecture: SKILL.md as universal router, coordinator with beat model, worker roles with optional commands/, shared specs, and templates.
## Architecture Overview
```
┌─────────────────────────────────────────────────────────────────┐
│ Team Skill Designer (SKILL.md) │
│ → Orchestrator: gather requirements, generate files, validate │
└───────────────────────────┬──────────────────────────────────────┘
│
┌───────────┬───────────┼───────────┬───────────┐
↓ ↓ ↓ ↓
┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐
│ Phase 1 │ │ Phase 2 │ │ Phase 3 │ │ Phase 4 │
│ Require │ │ Scaffold│ │ Content │ │ Valid │
│ Analysis│ │ Gen │ │ Gen │ │ & Report│
└─────────┘ └─────────┘ └─────────┘ └─────────┘
↓ ↓ ↓ ↓
teamConfig SKILL.md roles/ Validated
+ dirs specs/ skill pkg
templates/
```
## Key Design Principles
1. **v4 Architecture Compliance**: Generated skills follow team-lifecycle-v4 pattern — SKILL.md = pure router, beat model = coordinator-only, unified structure (roles/ + specs/ + templates/)
2. **Golden Sample Reference**: Uses `team-lifecycle-v4` as reference implementation at `.claude/skills/team-lifecycle-v4/`
3. **Intelligent Commands Distribution**: Auto-determines which roles need `commands/` (2+ commands) vs inline logic (1 command)
4. **team-worker Compatibility**: Role.md files include correct YAML frontmatter for team-worker agent parsing
## Execution Flow
```
Input Parsing:
└─ Parse user requirements (skill name, roles, pipelines, domain)
Phase 1: Requirements Analysis
└─ Ref: phases/01-requirements-analysis.md
├─ Tasks: Detect input → Gather roles → Define pipelines → Build teamConfig
└─ Output: teamConfig
Phase 2: Scaffold Generation
└─ Ref: phases/02-scaffold-generation.md
├─ Tasks: Create dirs → Generate SKILL.md router → Verify
└─ Output: SKILL.md + directory structure
Phase 3: Content Generation
└─ Ref: phases/03-content-generation.md
├─ Tasks: Coordinator → Workers → Specs → Templates
└─ Output: roles/**/*.md, specs/*.md, templates/*.md
Phase 4: Validation
└─ Ref: phases/04-validation.md
└─ Output: Validation report (PASS/REVIEW/FAIL)
Return:
└─ Summary with skill location and usage instructions
```
**Phase Reference Documents** (read on-demand when phase executes):
| Phase | Document | Purpose |
|-------|----------|---------|
| 1 | [phases/01-requirements-analysis.md](phases/01-requirements-analysis.md) | Gather team skill requirements, build teamConfig |
| 2 | [phases/02-scaffold-generation.md](phases/02-scaffold-generation.md) | Generate SKILL.md router and directory structure |
| 3 | [phases/03-content-generation.md](phases/03-content-generation.md) | Generate coordinator, workers, specs, templates |
| 4 | [phases/04-validation.md](phases/04-validation.md) | Validate structure, references, and consistency |
## Golden Sample
Generated skills follow the architecture of `.claude/skills/team-lifecycle-v4/`:
```
.claude/skills/<skill-name>/
├── SKILL.md # Universal router (all roles read)
├── roles/
│ ├── coordinator/
│ │ ├── role.md # Orchestrator + beat model + entry router
│ │ └── commands/
│ │ ├── analyze.md # Task analysis
│ │ ├── dispatch.md # Task chain creation
│ │ └── monitor.md # Beat control + callbacks
│ ├── <inline-worker>/
│ │ └── role.md # Phase 2-4 embedded (simple role)
│ └── <command-worker>/
│ ├── role.md # Phase 2-4 dispatcher
│ └── commands/
│ ├── <cmd-1>.md
│ └── <cmd-2>.md
├── specs/
│ ├── pipelines.md # Pipeline definitions + task registry
│ └── <domain-specs>.md # Domain-specific specifications
└── templates/ # Optional document templates
```
## Data Flow
```
User Input (skill name, roles, pipelines)
↓
Phase 1: Requirements Analysis
↓ Output: teamConfig
↓
Phase 2: Scaffold Generation
↓ Input: teamConfig
↓ Output: SKILL.md + skillDir
↓
Phase 3: Content Generation
↓ Input: teamConfig + skillDir
↓ Output: roles/, specs/, templates/
↓
Phase 4: Validation
↓ Input: teamConfig + all files
↓ Output: validation report
↓
Return summary to user
```
## Core Rules
1. **Start Immediately**: First action is Phase 1 execution
2. **Parse Every Output**: Extract teamConfig from Phase 1 for subsequent phases
3. **Auto-Continue**: After each phase, automatically execute next phase
4. **Progressive Phase Loading**: Read phase docs ONLY when that phase is about to execute
5. **Golden Sample Fidelity**: Generated files must match team-lifecycle-v4 patterns
6. **DO NOT STOP**: Continuous workflow until all 4 phases complete
## Input Processing
Convert user input to structured format:
```
SKILL_NAME: [kebab-case name, e.g., team-code-review]
DOMAIN: [what this team does, e.g., "multi-stage code review with security analysis"]
ROLES: [worker roles beyond coordinator, e.g., "analyst, reviewer, security-expert"]
PIPELINES: [pipeline types and flows, e.g., "review-only: SCAN-001 → REVIEW-001 → REPORT-001"]
SESSION_PREFIX: [3-4 char, e.g., TCR]
```
## Error Handling
- **Invalid role name**: Must be lowercase alphanumeric with hyphens, max 20 chars
- **Circular dependencies**: Detect and report in pipeline validation
- **Missing golden sample**: Fall back to embedded templates in phase files
- **Directory conflict**: Warn if skill directory already exists, ask user to confirm overwrite

265
.claude/skills/team-designer/phases/01-requirements-analysis.md Normal file
View File

@@ -0,0 +1,265 @@
# Phase 1: Requirements Analysis
Gather team skill requirements from user input and build the `teamConfig` data structure that drives all subsequent phases.
## Objective
- Parse user input (text description, reference skill, or interactive)
- Determine roles, pipelines, specs, templates
- Auto-decide commands distribution (inline vs commands/ folder)
- Build comprehensive `teamConfig` object
- Confirm with user before proceeding
## Step 1.1: Detect Input Source
```javascript
function detectInputSource(userInput) {
// Source A: Reference to existing skill
if (userInput.includes('based on') || userInput.includes('参考') || userInput.includes('like')) {
return { type: 'reference', refSkill: extractSkillName(userInput) };
}
// Source B: Structured input with roles/pipelines
if (userInput.includes('ROLES:') || userInput.includes('PIPELINES:')) {
return { type: 'structured', data: parseStructuredInput(userInput) };
}
// Source C: Natural language description
return { type: 'natural', description: userInput };
}
```
**For reference source**: Read the referenced skill's SKILL.md and role files to extract structure.
**For natural language**: Use AskUserQuestion to gather missing details interactively.
## Step 1.2: Gather Core Identity
```javascript
const coreIdentity = AskUserQuestion({
questions: [
{
question: "团队技能名称？(kebab-case, e.g., team-code-review)",
header: "Skill Name",
multiSelect: false,
options: [
{ label: suggestedName, description: "Auto-suggested from description" },
{ label: "Custom", description: "Enter custom name" }
]
},
{
question: "会话前缀？(3-4字符用于任务ID, e.g., TCR)",
header: "Prefix",
multiSelect: false,
options: [
{ label: suggestedPrefix, description: "Auto-suggested" },
{ label: "Custom", description: "Enter custom prefix" }
]
}
]
});
```
If user provided clear name/prefix in input, skip this step.
## Step 1.3: Determine Roles
### Role Discovery from Domain
Analyze domain description to identify required roles:
```javascript
function discoverRoles(domain) {
const rolePatterns = {
'analyst': ['分析', 'analyze', 'research', 'explore', 'investigate', 'scan'],
'planner': ['规划', 'plan', 'design', 'architect', 'decompose'],
'writer': ['文档', 'write', 'document', 'draft', 'spec', 'report'],
'executor': ['实现', 'implement', 'execute', 'build', 'code', 'develop'],
'tester': ['测试', 'test', 'verify', 'validate', 'qa'],
'reviewer': ['审查', 'review', 'quality', 'check', 'audit', 'inspect'],
'security-expert': ['安全', 'security', 'vulnerability', 'penetration'],
'performance-optimizer': ['性能', 'performance', 'optimize', 'benchmark'],
'data-engineer': ['数据', 'data', 'pipeline', 'etl', 'migration'],
'devops-engineer': ['部署', 'devops', 'deploy', 'ci/cd', 'infrastructure'],
};
const matched = [];
for (const [role, keywords] of Object.entries(rolePatterns)) {
if (keywords.some(kw => domain.toLowerCase().includes(kw))) {
matched.push(role);
}
}
return matched;
}
```
### Role Configuration
For each discovered role, determine:
```javascript
function configureRole(roleName) {
return {
name: roleName,
prefix: determinePrefix(roleName),
inner_loop: determineInnerLoop(roleName),
hasCommands: false, // determined in Step 1.5
commands: [],
message_types: determineMessageTypes(roleName),
path: `roles/${roleName}/role.md`
};
}
// Standard prefix mapping
const prefixMap = {
'analyst': 'RESEARCH',
'writer': 'DRAFT',
'planner': 'PLAN',
'executor': 'IMPL',
'tester': 'TEST',
'reviewer': 'REVIEW',
// Dynamic roles use uppercase role name
};
// Inner loop: roles that process multiple tasks sequentially
const innerLoopRoles = ['executor', 'writer', 'planner'];
// Message types the role handles
const messageMap = {
'analyst': ['state_update'],
'writer': ['state_update', 'discuss_response'],
'planner': ['state_update'],
'executor': ['state_update', 'revision_request'],
'tester': ['state_update'],
'reviewer': ['state_update', 'discuss_request'],
};
```
## Step 1.4: Define Pipelines
### Pipeline Types from Role Combination
```javascript
function definePipelines(roles, domain) {
const has = name => roles.some(r => r.name === name);
// Full lifecycle: analyst → writer → planner → executor → tester → reviewer
if (has('analyst') && has('writer') && has('planner') && has('executor'))
return [{ name: 'full-lifecycle', tasks: buildFullLifecycleTasks(roles) }];
// Spec-only: analyst → writer → reviewer
if (has('analyst') && has('writer') && !has('executor'))
return [{ name: 'spec-only', tasks: buildSpecOnlyTasks(roles) }];
// Impl-only: planner → executor → tester → reviewer
if (has('planner') && has('executor') && !has('analyst'))
return [{ name: 'impl-only', tasks: buildImplOnlyTasks(roles) }];
// Custom: user-defined
return [{ name: 'custom', tasks: buildCustomTasks(roles, domain) }];
}
```
### Task Schema
```javascript
const taskSchema = {
id: 'PREFIX-NNN', // e.g., RESEARCH-001
role: 'analyst', // which role executes
name: 'Seed Analysis', // human-readable name
dependsOn: [], // task IDs that must complete first
isCheckpoint: false, // true for quality gates
isConditional: false, // true for routing decisions
description: '...'
};
```
## Step 1.5: Determine Commands Distribution
**Rule**: 1 action → inline in role.md. 2+ distinct actions → commands/ folder.
```javascript
function determineCommandsDistribution(roles) {
// Coordinator: always has commands/
// coordinator.commands = ['analyze', 'dispatch', 'monitor']
// Standard multi-action roles:
// executor → implement + fix → commands/
// reviewer (if both code & spec review) → review-code + review-spec → commands/
// All others → typically inline
for (const role of roles) {
const actions = countDistinctActions(role);
if (actions.length >= 2) {
role.hasCommands = true;
role.commands = actions.map(a => a.name);
}
}
}
```
## Step 1.6: Determine Specs and Templates
```javascript
// Specs: always include pipelines, add domain-specific
const specs = ['pipelines'];
if (hasQualityGates) specs.push('quality-gates');
if (hasKnowledgeTransfer) specs.push('knowledge-transfer');
// Templates: only if writer role exists
const templates = [];
if (has('writer')) {
// Detect from domain keywords
if (domain.includes('product')) templates.push('product-brief');
if (domain.includes('requirement')) templates.push('requirements');
if (domain.includes('architecture')) templates.push('architecture');
if (domain.includes('epic')) templates.push('epics');
}
```
## Step 1.7: Build teamConfig
```javascript
const teamConfig = {
skillName: string, // e.g., "team-code-review"
sessionPrefix: string, // e.g., "TCR"
domain: string, // domain description
title: string, // e.g., "Code Review Team"
roles: Array<RoleConfig>, // includes coordinator
pipelines: Array<Pipeline>,
specs: Array<string>, // filenames without .md
templates: Array<string>, // filenames without .md
conditionalRouting: boolean,
dynamicSpecialists: Array<string>,
};
```
## Step 1.8: Confirm with User
```
╔══════════════════════════════════════════╗
║ Team Skill Configuration Summary ║
╠══════════════════════════════════════════╣
Skill Name: ${skillName}
Session Prefix: ${sessionPrefix}
Domain: ${domain}
Roles (N):
├─ coordinator (commands: analyze, dispatch, monitor)
├─ role-a [PREFIX-*] (inline) 🔄
└─ role-b [PREFIX-*] (commands: cmd1, cmd2)
Pipelines:
└─ pipeline-name: TASK-001 → TASK-002 → TASK-003
Specs: pipelines, quality-gates
Templates: (none)
╚══════════════════════════════════════════╝
```
Use AskUserQuestion to confirm or allow modifications.
## Output
- **Variable**: `teamConfig` — complete configuration for all subsequent phases
- **Next**: Phase 2 - Scaffold Generation

236
.claude/skills/team-designer/phases/02-scaffold-generation.md Normal file
View File

@@ -0,0 +1,236 @@
# Phase 2: Scaffold Generation
Generate the SKILL.md universal router and create the directory structure for the team skill.
## Objective
- Create directory structure (roles/, specs/, templates/)
- Generate SKILL.md as universal router following v4 pattern
- SKILL.md must NOT contain beat model, pipeline details, or role Phase 2-4 logic
## Step 2.1: Create Directory Structure
```bash
skillDir=".claude/skills/${teamConfig.skillName}"
mkdir -p "${skillDir}"
# Create role directories
for role in teamConfig.roles:
mkdir -p "${skillDir}/roles/${role.name}"
if role.hasCommands:
mkdir -p "${skillDir}/roles/${role.name}/commands"
# Create specs directory
mkdir -p "${skillDir}/specs"
# Create templates directory (if needed)
if teamConfig.templates.length > 0:
mkdir -p "${skillDir}/templates"
```
## Step 2.2: Generate SKILL.md
The SKILL.md follows a strict template. Every generated SKILL.md contains these sections in order:
### Section 1: Frontmatter
```yaml
---
name: ${teamConfig.skillName}
description: ${teamConfig.domain}. Triggers on "${teamConfig.skillName}".
allowed-tools: TeamCreate(*), TeamDelete(*), SendMessage(*), TaskCreate(*), TaskUpdate(*), TaskList(*), TaskGet(*), Agent(*), AskUserQuestion(*), Read(*), Write(*), Edit(*), Bash(*), Glob(*), Grep(*)
---
```
### Section 2: Title + Architecture Diagram
```markdown
# ${Title}
${One-line description}
## Architecture
\```
Skill(skill="${teamConfig.skillName}", args="task description")
|
SKILL.md (this file) = Router
|
+--------------+--------------+
| |
no --role flag --role <name>
| |
Coordinator Worker
roles/coordinator/role.md roles/<name>/role.md
|
+-- analyze → dispatch → spawn workers → STOP
|
+-------+-------+-------+
v v v v
[team-worker agents, each loads roles/<role>/role.md]
\```
```
### Section 3: Role Registry
```markdown
## Role Registry
| Role | Path | Prefix | Inner Loop |
|------|------|--------|------------|
| coordinator | roles/coordinator/role.md | — | — |
${teamConfig.roles.filter(r => r.name !== 'coordinator').map(r =>
`| ${r.name} | ${r.path} | ${r.prefix}-* | ${r.inner_loop} |`
).join('\n')}
```
### Section 4: Role Router
```markdown
## Role Router
Parse `$ARGUMENTS`:
- Has `--role <name>` → Read `roles/<name>/role.md`, execute Phase 2-4
- No `--role` → Read `roles/coordinator/role.md`, execute entry router
```
### Section 5: Shared Constants
```markdown
## Shared Constants
- **Session prefix**: `${teamConfig.sessionPrefix}`
- **Session path**: `.workflow/.team/${teamConfig.sessionPrefix}-<slug>-<date>/`
- **CLI tools**: `ccw cli --mode analysis` (read-only), `ccw cli --mode write` (modifications)
- **Message bus**: `mcp__ccw-tools__team_msg(session_id=<session-id>, ...)`
```
### Section 6: Worker Spawn Template
```markdown
## Worker Spawn Template
Coordinator spawns workers using this template:
\```
Agent({
subagent_type: "team-worker",
description: "Spawn <role> worker",
team_name: <team-name>,
name: "<role>",
run_in_background: true,
prompt: `## Role Assignment
role: <role>
role_spec: .claude/skills/${teamConfig.skillName}/roles/<role>/role.md
session: <session-folder>
session_id: <session-id>
team_name: <team-name>
requirement: <task-description>
inner_loop: <true|false>
Read role_spec file to load Phase 2-4 domain instructions.
Execute built-in Phase 1 (task discovery) -> role Phase 2-4 -> built-in Phase 5 (report).`
})
\```
```
### Section 7: User Commands
```markdown
## User Commands
| Command | Action |
|---------|--------|
| `check` / `status` | View execution status graph |
| `resume` / `continue` | Advance to next step |
| `revise <TASK-ID> [feedback]` | Revise specific task |
| `feedback <text>` | Inject feedback for revision |
| `recheck` | Re-run quality check |
| `improve [dimension]` | Auto-improve weakest dimension |
```
### Section 8: Completion Action
```markdown
## Completion Action
When pipeline completes, coordinator presents:
\```
AskUserQuestion({
questions: [{
question: "Pipeline complete. What would you like to do?",
header: "Completion",
multiSelect: false,
options: [
{ label: "Archive & Clean (Recommended)", description: "Archive session, clean up team" },
{ label: "Keep Active", description: "Keep session for follow-up work" },
{ label: "Export Results", description: "Export deliverables to target directory" }
]
}]
})
\```
```
### Section 9: Specs Reference
```markdown
## Specs Reference
${teamConfig.specs.map(s =>
`- [specs/${s}.md](specs/${s}.md) — ${specDescription(s)}`
).join('\n')}
```
### Section 10: Session Directory
```markdown
## Session Directory
\```
.workflow/.team/${teamConfig.sessionPrefix}-<slug>-<date>/
├── team-session.json # Session state + role registry
├── spec/ # Spec phase outputs
├── plan/ # Implementation plan + TASK-*.json
├── artifacts/ # All deliverables
├── wisdom/ # Cross-task knowledge
├── explorations/ # Shared explore cache
├── discussions/ # Discuss round records
└── .msg/ # Team message bus
\```
```
### Section 11: Error Handling
```markdown
## Error Handling
| Scenario | Resolution |
|----------|------------|
| Unknown command | Error with available command list |
| Role not found | Error with role registry |
| CLI tool fails | Worker fallback to direct implementation |
| Fast-advance conflict | Coordinator reconciles on next callback |
| Completion action fails | Default to Keep Active |
```
## Step 2.3: Assemble and Write
Assemble all sections into a single SKILL.md file and write to `${skillDir}/SKILL.md`.
**Quality Rules**:
1. SKILL.md must NOT contain beat model (ONE_STEP_PER_INVOCATION, spawn-and-stop)
2. SKILL.md must NOT contain pipeline task details (task IDs, dependencies)
3. SKILL.md must NOT contain role Phase 2-4 logic
4. SKILL.md MUST contain role registry table with correct paths
5. SKILL.md MUST contain worker spawn template with correct `role_spec` paths
## Output
- **File**: `.claude/skills/${teamConfig.skillName}/SKILL.md`
- **Variable**: `skillDir` (path to skill root directory)
- **Next**: Phase 3 - Content Generation
## Next Phase
Return to orchestrator, then auto-continue to [Phase 3: Content Generation](03-content-generation.md).

330
.claude/skills/team-designer/phases/03-content-generation.md Normal file
View File

@@ -0,0 +1,330 @@
# Phase 3: Content Generation
Generate all role files, specs, and templates based on `teamConfig` and the generated SKILL.md.
## Objective
- Generate coordinator role.md + commands/ (analyze, dispatch, monitor)
- Generate each worker role.md (inline or with commands/)
- Generate specs/ files (pipelines.md + domain specs)
- Generate templates/ if needed
- Follow team-lifecycle-v4 golden sample patterns
## Golden Sample Reference
Read the golden sample at `.claude/skills/team-lifecycle-v4/` for each file type before generating. This ensures pattern fidelity.
## Step 3.1: Generate Coordinator
The coordinator is the most complex role. It always has 3 commands.
### coordinator/role.md
```markdown
---
role: coordinator
---
# Coordinator — ${teamConfig.title}
## Identity
You are the coordinator for ${teamConfig.title}. You orchestrate the ${teamConfig.domain} pipeline by analyzing requirements, dispatching tasks, and monitoring worker progress.
## Boundaries
- **DO**: Analyze, dispatch, monitor, reconcile, report
- **DO NOT**: Implement domain work directly — delegate to workers
## Command Execution Protocol
Read command file → Execute ALL steps sequentially → Return to entry router.
Commands: `commands/analyze.md`, `commands/dispatch.md`, `commands/monitor.md`.
## Entry Router
On each invocation, detect current state and route:
| Condition | Handler |
|-----------|---------|
| First invocation (no session) | → Phase 1: Requirement Clarification |
| Session exists, no team | → Phase 2: Team Setup |
| Team exists, no tasks | → Phase 3: Dispatch (analyze.md → dispatch.md) |
| Tasks exist, none started | → Phase 4: Spawn First (monitor.md → handleSpawnNext) |
| Callback received | → monitor.md → handleCallback |
| User says "check"/"status" | → monitor.md → handleCheck |
| User says "resume"/"continue" | → monitor.md → handleResume |
| All tasks completed | → Phase 5: Report & Completion |
## Phase 0: Session Resume
If `.workflow/.team/${teamConfig.sessionPrefix}-*/team-session.json` exists:
- Load session state, verify team, reconcile task status
- Route to appropriate handler based on current state
## Phase 1: Requirement Clarification
- Parse user's task description at TEXT LEVEL
- Use AskUserQuestion if requirements are ambiguous
- Execute `commands/analyze.md` for signal detection + complexity scoring
## Phase 2: Team Setup
- TeamCreate with session ID: `${teamConfig.sessionPrefix}-<slug>-<date>`
- Initialize team_msg message bus
- Create session directory structure
## Phase 3: Dispatch
- Execute `commands/dispatch.md`
- Creates TaskCreate calls with blockedBy dependencies
## Phase 4: Spawn & Monitor
- Execute `commands/monitor.md` → handleSpawnNext
- Spawn ready workers as team-worker agents
- **STOP after spawning** — wait for callback
## Phase 5: Report & Completion
- Aggregate all task artifacts
- Present completion action to user
```
### coordinator/commands/analyze.md
Template based on golden sample — includes:
- Signal detection (keywords → capabilities)
- Dependency graph construction (tiers)
- Complexity scoring (1-3 Low, 4-6 Medium, 7+ High)
- Role minimization (cap at 5)
- Output: task-analysis.json
```markdown
# Command: Analyze
## Signal Detection
Scan requirement text for capability signals:
${teamConfig.roles.filter(r => r.name !== 'coordinator').map(r =>
`- **${r.name}**: [domain-specific keywords]`
).join('\n')}
## Dependency Graph
Build 4-tier dependency graph:
- Tier 0: Independent tasks (can run in parallel)
- Tier 1: Depends on Tier 0
- Tier 2: Depends on Tier 1
- Tier 3: Depends on Tier 2
## Complexity Scoring
| Score | Level | Strategy |
|-------|-------|----------|
| 1-3 | Low | Direct implementation, skip deep planning |
| 4-6 | Medium | Standard pipeline with planning |
| 7+ | High | Full spec → plan → implement cycle |
## Output
Write `task-analysis.json` to session directory:
\```json
{
"signals": [...],
"roles_needed": [...],
"dependency_tiers": [...],
"complexity": { "score": N, "level": "Low|Medium|High" },
"pipeline": "${teamConfig.pipelines[0].name}"
}
\```
```
### coordinator/commands/dispatch.md
Template — includes:
- Topological sort from dependency graph
- TaskCreate with blockedBy
- Task description template (PURPOSE/TASK/CONTEXT/EXPECTED/CONSTRAINTS)
### coordinator/commands/monitor.md
Template — includes:
- Beat model constants (ONE_STEP_PER_INVOCATION, SPAWN_MODE: spawn-and-stop)
- 6 handlers: handleCallback, handleCheck, handleResume, handleSpawnNext, handleComplete, handleAdapt
- Checkpoint detection for quality gates
- Fast-advance reconciliation
**Critical**: This is the ONLY file that contains beat model logic.
## Step 3.2: Generate Worker Roles
For each worker role in `teamConfig.roles`:
### Inline Role Template (no commands/)
```markdown
---
role: ${role.name}
prefix: ${role.prefix}
inner_loop: ${role.inner_loop}
message_types: [${role.message_types.join(', ')}]
---
# ${capitalize(role.name)} — ${teamConfig.title}
## Identity
You are the ${role.name} for ${teamConfig.title}.
Task prefix: `${role.prefix}-*`
## Phase 2: Context Loading
- Read task description from TaskGet
- Load relevant session artifacts from session directory
- Load specs from `specs/` as needed
## Phase 3: Domain Execution
[Domain-specific execution logic for this role]
### Execution Steps
1. [Step 1 based on role's domain]
2. [Step 2]
3. [Step 3]
### Tools Available
- CLI tools: `ccw cli --mode analysis|write`
- Direct tools: Read, Write, Edit, Bash, Grep, Glob
- Message bus: `mcp__ccw-tools__team_msg`
- **Cannot use Agent()** — workers must use CLI or direct tools
## Phase 4: Output & Report
- Write artifacts to session directory
- Log state_update via team_msg
- Publish wisdom if cross-task knowledge discovered
```
### Command-Based Role Template (has commands/)
```markdown
---
role: ${role.name}
prefix: ${role.prefix}
inner_loop: ${role.inner_loop}
message_types: [${role.message_types.join(', ')}]
---
# ${capitalize(role.name)} — ${teamConfig.title}
## Identity
You are the ${role.name} for ${teamConfig.title}.
Task prefix: `${role.prefix}-*`
## Phase 2: Context Loading
Load task description, detect mode/command.
## Phase 3: Command Router
| Condition | Command |
|-----------|---------|
${role.commands.map(cmd =>
`| [condition for ${cmd}] | → commands/${cmd}.md |`
).join('\n')}
Read command file → Execute ALL steps → Return to Phase 4.
## Phase 4: Output & Report
Write artifacts, log state_update.
```
Then generate each `commands/<cmd>.md` with domain-specific logic.
## Step 3.3: Generate Specs
### specs/pipelines.md
```markdown
# Pipeline Definitions
## Available Pipelines
${teamConfig.pipelines.map(p => `
### ${p.name}
| Task ID | Role | Name | Depends On | Checkpoint |
|---------|------|------|------------|------------|
${p.tasks.map(t =>
`| ${t.id} | ${t.role} | ${t.name} | ${t.dependsOn.join(', ') || '—'} | ${t.isCheckpoint ? '✓' : '—'} |`
).join('\n')}
`).join('\n')}
## Task Metadata Registry
Standard task description template:
\```
PURPOSE: [goal]
TASK: [steps]
CONTEXT: [session artifacts + specs]
EXPECTED: [deliverable format]
CONSTRAINTS: [scope limits]
\```
## Conditional Routing
${teamConfig.conditionalRouting ? `
PLAN-001 complexity assessment routes to:
- Low (1-3): Direct implementation
- Medium (4-6): Standard planning
- High (7+): Full spec → plan → implement
` : 'No conditional routing in this pipeline.'}
## Dynamic Specialist Injection
${teamConfig.dynamicSpecialists.length > 0 ?
teamConfig.dynamicSpecialists.map(s => `- ${s}: Injected when domain keywords detected`).join('\n') :
'No dynamic specialists configured.'
}
```
### Additional Specs
For each additional spec in `teamConfig.specs` (beyond pipelines), generate domain-appropriate content:
- **quality-gates.md**: Thresholds (Pass≥80%, Review 60-79%, Fail<60%), scoring dimensions, per-phase gates
- **knowledge-transfer.md**: 5 transfer channels, Phase 2 loading protocol, Phase 4 publishing protocol
## Step 3.4: Generate Templates
For each template in `teamConfig.templates`:
1. Check if golden sample has matching template at `.claude/skills/team-lifecycle-v4/templates/`
2. If exists: copy and adapt for new domain
3. If not: generate domain-appropriate template structure
## Step 3.5: Generation Order
Execute in this order (respects dependencies):
1. **specs/** — needed by roles for reference
2. **coordinator/** — role.md + commands/ (3 files)
3. **workers/** — each role.md (+ optional commands/)
4. **templates/** — independent, generate last
For each file:
1. Read golden sample equivalent (if exists)
2. Adapt content for current teamConfig
3. Write file
4. Verify file exists
## Output
- **Files**: All role.md, commands/*.md, specs/*.md, templates/*.md
- **Next**: Phase 4 - Validation

329
.claude/skills/team-designer/phases/04-validation.md Normal file
View File

@@ -0,0 +1,329 @@
# Phase 4: Validation
Validate the generated team skill package for structural completeness, reference integrity, role consistency, and team-worker compatibility.
## Objective
- Verify all required files exist
- Validate SKILL.md role registry matches actual role files
- Check role.md frontmatter format for team-worker compatibility
- Verify pipeline task references match existing roles
- Report validation results
## Step 4.1: Structural Validation
```javascript
function validateStructure(teamConfig) {
const skillDir = `.claude/skills/${teamConfig.skillName}`;
const results = { errors: [], warnings: [], info: [] };
// Check SKILL.md exists
if (!fileExists(`${skillDir}/SKILL.md`)) {
results.errors.push('SKILL.md not found');
}
// Check coordinator structure
if (!fileExists(`${skillDir}/roles/coordinator/role.md`)) {
results.errors.push('Coordinator role.md not found');
}
for (const cmd of ['analyze', 'dispatch', 'monitor']) {
if (!fileExists(`${skillDir}/roles/coordinator/commands/${cmd}.md`)) {
results.errors.push(`Coordinator command ${cmd}.md not found`);
}
}
// Check worker roles
for (const role of teamConfig.roles.filter(r => r.name !== 'coordinator')) {
if (!fileExists(`${skillDir}/roles/${role.name}/role.md`)) {
results.errors.push(`Worker role.md not found: ${role.name}`);
}
if (role.hasCommands) {
for (const cmd of role.commands) {
if (!fileExists(`${skillDir}/roles/${role.name}/commands/${cmd}.md`)) {
results.errors.push(`Worker command not found: ${role.name}/commands/${cmd}.md`);
}
}
}
}
// Check specs
if (!fileExists(`${skillDir}/specs/pipelines.md`)) {
results.errors.push('specs/pipelines.md not found');
}
return results;
}
```
## Step 4.2: SKILL.md Content Validation
```javascript
function validateSkillMd(teamConfig) {
const skillDir = `.claude/skills/${teamConfig.skillName}`;
const results = { errors: [], warnings: [], info: [] };
const skillMd = Read(`${skillDir}/SKILL.md`);
// Required sections
const requiredSections = [
'Role Registry', 'Role Router', 'Shared Constants',
'Worker Spawn Template', 'User Commands', 'Session Directory'
];
for (const section of requiredSections) {
if (!skillMd.includes(section)) {
results.errors.push(`SKILL.md missing section: ${section}`);
}
}
// Verify role registry completeness
for (const role of teamConfig.roles) {
if (!skillMd.includes(role.path || `roles/${role.name}/role.md`)) {
results.errors.push(`Role registry missing path for: ${role.name}`);
}
}
// Verify session prefix
if (!skillMd.includes(teamConfig.sessionPrefix)) {
results.warnings.push(`Session prefix ${teamConfig.sessionPrefix} not found in SKILL.md`);
}
// Verify NO beat model content in SKILL.md
const beatModelPatterns = [
'ONE_STEP_PER_INVOCATION',
'spawn-and-stop',
'SPAWN_MODE',
'handleCallback',
'handleSpawnNext'
];
for (const pattern of beatModelPatterns) {
if (skillMd.includes(pattern)) {
results.errors.push(`SKILL.md contains beat model content: ${pattern} (should be in coordinator only)`);
}
}
return results;
}
```
## Step 4.3: Role Frontmatter Validation
Verify role.md files have correct YAML frontmatter for team-worker agent compatibility:
```javascript
function validateRoleFrontmatter(teamConfig) {
const skillDir = `.claude/skills/${teamConfig.skillName}`;
const results = { errors: [], warnings: [], info: [] };
for (const role of teamConfig.roles.filter(r => r.name !== 'coordinator')) {
const roleMd = Read(`${skillDir}/roles/${role.name}/role.md`);
// Check frontmatter exists
if (!roleMd.startsWith('---')) {
results.errors.push(`${role.name}/role.md missing YAML frontmatter`);
continue;
}
// Extract frontmatter
const fmMatch = roleMd.match(/^---\n([\s\S]*?)\n---/);
if (!fmMatch) {
results.errors.push(`${role.name}/role.md malformed frontmatter`);
continue;
}
const fm = fmMatch[1];
// Required fields
if (!fm.includes(`role: ${role.name}`)) {
results.errors.push(`${role.name}/role.md frontmatter missing 'role: ${role.name}'`);
}
if (!fm.includes(`prefix: ${role.prefix}`)) {
results.errors.push(`${role.name}/role.md frontmatter missing 'prefix: ${role.prefix}'`);
}
if (!fm.includes(`inner_loop: ${role.inner_loop}`)) {
results.warnings.push(`${role.name}/role.md frontmatter missing 'inner_loop: ${role.inner_loop}'`);
}
if (!fm.includes('message_types:')) {
results.warnings.push(`${role.name}/role.md frontmatter missing 'message_types'`);
}
}
return results;
}
```
## Step 4.4: Pipeline Consistency
```javascript
function validatePipelines(teamConfig) {
const skillDir = `.claude/skills/${teamConfig.skillName}`;
const results = { errors: [], warnings: [], info: [] };
// Check every role referenced in pipelines exists
const definedRoles = new Set(teamConfig.roles.map(r => r.name));
for (const pipeline of teamConfig.pipelines) {
for (const task of pipeline.tasks) {
if (!definedRoles.has(task.role)) {
results.errors.push(
`Pipeline '${pipeline.name}' task ${task.id} references undefined role: ${task.role}`
);
}
}
// Check for circular dependencies
const visited = new Set();
const stack = new Set();
for (const task of pipeline.tasks) {
if (hasCycle(task, pipeline.tasks, visited, stack)) {
results.errors.push(`Pipeline '${pipeline.name}' has circular dependency involving ${task.id}`);
}
}
}
// Verify specs/pipelines.md contains all pipelines
const pipelinesMd = Read(`${skillDir}/specs/pipelines.md`);
for (const pipeline of teamConfig.pipelines) {
if (!pipelinesMd.includes(pipeline.name)) {
results.warnings.push(`specs/pipelines.md missing pipeline: ${pipeline.name}`);
}
}
return results;
}
```
## Step 4.5: Commands Distribution Validation
```javascript
function validateCommandsDistribution(teamConfig) {
const skillDir = `.claude/skills/${teamConfig.skillName}`;
const results = { errors: [], warnings: [], info: [] };
for (const role of teamConfig.roles.filter(r => r.name !== 'coordinator')) {
if (role.hasCommands) {
// Verify commands/ directory exists and has files
const cmdDir = `${skillDir}/roles/${role.name}/commands`;
if (role.commands.length < 2) {
results.warnings.push(
`${role.name} has commands/ but only ${role.commands.length} command(s) — consider inline`
);
}
// Verify role.md references commands
const roleMd = Read(`${skillDir}/roles/${role.name}/role.md`);
for (const cmd of role.commands) {
if (!roleMd.includes(`commands/${cmd}.md`)) {
results.warnings.push(
`${role.name}/role.md doesn't reference commands/${cmd}.md`
);
}
}
} else {
// Verify no commands/ directory exists
const cmdDir = `${skillDir}/roles/${role.name}/commands`;
if (directoryExists(cmdDir)) {
results.warnings.push(
`${role.name} is inline but has commands/ directory`
);
}
}
}
return results;
}
```
## Step 4.6: Aggregate Results and Report
```javascript
function generateValidationReport(teamConfig) {
const structural = validateStructure(teamConfig);
const skillMd = validateSkillMd(teamConfig);
const frontmatter = validateRoleFrontmatter(teamConfig);
const pipelines = validatePipelines(teamConfig);
const commands = validateCommandsDistribution(teamConfig);
const allErrors = [
...structural.errors, ...skillMd.errors,
...frontmatter.errors, ...pipelines.errors, ...commands.errors
];
const allWarnings = [
...structural.warnings, ...skillMd.warnings,
...frontmatter.warnings, ...pipelines.warnings, ...commands.warnings
];
const gate = allErrors.length === 0 ? 'PASS' :
allErrors.length <= 2 ? 'REVIEW' : 'FAIL';
const skillDir = `.claude/skills/${teamConfig.skillName}`;
console.log(`
╔══════════════════════════════════════╗
║ Team Skill Validation Report ║
╠══════════════════════════════════════╣
║ Skill: ${teamConfig.skillName.padEnd(28)}║
║ Gate: ${gate.padEnd(28)}║
╚══════════════════════════════════════╝
Structure:
${skillDir}/
├── SKILL.md ✓
├── roles/
│ ├── coordinator/
│ │ ├── role.md ✓
│ │ └── commands/ (analyze, dispatch, monitor)
${teamConfig.roles.filter(r => r.name !== 'coordinator').map(r => {
const structure = r.hasCommands
? ` │ ├── ${r.name}/ (role.md + commands/)`
: ` │ ├── ${r.name}/role.md`;
return `${structure.padEnd(50)}✓`;
}).join('\n')}
├── specs/
│ └── pipelines.md ✓
└── templates/ ${teamConfig.templates.length > 0 ? '✓' : '(empty)'}
${allErrors.length > 0 ? `Errors (${allErrors.length}):\n${allErrors.map(e => ` ✗ ${e}`).join('\n')}` : 'Errors: None ✓'}
${allWarnings.length > 0 ? `Warnings (${allWarnings.length}):\n${allWarnings.map(w => ` ⚠ ${w}`).join('\n')}` : 'Warnings: None ✓'}
Usage:
Skill(skill="${teamConfig.skillName}", args="<task description>")
`);
return { gate, errors: allErrors, warnings: allWarnings };
}
```
## Step 4.7: Error Recovery
```javascript
if (report.gate === 'FAIL') {
const recovery = AskUserQuestion({
questions: [{
question: `Validation found ${report.errors.length} errors. How to proceed?`,
header: "Recovery",
multiSelect: false,
options: [
{ label: "Auto-fix", description: "Attempt automatic fixes (missing files, frontmatter)" },
{ label: "Regenerate", description: "Re-run Phase 3 with fixes" },
{ label: "Accept as-is", description: "Manual fix later" }
]
}]
});
}
```
## Output
- **Report**: Validation results with quality gate (PASS/REVIEW/FAIL)
- **Completion**: Team skill package ready at `.claude/skills/${teamConfig.skillName}/`
## Completion
Team Skill Designer has completed. The generated team skill is ready for use.
```
Next Steps:
1. Review SKILL.md router for correctness
2. Review each role.md for domain accuracy
3. Test: Skill(skill="${teamConfig.skillName}", args="<test task>")
4. Iterate based on execution results
```

32
.claude/skills/team-executor/SKILL.md
View File

@@ -157,38 +157,6 @@ AskUserQuestion({
---
## Cadence Control
**Beat model**: Event-driven, each beat = executor wake -> process -> spawn -> STOP.
```
Beat Cycle (single beat)
======================================================================
Event Executor Workers
----------------------------------------------------------------------
callback/resume --> +- handleCallback -+
| mark completed |
| check pipeline |
+- handleSpawnNext -+
| find ready tasks |
| spawn workers ---+--> [team-worker A] Phase 1-5
| (parallel OK) --+--> [team-worker B] Phase 1-5
+- STOP (idle) -----+ |
|
callback <-----------------------------------------+
(next beat) SendMessage + TaskUpdate(completed)
======================================================================
Fast-Advance (skips executor for simple linear successors)
======================================================================
[Worker A] Phase 5 complete
+- 1 ready task? simple successor? --> spawn team-worker B directly
+- complex case? --> SendMessage to executor
======================================================================
```
---
## Integration with team-coordinate
| Scenario | Skill |

277
.claude/skills/team-frontend/SKILL.md
View File

@@ -1,111 +1,61 @@
---
name: team-frontend
description: Unified team skill for frontend development. Uses team-worker agent architecture with role-spec files for domain logic. Coordinator orchestrates pipeline, workers are team-worker agents. Built-in ui-ux-pro-max design intelligence. Triggers on "team frontend".
allowed-tools: Agent, TaskCreate, TaskList, TaskGet, TaskUpdate, TeamCreate, TeamDelete, SendMessage, AskUserQuestion, Read, Write, Edit, Bash, Glob, Grep, WebFetch, WebSearch, mcp__ace-tool__search_context
description: Unified team skill for frontend development. Pure router — all roles read this file. Beat model is coordinator-only in monitor.md. Built-in ui-ux-pro-max design intelligence. Triggers on "team frontend".
allowed-tools: Agent(*), TaskCreate(*), TaskList(*), TaskGet(*), TaskUpdate(*), TeamCreate(*), TeamDelete(*), SendMessage(*), AskUserQuestion(*), Read(*), Write(*), Edit(*), Bash(*), Glob(*), Grep(*), WebFetch(*), WebSearch(*), mcp__ace-tool__search_context(*)
---
# Team Frontend Development
Unified team skill: frontend development with built-in ui-ux-pro-max design intelligence. Covers requirement analysis, design system generation, frontend implementation, and quality assurance. Built on **team-worker agent architecture** -- all worker roles share a single agent definition with role-specific Phase 2-4 loaded from markdown specs.
Unified team skill: frontend development with built-in ui-ux-pro-max design intelligence. Covers requirement analysis, design system generation, frontend implementation, and quality assurance. Built on **team-worker agent architecture** — all worker roles share a single agent definition with role-specific Phase 2-4 loaded from role.md specs.
## Architecture
```
+---------------------------------------------------+
| Skill(skill="team-frontend") |
| args="<task-description>" |
+-------------------+-------------------------------+
Skill(skill="team-frontend", args="task description")
|
Orchestration Mode (auto -> coordinator)
SKILL.md (this file) = Router
|
Coordinator (inline)
Phase 0-5 orchestration
+--------------+--------------+
| |
no --role flag --role <name>
| |
Coordinator Worker
roles/coordinator/role.md roles/<name>/role.md
|
+-------+-------+-------+-------+
+-- analyze -> dispatch -> spawn workers -> STOP
|
+-------+-------+-------+
v v v v
[tw] [tw] [tw] [tw]
analyst archi- devel- qa
tect oper
(tw) = team-worker agent
[analyst] [architect] [developer] [qa]
(team-worker agents, each loads roles/<role>/role.md)
```
## Role Registry
| Role | Path | Prefix | Inner Loop |
|------|------|--------|------------|
| coordinator | [roles/coordinator/role.md](roles/coordinator/role.md) | — | — |
| analyst | [roles/analyst/role.md](roles/analyst/role.md) | ANALYZE-* | false |
| architect | [roles/architect/role.md](roles/architect/role.md) | ARCH-* | false |
| developer | [roles/developer/role.md](roles/developer/role.md) | DEV-* | true |
| qa | [roles/qa/role.md](roles/qa/role.md) | QA-* | false |
## Role Router
This skill is **coordinator-only**. Workers do NOT invoke this skill -- they are spawned as `team-worker` agents directly.
Parse `$ARGUMENTS`:
- Has `--role <name>` → Read `roles/<name>/role.md`, execute Phase 2-4
- No `--role` → Read `roles/coordinator/role.md`, execute entry router
### Input Parsing
## Shared Constants
Parse `$ARGUMENTS`. No `--role` needed -- always routes to coordinator.
- **Session prefix**: `FE`
- **Session path**: `.workflow/.team/FE-<slug>-<date>/`
- **CLI tools**: `ccw cli --mode analysis` (read-only), `ccw cli --mode write` (modifications)
- **Message bus**: `mcp__ccw-tools__team_msg(session_id=<session-id>, ...)`
### Role Registry
## Worker Spawn Template
| Role | Spec | Task Prefix | Type | Inner Loop |
|------|------|-------------|------|------------|
| coordinator | [roles/coordinator/role.md](roles/coordinator/role.md) | (none) | orchestrator | - |
| analyst | [role-specs/analyst.md](role-specs/analyst.md) | ANALYZE-* | read_only_analysis | false |
| architect | [role-specs/architect.md](role-specs/architect.md) | ARCH-* | code_generation | false |
| developer | [role-specs/developer.md](role-specs/developer.md) | DEV-* | code_generation | true |
| qa | [role-specs/qa.md](role-specs/qa.md) | QA-* | read_only_analysis | false |
### Dispatch
Always route to coordinator. Coordinator reads `roles/coordinator/role.md` and executes its phases.
### Orchestration Mode
User just provides task description.
**Invocation**:
```bash
Skill(skill="team-frontend", args="<task-description>")
```
**Lifecycle**:
```
User provides task description
-> coordinator Phase 1-3: Parse requirements -> TeamCreate -> Create task chain
-> coordinator Phase 4: spawn first batch workers (background) -> STOP
-> Worker (team-worker agent) executes -> SendMessage callback -> coordinator advances
-> GC loop (developer <-> qa) if fix_required (max 2 rounds)
-> All tasks complete -> Phase 5 report + completion action
```
**User Commands** (wake paused coordinator):
| Command | Action |
|---------|--------|
| `check` / `status` | Output execution status graph, no advancement |
| `resume` / `continue` | Check worker states, advance next step |
---
## Command Execution Protocol
When coordinator needs to execute a command (dispatch, monitor):
1. **Read the command file**: `roles/coordinator/commands/<command-name>.md`
2. **Follow the workflow** defined in the command file (Phase 2-4 structure)
3. **Commands are inline execution guides** -- NOT separate agents or subprocesses
4. **Execute synchronously** -- complete the command workflow before proceeding
Example:
```
Phase 3 needs task dispatch
-> Read roles/coordinator/commands/dispatch.md
-> Execute Phase 2 (Context Loading)
-> Execute Phase 3 (Task Chain Creation)
-> Execute Phase 4 (Validation)
-> Continue to Phase 4
```
---
## Coordinator Spawn Template
### v5 Worker Spawn (all roles)
When coordinator spawns workers, use `team-worker` agent with role-spec path:
Coordinator spawns workers using this template:
```
Agent({
@@ -116,7 +66,7 @@ Agent({
run_in_background: true,
prompt: `## Role Assignment
role: <role>
role_spec: .claude/skills/team-frontend/role-specs/<role>.md
role_spec: .claude/skills/team-frontend/roles/<role>/role.md
session: <session-folder>
session_id: <session-id>
team_name: frontend
@@ -124,150 +74,16 @@ requirement: <task-description>
inner_loop: <true|false>
Read role_spec file to load Phase 2-4 domain instructions.
Execute built-in Phase 1 (task discovery) -> role-spec Phase 2-4 -> built-in Phase 5 (report).`
Execute built-in Phase 1 (task discovery) -> role Phase 2-4 -> built-in Phase 5 (report).`
})
```
**Inner Loop roles** (developer): Set `inner_loop: true`. The team-worker agent handles the loop internally.
## User Commands
**Single-task roles** (analyst, architect, qa): Set `inner_loop: false`.
---
## Pipeline Definitions
### Pipeline Diagrams
**Page Mode** (4 beats, linear):
```
Pipeline: Page (Linear)
=====================================================
Stage 1 Stage 2 Stage 3 Stage 4
ANALYZE-001 --> ARCH-001 --> DEV-001 --> QA-001
[analyst] [architect] [developer] [qa]
```
**Feature Mode** (5 beats, with architecture review gate):
```
Pipeline: Feature (Architecture Review Gate)
=====================================================
Stage 1 Stage 2 Stage 3 Stage 4 Stage 5
ANALYZE-001 --> ARCH-001 --> QA-001 --> DEV-001 --> QA-002
[analyst] [architect] [qa:arch-rev] [developer] [qa:code-rev]
```
**System Mode** (7 beats, dual-track parallel):
```
Pipeline: System (Dual-Track Parallel)
=====================================================
Stage 1 Stage 2 Stage 3 Stage 4 (parallel) Stage 5 Stage 6 Stage 7
ANALYZE-001 --> ARCH-001 --> QA-001 --> ARCH-002 ─┐ --> QA-002 --> DEV-002 --> QA-003
[analyst] [architect] [qa:arch-rev] [architect] | [qa] [developer] [qa:final]
DEV-001 ──┘
[developer:tokens]
```
### Generator-Critic Loop (developer <-> qa)
```
developer (Generator) -> QA artifact -> qa (Critic)
<- QA feedback <-
(max 2 rounds)
Convergence: qa.score >= 8 && qa.critical_count === 0
```
---
## Task Metadata Registry
| Task ID | Role | Stage | Dependencies | Description |
|---------|------|-------|-------------|-------------|
| ANALYZE-001 | analyst | analysis | (none) | Requirement analysis + design intelligence |
| ARCH-001 | architect | design | ANALYZE-001 | Design token system + component architecture |
| ARCH-002 | architect | design | QA-001 (system) | Component specs refinement |
| DEV-001 | developer | impl | ARCH-001 or QA-001 | Frontend implementation |
| DEV-002 | developer | impl | QA-002 (system) | Component implementation |
| QA-001 | qa | review | ARCH-001 or DEV-001 | Architecture or code review |
| QA-002 | qa | review | DEV-001 | Code review |
| QA-003 | qa | review | DEV-002 (system) | Final quality check |
---
## ui-ux-pro-max Integration
### Design Intelligence Engine
Analyst role invokes ui-ux-pro-max via Skill to obtain industry design intelligence:
| Action | Invocation |
|--------|------------|
| Full design system | `Skill(skill="ui-ux-pro-max", args="<industry> <keywords> --design-system")` |
| Domain search | `Skill(skill="ui-ux-pro-max", args="<query> --domain <domain>")` |
| Tech stack guidance | `Skill(skill="ui-ux-pro-max", args="<query> --stack <stack>")` |
**Supported Domains**: product, style, typography, color, landing, chart, ux, web
**Supported Stacks**: html-tailwind, react, nextjs, vue, svelte, shadcn, swiftui, react-native, flutter
**Fallback**: If ui-ux-pro-max skill not installed, degrade to LLM general design knowledge. Suggest installation: `/plugin install ui-ux-pro-max@ui-ux-pro-max-skill`
---
## Completion Action
At Phase 5, coordinator offers interactive completion:
```
AskUserQuestion({
questions: [{
question: "Team pipeline complete. What would you like to do?",
header: "Completion",
options: [
{ label: "Archive & Clean (Recommended)" },
{ label: "Keep Active" },
{ label: "Export Results" }
]
}]
})
```
| Choice | Steps |
|--------|-------|
| Archive & Clean | Verify completed -> update status -> TeamDelete() -> final summary |
| Keep Active | Status="paused" -> "Resume with: Skill(skill='team-frontend', args='resume')" |
| Export Results | Ask target dir -> copy artifacts -> Archive flow |
---
## Message Bus
Every SendMessage must be preceded by `mcp__ccw-tools__team_msg` log:
```
mcp__ccw-tools__team_msg({
operation: "log",
session_id: <session-id>,
from: <role>,
type: <message-type>,
data: {ref: <artifact-path>}
})
```
`to` and `summary` auto-defaulted -- do NOT specify explicitly.
**CLI fallback**: `ccw team log --session-id <session-id> --from <role> --type <type> --json`
**Message types by role**:
| Role | Types |
|------|-------|
| coordinator | `task_unblocked`, `sync_checkpoint`, `fix_required`, `error`, `shutdown` |
| analyst | `analyze_ready`, `error` |
| architect | `arch_ready`, `arch_revision`, `error` |
| developer | `dev_complete`, `dev_progress`, `error` |
| qa | `qa_passed`, `qa_result`, `fix_required`, `error` |
---
| Command | Action |
|---------|--------|
| `check` / `status` | View execution status graph |
| `resume` / `continue` | Advance to next step |
## Session Directory
@@ -276,6 +92,7 @@ mcp__ccw-tools__team_msg({
├── .msg/
│ ├── messages.jsonl # Message bus log
│ └── meta.json # Session state + cross-role state
├── task-analysis.json # Coordinator analyze output
├── wisdom/ # Cross-task knowledge
├── analysis/ # Analyst output
│ ├── design-intelligence.json
@@ -289,13 +106,17 @@ mcp__ccw-tools__team_msg({
└── build/ # Developer output
```
## Specs Reference
- [specs/pipelines.md](specs/pipelines.md) — Pipeline definitions and task registry
## Error Handling
| Scenario | Resolution |
|----------|------------|
| Unknown command | Error with available command list |
| Role not found | Error with role registry |
| QA score < 6 over 2 GC rounds | Escalate to user |
| Dual-track sync failure (system mode) | Fallback to single-track sequential |
| ui-ux-pro-max unavailable | Degrade to LLM general design knowledge |
| Worker no response | Report waiting task, suggest user `resume` |
| Pipeline deadlock | Check blockedBy chain, report blocking point |

92
.claude/skills/team-frontend/roles/analyst/role.md Normal file
View File

@@ -0,0 +1,92 @@
---
role: analyst
prefix: ANALYZE
inner_loop: false
message_types:
success: analyze_ready
error: error
---
# Requirements Analyst
Analyze frontend requirements and retrieve industry design intelligence via ui-ux-pro-max skill. Produce design-intelligence.json and requirements.md for downstream consumption by architect and developer roles.
## Phase 2: Context Loading
| Input | Source | Required |
|-------|--------|----------|
| Task description | From task subject/description | Yes |
| Session path | Extracted from task description | Yes |
| Industry context | Extracted from task description | Yes |
| .msg/meta.json | <session>/.msg/meta.json | No |
1. Extract session path, industry type, and tech stack from task description
2. Detect existing design system:
| Signal | Detection Method |
|--------|-----------------|
| Token files | Glob `**/*token*.*` |
| CSS files | Glob `**/*.css` |
| Package.json | Read for framework dependencies |
3. Detect tech stack from package.json:
| Dependency | Stack |
|------------|-------|
| `next` | nextjs |
| `react` | react |
| `vue` | vue |
| `svelte` | svelte |
| `@shadcn/ui` | shadcn |
| (none) | html-tailwind |
4. Load .msg/meta.json for shared state
## Phase 3: Design Intelligence Retrieval
Retrieve design intelligence via ui-ux-pro-max skill integration.
**Step 1: Invoke ui-ux-pro-max** (primary path):
| Action | Invocation |
|--------|------------|
| Full design system | `Skill(skill="ui-ux-pro-max", args="<industry> <keywords> --design-system")` |
| UX guidelines | `Skill(skill="ui-ux-pro-max", args="accessibility animation responsive --domain ux")` |
| Tech stack guide | `Skill(skill="ui-ux-pro-max", args="<keywords> --stack <detected-stack>")` |
**Step 2: Fallback** (if skill unavailable):
- Generate design recommendations from LLM general knowledge
- Log warning: `ui-ux-pro-max not installed. Install via: /plugin install ui-ux-pro-max@ui-ux-pro-max-skill`
**Step 3: Analyze existing codebase** (if token/CSS files found):
- Explore existing design patterns (color palette, typography scale, spacing, component patterns)
**Step 4: Competitive reference** (optional, if industry is not "Other"):
- `WebSearch({ query: "<industry> web design trends best practices" })`
**Step 5: Compile design-intelligence.json**:
| Field | Source |
|-------|--------|
| `_source` | "ui-ux-pro-max-skill" or "llm-general-knowledge" |
| `industry` | Task description |
| `detected_stack` | Phase 2 detection |
| `design_system` | Skill output (colors, typography, effects) |
| `ux_guidelines` | Skill UX domain output |
| `stack_guidelines` | Skill stack output |
| `recommendations` | Synthesized: style, anti-patterns, must-have |
**Output files**:
- `<session>/analysis/design-intelligence.json`
- `<session>/analysis/requirements.md`
## Phase 4: Self-Review
| Check | Method | Pass Criteria |
|-------|--------|---------------|
| JSON validity | Parse design-intelligence.json | No parse errors |
| Required fields | Check _source, industry, design_system | All present |
| Anti-patterns populated | Check recommendations.anti_patterns | Non-empty array |
| Requirements doc exists | File check | requirements.md written |
Update .msg/meta.json: merge `design_intelligence` and `industry_context` keys.

86
.claude/skills/team-frontend/roles/architect/role.md Normal file
View File

@@ -0,0 +1,86 @@
---
role: architect
prefix: ARCH
inner_loop: false
message_types:
success: arch_ready
error: error
---
# Frontend Architect
Consume design-intelligence.json to define design token system, component architecture, and project structure. Token values prioritize ui-ux-pro-max recommendations. Produce architecture artifacts for developer consumption.
## Phase 2: Context Loading
| Input | Source | Required |
|-------|--------|----------|
| Task description | From task subject/description | Yes |
| Session path | Extracted from task description | Yes |
| Scope | Extracted from task description (tokens/components/full) | No (default: full) |
| Design intelligence | <session>/analysis/design-intelligence.json | Yes |
| .msg/meta.json | <session>/.msg/meta.json | No |
1. Extract session path and scope from task description
2. Load design intelligence from analyst output
3. Load .msg/meta.json for shared state (industry_context, design_intelligence)
4. Detect existing project structure via Glob `src/**/*`
**Fail-safe**: If design-intelligence.json not found, use default token values and log warning.
## Phase 3: Architecture Design
**Scope selection**:
| Scope | Output |
|-------|--------|
| `tokens` | Design token system only |
| `components` | Component specs only |
| `full` | Both tokens and components + project structure |
**Step 1: Design Token System** (scope: tokens or full):
Generate `<session>/architecture/design-tokens.json` with categories:
| Category | Content | Source |
|----------|---------|--------|
| `color` | Primary, secondary, background, surface, text, CTA | ui-ux-pro-max |
| `typography` | Font families, font sizes (scale) | ui-ux-pro-max |
| `spacing` | xs through 2xl | Standard scale |
| `border-radius` | sm, md, lg, full | Standard scale |
| `shadow` | sm, md, lg | Standard elevation |
| `transition` | fast, normal, slow | Standard durations |
Use `$type` + `$value` format (Design Tokens Community Group). Support light/dark mode via nested values.
**Step 2: Component Architecture** (scope: components or full):
Generate component specs in `<session>/architecture/component-specs/`:
- Design reference (style, stack)
- Props table (name, type, default, description)
- Variants table
- Accessibility requirements (role, keyboard, ARIA, contrast)
- Anti-patterns to avoid (from design intelligence)
**Step 3: Project Structure** (scope: full):
Generate `<session>/architecture/project-structure.md` with stack-specific layout:
| Stack | Key Directories |
|-------|----------------|
| react | src/components/, src/pages/, src/hooks/, src/styles/ |
| nextjs | app/(routes)/, app/components/, app/lib/, app/styles/ |
| vue | src/components/, src/views/, src/composables/, src/styles/ |
| html-tailwind | src/components/, src/pages/, src/styles/ |
## Phase 4: Self-Review
| Check | Method | Pass Criteria |
|-------|--------|---------------|
| JSON validity | Parse design-tokens.json | No errors |
| Required categories | Check color, typography, spacing | All present |
| Anti-pattern compliance | Token values vs anti-patterns | No violations |
| Component specs complete | Each has props + accessibility | All complete |
| File existence | Verify all planned files | All present |
Update .msg/meta.json: merge `design_token_registry` and `component_inventory` keys.

52
.claude/skills/team-frontend/roles/coordinator/commands/analyze.md Normal file
View File

@@ -0,0 +1,52 @@
# Analyze Task
Parse frontend task -> detect capabilities -> assess pipeline complexity -> design roles.
**CONSTRAINT**: Text-level analysis only. NO source code reading, NO codebase exploration.
## Signal Detection
| Keywords | Capability | Role |
|----------|------------|------|
| analyze, requirements, design intelligence | analyst | analyst |
| design tokens, component architecture, design system | architect | architect |
| implement, build, code, develop, page, component | developer | developer |
| review, audit, quality, test, accessibility | qa | qa |
## Pipeline Selection
| Scope Signal | Pipeline |
|--------------|----------|
| single page, landing, simple | page (4-beat) |
| feature, multi-component, complex | feature (5-beat with arch review gate) |
| full system, design system, multiple pages | system (7-beat dual-track) |
Default to `feature` if ambiguous.
## Complexity Scoring
| Factor | Points |
|--------|--------|
| ui-ux-pro-max integration needed | +1 |
| Existing design system detected | +1 |
| Accessibility strict mode (healthcare/finance) | +2 |
| Multiple tech stacks | +2 |
| Dark mode required | +1 |
Results: 1-2 page, 3-4 feature, 5+ system
## Output
Write <session>/task-analysis.json:
```json
{
"task_description": "<original>",
"pipeline_type": "<page|feature|system>",
"capabilities": [{ "name": "<cap>", "role": "<role>", "keywords": ["..."] }],
"roles": [{ "name": "<role>", "prefix": "<PREFIX>", "inner_loop": false }],
"complexity": { "score": 0, "level": "Low|Medium|High" },
"industry": "<industry>",
"constraints": [],
"needs_ui_ux_pro_max": true
}
```

22
.claude/skills/team-frontend/roles/coordinator/commands/monitor.md
View File

@@ -1,6 +1,24 @@
# Command: Monitor
Handle all coordinator monitoring events: worker callbacks, status checks, pipeline advancement, GC loops, and completion.
Event-driven pipeline coordination. Beat model: coordinator wake -> process -> spawn -> STOP.
## Constants
- SPAWN_MODE: background
- ONE_STEP_PER_INVOCATION: true
- FAST_ADVANCE_AWARE: true
- WORKER_AGENT: team-worker
- MAX_GC_ROUNDS: 2
## Handler Router
| Source | Handler |
|--------|---------|
| Message contains [analyst], [architect], [developer], [qa] | handleCallback |
| "check" or "status" | handleCheck |
| "resume" or "continue" | handleResume |
| All tasks completed | handleComplete |
| Default | handleSpawnNext |
## Phase 2: Context Loading
@@ -111,7 +129,7 @@ Agent({
run_in_background: true,
prompt: `## Role Assignment
role: <role>
role_spec: .claude/skills/team-frontend/role-specs/<role>.md
role_spec: .claude/skills/team-frontend/roles/<role>/role.md
session: <session-folder>
session_id: <session-id>
team_name: frontend

249
.claude/skills/team-frontend/roles/coordinator/role.md
View File

@@ -1,15 +1,14 @@
# Coordinator - Frontend Development Team
# Coordinator Role
**Role**: coordinator
**Type**: Orchestrator
**Team**: frontend
Orchestrate team-frontend: analyze -> dispatch -> spawn -> monitor -> report.
Orchestrates the frontend development pipeline: manages task chains, spawns team-worker agents, handles Generator-Critic loops (developer <-> qa), consulting pattern (developer -> analyst), and drives the pipeline to completion.
## Identity
- Name: coordinator | Tag: [coordinator]
- Responsibility: Analyze task -> Create team -> Dispatch tasks -> Monitor progress -> Report results
## Boundaries
### MUST
- Use `team-worker` agent type for all worker spawns (NOT `general-purpose`)
- Follow Command Execution Protocol for dispatch and monitor commands
- Respect pipeline stage dependencies (blockedBy)
@@ -18,102 +17,47 @@ Orchestrates the frontend development pipeline: manages task chains, spawns team
- Execute completion action in Phase 5
### MUST NOT
- Implement domain logic (analyzing, designing, coding, reviewing) -- workers handle this
- Spawn workers without creating tasks first
- Skip architecture review gate when configured (feature/system modes)
- Force-advance pipeline past failed QA review
- Modify source code directly -- delegate to developer worker
---
## Command Execution Protocol
When coordinator needs to execute a command (dispatch, monitor):
1. **Read the command file**: `roles/coordinator/commands/<command-name>.md`
2. **Follow the workflow** defined in the command file (Phase 2-4 structure)
3. **Commands are inline execution guides** -- NOT separate agents or subprocesses
4. **Execute synchronously** -- complete the command workflow before proceeding
Example:
```
Phase 3 needs task dispatch
-> Read roles/coordinator/commands/dispatch.md
-> Execute Phase 2 (Context Loading)
-> Execute Phase 3 (Task Chain Creation)
-> Execute Phase 4 (Validation)
-> Continue to Phase 4
```
---
When coordinator needs to execute a command:
1. Read `commands/<command>.md`
2. Follow the workflow defined in the command
3. Commands are inline execution guides, NOT separate agents
4. Execute synchronously, complete before proceeding
## Entry Router
When coordinator is invoked, detect invocation type:
| Detection | Condition | Handler |
|-----------|-----------|---------|
| Worker callback | Message contains role tag [analyst], [architect], [developer], [qa] | -> handleCallback |
| Status check | Arguments contain "check" or "status" | -> handleCheck |
| Manual resume | Arguments contain "resume" or "continue" | -> handleResume |
| Pipeline complete | All tasks have status "completed" | -> handleComplete |
| Interrupted session | Active/paused session exists | -> Phase 0 (Resume Check) |
| New session | None of above | -> Phase 1 (Requirement Clarification) |
| Worker callback | Message contains [analyst], [architect], [developer], [qa] | -> handleCallback (monitor.md) |
| Status check | Args contain "check" or "status" | -> handleCheck (monitor.md) |
| Manual resume | Args contain "resume" or "continue" | -> handleResume (monitor.md) |
| Pipeline complete | All tasks completed | -> handleComplete (monitor.md) |
| Interrupted session | Active/paused session in .workflow/.team/FE-* | -> Phase 0 |
| New session | None of above | -> Phase 1 |
For callback/check/resume/complete: load `commands/monitor.md` and execute matched handler, then STOP.
### Router Implementation
1. **Load session context** (if exists):
- Scan `.workflow/.team/FE-*/.msg/meta.json` for active/paused sessions
- If found, extract session folder path, status, and pipeline mode
2. **Parse $ARGUMENTS** for detection keywords:
- Check for role name tags in message content
- Check for "check", "status", "resume", "continue" keywords
3. **Route to handler**:
- For monitor handlers: Read `commands/monitor.md`, execute matched handler, STOP
- For Phase 0: Execute Session Resume Check below
- For Phase 1: Execute Requirement Clarification below
---
For callback/check/resume/complete: load commands/monitor.md, execute handler, STOP.
## Phase 0: Session Resume Check
Triggered when an active/paused session is detected on coordinator entry.
1. Load session.json from detected session folder
2. Audit task list:
```
TaskList()
```
3. Reconcile session state vs task status:
| Task Status | Session Expects | Action |
|-------------|----------------|--------|
| in_progress | Should be running | Reset to pending (worker was interrupted) |
| completed | Already tracked | Skip |
| pending + unblocked | Ready to run | Include in spawn list |
4. Rebuild team if not active:
```
TeamCreate({ team_name: "frontend" })
```
5. Spawn workers for ready tasks -> Phase 4 coordination loop
---
1. Scan `.workflow/.team/FE-*/.msg/meta.json` for active/paused sessions
2. No sessions -> Phase 1
3. Single session -> reconcile (audit TaskList, reset in_progress->pending, rebuild team, kick first ready task)
4. Multiple -> AskUserQuestion for selection
## Phase 1: Requirement Clarification
1. Parse user task description from $ARGUMENTS
TEXT-LEVEL ONLY. No source code reading.
2. Ask for missing parameters via AskUserQuestion:
1. Parse task description from $ARGUMENTS
2. Delegate to commands/analyze.md -> produces task-analysis.json
3. Ask for missing parameters via AskUserQuestion:
**Scope Selection**:
@@ -134,107 +78,50 @@ TeamCreate({ team_name: "frontend" })
**Design Constraints** (multi-select): Existing design system, WCAG AA, Responsive, Dark mode
3. Record requirements: mode, scope, industry, constraints
---
4. Record requirements: mode, scope, industry, constraints
5. CRITICAL: Always proceed to Phase 2, never skip team workflow
## Phase 2: Session & Team Setup
1. Create session directory:
1. Generate session ID: `FE-<slug>-<YYYY-MM-DD>`
2. Create session folder structure:
```
Bash("mkdir -p .workflow/.team/FE-<slug>-<YYYY-MM-DD>/{.msg,wisdom,analysis,architecture,qa,build}")
mkdir -p .workflow/.team/<session-id>/{.msg,wisdom,analysis,architecture,qa,build}
```
2. Write session.json:
```json
{
"status": "active",
"team_name": "frontend",
"requirement": "<requirement>",
"timestamp": "<ISO-8601>",
"pipeline_mode": "<page|feature|system>",
"industry": "<industry>",
"constraints": [],
"gc_rounds": {}
}
```
3. Initialize meta.json with pipeline metadata:
3. TeamCreate with team name: `TeamCreate({ team_name: "frontend" })`
4. Read specs/pipelines.md -> select pipeline based on scope
5. Register roles in session state
6. Initialize meta.json with pipeline metadata:
```typescript
// Use team_msg to write pipeline metadata to .msg/meta.json
mcp__ccw-tools__team_msg({
operation: "log",
session_id: "<session-id>",
from: "coordinator",
type: "state_update",
summary: "Session initialized",
operation: "log", session_id: "<id>", from: "coordinator",
type: "state_update", summary: "Session initialized",
data: {
pipeline_mode: "<page|feature|system>",
pipeline_stages: ["analyst", "architect", "developer", "qa"],
roles: ["coordinator", "analyst", "architect", "developer", "qa"],
team_name: "frontend"
team_name: "frontend",
industry: "<industry>",
constraints: []
}
})
```
4. Create team:
```
TeamCreate({ team_name: "frontend" })
```
---
7. Write session.json
## Phase 3: Task Chain Creation
Execute `commands/dispatch.md` inline (Command Execution Protocol):
Delegate to commands/dispatch.md:
1. Read specs/pipelines.md for selected pipeline task registry
2. Create tasks via TaskCreate with blockedBy
3. Update session.json
1. Read `roles/coordinator/commands/dispatch.md`
2. Follow dispatch Phase 2 (context loading) -> Phase 3 (task chain creation) -> Phase 4 (validation)
3. Result: all pipeline tasks created with correct blockedBy dependencies
## Phase 4: Spawn-and-Stop
---
## Phase 4: Spawn & Coordination Loop
### Initial Spawn
Find first unblocked task and spawn its worker:
```
Agent({
subagent_type: "team-worker",
description: "Spawn analyst worker",
team_name: "frontend",
name: "analyst",
run_in_background: true,
prompt: `## Role Assignment
role: analyst
role_spec: .claude/skills/team-frontend/role-specs/analyst.md
session: <session-folder>
session_id: <session-id>
team_name: frontend
requirement: <requirement>
inner_loop: false
Read role_spec file to load Phase 2-4 domain instructions.
Execute built-in Phase 1 -> role-spec Phase 2-4 -> built-in Phase 5.`
})
```
**STOP** after spawning. Wait for worker callback.
### Coordination (via monitor.md handlers)
All subsequent coordination is handled by `commands/monitor.md` handlers triggered by worker callbacks:
- handleCallback -> mark task done -> check pipeline -> handleSpawnNext
- handleSpawnNext -> find ready tasks -> spawn team-worker agents -> STOP
- handleComplete -> all done -> Phase 5
---
Delegate to commands/monitor.md#handleSpawnNext:
1. Find ready tasks (pending + blockedBy resolved)
2. Spawn team-worker agents (see SKILL.md Spawn Template)
3. Output status summary
4. STOP
## Phase 5: Report + Completion Action
@@ -251,28 +138,18 @@ All subsequent coordination is handled by `commands/monitor.md` handlers trigger
| QA Audits | <session>/qa/audit-*.md |
3. Output pipeline summary: task count, duration, QA scores
4. Execute completion action per session.completion_action:
- interactive -> AskUserQuestion (Archive/Keep/Export)
- auto_archive -> Archive & Clean (status=completed, TeamDelete)
- auto_keep -> Keep Active (status=paused)
4. **Completion Action** (interactive):
## Error Handling
```
AskUserQuestion({
questions: [{
question: "Team pipeline complete. What would you like to do?",
header: "Completion",
multiSelect: false,
options: [
{ label: "Archive & Clean (Recommended)", description: "Archive session, clean up tasks and team resources" },
{ label: "Keep Active", description: "Keep session active for follow-up work or inspection" },
{ label: "Export Results", description: "Export deliverables to a specified location, then clean" }
]
}]
})
```
5. Handle user choice:
| Choice | Steps |
|--------|-------|
| Archive & Clean | TaskList -> verify all completed -> update session status="completed" -> TeamDelete() -> output final summary |
| Keep Active | Update session status="paused" -> output: "Session paused. Resume with: Skill(skill='team-frontend', args='resume')" |
| Export Results | AskUserQuestion for target directory -> copy artifacts -> Archive & Clean flow |
| Error | Resolution |
|-------|------------|
| Task too vague | AskUserQuestion for clarification |
| Session corruption | Attempt recovery, fallback to manual |
| Worker crash | Reset task to pending, respawn |
| Dependency cycle | Detect in analysis, halt |
| QA score < 6 over 2 GC rounds | Escalate to user |
| ui-ux-pro-max unavailable | Degrade to LLM general design knowledge |

93
.claude/skills/team-frontend/roles/developer/role.md Normal file
View File

@@ -0,0 +1,93 @@
---
role: developer
prefix: DEV
inner_loop: true
message_types:
success: dev_complete
error: error
---
# Frontend Developer
Consume architecture artifacts (design tokens, component specs, project structure) to implement frontend code. Reference design-intelligence.json for implementation checklist, tech stack guidelines, and anti-pattern constraints.
## Phase 2: Context Loading
| Input | Source | Required |
|-------|--------|----------|
| Task description | From task subject/description | Yes |
| Session path | Extracted from task description | Yes |
| Scope | Extracted from task description (tokens/components/full) | No (default: full) |
| Design intelligence | <session>/analysis/design-intelligence.json | No |
| Design tokens | <session>/architecture/design-tokens.json | Yes |
| Component specs | <session>/architecture/component-specs/*.md | No |
| Project structure | <session>/architecture/project-structure.md | No |
| .msg/meta.json | <session>/.msg/meta.json | No |
1. Extract session path and scope from task description
2. Load design tokens (required -- if missing, report to coordinator)
3. Load design intelligence for anti-patterns and guidelines
4. Load component specs and project structure
5. Detect tech stack from design intelligence `detected_stack`
6. Load .msg/meta.json for shared state
## Phase 3: Code Implementation
**Scope selection**:
| Scope | Output |
|-------|--------|
| `tokens` | CSS custom properties from design tokens |
| `components` | Component code from specs |
| `full` | Both token CSS and components |
**Step 1: Generate Design Token CSS** (scope: tokens or full):
Convert design-tokens.json to `src/styles/tokens.css`:
| JSON Category | CSS Variable Prefix |
|---------------|---------------------|
| color | `--color-` |
| typography.font-family | `--font-` |
| typography.font-size | `--text-` |
| spacing | `--space-` |
| border-radius | `--radius-` |
| shadow | `--shadow-` |
| transition | `--duration-` |
Add `@media (prefers-color-scheme: dark)` override for color tokens.
**Step 2: Implement Components** (scope: components or full):
Implementation strategy by complexity:
| Condition | Strategy |
|-----------|----------|
| <= 2 components | Direct inline Edit/Write |
| 3-5 components | Single batch implementation |
| > 5 components | Group by module, implement per batch |
**Coding standards** (mandatory):
- Use design token CSS variables -- never hardcode colors/spacing
- All interactive elements: `cursor: pointer`
- Transitions: 150-300ms via `var(--duration-normal)`
- Text contrast: minimum 4.5:1 ratio
- Include `focus-visible` styles for keyboard navigation
- Support `prefers-reduced-motion`
- Responsive: mobile-first with md/lg breakpoints
- No emoji as functional icons
## Phase 4: Self-Review
| Check | Method | Pass Criteria |
|-------|--------|---------------|
| Hardcoded colors | Scan for hex codes outside tokens.css | None found |
| cursor-pointer | Check buttons/links | All have cursor-pointer |
| Focus styles | Check interactive elements | All have focus styles |
| Responsive | Check for breakpoints | Breakpoints present |
| File existence | Verify all planned files | All present |
| Import resolution | Check no broken imports | All imports resolve |
Auto-fix where possible: add missing cursor-pointer, basic focus styles.
Update .msg/meta.json: merge `component_inventory` key with implemented file list.

79
.claude/skills/team-frontend/roles/qa/role.md Normal file
View File

@@ -0,0 +1,79 @@
---
role: qa
prefix: QA
inner_loop: false
message_types:
success: qa_passed
error: error
---
# QA Engineer
Execute 5-dimension quality audit integrating ux-guidelines Do/Don't rules, pre-delivery checklist, and industry anti-pattern library. Perform CSS-level precise review on architecture artifacts and implementation code.
## Phase 2: Context Loading
| Input | Source | Required |
|-------|--------|----------|
| Task description | From task subject/description | Yes |
| Session path | Extracted from task description | Yes |
| Review type | Extracted from task description | No (default: code-review) |
| Design intelligence | <session>/analysis/design-intelligence.json | No |
| Design tokens | <session>/architecture/design-tokens.json | No |
| .msg/meta.json | <session>/.msg/meta.json | No |
1. Extract session path and review type from task description
2. Load design intelligence (for anti-patterns, must-have rules)
3. Load design tokens (for compliance checks)
4. Load .msg/meta.json (for industry context, strictness level)
5. Collect files to review based on review type:
| Type | Files to Review |
|------|-----------------|
| architecture-review | `<session>/architecture/**/*` |
| token-review | `<session>/architecture/**/*` |
| code-review | `src/**/*.{tsx,jsx,vue,svelte,html,css}` |
| final | `src/**/*.{tsx,jsx,vue,svelte,html,css}` |
## Phase 3: 5-Dimension Audit
| Dimension | Weight | Focus |
|-----------|--------|-------|
| Code Quality | 0.20 | Structure, naming, maintainability |
| Accessibility | 0.25 | WCAG compliance, keyboard nav, screen reader |
| Design Compliance | 0.20 | Anti-pattern check, design token usage |
| UX Best Practices | 0.20 | Interaction patterns, responsive, animations |
| Pre-Delivery | 0.15 | Final checklist (code-review/final types only) |
**Dimension 1 -- Code Quality**: File length (>300 LOC), console.log, empty catch, unused imports.
**Dimension 2 -- Accessibility**: Image alt text, input labels, button text, heading hierarchy, focus styles, ARIA roles. Strict mode (medical/financial): prefers-reduced-motion required.
**Dimension 3 -- Design Compliance**: Hardcoded colors (must use `var(--color-*)`), hardcoded spacing, industry anti-patterns from design intelligence.
**Dimension 4 -- UX Best Practices**: cursor-pointer on clickable, transition 150-300ms, responsive design, loading states, error states.
**Dimension 5 -- Pre-Delivery** (final/code-review only): No emoji icons, cursor-pointer, transitions, focus states, reduced-motion, responsive, no hardcoded colors, dark mode support.
**Score calculation**: `score = sum(dimension_score * weight)`
**Verdict**:
| Condition | Verdict | Message Type |
|-----------|---------|-------------|
| score >= 8 AND critical == 0 | PASSED | `qa_passed` |
| score >= 6 AND critical == 0 | PASSED_WITH_WARNINGS | `qa_result` |
| score < 6 OR critical > 0 | FIX_REQUIRED | `fix_required` |
## Phase 4: Self-Review
| Check | Method | Pass Criteria |
|-------|--------|---------------|
| All dimensions scored | Check 5 dimension scores | All present |
| Audit report written | File check | audit-NNN.md exists |
| Verdict determined | Score calculated | Verdict assigned |
| Issues categorized | Severity labels | All issues have severity |
Write audit report to `<session>/qa/audit-<NNN>.md` with: summary, dimension scores, issues by severity, passed dimensions.
Update .msg/meta.json: append to `qa_history` array.

76
.claude/skills/team-frontend/specs/pipelines.md Normal file
View File

@@ -0,0 +1,76 @@
# Frontend Pipeline Definitions
## Pipeline Modes
### Page Mode (4 beats, linear)
```
ANALYZE-001 --> ARCH-001 --> DEV-001 --> QA-001
[analyst] [architect] [developer] [qa]
```
### Feature Mode (5 beats, with architecture review gate)
```
ANALYZE-001 --> ARCH-001 --> QA-001 --> DEV-001 --> QA-002
[analyst] [architect] [qa:arch] [developer] [qa:code]
```
### System Mode (7 beats, dual-track parallel)
```
ANALYZE-001 --> ARCH-001 --> QA-001 --> ARCH-002 ─┐
[analyst] [architect] [qa:arch] [architect] |
DEV-001 ──┘ --> QA-002 --> DEV-002 --> QA-003
[developer:tokens] [qa] [developer] [qa:final]
```
### Generator-Critic Loop (developer <-> qa)
```
developer (Generator) -> QA artifact -> qa (Critic)
<- QA feedback <-
(max 2 rounds)
Convergence: qa.score >= 8 && qa.critical_count === 0
```
## Task Metadata Registry
| Task ID | Role | Pipeline | Dependencies | Description |
|---------|------|----------|-------------|-------------|
| ANALYZE-001 | analyst | all | (none) | Requirement analysis + design intelligence |
| ARCH-001 | architect | all | ANALYZE-001 | Design token system + component architecture |
| ARCH-002 | architect | system | QA-001 | Component specs refinement |
| DEV-001 | developer | all | ARCH-001 or QA-001 | Frontend implementation |
| DEV-002 | developer | system | QA-002 | Component implementation |
| DEV-fix-N | developer | all | QA-N (GC loop trigger) | Fix issues from QA |
| QA-001 | qa | all | ARCH-001 or DEV-001 | Architecture or code review |
| QA-002 | qa | feature/system | DEV-001 | Code review |
| QA-003 | qa | system | DEV-002 | Final quality check |
| QA-recheck-N | qa | all | DEV-fix-N | Re-audit after developer fixes |
## Pipeline Selection Logic
| Score | Pipeline |
|-------|----------|
| 1-2 | page |
| 3-4 | feature |
| 5+ | system |
Default: feature.
## ui-ux-pro-max Integration
Analyst role invokes ui-ux-pro-max via Skill to obtain industry design intelligence:
| Action | Invocation |
|--------|------------|
| Full design system | `Skill(skill="ui-ux-pro-max", args="<industry> <keywords> --design-system")` |
| Domain search | `Skill(skill="ui-ux-pro-max", args="<query> --domain <domain>")` |
| Tech stack guidance | `Skill(skill="ui-ux-pro-max", args="<query> --stack <stack>")` |
**Supported Domains**: product, style, typography, color, landing, chart, ux, web
**Supported Stacks**: html-tailwind, react, nextjs, vue, svelte, shadcn, swiftui, react-native, flutter
**Fallback**: If ui-ux-pro-max skill not installed, degrade to LLM general design knowledge.

406
.claude/skills/team-issue/SKILL.md
View File

@@ -1,304 +1,62 @@
---
name: team-issue
description: Unified team skill for issue resolution. All roles invoke this skill with --role arg for role-specific execution. Triggers on "team issue".
description: Unified team skill for issue resolution. Uses team-worker agent architecture with role directories for domain logic. Coordinator orchestrates pipeline, workers are team-worker agents. Triggers on "team issue".
allowed-tools: TeamCreate(*), TeamDelete(*), SendMessage(*), TaskCreate(*), TaskUpdate(*), TaskList(*), TaskGet(*), Agent(*), AskUserQuestion(*), Read(*), Write(*), Edit(*), Bash(*), Glob(*), Grep(*), mcp__ace-tool__search_context(*), mcp__ccw-tools__team_msg(*)
---
# Team Issue Resolution
Unified team skill: issue processing pipeline (explore → plan → implement → review → integrate). All team members invoke with `--role=xxx` to route to role-specific execution.
**Scope**: Issue processing flow (plan → queue → execute). Issue creation/discovery handled by `issue-discover`, CRUD management by `issue-manage`.
Orchestrate issue resolution pipeline: explore context -> plan solution -> review (optional) -> marshal queue -> implement. Supports Quick, Full, and Batch pipelines with review-fix cycle.
## Architecture
```
+---------------------------------------------------+
| Skill(skill="team-issue") |
| args="<issue-ids>" |
+-------------------+-------------------------------+
Skill(skill="team-issue", args="<issue-ids> [--mode=<mode>]")
|
Orchestration Mode (auto -> coordinator)
SKILL.md (this file) = Router
|
Coordinator (inline)
Phase 0-5 orchestration
+--------------+--------------+
| |
no --role flag --role <name>
| |
Coordinator Worker
roles/coordinator/role.md roles/<name>/role.md
|
+-----+-----+-----+-----+-----+
+-- clarify -> dispatch -> spawn workers -> STOP
|
+-------+-------+-------+-------+
v v v v v
[tw] [tw] [tw] [tw] [tw]
explor plann review integ- imple-
er er er rator menter
(tw) = team-worker agent
[explor] [plann] [review] [integ] [imple]
```
## Role Registry
| Role | Path | Prefix | Inner Loop |
|------|------|--------|------------|
| coordinator | [roles/coordinator/role.md](roles/coordinator/role.md) | — | — |
| explorer | [roles/explorer/role.md](roles/explorer/role.md) | EXPLORE-* | false |
| planner | [roles/planner/role.md](roles/planner/role.md) | SOLVE-* | false |
| reviewer | [roles/reviewer/role.md](roles/reviewer/role.md) | AUDIT-* | false |
| integrator | [roles/integrator/role.md](roles/integrator/role.md) | MARSHAL-* | false |
| implementer | [roles/implementer/role.md](roles/implementer/role.md) | BUILD-* | false |
## Role Router
### Input Parsing
Parse `$ARGUMENTS`:
- Has `--role <name>` → Read `roles/<name>/role.md`, execute Phase 2-4
- No `--role` → Read `roles/coordinator/role.md`, execute entry router
Parse `$ARGUMENTS` to extract `--role`. If absent → Orchestration Mode (auto route to coordinator). Extract issue IDs and `--mode` from remaining arguments.
## Shared Constants
### Role Registry
- **Session prefix**: `TISL`
- **Session path**: `.workflow/.team/TISL-<slug>-<date>/`
- **Team name**: `issue`
- **CLI tools**: `ccw cli --mode analysis` (read-only), `ccw cli --mode write` (modifications)
- **Message bus**: `mcp__ccw-tools__team_msg(session_id=<session-id>, ...)`
| Role | Spec | Task Prefix | Inner Loop |
|------|------|-------------|------------|
| coordinator | [roles/coordinator/role.md](roles/coordinator/role.md) | (none) | - |
| explorer | [role-specs/explorer.md](role-specs/explorer.md) | EXPLORE-* | false |
| planner | [role-specs/planner.md](role-specs/planner.md) | SOLVE-* | false |
| reviewer | [role-specs/reviewer.md](role-specs/reviewer.md) | AUDIT-* | false |
| integrator | [role-specs/integrator.md](role-specs/integrator.md) | MARSHAL-* | false |
| implementer | [role-specs/implementer.md](role-specs/implementer.md) | BUILD-* | false |
## Worker Spawn Template
> **⚠️ COMPACT PROTECTION**: 角色文件是执行文档，不是参考资料。当 context compression 发生后，角色指令仅剩摘要时，**必须立即 `Read` 对应 role.md 重新加载后再继续执行**。不得基于摘要执行任何 Phase。
### Dispatch
1. Extract `--role` from arguments
2. If no `--role` → route to coordinator (Orchestration Mode)
3. Look up role in registry → Read the role file → Execute its phases
### Orchestration Mode
When invoked without `--role`, coordinator auto-starts. User provides issue IDs and optional mode.
**Invocation**: `Skill(skill="team-issue", args="<issue-ids> [--mode=<mode>]")`
**Lifecycle**:
```
User provides issue IDs
→ coordinator Phase 1-3: Mode detection → TeamCreate → Create task chain
→ coordinator Phase 4: spawn first batch workers (background) → STOP
→ Worker executes → SendMessage callback → coordinator advances next step
→ Loop until pipeline complete → Phase 5 report
```
**User Commands** (wake paused coordinator):
| Command | Action |
|---------|--------|
| `check` / `status` | Output execution status graph, no advancement |
| `resume` / `continue` | Check worker states, advance next step |
---
## Shared Infrastructure
The following templates apply to all worker roles. Each role.md only needs to write **Phase 2-4** role-specific logic.
### Worker Phase 1: Task Discovery (shared by all workers)
Every worker executes the same task discovery flow on startup:
1. Call `TaskList()` to get all tasks
2. Filter: subject matches this role's prefix + owner is this role + status is pending + blockedBy is empty
3. No tasks → idle wait
4. Has tasks → `TaskGet` for details → `TaskUpdate` mark in_progress
**Resume Artifact Check** (prevent duplicate output after resume):
- Check whether this task's output artifact already exists
- Artifact complete → skip to Phase 5 report completion
- Artifact incomplete or missing → normal Phase 2-4 execution
### Worker Phase 5: Report (shared by all workers)
Standard reporting flow after task completion:
1. **Message Bus**: Call `mcp__ccw-tools__team_msg` to log message
- Parameters: operation="log", session_id=<session-id>, from=<role>, type=<message-type>, data={ref: "<artifact-path>"}
- `to` and `summary` auto-defaulted -- do NOT specify explicitly
- **CLI fallback**: `ccw team log --session-id <session-id> --from <role> --type <type> --json`
2. **SendMessage**: Send result to coordinator
3. **TaskUpdate**: Mark task completed
4. **Loop**: Return to Phase 1 to check next task
### Wisdom Accumulation (all roles)
Cross-task knowledge accumulation. Coordinator creates `wisdom/` directory at session initialization.
**Directory**:
```
<session-folder>/wisdom/
├── learnings.md # Patterns and insights
├── decisions.md # Architecture and design decisions
├── conventions.md # Codebase conventions
└── issues.md # Known risks and issues
```
**Worker Load** (Phase 2): Extract `Session: <path>` from task description, read wisdom directory files.
**Worker Contribute** (Phase 4/5): Write this task's discoveries to corresponding wisdom files.
### Role Isolation Rules
| Allowed | Forbidden |
|---------|-----------|
| Process tasks with own prefix | Process tasks with other role prefixes |
| SendMessage to coordinator | Communicate directly with other workers |
| Use tools declared in Toolbox | Create tasks for other roles |
| Delegate to reused agents | Modify resources outside own responsibility |
Coordinator additional restrictions: Do not write/modify code directly, do not execute analysis/review directly. Team members use CLI tools for analysis/implementation tasks.
### Output Tagging
All outputs must carry `[role_name]` prefix in both SendMessage content/summary and team_msg summary.
### Message Bus (All Roles)
Every SendMessage **before**, must call `mcp__ccw-tools__team_msg` to log:
**Parameters**: operation="log", session_id=<session-id>, from=<role>, type=<message-type>, data={ref: "<artifact-path>"}
`to` and `summary` auto-defaulted -- do NOT specify explicitly.
**CLI fallback**: `ccw team log --session-id <session-id> --from <role> --type <type> --json`
**Message types by role**:
| Role | Types |
|------|-------|
| coordinator | `task_assigned`, `pipeline_update`, `escalation`, `shutdown`, `error` |
| explorer | `context_ready`, `impact_assessed`, `error` |
| planner | `solution_ready`, `multi_solution`, `error` |
| reviewer | `approved`, `rejected`, `concerns`, `error` |
| integrator | `queue_ready`, `conflict_found`, `error` |
| implementer | `impl_complete`, `impl_failed`, `error` |
### Team Configuration
| Setting | Value |
|---------|-------|
| Team name | issue |
| Session directory | `.workflow/.team-plan/issue/` |
| Issue data directory | `.workflow/issues/` |
---
## Pipeline Modes
```
Quick Mode (1-2 simple issues):
EXPLORE-001 → SOLVE-001 → MARSHAL-001 → BUILD-001
Full Mode (complex issues, with review):
EXPLORE-001 → SOLVE-001 → AUDIT-001 ─┬─(approved)→ MARSHAL-001 → BUILD-001..N(parallel)
└─(rejected)→ SOLVE-fix → AUDIT-002(re-review, max 2x)
Batch Mode (5-100 issues):
EXPLORE-001..N(batch<=5) → SOLVE-001..N(batch<=3) → AUDIT-001(batch) → MARSHAL-001 → BUILD-001..M(DAG parallel)
```
### Mode Auto-Detection
When user does not specify `--mode`, auto-detect based on issue count and complexity:
| Condition | Mode | Description |
|-----------|------|-------------|
| User explicitly specifies `--mode=<M>` | Use specified mode | User override takes priority |
| Issue count <= 2 AND no high-priority issues (priority < 4) | `quick` | Simple issues, skip review step |
| Issue count <= 2 AND has high-priority issues (priority >= 4) | `full` | Complex issues need review gate |
| Issue count > 2 | `batch` | Multiple issues, parallel exploration and implementation |
### Review Gate (Full/Batch modes)
| AUDIT Verdict | Action |
|---------------|--------|
| approved | Proceed to MARSHAL → BUILD |
| rejected (round < 2) | Create SOLVE-fix task → AUDIT re-review |
| rejected (round >= 2) | Force proceed with warnings, report to user |
### Cadence Control
**Beat model**: Event-driven, each beat = coordinator wake → process → spawn → STOP. Issue beat: explore → plan → implement → review → integrate.
```
Beat Cycle (single beat)
═══════════════════════════════════════════════════════════
Event Coordinator Workers
───────────────────────────────────────────────────────────
callback/resume ──→ ┌─ handleCallback ─┐
│ mark completed │
│ check pipeline │
├─ handleSpawnNext ─┤
│ find ready tasks │
│ spawn workers ───┼──→ [Worker A] Phase 1-5
│ (parallel OK) ──┼──→ [Worker B] Phase 1-5
└─ STOP (idle) ─────┘ │
│
callback ←─────────────────────────────────────────┘
(next beat) SendMessage + TaskUpdate(completed)
═══════════════════════════════════════════════════════════
```
**Pipeline beat views**:
```
Quick Mode (4 beats, strictly serial)
──────────────────────────────────────────────────────────
Beat 1 2 3 4
│ │ │ │
EXPLORE → SOLVE → MARSHAL ──→ BUILD
▲ ▲
pipeline pipeline
start done
EXPLORE=explorer SOLVE=planner MARSHAL=integrator BUILD=implementer
Full Mode (5-7 beats, with review gate)
──────────────────────────────────────────────────────────
Beat 1 2 3 4 5
│ │ │ │ │
EXPLORE → SOLVE → AUDIT ─┬─(ok)→ MARSHAL → BUILD
│
(rejected?)
SOLVE-fix → AUDIT-2 → MARSHAL → BUILD
Batch Mode (parallel windows)
──────────────────────────────────────────────────────────
Beat 1 2 3 4 5
┌────┴────┐ ┌────┴────┐ │ │ ┌────┴────┐
EXP-1..N → SOLVE-1..N → AUDIT → MARSHAL → BUILD-1..M
▲ ▲
parallel DAG parallel
window (<=5) window (<=3)
```
**Checkpoints**:
| Trigger | Location | Behavior |
|---------|----------|----------|
| Review gate | After AUDIT-* | If approved → MARSHAL; if rejected → SOLVE-fix (max 2 rounds) |
| Review loop limit | AUDIT round >= 2 | Force proceed with warnings |
| Pipeline stall | No ready + no running | Check missing tasks, report to user |
**Stall Detection** (coordinator `handleCheck` executes):
| Check | Condition | Resolution |
|-------|-----------|------------|
| Worker no response | in_progress task no callback | Report waiting task list, suggest user `resume` |
| Pipeline deadlock | no ready + no running + has pending | Check blockedBy dependency chain, report blocking point |
| Review loop exceeded | AUDIT rejection > 2 rounds | Terminate loop, force proceed with current solution |
### Task Metadata Registry
| Task ID | Role | Phase | Dependencies | Description |
|---------|------|-------|-------------|-------------|
| EXPLORE-001 | explorer | explore | (none) | Context analysis and impact assessment |
| EXPLORE-002..N | explorer | explore | (none) | Parallel exploration (Batch mode only) |
| SOLVE-001 | planner | plan | EXPLORE-001 (or all EXPLORE-*) | Solution design and task decomposition |
| SOLVE-002..N | planner | plan | EXPLORE-* | Parallel solution design (Batch mode only) |
| AUDIT-001 | reviewer | review | SOLVE-001 (or all SOLVE-*) | Technical feasibility and risk review |
| MARSHAL-001 | integrator | integrate | AUDIT-001 (or last SOLVE-*) | Conflict detection and queue orchestration |
| BUILD-001 | implementer | implement | MARSHAL-001 | Code implementation and result submission |
| BUILD-002..M | implementer | implement | MARSHAL-001 | Parallel implementation (Batch DAG parallel) |
---
## Coordinator Spawn Template
### v5 Worker Spawn (all roles)
When coordinator spawns workers, use `team-worker` agent with role-spec path:
Coordinator spawns workers using this template:
```
Agent({
@@ -309,7 +67,7 @@ Agent({
run_in_background: true,
prompt: `## Role Assignment
role: <role>
role_spec: .claude/skills/team-issue/role-specs/<role>.md
role_spec: .claude/skills/team-issue/roles/<role>/role.md
session: <session-folder>
session_id: <session-id>
team_name: issue
@@ -317,42 +75,21 @@ requirement: <task-description>
inner_loop: false
Read role_spec file to load Phase 2-4 domain instructions.
Execute built-in Phase 1 (task discovery) -> role-spec Phase 2-4 -> built-in Phase 5 (report).`
Execute built-in Phase 1 (task discovery) -> role Phase 2-4 -> built-in Phase 5 (report).`
})
```
**All roles** (explorer, planner, reviewer, integrator, implementer): Set `inner_loop: false`.
### Parallel Spawn (Batch Mode)
> When Batch mode has parallel tasks assigned to the same role, spawn N distinct team-worker agents with unique names.
**Explorer parallel spawn** (Batch mode, N issues):
| Condition | Action |
|-----------|--------|
| Batch mode with N issues (N > 1) | Spawn min(N, 5) team-worker agents: `explorer-1`, `explorer-2`, ... with `run_in_background: true` |
| Quick/Full mode (single explorer) | Standard spawn: single `explorer` team-worker agent |
**Implementer parallel spawn** (Batch mode, M BUILD tasks):
| Condition | Action |
|-----------|--------|
| Batch mode with M BUILD tasks (M > 2) | Spawn min(M, 3) team-worker agents: `implementer-1`, `implementer-2`, ... with `run_in_background: true` |
| Quick/Full mode (single implementer) | Standard spawn: single `implementer` team-worker agent |
**Parallel spawn template**:
**Parallel spawn** (Batch mode, N explorer or M implementer instances):
```
Agent({
subagent_type: "team-worker",
description: "Spawn <role>-<N> worker",
team_name: "issue",
name: "<role>-<N>",
team_name: "issue",
run_in_background: true,
prompt: `## Role Assignment
role: <role>
role_spec: .claude/skills/team-issue/role-specs/<role>.md
role_spec: .claude/skills/team-issue/roles/<role>/role.md
session: <session-folder>
session_id: <session-id>
team_name: issue
@@ -361,45 +98,23 @@ agent_name: <role>-<N>
inner_loop: false
Read role_spec file to load Phase 2-4 domain instructions.
Execute built-in Phase 1 (task discovery, owner=<role>-<N>) -> role-spec Phase 2-4 -> built-in Phase 5 (report).`
Execute built-in Phase 1 (task discovery, owner=<role>-<N>) -> role Phase 2-4 -> built-in Phase 5 (report).`
})
```
**Dispatch must match agent names**: When dispatching parallel tasks, coordinator sets each task's owner to the corresponding instance name (`explorer-1`, `explorer-2`, etc. or `implementer-1`, `implementer-2`, etc.).
## User Commands
---
## Completion Action
When the pipeline completes (all tasks done, coordinator Phase 5):
```
AskUserQuestion({
questions: [{
question: "Issue resolution pipeline complete. What would you like to do?",
header: "Completion",
multiSelect: false,
options: [
{ label: "Archive & Clean (Recommended)", description: "Archive session, clean up tasks and team resources" },
{ label: "Keep Active", description: "Keep session active for follow-up work or inspection" },
{ label: "Export Results", description: "Export deliverables to a specified location, then clean" }
]
}]
})
```
| Choice | Action |
|--------|--------|
| Archive & Clean | Update session status="completed" -> TeamDelete() -> output final summary |
| Keep Active | Update session status="paused" -> output resume instructions: `Skill(skill="team-issue", args="resume")` |
| Export Results | AskUserQuestion for target path -> copy deliverables -> Archive & Clean |
---
| Command | Action |
|---------|--------|
| `check` / `status` | View execution status graph, no advancement |
| `resume` / `continue` | Check worker states, advance next step |
## Session Directory
```
.workflow/.team-plan/issue/
.workflow/.team/TISL-<slug>-<date>/
├── session.json # Session metadata + pipeline + fix_cycles
├── task-analysis.json # Coordinator analyze output
├── .msg/
│ ├── messages.jsonl # Message bus log
│ └── meta.json # Session state + cross-role state
@@ -409,19 +124,28 @@ AskUserQuestion({
│ ├── conventions.md
│ └── issues.md
├── explorations/ # Explorer output
│ └── context-<issueId>.json
├── solutions/ # Planner output
│ └── solution-<issueId>.json
├── audits/ # Reviewer output
├── queue/ # Integrator output
│ └── audit-report.json
├── queue/ # Integrator output (also .workflow/issues/queue/)
└── builds/ # Implementer output
```
## Specs Reference
- [specs/pipelines.md](specs/pipelines.md) — Pipeline definitions and task registry
## Error Handling
| Scenario | Resolution |
|----------|------------|
| Unknown --role value | Error with available role list |
| Missing --role arg | Orchestration Mode → auto route to coordinator |
| Role file not found | Error with expected path (roles/<name>.md) |
| Task prefix conflict | Log warning, proceed |
| Review rejection exceeds 2 rounds | Force proceed with warnings |
| Unknown command | Error with available command list |
| Role not found | Error with role registry |
| CLI tool fails | Worker fallback to direct implementation |
| Fast-advance conflict | Coordinator reconciles on next callback |
| Completion action fails | Default to Keep Active |
| Review rejection exceeds 2 rounds | Force convergence to integrator |
| No issues found for given IDs | Coordinator reports error to user |
| Deferred BUILD count unknown | Defer to MARSHAL callback |

64
.claude/skills/team-issue/roles/coordinator/commands/analyze.md Normal file
View File

@@ -0,0 +1,64 @@
# Analyze Task
Parse user issue description -> detect required capabilities -> assess complexity -> select pipeline mode.
**CONSTRAINT**: Text-level analysis only. NO source code reading, NO codebase exploration.
## Signal Detection
| Keywords | Capability | Prefix |
|----------|------------|--------|
| explore, analyze, context, impact, understand | explorer | EXPLORE |
| plan, solve, design, solution, approach | planner | SOLVE |
| review, audit, validate, feasibility | reviewer | AUDIT |
| marshal, integrate, queue, conflict, order | integrator | MARSHAL |
| build, implement, execute, code, develop | implementer | BUILD |
## Dependency Graph
Natural ordering tiers:
- Tier 0: explorer (context analysis — no dependencies)
- Tier 1: planner (requires explorer output)
- Tier 2: reviewer (requires planner output, full/batch modes only)
- Tier 3: integrator (requires reviewer or planner output)
- Tier 4: implementer (requires integrator output)
## Complexity Scoring
| Factor | Points |
|--------|--------|
| Issue count > 2 | +3 |
| Issue count > 4 | +2 more |
| Any high-priority issue (priority >= 4) | +2 |
| Multiple issue types / cross-cutting | +2 |
| Simple / single issue | -2 |
Results:
- 0-2: Low -> quick (4 tasks: EXPLORE → SOLVE → MARSHAL → BUILD)
- 3-4: Medium -> full (5 tasks: EXPLORE → SOLVE → AUDIT → MARSHAL → BUILD)
- 5+: High -> batch (N+N+1+1+M tasks, parallel exploration and implementation)
## Pipeline Selection
| Complexity | Pipeline | Tasks |
|------------|----------|-------|
| Low | quick | EXPLORE → SOLVE → MARSHAL → BUILD |
| Medium | full | EXPLORE → SOLVE → AUDIT → MARSHAL → BUILD |
| High | batch | EXPLORE-001..N (parallel) → SOLVE-001..N → AUDIT → MARSHAL → BUILD-001..M (parallel) |
## Output
Write <session>/task-analysis.json:
```json
{
"task_description": "<original>",
"pipeline_type": "<quick|full|batch>",
"issue_ids": ["<id1>", "<id2>"],
"capabilities": [{ "name": "<cap>", "prefix": "<PREFIX>", "keywords": ["..."] }],
"dependency_graph": { "<TASK-ID>": { "role": "<role>", "blockedBy": ["..."], "priority": "P0|P1|P2" } },
"roles": [{ "name": "<role>", "prefix": "<PREFIX>", "inner_loop": false }],
"complexity": { "score": 0, "level": "Low|Medium|High" },
"parallel_explorers": 1,
"parallel_builders": 1
}
```

54
.claude/skills/team-issue/roles/coordinator/commands/dispatch.md
View File

@@ -1,8 +1,8 @@
# Command: Dispatch
# Dispatch
Create the issue resolution task chain with correct dependencies and structured task descriptions based on selected pipeline mode.
## Phase 2: Context Loading
## Context Loading
| Input | Source | Required |
|-------|--------|----------|
@@ -16,9 +16,7 @@ Create the issue resolution task chain with correct dependencies and structured
1. Load requirement, pipeline mode, issue IDs, and execution method from session.json
2. Determine task chain from pipeline mode
## Phase 3: Task Chain Creation
### Task Description Template
## Task Description Template
Every task description uses structured format:
@@ -44,13 +42,13 @@ code_review: <setting>"
TaskUpdate({ taskId: "<TASK-ID>", addBlockedBy: [<dependency-list>], owner: "<role>" })
```
### Pipeline Router
## Pipeline Router
| Mode | Action |
|------|--------|
| quick | Create 4 tasks (EXPLORE -> SOLVE -> MARSHAL -> BUILD) |
| full | Create 5 tasks (EXPLORE -> SOLVE -> AUDIT -> MARSHAL -> BUILD) |
| batch | Create N+N+1+1+M tasks (EXPLORE-001..N -> SOLVE-001..N -> AUDIT-001 -> MARSHAL-001 -> BUILD-001..M) |
| quick | Create 4 tasks (EXPLORE → SOLVE → MARSHAL → BUILD) |
| full | Create 5 tasks (EXPLORE → SOLVE → AUDIT → MARSHAL → BUILD) |
| batch | Create N+N+1+1+M tasks (EXPLORE-001..N → SOLVE-001..N → AUDIT-001 → MARSHAL-001 → BUILD-001..M) |
---
@@ -83,7 +81,7 @@ TaskCreate({
description: "PURPOSE: Design solution and decompose into implementation tasks | Success: Bound solution with task decomposition
TASK:
- Load explorer context report
- Generate solution plan via issue-plan-agent
- Generate solution plan via CLI
- Bind solution to issue
CONTEXT:
- Session: <session-folder>
@@ -125,7 +123,7 @@ TaskCreate({
description: "PURPOSE: Implement solution plan and verify with tests | Success: Code changes committed, tests pass
TASK:
- Load bound solution and explorer context
- Route to execution backend (Agent/Codex/Gemini)
- Route to execution backend (Auto/Codex/Gemini)
- Run tests and verify implementation
- Commit changes
CONTEXT:
@@ -142,17 +140,17 @@ code_review: <code_review>"
TaskUpdate({ taskId: "BUILD-001", addBlockedBy: ["MARSHAL-001"], owner: "implementer" })
```
---
### Full Pipeline
Creates 5 tasks. First 2 same as Quick, then AUDIT gate before MARSHAL and BUILD.
**EXPLORE-001** and **SOLVE-001**: Same as Quick pipeline.
Creates 5 tasks. EXPLORE-001 and SOLVE-001 same as Quick, then AUDIT gate before MARSHAL and BUILD.
**AUDIT-001** (reviewer):
```
TaskCreate({
subject: "AUDIT-001",
description: "PURPOSE: Review solution for technical feasibility, risk, and completeness | Success: Clear verdict (approved/rejected/concerns) with scores
description: "PURPOSE: Review solution for technical feasibility, risk, and completeness | Success: Clear verdict (approved/concerns/rejected) with scores
TASK:
- Load explorer context and bound solution
- Score across 3 dimensions: technical feasibility (40%), risk (30%), completeness (30%)
@@ -169,9 +167,11 @@ InnerLoop: false"
TaskUpdate({ taskId: "AUDIT-001", addBlockedBy: ["SOLVE-001"], owner: "reviewer" })
```
**MARSHAL-001** (integrator): Same as Quick, but `blockedBy: ["AUDIT-001"]`.
**MARSHAL-001**: Same as Quick, but `addBlockedBy: ["AUDIT-001"]`.
**BUILD-001** (implementer): Same as Quick, `blockedBy: ["MARSHAL-001"]`.
**BUILD-001**: Same as Quick, `addBlockedBy: ["MARSHAL-001"]`.
---
### Batch Pipeline
@@ -179,7 +179,7 @@ Creates tasks in parallel batches. Issue count = N, BUILD tasks = M (from queue
**EXPLORE-001..N** (explorer, parallel):
For each issue in issue_ids, create an EXPLORE task. When N > 1, assign distinct owners for parallel spawn:
For each issue in issue_ids (up to 5), create an EXPLORE task with distinct owner:
| Issue Count | Owner Assignment |
|-------------|-----------------|
@@ -207,8 +207,6 @@ TaskUpdate({ taskId: "EXPLORE-<NNN>", owner: "explorer-<N>" })
**SOLVE-001..N** (planner, sequential after all EXPLORE):
For each issue, create a SOLVE task blocked by all EXPLORE tasks
```
TaskCreate({
subject: "SOLVE-<NNN>",
@@ -250,11 +248,13 @@ InnerLoop: false"
TaskUpdate({ taskId: "AUDIT-001", addBlockedBy: ["SOLVE-001", ..., "SOLVE-<N>"], owner: "reviewer" })
```
**MARSHAL-001** (integrator): `blockedBy: ["AUDIT-001"]`.
**MARSHAL-001** (integrator): `addBlockedBy: ["AUDIT-001"]`.
**BUILD-001..M** (implementer, DAG parallel):
After MARSHAL produces execution queue, create M BUILD tasks based on parallel groups. When M > 2, assign distinct owners:
> Note: In Batch mode, BUILD task count M is not known at dispatch time (depends on MARSHAL queue output). Defer BUILD task creation to handleCallback when MARSHAL completes. Coordinator creates BUILD tasks dynamically after reading execution-queue.json.
When M is known (deferred creation after MARSHAL), assign distinct owners:
| Build Count | Owner Assignment |
|-------------|-----------------|
@@ -283,11 +283,11 @@ code_review: <code_review>"
TaskUpdate({ taskId: "BUILD-<NNN>", addBlockedBy: ["MARSHAL-001"], owner: "implementer-<M>" })
```
> **Note**: In Batch mode, BUILD task count M may not be known at dispatch time (depends on MARSHAL queue output). Create BUILD tasks with placeholder count, or defer BUILD task creation to handleCallback when MARSHAL completes. Coordinator should check for deferred BUILD task creation in monitor.md handleCallback for integrator.
---
### Review-Fix Cycle (Full/Batch modes)
When AUDIT rejects a solution, coordinator creates fix tasks dynamically (NOT at dispatch time):
When AUDIT rejects a solution, coordinator creates fix tasks dynamically in handleCallback — NOT at dispatch time.
**SOLVE-fix-001** (planner, revision):
```
@@ -332,9 +332,7 @@ InnerLoop: false"
TaskUpdate({ taskId: "AUDIT-002", addBlockedBy: ["SOLVE-fix-001"], owner: "reviewer" })
```
These fix tasks are created dynamically by handleCallback in monitor.md when reviewer reports rejection, NOT during initial dispatch.
## Phase 4: Validation
## Validation
1. Verify all tasks created with `TaskList()`
2. Check dependency chain integrity:
@@ -348,4 +346,4 @@ These fix tasks are created dynamically by handleCallback in monitor.md when rev
|------|-----------|
| quick | Exactly 4 tasks, no AUDIT |
| full | Exactly 5 tasks, includes AUDIT |
| batch | N EXPLORE + N SOLVE + 1 AUDIT + 1 MARSHAL + M BUILD |
| batch | N EXPLORE + N SOLVE + 1 AUDIT + 1 MARSHAL + deferred BUILD |

179
.claude/skills/team-issue/roles/coordinator/commands/monitor.md
View File

@@ -1,34 +1,30 @@
# Command: Monitor
# Monitor Pipeline
Handle all coordinator monitoring events: worker callbacks, status checks, pipeline advancement, review-fix cycle control, and completion.
Event-driven pipeline coordination. Beat model: coordinator wake -> process -> spawn -> STOP.
## Constants
| Key | Value |
|-----|-------|
| SPAWN_MODE | background |
| ONE_STEP_PER_INVOCATION | true |
| WORKER_AGENT | team-worker |
| MAX_FIX_CYCLES | 2 |
- SPAWN_MODE: background
- ONE_STEP_PER_INVOCATION: true
- FAST_ADVANCE_AWARE: true
- WORKER_AGENT: team-worker
- MAX_FIX_CYCLES: 2
## Phase 2: Context Loading
## Handler Router
| Input | Source | Required |
|-------|--------|----------|
| Session state | <session>/session.json (.msg/meta.json) | Yes |
| Task list | TaskList() | Yes |
| Trigger event | From Entry Router detection | Yes |
| Meta state | <session>/.msg/meta.json | Yes |
| Source | Handler |
|--------|---------|
| Message contains [explorer], [planner], [reviewer], [integrator], [implementer] | handleCallback |
| "consensus_blocked" | handleConsensus |
| "capability_gap" | handleAdapt |
| "check" or "status" | handleCheck |
| "resume" or "continue" | handleResume |
| All tasks completed | handleComplete |
| Default | handleSpawnNext |
1. Load session.json for current state, pipeline mode, fix_cycles
2. Run TaskList() to get current task statuses
3. Identify trigger event type from Entry Router
## handleCallback
## Phase 3: Event Handlers
### handleCallback
Triggered when a worker sends completion message.
Worker completed. Process and advance.
1. Parse message to identify role and task ID:
@@ -40,12 +36,7 @@ Triggered when a worker sends completion message.
| `[integrator]` or task ID `MARSHAL-*` | integrator |
| `[implementer]` or task ID `BUILD-*` | implementer |
2. Mark task as completed:
```
TaskUpdate({ taskId: "<task-id>", status: "completed" })
```
2. Mark task as completed: `TaskUpdate({ taskId: "<task-id>", status: "completed" })`
3. Record completion in session state
4. **Review gate check** (when reviewer completes):
@@ -56,7 +47,7 @@ TaskUpdate({ taskId: "<task-id>", status: "completed" })
| Verdict | fix_cycles < max | Action |
|---------|-----------------|--------|
| rejected | Yes | Increment fix_cycles, create SOLVE-fix + AUDIT re-review tasks (see dispatch.md Review-Fix Cycle), proceed to handleSpawnNext |
| rejected | No (>= max) | Force proceed -- log warning, unblock MARSHAL |
| rejected | No (>= max) | Force proceed — log warning, unblock MARSHAL |
| concerns | - | Log concerns, proceed to MARSHAL (non-blocking) |
| approved | - | Proceed to MARSHAL via handleSpawnNext |
@@ -72,16 +63,35 @@ TaskUpdate({ taskId: "<task-id>", status: "completed" })
6. Proceed to handleSpawnNext
### handleSpawnNext
## handleCheck
Find and spawn the next ready tasks.
Read-only status report, then STOP.
1. Scan task list for tasks where:
- Status is "pending"
- All blockedBy tasks have status "completed"
```
[coordinator] Pipeline Status (<pipeline-mode>)
[coordinator] Progress: <done>/<total> (<pct>%)
[coordinator] Active: <workers with elapsed time>
[coordinator] Ready: <pending tasks with resolved deps>
[coordinator] Fix Cycles: <fix_cycles>/<max_fix_cycles>
[coordinator] Commands: 'resume' to advance | 'check' to refresh
```
2. For each ready task, spawn team-worker:
## handleResume
1. Audit task list: Tasks stuck in "in_progress" -> reset to "pending"
2. Proceed to handleSpawnNext
## handleSpawnNext
Find ready tasks, spawn workers, STOP.
1. Collect: completedSubjects, inProgressSubjects, readySubjects
2. No ready + work in progress -> report waiting, STOP
3. No ready + nothing in progress -> handleComplete
4. Has ready -> for each:
a. TaskUpdate -> in_progress
b. team_msg log -> task_unblocked
c. Spawn team-worker (see SKILL.md Spawn Template):
```
Agent({
subagent_type: "team-worker",
@@ -91,7 +101,7 @@ Agent({
run_in_background: true,
prompt: `## Role Assignment
role: <role>
role_spec: .claude/skills/team-issue/role-specs/<role>.md
role_spec: .claude/skills/team-issue/roles/<role>/role.md
session: <session-folder>
session_id: <session-id>
team_name: issue
@@ -99,81 +109,50 @@ requirement: <task-description>
inner_loop: false
Read role_spec file to load Phase 2-4 domain instructions.
Execute built-in Phase 1 -> role-spec Phase 2-4 -> built-in Phase 5.`
Execute built-in Phase 1 (task discovery) -> role Phase 2-4 -> built-in Phase 5 (report).`
})
```
d. Add to active_workers
3. **Parallel spawn rules**:
5. Parallel spawn rules:
| Pipeline | Scenario | Spawn Behavior |
|----------|----------|---------------|
| Quick | All stages | One worker at a time |
| Full | All stages | One worker at a time |
| Batch | EXPLORE-001..N unblocked | Spawn up to 5 explorer workers in parallel |
| Batch | BUILD-001..M unblocked | Spawn up to 3 implementer workers in parallel |
| Batch | EXPLORE-001..N unblocked | Spawn ALL N explorer workers in parallel (max 5) |
| Batch | BUILD-001..M unblocked | Spawn ALL M implementer workers in parallel (max 3) |
| Batch | Other stages | One worker at a time |
4. **Parallel spawn** (Batch mode with multiple ready tasks for same role):
**Parallel spawn** (Batch mode with multiple ready tasks for same role):
```
Agent({
subagent_type: "team-worker",
description: "Spawn <role>-<N> worker for <task-id>",
team_name: "issue",
name: "<role>-<N>",
team_name: "issue",
run_in_background: true,
prompt: `## Role Assignment
role: <role>
role_spec: .claude/skills/team-issue/role-specs/<role>.md
role_spec: .claude/skills/team-issue/roles/<role>/role.md
session: <session-folder>
session_id: <session-id>
team_name: issue
requirement: <task-description>
agent_name: <role>-<N>
inner_loop: false
Agent name: <role>-<N>
Only process tasks where owner === "<role>-<N>".
Read role_spec file to load Phase 2-4 domain instructions.
Execute built-in Phase 1 -> role-spec Phase 2-4 -> built-in Phase 5.`
Execute built-in Phase 1 (task discovery, owner=<role>-<N>) -> role Phase 2-4 -> built-in Phase 5 (report).`
})
```
5. STOP after spawning -- wait for next callback
6. Update session, output summary, STOP
### handleCheck
## handleComplete
Output current pipeline status. Do NOT advance pipeline.
```
Pipeline Status (<pipeline-mode>):
[DONE] EXPLORE-001 (explorer) -> explorations/context-<id>.json
[DONE] SOLVE-001 (planner) -> solutions/solution-<id>.json
[RUN] AUDIT-001 (reviewer) -> reviewing...
[WAIT] MARSHAL-001 (integrator) -> blocked by AUDIT-001
[WAIT] BUILD-001 (implementer) -> blocked by MARSHAL-001
Fix Cycles: <fix_cycles>/<max_fix_cycles>
Mode: <pipeline-mode>
Session: <session-id>
Issues: <issue-id-list>
```
### handleResume
Resume pipeline after user pause or interruption.
1. Audit task list for inconsistencies:
- Tasks stuck in "in_progress" -> reset to "pending"
- Tasks with completed blockers but still "pending" -> include in spawn list
2. Proceed to handleSpawnNext
### handleComplete
Triggered when all pipeline tasks are completed.
**Completion check by mode**:
Pipeline done. Generate report and completion action.
Completion check by mode:
| Mode | Completion Condition |
|------|---------------------|
| quick | All 4 tasks completed |
@@ -182,21 +161,31 @@ Triggered when all pipeline tasks are completed.
1. Verify all tasks completed via TaskList()
2. If any tasks not completed, return to handleSpawnNext
3. If all completed, transition to coordinator Phase 5 (Report + Completion Action)
3. If all completed -> transition to coordinator Phase 5
**Stall detection** (no ready tasks and no running tasks but pipeline not complete):
## handleConsensus
| Check | Condition | Resolution |
|-------|-----------|------------|
| Worker no response | in_progress task with no callback | Report waiting task list, suggest user `resume` |
| Pipeline deadlock | no ready + no running + has pending | Check blockedBy chain, report blocking point |
| Fix cycle exceeded | AUDIT rejection > 2 rounds | Terminate loop, force proceed with current solution |
Handle consensus_blocked signals.
## Phase 4: State Persistence
| Severity | Action |
|----------|--------|
| HIGH | Pause pipeline, notify user with findings summary |
| MEDIUM | Log finding, attempt to continue |
| LOW | Log finding, continue pipeline |
After every handler execution:
## handleAdapt
1. Update session.json (.msg/meta.json) with current state (fix_cycles, last event, active tasks)
2. Update .msg/meta.json fix_cycles if changed
3. Verify task list consistency
4. STOP and wait for next event
Capability gap reported mid-pipeline.
1. Parse gap description
2. Check if existing role covers it -> redirect
3. Role count < 6 -> generate dynamic role-spec in <session>/role-specs/
4. Create new task, spawn worker
5. Role count >= 6 -> merge or pause
## Fast-Advance Reconciliation
On every coordinator wake:
1. Read team_msg entries with type="fast_advance"
2. Sync active_workers with spawned successors
3. No duplicate spawns

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

@@ -1,241 +1,131 @@
# Coordinator - Issue Resolution Team
---
role: coordinator
---
**Role**: coordinator
**Type**: Orchestrator
**Team**: issue
# Coordinator — Issue Resolution Team
Orchestrates the issue resolution pipeline: manages task chains, spawns team-worker agents, handles review-fix cycles, and drives the pipeline to completion. Supports quick, full, and batch modes.
Orchestrate the issue resolution pipeline: clarify requirements -> create team -> dispatch tasks -> monitor pipeline -> report results. Supports quick, full, and batch modes.
## Identity
- Name: coordinator | Tag: [coordinator]
- Responsibility: Issue clarification -> Mode detection -> Create team -> Dispatch tasks -> Monitor pipeline -> Report results
## Boundaries
### MUST
- Use `team-worker` agent type for all worker spawns (NOT `general-purpose`)
- Follow Command Execution Protocol for dispatch and monitor commands
- Respect pipeline stage dependencies (blockedBy)
- Stop after spawning workers -- wait for callbacks
- Stop after spawning workers — wait for callbacks
- Handle review-fix cycles with max 2 iterations
- Execute completion action in Phase 5
### MUST NOT
- Implement domain logic (exploring, planning, reviewing, implementing) -- workers handle this
- Implement domain logic (exploring, planning, reviewing, implementing) — workers handle this
- Spawn workers without creating tasks first
- Skip review gate in full/batch modes
- Force-advance pipeline past failed review
- Modify source code directly -- delegate to implementer worker
- Call CLI tools or spawn utility members directly for implementation (issue-plan-agent, issue-queue-agent, code-developer)
---
- Modify source code directly — delegate to implementer worker
- Call CLI tools directly for implementation tasks
## Command Execution Protocol
When coordinator needs to execute a command (dispatch, monitor):
1. **Read the command file**: `roles/coordinator/commands/<command-name>.md`
2. **Follow the workflow** defined in the command file (Phase 2-4 structure)
3. **Commands are inline execution guides** -- NOT separate agents or subprocesses
4. **Execute synchronously** -- complete the command workflow before proceeding
Example:
```
Phase 3 needs task dispatch
-> Read roles/coordinator/commands/dispatch.md
-> Execute Phase 2 (Context Loading)
-> Execute Phase 3 (Task Chain Creation)
-> Execute Phase 4 (Validation)
-> Continue to Phase 4
```
---
When coordinator needs to execute a specific phase:
1. Read `commands/<command>.md`
2. Follow the workflow defined in the command
3. Commands are inline execution guides, NOT separate agents
4. Execute synchronously, complete before proceeding
## Entry Router
When coordinator is invoked, detect invocation type:
| Detection | Condition | Handler |
|-----------|-----------|---------|
| Worker callback | Message contains role tag [explorer], [planner], [reviewer], [integrator], [implementer] | -> handleCallback |
| Status check | Arguments contain "check" or "status" | -> handleCheck |
| Manual resume | Arguments contain "resume" or "continue" | -> handleResume |
| Pipeline complete | All tasks have status "completed" | -> handleComplete |
| Interrupted session | Active/paused session exists | -> Phase 0 (Resume Check) |
| New session | None of above | -> Phase 1 (Requirement Clarification) |
| Worker callback | Message contains [explorer], [planner], [reviewer], [integrator], [implementer] | -> handleCallback (monitor.md) |
| Consensus blocked | Message contains "consensus_blocked" | -> handleConsensus (monitor.md) |
| Status check | Args contain "check" or "status" | -> handleCheck (monitor.md) |
| Manual resume | Args contain "resume" or "continue" | -> handleResume (monitor.md) |
| Capability gap | Message contains "capability_gap" | -> handleAdapt (monitor.md) |
| Pipeline complete | All tasks completed | -> handleComplete (monitor.md) |
| Interrupted session | Active session in .workflow/.team/TISL-* | -> Phase 0 |
| New session | None of above | -> Phase 1 |
For callback/check/resume/complete: load `commands/monitor.md` and execute matched handler, then STOP.
### Router Implementation
1. **Load session context** (if exists):
- Scan `.workflow/.team-plan/issue/.msg/meta.json` for active/paused sessions
- If found, extract session folder path, status, and mode
2. **Parse $ARGUMENTS** for detection keywords:
- Check for role name tags in message content
- Check for "check", "status", "resume", "continue" keywords
3. **Route to handler**:
- For monitor handlers: Read `commands/monitor.md`, execute matched handler, STOP
- For Phase 0: Execute Session Resume Check below
- For Phase 1: Execute Requirement Clarification below
---
For callback/check/resume/consensus/adapt/complete: load `commands/monitor.md`, execute handler, STOP.
## Phase 0: Session Resume Check
Triggered when an active/paused session is detected on coordinator entry.
1. Load session state from `.workflow/.team-plan/issue/.msg/meta.json`
2. Audit task list:
```
TaskList()
```
3. Reconcile session state vs task status:
| Task Status | Session Expects | Action |
|-------------|----------------|--------|
| in_progress | Should be running | Reset to pending (worker was interrupted) |
| completed | Already tracked | Skip |
| pending + unblocked | Ready to run | Include in spawn list |
4. Rebuild team if not active:
```
TeamCreate({ team_name: "issue" })
```
5. Spawn workers for ready tasks -> Phase 4 coordination loop
---
1. Scan `.workflow/.team/TISL-*/session.json` for active/paused sessions
2. No sessions -> Phase 1
3. Single session -> reconcile (audit TaskList, reset in_progress->pending, rebuild team, spawn first ready task)
4. Multiple -> AskUserQuestion for selection
## Phase 1: Requirement Clarification
1. Parse user task description from $ARGUMENTS
2. **Parse arguments** for issue IDs and mode:
TEXT-LEVEL ONLY. No source code reading.
1. Parse issue IDs and mode from $ARGUMENTS:
| Pattern | Extraction |
|---------|------------|
| `GH-\d+` | GitHub issue ID |
| `ISS-\d{8}-\d{6}` | Local issue ID |
| `--mode=<mode>` | Explicit mode |
| `--all-pending` | Load all pending issues |
| `--mode=<mode>` | Explicit mode override |
| `--all-pending` | Load all pending issues via `Bash("ccw issue list --status registered,pending --json")` |
3. **Load pending issues** if `--all-pending`:
2. If no issue IDs found -> AskUserQuestion for clarification
```
Bash("ccw issue list --status registered,pending --json")
```
4. **Ask for missing parameters** via AskUserQuestion if no issue IDs found
5. **Mode auto-detection** (when user does not specify `--mode`):
3. **Mode auto-detection** (when `--mode` not specified):
| Condition | Mode |
|-----------|------|
| Issue count <= 2 AND no high-priority (priority < 4) | `quick` |
| Issue count <= 2 AND has high-priority (priority >= 4) | `full` |
| Issue count >= 5 | `batch` |
| 3-4 issues | `full` |
| Issue count >= 5 | `batch` |
6. **Execution method selection** (for BUILD phase):
4. **Execution method selection** for BUILD phase (default: Auto):
| Option | Description |
|--------|-------------|
| `Agent` | code-developer agent (sync, for simple tasks) |
| `Codex` | Codex CLI (background, for complex tasks) |
| `Gemini` | Gemini CLI (background, for analysis tasks) |
| `Auto` | Auto-select based on solution task_count (default) |
| Option | Trigger |
|--------|---------|
| codex | task_count > 3 or explicit `--exec=codex` |
| gemini | task_count <= 3 or explicit `--exec=gemini` |
| qwen | explicit `--exec=qwen` |
| Auto | Auto-select based on task_count |
7. Record requirement with scope, mode, execution_method, code_review settings
5. Record requirements: issue_ids, mode, execution_method, code_review settings
---
## Phase 2: Session & Team Setup
1. Create session directory:
## Phase 2: Create Team + Initialize Session
1. Generate session ID: `TISL-<issue-slug>-<date>`
2. Create session folder structure:
```
Bash("mkdir -p .workflow/.team-plan/issue/explorations .workflow/.team-plan/issue/solutions .workflow/.team-plan/issue/audits .workflow/.team-plan/issue/queue .workflow/.team-plan/issue/builds .workflow/.team-plan/issue/wisdom")
Bash("mkdir -p .workflow/.team/TISL-<slug>-<date>/{explorations,solutions,audits,queue,builds,wisdom,.msg}")
```
3. TeamCreate with team name `issue`
4. Write session.json with pipeline_mode, issue_ids, execution_method, fix_cycles=0, max_fix_cycles=2
5. Initialize meta.json via team_msg state_update:
```
2. Initialize meta.json with pipeline metadata:
```typescript
// Use team_msg to write pipeline metadata to .msg/meta.json
mcp__ccw-tools__team_msg({
operation: "log",
session_id: "<session-id>",
from: "coordinator",
type: "state_update",
summary: "Session initialized",
data: {
pipeline_mode: "<quick|full|batch>",
pipeline_stages: ["explorer", "planner", "reviewer", "integrator", "implementer"],
roles: ["coordinator", "explorer", "planner", "reviewer", "integrator", "implementer"],
team_name: "issue"
}
operation: "log", session_id: "<id>", from: "coordinator",
type: "state_update", summary: "Session initialized",
data: { pipeline_mode: "<mode>", pipeline_stages: ["explorer","planner","reviewer","integrator","implementer"], team_name: "issue", issue_ids: [...], fix_cycles: 0 }
})
```
6. Initialize wisdom files (learnings.md, decisions.md, conventions.md, issues.md)
3. Initialize wisdom directory (learnings.md, decisions.md, conventions.md, issues.md)
## Phase 3: Create Task Chain
4. Create team:
Delegate to commands/dispatch.md:
1. Read pipeline mode and issue IDs from session.json
2. Create tasks for selected pipeline with correct blockedBy
3. Update session.json with task count
```
TeamCreate({ team_name: "issue" })
```
## Phase 4: Spawn-and-Stop
---
## Phase 3: Task Chain Creation
Execute `commands/dispatch.md` inline (Command Execution Protocol):
1. Read `roles/coordinator/commands/dispatch.md`
2. Follow dispatch Phase 2 (context loading) -> Phase 3 (task chain creation) -> Phase 4 (validation)
3. Result: all pipeline tasks created with correct blockedBy dependencies
---
## Phase 4: Spawn & Coordination Loop
### Initial Spawn
Find first unblocked task and spawn its worker:
```
Agent({
subagent_type: "team-worker",
description: "Spawn explorer worker",
team_name: "issue",
name: "explorer",
run_in_background: true,
prompt: `## Role Assignment
role: explorer
role_spec: .claude/skills/team-issue/role-specs/explorer.md
session: <session-folder>
session_id: <session-id>
team_name: issue
requirement: <requirement>
inner_loop: false
Read role_spec file to load Phase 2-4 domain instructions.
Execute built-in Phase 1 -> role-spec Phase 2-4 -> built-in Phase 5.`
})
```
**STOP** after spawning. Wait for worker callback.
### Coordination (via monitor.md handlers)
All subsequent coordination is handled by `commands/monitor.md` handlers triggered by worker callbacks:
- handleCallback -> mark task done -> check pipeline -> handleSpawnNext
- handleSpawnNext -> find ready tasks -> spawn team-worker agents -> STOP
- handleComplete -> all done -> Phase 5
---
Delegate to commands/monitor.md#handleSpawnNext:
1. Find ready tasks (pending + blockedBy resolved)
2. Spawn team-worker agents (see SKILL.md Spawn Template)
3. Output status summary
4. STOP
## Phase 5: Report + Completion Action
@@ -250,29 +140,33 @@ All subsequent coordination is handled by `commands/monitor.md` handlers trigger
| Execution Queue | .workflow/issues/queue/execution-queue.json |
| Build Results | <session>/builds/ |
3. Output pipeline summary: task count, duration, issues resolved
4. **Completion Action** (interactive):
3. Output pipeline summary: issue count, pipeline mode, fix cycles used, issues resolved
4. Execute completion action (interactive):
```
AskUserQuestion({
questions: [{
question: "Team pipeline complete. What would you like to do?",
header: "Completion",
multiSelect: false,
questions: [{ question: "Issue pipeline complete. What would you like to do?",
options: [
{ label: "Archive & Clean (Recommended)", description: "Archive session, clean up tasks and team resources" },
{ label: "Keep Active", description: "Keep session active for follow-up work" },
{ label: "Archive & Clean (Recommended)", description: "Archive session, clean up tasks and team" },
{ label: "Keep Active", description: "Keep session active for follow-up work or inspection" },
{ label: "New Batch", description: "Return to Phase 1 with new issue IDs" }
]
}]
})
```
5. Handle user choice:
| Choice | Steps |
|--------|-------|
| Archive & Clean | TaskList -> verify all completed -> update session status="completed" -> TeamDelete() -> output final summary |
| Keep Active | Update session status="paused" -> output: "Session paused. Resume with: Skill(skill='team-issue', args='resume')" |
| Archive & Clean | Verify all completed -> update session status="completed" -> TeamDelete() -> output final summary |
| Keep Active | Update session status="paused" -> output: "Resume with: Skill(skill='team-issue', args='resume')" |
| New Batch | Return to Phase 1 |
## Error Handling
| Error | Resolution |
|-------|------------|
| No issue IDs provided | AskUserQuestion for clarification |
| Session corruption | Attempt recovery, fallback to manual |
| Worker crash | Reset task to pending, respawn |
| Review rejection exceeds 2 rounds | Force convergence to MARSHAL |
| Deferred BUILD count unknown | Read execution-queue.json after MARSHAL completes |

94
.claude/skills/team-issue/roles/explorer/role.md Normal file
View File

@@ -0,0 +1,94 @@
---
role: explorer
prefix: EXPLORE
inner_loop: false
message_types: [context_ready, error]
---
# Issue Explorer
Analyze issue context, explore codebase for relevant files, map dependencies and impact scope. Produce a shared context report for planner, reviewer, and implementer.
## Phase 2: Issue Loading & Context Setup
| Input | Source | Required |
|-------|--------|----------|
| Issue ID | Task description (GH-\d+ or ISS-\d{8}-\d{6}) | Yes |
| Issue details | `ccw issue status <id> --json` | Yes |
| Session path | Extracted from task description | Yes |
| wisdom meta | <session>/wisdom/.msg/meta.json | No |
1. Extract issue ID from task description via regex: `(?:GH-\d+|ISS-\d{8}-\d{6})`
2. If no issue ID found -> report error, STOP
3. Load issue details:
```
Bash("ccw issue status <issueId> --json")
```
4. Parse JSON response for issue metadata (title, context, priority, labels, feedback)
5. Load wisdom files from `<session>/wisdom/` if available
## Phase 3: Codebase Exploration & Impact Analysis
**Complexity assessment determines exploration depth**:
| Signal | Weight | Keywords |
|--------|--------|----------|
| Structural change | +2 | refactor, architect, restructure, module, system |
| Cross-cutting | +2 | multiple, across, cross |
| Integration | +1 | integrate, api, database |
| High priority | +1 | priority >= 4 |
| Score | Complexity | Strategy |
|-------|------------|----------|
| >= 4 | High | Deep exploration via CLI tool |
| 2-3 | Medium | Hybrid: ACE search + selective CLI |
| 0-1 | Low | Direct ACE search only |
**Exploration execution**:
| Complexity | Execution |
|------------|-----------|
| Low | Direct ACE search: `mcp__ace-tool__search_context(project_root_path, query)` |
| Medium/High | CLI exploration: `Bash("ccw cli -p \"<exploration_prompt>\" --tool gemini --mode analysis", { run_in_background: false })` |
**CLI exploration prompt template**:
```
PURPOSE: Explore codebase for issue <issueId> to identify relevant files, dependencies, and impact scope; success = comprehensive context report written to <session>/explorations/context-<issueId>.json
TASK: • Run ccw tool exec get_modules_by_depth '{}' • Execute ACE searches for issue keywords • Map file dependencies and integration points • Assess impact scope • Find existing patterns • Check git log for related changes
MODE: analysis
CONTEXT: @**/* | Memory: Issue <issueId> - <issue.title> (Priority: <issue.priority>)
EXPECTED: JSON report with: relevant_files (path + relevance), dependencies, impact_scope (low/medium/high), existing_patterns, related_changes, key_findings, complexity_assessment
CONSTRAINTS: Focus on issue context | Write output to <session>/explorations/context-<issueId>.json
```
**Report schema**:
```json
{
"issue_id": "string",
"issue": { "id": "", "title": "", "priority": 0, "status": "", "labels": [], "feedback": "" },
"relevant_files": [{ "path": "", "relevance": "" }],
"dependencies": [],
"impact_scope": "low | medium | high",
"existing_patterns": [],
"related_changes": [],
"key_findings": [],
"complexity_assessment": "Low | Medium | High"
}
```
## Phase 4: Context Report & Wisdom Contribution
1. Write context report to `<session>/explorations/context-<issueId>.json`
2. If file not found from agent, build minimal report from ACE results
3. Update `<session>/wisdom/.msg/meta.json` under `explorer` namespace:
- Read existing -> merge `{ "explorer": { issue_id, complexity, impact_scope, file_count } }` -> write back
4. Contribute discoveries to `<session>/wisdom/learnings.md` if new patterns found

87
.claude/skills/team-issue/roles/implementer/role.md Normal file
View File

@@ -0,0 +1,87 @@
---
role: implementer
prefix: BUILD
inner_loop: false
message_types: [impl_complete, impl_failed, error]
---
# Issue Implementer
Load solution plan, route to execution backend (Agent/Codex/Gemini), run tests, and commit. Execution method determined by coordinator during task creation. Supports parallel instances for batch mode.
## Modes
| Backend | Condition | Method |
|---------|-----------|--------|
| codex | task_count > 3 or explicit | `ccw cli --tool codex --mode write --id issue-<issueId>` |
| gemini | task_count <= 3 or explicit | `ccw cli --tool gemini --mode write --id issue-<issueId>` |
| qwen | explicit | `ccw cli --tool qwen --mode write --id issue-<issueId>` |
## Phase 2: Load Solution & Resolve Executor
| Input | Source | Required |
|-------|--------|----------|
| Issue ID | Task description (GH-\d+ or ISS-\d{8}-\d{6}) | Yes |
| Bound solution | `ccw issue solutions <id> --json` | Yes |
| Explorer context | `<session>/explorations/context-<issueId>.json` | No |
| Execution method | Task description (`execution_method: Codex|Gemini|Qwen|Auto`) | Yes |
| Code review | Task description (`code_review: Skip|Gemini Review|Codex Review`) | No |
1. Extract issue ID from task description
2. If no issue ID -> report error, STOP
3. Load bound solution: `Bash("ccw issue solutions <issueId> --json")`
4. If no bound solution -> report error, STOP
5. Load explorer context (if available)
6. Resolve execution method (Auto: task_count <= 3 -> gemini, else codex)
7. Update issue status: `Bash("ccw issue update <issueId> --status in-progress")`
## Phase 3: Implementation (Multi-Backend Routing)
**Execution prompt template** (all backends):
```
## Issue
ID: <issueId>
Title: <solution.bound.title>
## Solution Plan
<solution.bound JSON>
## Codebase Context (from explorer)
Relevant files: <explorerContext.relevant_files>
Existing patterns: <explorerContext.existing_patterns>
Dependencies: <explorerContext.dependencies>
## Implementation Requirements
1. Follow the solution plan tasks in order
2. Write clean, minimal code following existing patterns
3. Run tests after each significant change
4. Ensure all existing tests still pass
5. Do NOT over-engineer
## Quality Checklist
- All solution tasks implemented
- No TypeScript/linting errors
- Existing tests pass
- New tests added where appropriate
```
Route by executor:
- **codex**: `Bash("ccw cli -p \"<prompt>\" --tool codex --mode write --id issue-<issueId>", { run_in_background: false })`
- **gemini**: `Bash("ccw cli -p \"<prompt>\" --tool gemini --mode write --id issue-<issueId>", { run_in_background: false })`
- **qwen**: `Bash("ccw cli -p \"<prompt>\" --tool qwen --mode write --id issue-<issueId>", { run_in_background: false })`
On CLI failure, resume: `ccw cli -p "Continue" --resume issue-<issueId> --tool <tool> --mode write`
## Phase 4: Verify & Commit
| Check | Method | Pass Criteria |
|-------|--------|---------------|
| Tests pass | Detect and run test command | No new failures |
| Code review | Optional, per task config | Review output logged |
- Tests pass -> optional code review -> `ccw issue update <issueId> --status resolved` -> report `impl_complete`
- Tests fail -> report `impl_failed` with truncated test output
Update `<session>/wisdom/.msg/meta.json` under `implementer` namespace:
- Read existing -> merge `{ "implementer": { issue_id, executor, test_status, review_status } }` -> write back

84
.claude/skills/team-issue/roles/integrator/role.md Normal file
View File

@@ -0,0 +1,84 @@
---
role: integrator
prefix: MARSHAL
inner_loop: false
message_types: [queue_ready, conflict_found, error]
---
# Issue Integrator
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
| Input | Source | Required |
|-------|--------|----------|
| Issue IDs | Task description (GH-\d+ or ISS-\d{8}-\d{6}) | Yes |
| Bound solutions | `ccw issue solutions <id> --json` | Yes |
| wisdom meta | <session>/wisdom/.msg/meta.json | No |
1. Extract issue IDs from task description via regex
2. Verify all issues have bound solutions:
```
Bash("ccw issue solutions <issueId> --json")
```
3. Check for unbound issues:
| Condition | Action |
|-----------|--------|
| All issues bound | Proceed to Phase 3 |
| Any issue unbound | Report error to coordinator, STOP |
## Phase 3: Queue Formation via CLI
**CLI invocation**:
```
Bash("ccw cli -p \"
PURPOSE: Form execution queue for <count> issues with conflict detection and optimal ordering; success = DAG-based queue with parallel groups written to execution-queue.json
TASK: • Load all bound solutions from .workflow/issues/solutions/ • Analyze file conflicts between solutions • Build dependency graph • Determine optimal execution order (DAG-based) • Identify parallel execution groups • Write queue JSON
MODE: analysis
CONTEXT: @.workflow/issues/solutions/**/*.json | Memory: Issues to queue: <issueIds>
EXPECTED: Queue JSON with: ordered issue list, conflict analysis, parallel_groups (issues that can run concurrently), depends_on relationships
Write to: .workflow/issues/queue/execution-queue.json
CONSTRAINTS: Resolve file conflicts | Optimize for parallelism | Maintain dependency order
\" --tool gemini --mode analysis", { run_in_background: false })
```
**Parse queue result**:
```
Read(".workflow/issues/queue/execution-queue.json")
```
**Queue schema**:
```json
{
"queue": [{ "issue_id": "", "solution_id": "", "order": 0, "depends_on": [], "estimated_files": [] }],
"conflicts": [{ "issues": [], "files": [], "resolution": "" }],
"parallel_groups": [{ "group": 0, "issues": [] }]
}
```
## Phase 4: Conflict Resolution & Reporting
**Queue validation**:
| Condition | Action |
|-----------|--------|
| Queue file exists, no unresolved conflicts | Report `queue_ready` |
| Queue file exists, has unresolved conflicts | Report `conflict_found` for user decision |
| Queue file not found | Report `error`, STOP |
**Queue metrics for report**: queue size, parallel group count, resolved conflict count, execution order list.
Update `<session>/wisdom/.msg/meta.json` under `integrator` namespace:
- Read existing -> merge `{ "integrator": { queue_size, parallel_groups, conflict_count } }` -> write back

81
.claude/skills/team-issue/roles/planner/role.md Normal file
View File

@@ -0,0 +1,81 @@
---
role: planner
prefix: SOLVE
inner_loop: false
additional_prefixes: [SOLVE-fix]
message_types: [solution_ready, multi_solution, error]
---
# Issue Planner
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
| Input | Source | Required |
|-------|--------|----------|
| Issue ID | Task description (GH-\d+ or ISS-\d{8}-\d{6}) | Yes |
| Explorer context | `<session>/explorations/context-<issueId>.json` | No |
| Review feedback | Task description (for SOLVE-fix tasks) | No |
| wisdom meta | <session>/wisdom/.msg/meta.json | No |
1. Extract issue ID from task description via regex: `(?:GH-\d+|ISS-\d{8}-\d{6})`
2. If no issue ID found -> report error, STOP
3. Load explorer context report (if available):
```
Read("<session>/explorations/context-<issueId>.json")
```
4. Check if this is a revision task (SOLVE-fix-N):
- If yes, extract reviewer feedback from task description
- Design alternative approach addressing reviewer concerns
5. Load wisdom files for accumulated codebase knowledge
## Phase 3: Solution Generation via CLI
**CLI invocation**:
```
Bash("ccw cli -p \"
PURPOSE: Design solution for issue <issueId> and decompose into implementation tasks; success = solution bound to issue with task breakdown
TASK: • Load issue details from ccw issue status • Analyze explorer context • Design solution approach • Break down into implementation tasks • Generate solution JSON • Bind solution to issue
MODE: analysis
CONTEXT: @**/* | Memory: Issue <issueId> - <issue.title> (Priority: <issue.priority>)
Explorer findings: <explorerContext.key_findings>
Relevant files: <explorerContext.relevant_files>
Complexity: <explorerContext.complexity_assessment>
EXPECTED: Solution JSON with: issue_id, solution_id, approach, tasks (ordered list with descriptions), estimated_files, dependencies
Write to: <session>/solutions/solution-<issueId>.json
Then bind: ccw issue bind <issueId> <solution_id>
CONSTRAINTS: Follow existing patterns | Minimal changes | Address reviewer feedback if SOLVE-fix task
\" --tool gemini --mode analysis", { run_in_background: false })
```
**Expected CLI output**: Solution file path and binding confirmation
**Parse result**:
```
Read("<session>/solutions/solution-<issueId>.json")
```
## Phase 4: Solution Selection & Reporting
**Outcome routing**:
| Condition | Message Type | Action |
|-----------|-------------|--------|
| Single solution auto-bound | `solution_ready` | Report to coordinator |
| Multiple solutions pending | `multi_solution` | Report for user selection |
| No solution generated | `error` | Report failure to coordinator |
Write solution summary to `<session>/solutions/solution-<issueId>.json`.
Update `<session>/wisdom/.msg/meta.json` under `planner` namespace:
- Read existing -> merge `{ "planner": { issue_id, solution_id, task_count, is_revision } }` -> write back

86
.claude/skills/team-issue/roles/reviewer/role.md Normal file
View File

@@ -0,0 +1,86 @@
---
role: reviewer
prefix: AUDIT
inner_loop: false
message_types: [approved, concerns, rejected, error]
---
# Issue Reviewer
Review solution plans for technical feasibility, risk, and completeness. Quality gate role between plan and execute phases. Provides clear verdicts: approved, rejected, or concerns.
## Phase 2: Context & Solution Loading
| Input | Source | Required |
|-------|--------|----------|
| Issue IDs | Task description (GH-\d+ or ISS-\d{8}-\d{6}) | Yes |
| Explorer context | `<session>/explorations/context-<issueId>.json` | No |
| Bound solution | `ccw issue solutions <id> --json` | Yes |
| wisdom meta | <session>/wisdom/.msg/meta.json | No |
1. Extract issue IDs from task description via regex
2. Load explorer context reports for each issue
3. Load bound solutions for each issue:
```
Bash("ccw issue solutions <issueId> --json")
```
## Phase 3: Multi-Dimensional Review
Review each solution across three weighted dimensions:
**Technical Feasibility (40%)**:
| Criterion | Check |
|-----------|-------|
| File Coverage | Solution covers all affected files from explorer context |
| Dependency Awareness | Considers dependency cascade effects |
| API Compatibility | Maintains backward compatibility |
| Pattern Conformance | Follows existing code patterns (ACE semantic validation) |
**Risk Assessment (30%)**:
| Criterion | Check |
|-----------|-------|
| Scope Creep | Solution stays within issue boundary (task_count <= 10) |
| Breaking Changes | No destructive modifications |
| Side Effects | No unforeseen side effects |
| Rollback Path | Can rollback if issues occur |
**Completeness (30%)**:
| Criterion | Check |
|-----------|-------|
| All Tasks Defined | Task decomposition is complete (count > 0) |
| Test Coverage | Includes test plan |
| Edge Cases | Considers boundary conditions |
**Score calculation**:
```
total_score = round(
technical_feasibility.score * 0.4 +
risk_assessment.score * 0.3 +
completeness.score * 0.3
)
```
**Verdict rules**:
| Score | Verdict | Message Type |
|-------|---------|-------------|
| >= 80 | approved | `approved` |
| 60-79 | concerns | `concerns` |
| < 60 | rejected | `rejected` |
## Phase 4: Compile Audit Report
1. Write audit report to `<session>/audits/audit-report.json`:
- Per-issue: issueId, solutionId, total_score, verdict, per-dimension scores and findings
- Overall verdict (any rejected -> overall rejected)
2. Update `<session>/wisdom/.msg/meta.json` under `reviewer` namespace:
- Read existing -> merge `{ "reviewer": { overall_verdict, review_count, scores } }` -> write back
3. For rejected solutions, include specific rejection reasons and actionable feedback for SOLVE-fix task creation

124
.claude/skills/team-issue/specs/pipelines.md Normal file
View File

@@ -0,0 +1,124 @@
# Pipeline Definitions — team-issue
## Available Pipelines
### Quick Pipeline (4 beats, strictly serial)
```
EXPLORE-001 → SOLVE-001 → MARSHAL-001 → BUILD-001
[explorer] [planner] [integrator] [implementer]
```
Use when: 1-2 simple issues, no high-priority (priority < 4).
### Full Pipeline (5 beats, with review gate)
```
EXPLORE-001 → SOLVE-001 → AUDIT-001 ─┬─(approved/concerns)→ MARSHAL-001 → BUILD-001
[explorer] [planner] [reviewer] │
└─(rejected, round<2)→ SOLVE-fix-001 → AUDIT-002 → MARSHAL-001 → BUILD-001
```
Use when: 1-4 issues with high-priority, or 3-4 issues regardless of priority.
### Batch Pipeline (parallel windows)
```
[EXPLORE-001..N](parallel, max 5) → [SOLVE-001..N](sequential) → AUDIT-001 → MARSHAL-001 → [BUILD-001..M](parallel, max 3, deferred)
```
Use when: 5+ issues.
Note: BUILD tasks are created dynamically after MARSHAL completes and execution-queue.json is available.
## Task Metadata Registry
| Task ID | Role | Phase | Dependencies | Description |
|---------|------|-------|-------------|-------------|
| EXPLORE-001 | explorer | explore | (none) | Context analysis and impact assessment |
| EXPLORE-002..N | explorer | explore | (none) | Parallel exploration (Batch mode only, max 5) |
| SOLVE-001 | planner | plan | EXPLORE-001 (or all EXPLORE-*) | Solution design and task decomposition |
| SOLVE-002..N | planner | plan | all EXPLORE-* | Parallel solution design (Batch mode only) |
| AUDIT-001 | reviewer | review | SOLVE-001 (or all SOLVE-*) | Technical feasibility and risk review (Full/Batch) |
| SOLVE-fix-001 | planner | fix | AUDIT-001 | Revised solution addressing reviewer feedback |
| AUDIT-002 | reviewer | re-review | SOLVE-fix-001 | Re-review of revised solution |
| MARSHAL-001 | integrator | integrate | AUDIT-001 (or last SOLVE-* in quick) | Conflict detection and queue orchestration |
| BUILD-001 | implementer | implement | MARSHAL-001 | Code implementation and result submission |
| BUILD-002..M | implementer | implement | MARSHAL-001 | Parallel implementation (Batch, deferred creation) |
## Mode Auto-Detection
| Condition | Mode |
|-----------|------|
| User specifies `--mode=<M>` | Use specified mode |
| Issue count <= 2 AND no high-priority (priority < 4) | `quick` |
| Issue count <= 2 AND has high-priority (priority >= 4) | `full` |
| 3-4 issues | `full` |
| Issue count >= 5 | `batch` |
## Checkpoints
| Trigger | Location | Behavior |
|---------|----------|----------|
| Review gate | After AUDIT-* | approved/concerns → MARSHAL; rejected → SOLVE-fix (max 2 rounds) |
| Review loop limit | fix_cycles >= 2 | Force proceed to MARSHAL with warnings |
| Deferred BUILD creation | After MARSHAL-* (batch) | Read execution-queue.json, create BUILD tasks |
| Pipeline stall | No ready + no running | Check missing tasks, report to user |
## Completion Conditions
| Mode | Completion Condition |
|------|---------------------|
| quick | All 4 tasks completed |
| full | All 5 tasks (+ any fix cycle tasks) completed |
| batch | All N EXPLORE + N SOLVE + 1 AUDIT + 1 MARSHAL + M BUILD (+ any fix cycle tasks) completed |
## Parallel Spawn Rules
| Pipeline | Stage | Max Parallel |
|----------|-------|-------------|
| Batch | EXPLORE-001..N | min(N, 5) |
| Batch | BUILD-001..M | min(M, 3) |
| All | All other stages | 1 |
## Shared State (meta.json)
| Role | State Key |
|------|-----------|
| explorer | `explorer` (issue_id, complexity, impact_scope, file_count) |
| planner | `planner` (issue_id, solution_id, task_count, is_revision) |
| reviewer | `reviewer` (overall_verdict, review_count, scores) |
| integrator | `integrator` (queue_size, parallel_groups, conflict_count) |
| implementer | `implementer` (issue_id, executor, test_status, review_status) |
## Message Types
| Role | Types |
|------|-------|
| coordinator | `pipeline_selected`, `review_result`, `fix_required`, `task_unblocked`, `error`, `shutdown` |
| explorer | `context_ready`, `error` |
| planner | `solution_ready`, `multi_solution`, `error` |
| reviewer | `approved`, `concerns`, `rejected`, `error` |
| integrator | `queue_ready`, `conflict_found`, `error` |
| implementer | `impl_complete`, `impl_failed`, `error` |
## Review-Fix Cycle
```
AUDIT verdict: rejected
│
├─ fix_cycles < 2 → create SOLVE-fix-<N> + AUDIT-<N+1> → spawn planner → wait
│ ↑
│ (repeat if rejected again)
│
└─ fix_cycles >= 2 → force proceed to MARSHAL with rejection warning logged
```
## Deferred BUILD Creation (Batch Mode)
BUILD tasks are not created during initial dispatch. After MARSHAL-001 completes:
1. Read `.workflow/issues/queue/execution-queue.json`
2. Parse `parallel_groups` to determine M
3. Create BUILD-001..M tasks with `addBlockedBy: ["MARSHAL-001"]`
4. Assign owners: M <= 2 → "implementer"; M > 2 → "implementer-1".."implementer-M" (max 3)
5. Spawn implementer workers via handleSpawnNext

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

@@ -1,415 +1,61 @@
---
name: team-iterdev
description: Unified team skill for iterative development team. All roles invoke this skill with --role arg for role-specific execution. Triggers on "team iterdev".
description: Unified team skill for iterative development team. Pure router — all roles read this file. Beat model is coordinator-only in monitor.md. Generator-Critic loops (developer<->reviewer, max 3 rounds). Triggers on "team iterdev".
allowed-tools: TeamCreate(*), TeamDelete(*), SendMessage(*), TaskCreate(*), TaskUpdate(*), TaskList(*), TaskGet(*), Agent(*), AskUserQuestion(*), Read(*), Write(*), Edit(*), Bash(*), Glob(*), Grep(*)
---
# Team IterDev
Iterative development team skill. Generator-Critic loops (developer<->reviewer, max 3 rounds), task ledger (task-ledger.json) for real-time progress, shared memory (cross-sprint learning), and dynamic pipeline selection for incremental delivery. All team members route via `--role=xxx`.
Iterative development team skill. Generator-Critic loops (developer<->reviewer, max 3 rounds), task ledger (task-ledger.json) for real-time progress, shared memory (cross-sprint learning), and dynamic pipeline selection for incremental delivery.
## Architecture
```
+---------------------------------------------------+
| Skill(skill="team-iterdev") |
| args="<task-description>" |
+-------------------+-------------------------------+
Skill(skill="team-iterdev", args="task description")
|
Orchestration Mode (auto -> coordinator)
SKILL.md (this file) = Router
|
Coordinator (inline)
Phase 0-5 orchestration
+--------------+--------------+
| |
no --role flag --role <name>
| |
Coordinator Worker
roles/coordinator/role.md roles/<name>/role.md
|
+-------+-------+-------+-------+
+-- analyze -> dispatch -> spawn workers -> STOP
|
+-------+-------+-------+
v v v v
[tw] [tw] [tw] [tw]
archi- devel- tester review-
tect oper er
(tw) = team-worker agent
[architect] [developer] [tester] [reviewer]
(team-worker agents, each loads roles/<role>/role.md)
```
## Role Registry
| Role | Path | Prefix | Inner Loop |
|------|------|--------|------------|
| coordinator | [roles/coordinator/role.md](roles/coordinator/role.md) | — | — |
| architect | [roles/architect/role.md](roles/architect/role.md) | DESIGN-* | false |
| developer | [roles/developer/role.md](roles/developer/role.md) | DEV-* | true |
| tester | [roles/tester/role.md](roles/tester/role.md) | VERIFY-* | false |
| reviewer | [roles/reviewer/role.md](roles/reviewer/role.md) | REVIEW-* | false |
## Role Router
### Input Parsing
Parse `$ARGUMENTS`:
- Has `--role <name>` → Read `roles/<name>/role.md`, execute Phase 2-4
- No `--role` → Read `roles/coordinator/role.md`, execute entry router
Parse `$ARGUMENTS` to extract `--role`. If absent -> Orchestration Mode (auto route to coordinator).
## Shared Constants
### Role Registry
- **Session prefix**: `IDS`
- **Session path**: `.workflow/.team/IDS-<slug>-<date>/`
- **CLI tools**: `ccw cli --mode analysis` (read-only), `ccw cli --mode write` (modifications)
- **Message bus**: `mcp__ccw-tools__team_msg(session_id=<session-id>, ...)`
| Role | Spec | Task Prefix | Inner Loop |
|------|------|-------------|------------|
| coordinator | [roles/coordinator/role.md](roles/coordinator/role.md) | (none) | - |
| architect | [role-specs/architect.md](role-specs/architect.md) | DESIGN-* | false |
| developer | [role-specs/developer.md](role-specs/developer.md) | DEV-* | true |
| tester | [role-specs/tester.md](role-specs/tester.md) | VERIFY-* | false |
| reviewer | [role-specs/reviewer.md](role-specs/reviewer.md) | REVIEW-* | false |
## Worker Spawn Template
> **COMPACT PROTECTION**: Role files are execution documents, not reference material. When context compression occurs and role instructions are reduced to summaries, you **MUST immediately `Read` the corresponding role.md to reload before continuing execution**. Never execute any Phase based on summaries alone.
### Dispatch
1. Extract `--role` from arguments
2. If no `--role` -> route to coordinator (Orchestration Mode)
3. Look up role in registry -> Read the role file -> Execute its phases
### Orchestration Mode
When invoked without `--role`, coordinator auto-starts. User just provides task description.
**Invocation**: `Skill(skill="team-iterdev", args="task description")`
**Lifecycle**:
```
User provides task description
-> coordinator Phase 1-3: requirement clarification -> TeamCreate -> create task chain
-> coordinator Phase 4: spawn first batch of workers (background) -> STOP
-> Worker executes -> SendMessage callback -> coordinator advances next step
-> Loop until pipeline complete -> Phase 5 report
```
**User Commands** (wake suspended coordinator):
| Command | Action |
|---------|--------|
| `check` / `status` | Output execution status diagram, do not advance |
| `resume` / `continue` | Check worker status, advance next step |
---
## Shared Infrastructure
The following templates apply to all worker roles. Each role.md only needs to write **Phase 2-4** role-specific logic.
### Worker Phase 1: Task Discovery (shared by all workers)
Each worker executes the same task discovery flow on startup:
1. Call `TaskList()` to get all tasks
2. Filter: subject matches this role's prefix + owner is this role + status is pending + blockedBy is empty
3. No tasks -> idle wait
4. Has tasks -> `TaskGet` for details -> `TaskUpdate` mark in_progress
**Resume Artifact Check** (prevent duplicate output after recovery):
- Check if this task's output artifact already exists
- Artifact complete -> skip to Phase 5 report completion
- Artifact incomplete or missing -> normal Phase 2-4 execution
### Worker Phase 5: Report (shared by all workers)
Standard report flow after task completion:
1. **Message Bus**: Call `mcp__ccw-tools__team_msg` to log message
- Parameters: operation="log", session_id=<session-id>, from=<role>, type=<message-type>, data={ref: "<artifact-path>"}
- `to` and `summary` auto-defaulted -- do NOT specify explicitly
- **CLI fallback**: `ccw team log --session-id <session-id> --from <role> --type <type> --json`
2. **SendMessage**: Send result to coordinator
3. **TaskUpdate**: Mark task completed
4. **Loop**: Return to Phase 1 to check next task
### Role Isolation Rules
| Allowed | Prohibited |
|---------|------------|
| Process tasks with own prefix | Process other roles' prefix tasks |
| 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 directly executing analysis/testing/review.
### Message Bus
Call `mcp__ccw-tools__team_msg` with: operation="log", session_id=<session-id>, from=<role>, type=<type>, data={ref: "<file_path>"}
`to` and `summary` auto-defaulted -- do NOT specify explicitly.
**CLI Fallback**: `ccw team log --session-id "<session-id>" --from "<role>" --type "<type>" --json`
| Role | Message Types |
|------|---------------|
| coordinator | `sprint_started`, `gc_loop_trigger`, `sprint_complete`, `task_unblocked`, `error`, `shutdown`, `conflict_detected`, `conflict_resolved`, `resource_locked`, `resource_unlocked`, `resource_contention`, `rollback_initiated`, `rollback_completed`, `rollback_failed`, `dependency_mismatch`, `dependency_update_needed`, `context_checkpoint_saved`, `context_restored`, `user_feedback_received`, `tech_debt_identified` |
| architect | `design_ready`, `design_revision`, `error` |
| developer | `dev_complete`, `dev_progress`, `error` |
| tester | `verify_passed`, `verify_failed`, `fix_required`, `error` |
| reviewer | `review_passed`, `review_revision`, `review_critical`, `error` |
### Team Configuration
| Setting | Value |
|---------|-------|
| Team name | iterdev |
| Session directory | `.workflow/.team/IDS-{slug}-{date}/` |
| State sharing | team_msg(type='state_update') + .msg/meta.json |
| Task ledger file | task-ledger.json |
---
## Coordinator Protocol Summary
The coordinator manages several operational protocols. Full implementations reside in [roles/coordinator.md](roles/coordinator.md). The tables below describe the behavioral contracts for each protocol.
> **NOTE**: These are behavioral specifications only. Full procedural logic, data format details, and edge case handling are defined in the coordinator role file.
### Resource Lock Protocol
Concurrency control for shared resources. Prevents multiple workers from modifying the same files simultaneously.
| Action | Trigger Condition | Coordinator Behavior |
|--------|-------------------|----------------------|
| Acquire lock | Worker requests exclusive access to a resource | Check `resource_locks` via team_msg(type='state_update'). If unlocked, record lock with task ID, timestamp, and holder role. Log `resource_locked` message. Return success. |
| Deny lock | Resource already locked by another task | Return failure with current holder's task ID. Log `resource_contention` message. Worker must wait or request alternative resource. |
| Release lock | Worker completes task or explicitly releases | Remove lock entry from `resource_locks`. Log `resource_unlocked` message to all workers. |
| Force release | Lock held beyond timeout (5 min) | Force-remove lock entry. Notify original holder and coordinator. Log warning. |
| Deadlock detection | Multiple tasks waiting on each other's locks | Abort youngest task, release its locks, notify coordinator. |
### Conflict Detection Protocol
Detects and resolves file-level conflicts between concurrent development tasks.
| Action | Trigger Condition | Coordinator Behavior |
|--------|-------------------|----------------------|
| Detect conflict | DEV task completes with changed files | Compare changed files against other in_progress/completed tasks in ledger. If overlap found, update task's `conflict_info` to status "detected" with conflicting file list. Log `conflict_detected` message. |
| Resolve conflict | Conflict detected requiring resolution | Set `conflict_info.resolution_strategy` (manual/auto_merge/abort). Create `{taskId}-fix-conflict` task assigned to developer. Log `conflict_resolved` message. |
| Skip (no conflict) | No file overlap with other tasks | No action needed, task proceeds normally. |
### Rollback Point Protocol
Manages state snapshots for safe recovery when tasks fail or produce undesirable results.
| Action | Trigger Condition | Coordinator Behavior |
|--------|-------------------|----------------------|
| Create rollback point | Task successfully completes a phase | Generate snapshot ID, record rollback procedure (default: `git revert HEAD`) and state reference in task's `rollback_info` in the ledger. |
| Execute rollback | Task failure or user-requested revert | Log `rollback_initiated`. Execute stored rollback procedure. On success, log `rollback_completed`. On failure, log `rollback_failed` with error details. |
| Validate snapshot | Before executing rollback | Verify snapshot ID exists and rollback procedure is valid. Abort with error if invalid. |
### Dependency Validation Protocol
Validates external dependencies (npm, pip, etc.) before task execution begins.
| Action | Trigger Condition | Coordinator Behavior |
|--------|-------------------|----------------------|
| Validate dependencies | Task startup with declared dependencies | For each dependency: check installed version against expected version range. Record results in task's `external_dependencies` array in ledger (status: ok/mismatch/missing). |
| Report mismatch | Any dependency has status mismatch or missing | Log `dependency_mismatch` message listing affected packages. Block task until resolved or user overrides. |
| Update notification | External dependency has important update available | Log `dependency_update_needed` message. Add to sprint backlog for consideration. |
### Checkpoint Management Protocol
Saves and restores task execution state for interruption recovery.
| Action | Trigger Condition | Coordinator Behavior |
|--------|-------------------|----------------------|
| Save checkpoint | Task reaches significant progress milestone | Store checkpoint in `task_checkpoints` via team_msg(type='state_update') with timestamp and state data pointer. Retain last 5 checkpoints per task. Log `context_checkpoint_saved`. |
| Restore checkpoint | Task resumes after interruption | Load latest checkpoint for task. Read state data from pointer path. Log `context_restored`. Return state data to worker. |
| Checkpoint not found | Resume requested but no checkpoints exist | Return failure with reason. Worker starts fresh from Phase 1. |
### User Feedback Protocol
Collects, categorizes, and tracks user feedback throughout the sprint.
| Action | Trigger Condition | Coordinator Behavior |
|--------|-------------------|----------------------|
| Receive feedback | User provides feedback (via AskUserQuestion or direct) | Create feedback item with ID (FB-xxx), severity, category, timestamp. Store in `user_feedback_items` via team_msg(type='state_update') (max 50 items). Log `user_feedback_received`. |
| Link to task | Feedback relates to specific task | Update feedback item's `source_task_id` and set status to "reviewed". |
| Triage feedback | New feedback with high/critical severity | Prioritize in next sprint planning. Create task if actionable. |
### Tech Debt Management Protocol
Identifies, tracks, and prioritizes technical debt discovered during development.
| Action | Trigger Condition | Coordinator Behavior |
|--------|-------------------|----------------------|
| Identify debt | Worker reports tech debt during development or review | Create debt item with ID (TD-xxx), category (code/design/test/documentation), severity, estimated effort. Store in `tech_debt_items` via team_msg(type='state_update'). Log `tech_debt_identified`. |
| Generate report | Sprint retrospective or user request | Aggregate debt items by severity and category. Report totals, open items, and in-progress items. |
| Prioritize debt | Sprint planning phase | Rank debt items by severity and priority. Recommend items for current sprint based on estimated effort and available capacity. |
| Resolve debt | Developer completes debt resolution task | Update debt item status to "resolved". Record resolution in sprint history. |
---
## Three-Pipeline Architecture
```
Patch (simple fix):
DEV-001 -> VERIFY-001
Sprint (standard feature):
DESIGN-001 -> DEV-001 -> [VERIFY-001 + REVIEW-001](parallel)
Multi-Sprint (large feature):
Sprint 1: DESIGN-001 -> DEV-001 -> DEV-002(incremental) -> VERIFY-001 -> DEV-fix -> REVIEW-001
Sprint 2: DESIGN-002(refined) -> DEV-003 -> VERIFY-002 -> REVIEW-002
...
```
### Generator-Critic Loop
developer <-> reviewer loop, max 3 rounds:
```
DEV -> REVIEW -> (if review.critical_count > 0 || review.score < 7)
-> DEV-fix -> REVIEW-2 -> (if still issues) -> DEV-fix-2 -> REVIEW-3
-> (max 3 rounds, then accept with warning)
```
### Multi-Sprint Dynamic Downgrade
If Sprint N metrics are strong (velocity >= expected, review avg >= 8), coordinator may downgrade Sprint N+1 from multi-sprint to sprint pipeline for efficiency.
### Cadence Control
**Beat Model**: Event-driven. Each beat = coordinator wakes -> processes -> spawns -> STOP.
```
Beat Cycle (single beat)
===========================================================
Event Coordinator Workers
-----------------------------------------------------------
callback/resume --> +- handleCallback -+
| mark completed |
| check pipeline |
+- handleSpawnNext -+
| find ready tasks |
| spawn workers ---+--> [Worker A] Phase 1-5
| (parallel OK) --+--> [Worker B] Phase 1-5
+- STOP (idle) -----+ |
|
callback <----------------------------------------+
(next beat) SendMessage + TaskUpdate(completed)
===========================================================
```
**Pipeline Beat Views**:
```
Patch (2 beats, strict serial)
----------------------------------------------------------
Beat 1 2
| |
DEV -> VERIFY
^ ^
pipeline pipeline
start done
Sprint (3 beats, with parallel window)
----------------------------------------------------------
Beat 1 2 3
| | +----+----+
DESIGN -> DEV --> VERIFY // REVIEW <- parallel window
+----+----+
pipeline
done
Multi-Sprint (N beats, iterative)
----------------------------------------------------------
Sprint 1:
Beat 1 2 3 4 5 6
| | | | +----+----+ |
DESIGN -> DEV -> DEV -> VERIFY // DEV-fix -> REVIEW
(incr) (GC loop)
Sprint 2: (refined pipeline based on Sprint 1 metrics)
Beat 7 8 9 10
| | | |
DESIGN -> DEV -> VERIFY -> REVIEW
```
**Checkpoints**:
| Trigger Condition | Location | Behavior |
|-------------------|----------|----------|
| GC loop exceeds max rounds | After REVIEW-3 | Stop iteration, accept with warning, record in shared memory |
| Sprint transition | End of Sprint N | Pause, retrospective, user confirms `resume` for Sprint N+1 |
| Pipeline stall | No ready + no running tasks | Check missing tasks, report blockedBy chain to user |
**Stall Detection** (coordinator `handleCheck`):
| Check | Condition | Resolution |
|-------|-----------|------------|
| Worker unresponsive | in_progress task with no callback | Report waiting task list, suggest user `resume` |
| Pipeline deadlock | No ready + no running + has pending | Inspect blockedBy dependency chain, report blockage |
| GC loop exceeded | DEV/REVIEW iteration > max_rounds (3) | Terminate loop, output latest review report |
---
## Task Metadata Registry
| Task ID | Role | Pipeline | Dependencies | Description |
|---------|------|----------|-------------|-------------|
| DESIGN-001 | architect | sprint/multi | (none) | Technical design and task breakdown |
| DEV-001 | developer | all | DESIGN-001 (sprint/multi) or (none for patch) | Code implementation |
| DEV-002 | developer | multi | DEV-001 | Incremental implementation |
| DEV-fix | developer | sprint/multi | REVIEW-* (GC loop trigger) | Fix issues from review |
| VERIFY-001 | tester | all | DEV-001 (or last DEV) | Test execution and fix cycles |
| REVIEW-001 | reviewer | sprint/multi | DEV-001 (or last DEV) | Code review and quality scoring |
---
## Wisdom Accumulation
Cross-sprint knowledge accumulation. Coordinator initializes `wisdom/` directory at session start. Equivalent to shared-memory sprint_history but structured for long-term learning.
**Directory**:
```
<session-folder>/wisdom/
+-- learnings.md # Patterns and insights
+-- decisions.md # Architecture and design decisions
+-- conventions.md # Codebase conventions
+-- issues.md # Known risks and issues
```
**Worker Loading** (Phase 2): Extract `Session: <path>` from task description, read wisdom directory files.
**Worker Contributing** (Phase 4/5): Write discoveries from current task into corresponding wisdom files.
**Shared Memory** (sprint-level learning, accumulated across sprints):
| Field | Purpose |
|-------|---------|
| `sprint_history[]` | Per-sprint: what_worked, what_failed, patterns_learned |
| `architecture_decisions[]` | Cross-sprint architecture decisions |
| `implementation_context[]` | Implementation patterns and context |
| `review_feedback_trends[]` | Review quality trends across sprints |
| `resource_locks{}` | Current resource lock state (see Resource Lock Protocol) |
| `task_checkpoints{}` | Task checkpoint data (see Checkpoint Management Protocol) |
| `user_feedback_items[]` | User feedback items (see User Feedback Protocol) |
| `tech_debt_items[]` | Tech debt tracking (see Tech Debt Management Protocol) |
---
## Task Ledger
Real-time tracking of all sprint task progress. Coordinator updates at each task state transition.
**Structure**:
| Field | Description |
|-------|-------------|
| `sprint_id` | Current sprint identifier |
| `sprint_goal` | Sprint objective |
| `tasks[]` | Array of task entries (see below) |
| `metrics` | Aggregated metrics: total, completed, in_progress, blocked, velocity |
**Task Entry Fields**:
| Field | Description |
|-------|-------------|
| `id` | Task identifier (e.g., DEV-001) |
| `title` | Task title |
| `owner` | Assigned role |
| `status` | pending / in_progress / completed / blocked |
| `started_at` / `completed_at` | Timestamps |
| `gc_rounds` | Generator-Critic iteration count |
| `review_score` | Reviewer score (null until reviewed) |
| `test_pass_rate` | Tester pass rate (null until tested) |
| `conflict_info` | Conflict state: status (none/detected/resolved), conflicting_files, resolution_strategy, resolved_by_task_id |
| `rollback_info` | Rollback state: snapshot_id, rollback_procedure, last_successful_state_id |
| `external_dependencies[]` | Dependency entries: name, version_range, actual_version, source, status (ok/mismatch/missing) |
---
## Coordinator Spawn Template
### v5 Worker Spawn (all roles)
When coordinator spawns workers, use `team-worker` agent with role-spec path:
Coordinator spawns workers using this template:
```
Agent({
@@ -420,7 +66,7 @@ Agent({
run_in_background: true,
prompt: `## Role Assignment
role: <role>
role_spec: .claude/skills/team-iterdev/role-specs/<role>.md
role_spec: .claude/skills/team-iterdev/roles/<role>/role.md
session: <session-folder>
session_id: <session-id>
team_name: iterdev
@@ -428,92 +74,54 @@ requirement: <task-description>
inner_loop: <true|false>
Read role_spec file to load Phase 2-4 domain instructions.
Execute built-in Phase 1 (task discovery) -> role-spec Phase 2-4 -> built-in Phase 5 (report).`
Execute built-in Phase 1 (task discovery) -> role Phase 2-4 -> built-in Phase 5 (report).`
})
```
**Inner Loop roles** (developer): Set `inner_loop: true`. The team-worker agent handles the loop internally.
## User Commands
**Single-task roles** (architect, tester, reviewer): Set `inner_loop: false`.
| Command | Action |
|---------|--------|
| `check` / `status` | View execution status graph |
| `resume` / `continue` | Advance to next step |
---
## Completion Action
When the pipeline completes (all tasks done, coordinator Phase 5):
## Session Directory
```
AskUserQuestion({
questions: [{
question: "IterDev pipeline complete. What would you like to do?",
header: "Completion",
multiSelect: false,
options: [
{ label: "Archive & Clean (Recommended)", description: "Archive session, clean up tasks and team resources" },
{ label: "Keep Active", description: "Keep session active for follow-up work or inspection" },
{ label: "Export Results", description: "Export deliverables to a specified location, then clean" }
]
}]
})
.workflow/.team/IDS-<slug>-<YYYY-MM-DD>/
├── .msg/
│ ├── messages.jsonl # Team message bus
│ └── meta.json # Session state
├── task-analysis.json # Coordinator analyze output
├── task-ledger.json # Real-time task progress ledger
├── wisdom/ # Cross-task knowledge accumulation
│ ├── learnings.md
│ ├── decisions.md
│ ├── conventions.md
│ └── issues.md
├── design/ # Architect output
│ ├── design-001.md
│ └── task-breakdown.json
├── code/ # Developer tracking
│ └── dev-log.md
├── verify/ # Tester output
│ └── verify-001.json
└── review/ # Reviewer output
└── review-001.md
```
| Choice | Action |
|--------|--------|
| Archive & Clean | Update session status="completed" -> TeamDelete() -> output final summary |
| Keep Active | Update session status="paused" -> output resume instructions: `Skill(skill="team-iterdev", args="resume")` |
| Export Results | AskUserQuestion for target path -> copy deliverables -> Archive & Clean |
## Specs Reference
---
## Unified Session Directory
```
.workflow/.team/IDS-{slug}-{YYYY-MM-DD}/
+-- .msg/meta.json
+-- .msg/messages.jsonl # Team message bus
+-- .msg/meta.json # Session metadata
+-- task-ledger.json # Real-time task progress ledger
+-- wisdom/ # Cross-task knowledge accumulation
| +-- learnings.md
| +-- decisions.md
| +-- conventions.md
| +-- issues.md
+-- design/ # Architect output
| +-- design-001.md
| +-- task-breakdown.json
+-- code/ # Developer tracking
| +-- dev-log.md
+-- verify/ # Tester output
| +-- verify-001.json
+-- review/ # Reviewer output
+-- review-001.md
```
## Session Resume
Coordinator supports `--resume` / `--continue` for interrupted sessions:
1. Scan `.workflow/.team/IDS-*/.msg/meta.json` for active/paused sessions
2. Multiple matches -> AskUserQuestion for selection
3. Audit TaskList -> reconcile session state with task status
4. Reset in_progress -> pending (interrupted tasks)
5. Rebuild team and spawn needed workers only
6. Create missing tasks with correct blockedBy
7. Kick first executable task -> Phase 4 coordination loop
- [specs/pipelines.md](specs/pipelines.md) — Pipeline definitions and task registry
## Error Handling
| Scenario | Resolution |
|----------|------------|
| Unknown --role value | Error with available role list |
| Missing --role arg | Orchestration Mode -> coordinator |
| Role file not found | Error with expected path |
| Unknown command | Error with available command list |
| Role not found | Error with role registry |
| GC loop exceeds 3 rounds | Accept with warning, record in shared memory |
| Sprint velocity drops below 50% | Coordinator alerts user, suggests scope reduction |
| Task ledger corrupted | Rebuild from TaskList state |
| Conflict detected | Update conflict_info, notify coordinator, create DEV-fix task |
| Resource lock timeout | Force release after 5 min, notify holder and coordinator |
| Rollback requested | Validate snapshot_id, execute rollback procedure, notify all |
| Deadlock detected | Abort youngest task, release its locks, notify coordinator |
| Dependency mismatch | Log mismatch, block task until resolved or user override |
| Checkpoint restore failure | Log error, worker restarts from Phase 1 |
| Pipeline deadlock | Check blockedBy chain, report blocking point |

65
.claude/skills/team-iterdev/roles/architect/role.md Normal file
View File

@@ -0,0 +1,65 @@
---
role: architect
prefix: DESIGN
inner_loop: false
message_types:
success: design_ready
revision: design_revision
error: error
---
# Architect
Technical design, task decomposition, and architecture decision records for iterative development.
## Phase 2: Context Loading + Codebase Exploration
| Input | Source | Required |
|-------|--------|----------|
| Task description | From task subject/description | Yes |
| Session path | Extracted from task description | Yes |
| .msg/meta.json | <session>/.msg/meta.json | No |
| Wisdom files | <session>/wisdom/ | No |
1. Extract session path and requirement from task description
2. Read .msg/meta.json for shared context (architecture_decisions, implementation_context)
3. Read wisdom files if available (learnings.md, decisions.md, conventions.md)
4. Explore codebase for existing patterns, module structure, dependencies:
- Use mcp__ace-tool__search_context for semantic discovery
- Identify similar implementations and integration points
## Phase 3: Technical Design + Task Decomposition
**Design strategy selection**:
| Condition | Strategy |
|-----------|----------|
| Single module change | Direct inline design |
| Cross-module change | Multi-component design with integration points |
| Large refactoring | Phased approach with milestones |
**Outputs**:
1. **Design Document** (`<session>/design/design-<num>.md`):
- Architecture decision: approach, rationale, alternatives
- Component design: responsibility, dependencies, files, complexity
- Task breakdown: files, estimated complexity, dependencies, acceptance criteria
- Integration points and risks with mitigations
2. **Task Breakdown JSON** (`<session>/design/task-breakdown.json`):
- Array of tasks with id, title, files, complexity, dependencies, acceptance_criteria
- Execution order for developer to follow
## Phase 4: Design Validation
| Check | Method | Pass Criteria |
|-------|--------|---------------|
| Components defined | Verify component list | At least 1 component |
| Task breakdown exists | Verify task list | At least 1 task |
| Dependencies mapped | All components have dependencies field | All present (can be empty) |
| Integration points | Verify integration section | Key integrations documented |
1. Run validation checks above
2. Write architecture_decisions entry to .msg/meta.json:
- design_id, approach, rationale, components, task_count
3. Write discoveries to wisdom/decisions.md and wisdom/conventions.md

62
.claude/skills/team-iterdev/roles/coordinator/commands/analyze.md Normal file
View File

@@ -0,0 +1,62 @@
# Analyze Task
Parse iterative development task -> detect capabilities -> assess pipeline complexity -> design roles.
**CONSTRAINT**: Text-level analysis only. NO source code reading, NO codebase exploration.
## Signal Detection
| Keywords | Capability | Role |
|----------|------------|------|
| design, architect, restructure, refactor plan | architect | architect |
| implement, build, code, fix, develop | developer | developer |
| test, verify, validate, coverage | tester | tester |
| review, audit, quality, check | reviewer | reviewer |
## Pipeline Selection
| Signal | Score |
|--------|-------|
| Changed files > 10 | +3 |
| Changed files 3-10 | +2 |
| Structural change (refactor, architect, restructure) | +3 |
| Cross-cutting (multiple, across, cross) | +2 |
| Simple fix (fix, bug, typo, patch) | -2 |
| Score | Pipeline |
|-------|----------|
| >= 5 | multi-sprint |
| 2-4 | sprint |
| 0-1 | patch |
## Dependency Graph
Natural ordering tiers:
- Tier 0: architect (design must come first)
- Tier 1: developer (implementation requires design)
- Tier 2: tester, reviewer (validation requires artifacts, can run parallel)
## Complexity Assessment
| Factor | Points |
|--------|--------|
| Cross-module changes | +2 |
| Serial depth > 3 | +1 |
| Multiple developers needed | +2 |
| GC loop likely needed | +1 |
## Output
Write <session>/task-analysis.json:
```json
{
"task_description": "<original>",
"pipeline_type": "<patch|sprint|multi-sprint>",
"capabilities": [{ "name": "<cap>", "role": "<role>", "keywords": ["..."] }],
"roles": [{ "name": "<role>", "prefix": "<PREFIX>", "inner_loop": false }],
"complexity": { "score": 0, "level": "Low|Medium|High" },
"needs_architecture": true,
"needs_testing": true,
"needs_review": true
}
```

26
.claude/skills/team-iterdev/roles/coordinator/commands/monitor.md
View File

@@ -1,15 +1,25 @@
# Command: Monitor
Handle all coordinator monitoring events: worker callbacks, status checks, pipeline advancement, Generator-Critic loop control (developer<->reviewer), and completion.
Event-driven pipeline coordination. Beat model: coordinator wake -> process -> spawn -> STOP.
## Constants
| Key | Value |
|-----|-------|
| SPAWN_MODE | background |
| ONE_STEP_PER_INVOCATION | true |
| WORKER_AGENT | team-worker |
| MAX_GC_ROUNDS | 3 |
- SPAWN_MODE: background
- ONE_STEP_PER_INVOCATION: true
- FAST_ADVANCE_AWARE: true
- WORKER_AGENT: team-worker
- MAX_GC_ROUNDS: 3
## Handler Router
| Source | Handler |
|--------|---------|
| Message contains [architect], [developer], [tester], [reviewer] | handleCallback |
| "capability_gap" | handleAdapt |
| "check" or "status" | handleCheck |
| "resume" or "continue" | handleResume |
| All tasks completed | handleComplete |
| Default | handleSpawnNext |
## Phase 2: Context Loading
@@ -91,7 +101,7 @@ Agent({
run_in_background: true,
prompt: `## Role Assignment
role: <role>
role_spec: .claude/skills/team-iterdev/role-specs/<role>.md
role_spec: .claude/skills/team-iterdev/roles/<role>/role.md
session: <session-folder>
session_id: <session-id>
team_name: iterdev

241
.claude/skills/team-iterdev/roles/coordinator/role.md
View File

@@ -1,15 +1,14 @@
# Coordinator - Iterative Development Team
# Coordinator Role
**Role**: coordinator
**Type**: Orchestrator
**Team**: iterdev
Orchestrate team-iterdev: analyze -> dispatch -> spawn -> monitor -> report.
Orchestrates the iterative development pipeline: sprint planning, task ledger maintenance, Generator-Critic loop control (developer<->reviewer, max 3 rounds), cross-sprint learning, and pipeline advancement.
## Identity
- Name: coordinator | Tag: [coordinator]
- Responsibility: Analyze task -> Create team -> Dispatch tasks -> Monitor progress -> Report results
## Boundaries
### MUST
- Use `team-worker` agent type for all worker spawns (NOT `general-purpose`)
- Follow Command Execution Protocol for dispatch and monitor commands
- Respect pipeline stage dependencies (blockedBy)
@@ -19,91 +18,47 @@ Orchestrates the iterative development pipeline: sprint planning, task ledger ma
- Execute completion action in Phase 5
### MUST NOT
- Implement domain logic (designing, coding, testing, reviewing) -- workers handle this
- Spawn workers without creating tasks first
- Write source code directly
- Force-advance pipeline past failed review/validation
- Modify task outputs (workers own their deliverables)
---
## Command Execution Protocol
When coordinator needs to execute a command (dispatch, monitor):
1. **Read the command file**: `roles/coordinator/commands/<command-name>.md`
2. **Follow the workflow** defined in the command file (Phase 2-4 structure)
3. **Commands are inline execution guides** -- NOT separate agents or subprocesses
4. **Execute synchronously** -- complete the command workflow before proceeding
Example:
```
Phase 3 needs task dispatch
-> Read roles/coordinator/commands/dispatch.md
-> Execute Phase 2 (Context Loading)
-> Execute Phase 3 (Task Chain Creation)
-> Execute Phase 4 (Validation)
-> Continue to Phase 4
```
---
When coordinator needs to execute a command:
1. Read `commands/<command>.md`
2. Follow the workflow defined in the command
3. Commands are inline execution guides, NOT separate agents
4. Execute synchronously, complete before proceeding
## Entry Router
When coordinator is invoked, detect invocation type:
| Detection | Condition | Handler |
|-----------|-----------|---------|
| Worker callback | Message contains role tag [architect], [developer], [tester], [reviewer] | -> handleCallback |
| Status check | Arguments contain "check" or "status" | -> handleCheck |
| Manual resume | Arguments contain "resume" or "continue" | -> handleResume |
| Pipeline complete | All tasks have status "completed" | -> handleComplete |
| Interrupted session | Active/paused session exists | -> Phase 0 (Resume Check) |
| New session | None of above | -> Phase 1 (Requirement Clarification) |
| Worker callback | Message contains [architect], [developer], [tester], [reviewer] | -> handleCallback (monitor.md) |
| Status check | Args contain "check" or "status" | -> handleCheck (monitor.md) |
| Manual resume | Args contain "resume" or "continue" | -> handleResume (monitor.md) |
| Pipeline complete | All tasks completed | -> handleComplete (monitor.md) |
| Interrupted session | Active/paused session in .workflow/.team/IDS-* | -> Phase 0 |
| New session | None of above | -> Phase 1 |
For callback/check/resume/complete: load `commands/monitor.md` and execute matched handler, then STOP.
### Router Implementation
1. **Load session context** (if exists):
- Scan `.workflow/.team/IDS-*/.msg/meta.json` for active/paused sessions
- If found, extract session folder path, status, and pipeline mode
2. **Parse $ARGUMENTS** for detection keywords:
- Check for role name tags in message content
- Check for "check", "status", "resume", "continue" keywords
3. **Route to handler**:
- For monitor handlers: Read `commands/monitor.md`, execute matched handler, STOP
- For Phase 0: Execute Session Resume Check below
- For Phase 1: Execute Requirement Clarification below
---
For callback/check/resume/complete: load commands/monitor.md, execute handler, STOP.
## Phase 0: Session Resume Check
Triggered when an active/paused session is detected on coordinator entry.
1. Load session.json from detected session folder
2. Audit task list: `TaskList()`
3. Reconcile session state vs task status:
| Task Status | Session Expects | Action |
|-------------|----------------|--------|
| in_progress | Should be running | Reset to pending (worker was interrupted) |
| completed | Already tracked | Skip |
| pending + unblocked | Ready to run | Include in spawn list |
4. Rebuild team if not active: `TeamCreate({ team_name: "iterdev" })`
5. Spawn workers for ready tasks -> Phase 4 coordination loop
---
1. Scan `.workflow/.team/IDS-*/.msg/meta.json` for active/paused sessions
2. No sessions -> Phase 1
3. Single session -> reconcile (audit TaskList, reset in_progress->pending, rebuild team, kick first ready task)
4. Multiple -> AskUserQuestion for selection
## Phase 1: Requirement Clarification
TEXT-LEVEL ONLY. No source code reading.
1. Parse user task description from $ARGUMENTS
2. Assess complexity for pipeline selection:
2. Delegate to commands/analyze.md
3. Assess complexity for pipeline selection:
| Signal | Weight |
|--------|--------|
@@ -119,58 +74,27 @@ Triggered when an active/paused session is detected on coordinator entry.
| 2-4 | sprint |
| 0-1 | patch |
3. Ask for missing parameters via AskUserQuestion (mode selection)
4. Record requirement with scope, pipeline mode
---
4. Ask for missing parameters via AskUserQuestion (mode selection)
5. Record requirement with scope, pipeline mode
6. CRITICAL: Always proceed to Phase 2, never skip team workflow
## Phase 2: Session & Team Setup
1. Generate session ID: `IDS-{slug}-{YYYY-MM-DD}`
1. Generate session ID: `IDS-<slug>-<YYYY-MM-DD>`
2. Create session folder structure:
```
Bash("mkdir -p .workflow/.team/<session-id>/design .workflow/.team/<session-id>/code .workflow/.team/<session-id>/verify .workflow/.team/<session-id>/review .workflow/.team/<session-id>/wisdom")
mkdir -p .workflow/.team/<session-id>/{design,code,verify,review,wisdom}
```
3. Create team: `TeamCreate({ team_name: "iterdev" })`
4. Initialize wisdom directory (learnings.md, decisions.md, conventions.md, issues.md)
5. Write session.json:
```json
{
"status": "active",
"team_name": "iterdev",
"requirement": "<requirement>",
"pipeline": "<patch|sprint|multi-sprint>",
"timestamp": "<ISO-8601>",
"gc_round": 0,
"max_gc_rounds": 3,
"fix_cycles": {}
}
```
6. Initialize task-ledger.json:
```json
{
"sprint_id": "sprint-1",
"sprint_goal": "<task-description>",
"pipeline": "<selected-pipeline>",
"tasks": [],
"metrics": { "total": 0, "completed": 0, "in_progress": 0, "blocked": 0, "velocity": 0 }
}
```
7. Initialize meta.json with pipeline metadata:
4. Read specs/pipelines.md -> select pipeline based on complexity
5. Initialize wisdom directory (learnings.md, decisions.md, conventions.md, issues.md)
6. Write session.json
7. Initialize task-ledger.json
8. Initialize meta.json with pipeline metadata:
```typescript
// Use team_msg to write pipeline metadata to .msg/meta.json
mcp__ccw-tools__team_msg({
operation: "log",
session_id: "<session-id>",
from: "coordinator",
type: "state_update",
summary: "Session initialized",
operation: "log", session_id: "<id>", from: "coordinator",
type: "state_update", summary: "Session initialized",
data: {
pipeline_mode: "<patch|sprint|multi-sprint>",
pipeline_stages: ["architect", "developer", "tester", "reviewer"],
@@ -180,56 +104,20 @@ mcp__ccw-tools__team_msg({
})
```
---
## Phase 3: Task Chain Creation
Execute `commands/dispatch.md` inline (Command Execution Protocol):
Delegate to commands/dispatch.md:
1. Read specs/pipelines.md for selected pipeline task registry
2. Create tasks via TaskCreate with blockedBy
3. Update task-ledger.json
1. Read `roles/coordinator/commands/dispatch.md`
2. Follow dispatch Phase 2 (context loading) -> Phase 3 (task chain creation) -> Phase 4 (validation)
3. Result: all pipeline tasks created with correct blockedBy dependencies
## Phase 4: Spawn-and-Stop
---
## Phase 4: Spawn & Coordination Loop
### Initial Spawn
Find first unblocked task and spawn its worker:
```
Agent({
subagent_type: "team-worker",
description: "Spawn <role> worker",
team_name: "iterdev",
name: "<role>",
run_in_background: true,
prompt: `## Role Assignment
role: <role>
role_spec: .claude/skills/team-iterdev/role-specs/<role>.md
session: <session-folder>
session_id: <session-id>
team_name: iterdev
requirement: <task-description>
inner_loop: <true|false>
Read role_spec file to load Phase 2-4 domain instructions.
Execute built-in Phase 1 (task discovery) -> role-spec Phase 2-4 -> built-in Phase 5 (report).`
})
```
**STOP** after spawning. Wait for worker callback.
### Coordination (via monitor.md handlers)
All subsequent coordination is handled by `commands/monitor.md` handlers triggered by worker callbacks:
- handleCallback -> mark task done -> check pipeline -> handleSpawnNext
- handleSpawnNext -> find ready tasks -> spawn team-worker agents -> STOP
- handleComplete -> all done -> Phase 5
---
Delegate to commands/monitor.md#handleSpawnNext:
1. Find ready tasks (pending + blockedBy resolved)
2. Spawn team-worker agents (see SKILL.md Spawn Template)
3. Output status summary
4. STOP
## Phase 5: Report + Completion Action
@@ -245,27 +133,18 @@ All subsequent coordination is handled by `commands/monitor.md` handlers trigger
| Verification Results | <session>/verify/verify-001.json |
| Review Report | <session>/review/review-001.md |
4. **Completion Action** (interactive):
4. Execute completion action per session.completion_action:
- interactive -> AskUserQuestion (Archive/Keep/Export)
- auto_archive -> Archive & Clean (status=completed, TeamDelete)
- auto_keep -> Keep Active (status=paused)
```
AskUserQuestion({
questions: [{
question: "Team pipeline complete. What would you like to do?",
header: "Completion",
multiSelect: false,
options: [
{ label: "Archive & Clean (Recommended)", description: "Archive session, clean up tasks and team resources" },
{ label: "Keep Active", description: "Keep session active for follow-up work or inspection" },
{ label: "Export Results", description: "Export deliverables to a specified location, then clean" }
]
}]
})
```
## Error Handling
5. Handle user choice:
| Choice | Steps |
|--------|-------|
| Archive & Clean | TaskList -> verify all completed -> update session status="completed" -> TeamDelete() -> output final summary |
| Keep Active | Update session status="paused" -> output: "Session paused. Resume with: Skill(skill='team-iterdev', args='resume')" |
| Export Results | AskUserQuestion for target directory -> copy all artifacts -> Archive & Clean flow |
| Error | Resolution |
|-------|------------|
| Task too vague | AskUserQuestion for clarification |
| Session corruption | Attempt recovery, fallback to manual |
| Worker crash | Reset task to pending, respawn |
| GC loop exceeds 3 rounds | Accept with warning, record in shared memory |
| Sprint velocity drops below 50% | Alert user, suggest scope reduction |
| Task ledger corrupted | Rebuild from TaskList state |

74
.claude/skills/team-iterdev/roles/developer/role.md Normal file
View File

@@ -0,0 +1,74 @@
---
role: developer
prefix: DEV
inner_loop: true
message_types:
success: dev_complete
progress: dev_progress
error: error
---
# Developer
Code implementer. Implements code according to design, incremental delivery. Acts as Generator in Generator-Critic loop (paired with reviewer).
## Phase 2: Context Loading
| Input | Source | Required |
|-------|--------|----------|
| Task description | From task subject/description | Yes |
| Session path | Extracted from task description | Yes |
| .msg/meta.json | <session>/.msg/meta.json | Yes |
| Design document | <session>/design/design-001.md | For non-fix tasks |
| Task breakdown | <session>/design/task-breakdown.json | For non-fix tasks |
| Review feedback | <session>/review/*.md | For fix tasks |
| Wisdom files | <session>/wisdom/ | No |
1. Extract session path from task description
2. Read .msg/meta.json for shared context
3. Detect task type:
| Task Type | Detection | Loading |
|-----------|-----------|---------|
| Fix task | Subject contains "fix" | Read latest review file for feedback |
| Normal task | No "fix" in subject | Read design document + task breakdown |
4. Load previous implementation_context from .msg/meta.json
5. Read wisdom files for conventions and known issues
## Phase 3: Code Implementation
**Implementation strategy selection**:
| Task Count | Complexity | Strategy |
|------------|------------|----------|
| <= 2 tasks | Low | Direct: inline Edit/Write |
| 3-5 tasks | Medium | Single agent: one code-developer for all |
| > 5 tasks | High | Batch agent: group by module, one agent per batch |
**Fix Task Mode** (GC Loop):
- Focus on review feedback items only
- Fix critical issues first, then high, then medium
- Do NOT change code that was not flagged
- Maintain existing code style and patterns
**Normal Task Mode**:
- Read target files, apply changes using Edit or Write
- Follow execution order from task breakdown
- Validate syntax after each major change
## Phase 4: Self-Validation
| Check | Method | Pass Criteria |
|-------|--------|---------------|
| Syntax | tsc --noEmit or equivalent | No errors |
| File existence | Verify all planned files exist | All files present |
| Import resolution | Check no broken imports | All imports resolve |
1. Run syntax check: `tsc --noEmit` / `python -m py_compile` / equivalent
2. Auto-fix if validation fails (max 2 attempts)
3. Write dev log to `<session>/code/dev-log.md`:
- Changed files count, syntax status, fix task flag, file list
4. Update implementation_context in .msg/meta.json:
- task, changed_files, is_fix, syntax_clean
5. Write discoveries to wisdom/learnings.md

66
.claude/skills/team-iterdev/roles/reviewer/role.md Normal file
View File

@@ -0,0 +1,66 @@
---
role: reviewer
prefix: REVIEW
inner_loop: false
message_types:
success: review_passed
revision: review_revision
critical: review_critical
error: error
---
# Reviewer
Code reviewer. Multi-dimensional review, quality scoring, improvement suggestions. Acts as Critic in Generator-Critic loop (paired with developer).
## Phase 2: Context Loading
| Input | Source | Required |
|-------|--------|----------|
| Task description | From task subject/description | Yes |
| Session path | Extracted from task description | Yes |
| .msg/meta.json | <session>/.msg/meta.json | Yes |
| Design document | <session>/design/design-001.md | For requirements alignment |
| Changed files | Git diff | Yes |
1. Extract session path from task description
2. Read .msg/meta.json for shared context and previous review_feedback_trends
3. Read design document for requirements alignment
4. Get changed files via git diff, read file contents (limit 20 files)
## Phase 3: Multi-Dimensional Review
**Review dimensions**:
| Dimension | Weight | Focus Areas |
|-----------|--------|-------------|
| Correctness | 30% | Logic correctness, boundary handling |
| Completeness | 25% | Coverage of design requirements |
| Maintainability | 25% | Readability, code style, DRY |
| Security | 20% | Vulnerabilities, input validation |
Per-dimension: scan modified files, record findings with severity (CRITICAL/HIGH/MEDIUM/LOW), include file:line references and suggestions.
**Scoring**: Weighted average of dimension scores (1-10 each).
**Output review report** (`<session>/review/review-<num>.md`):
- Files reviewed count, quality score, issue counts by severity
- Per-finding: severity, file:line, dimension, description, suggestion
- Scoring breakdown by dimension
- Signal: CRITICAL / REVISION_NEEDED / APPROVED
- Design alignment notes
## Phase 4: Trend Analysis + Verdict
1. Compare with previous review_feedback_trends from .msg/meta.json
2. Identify recurring issues, improvement areas, new issues
| Verdict Condition | Message Type |
|-------------------|--------------|
| criticalCount > 0 | review_critical |
| score < 7 | review_revision |
| else | review_passed |
3. Update review_feedback_trends in .msg/meta.json:
- review_id, score, critical count, high count, dimensions, gc_round
4. Write discoveries to wisdom/learnings.md

88
.claude/skills/team-iterdev/roles/tester/role.md Normal file
View File

@@ -0,0 +1,88 @@
---
role: tester
prefix: VERIFY
inner_loop: false
message_types:
success: verify_passed
failure: verify_failed
fix: fix_required
error: error
---
# Tester
Test validator. Test execution, fix cycles, and regression detection.
## Phase 2: Environment Detection
| Input | Source | Required |
|-------|--------|----------|
| Task description | From task subject/description | Yes |
| Session path | Extracted from task description | Yes |
| .msg/meta.json | <session>/.msg/meta.json | Yes |
| Changed files | Git diff | Yes |
1. Extract session path from task description
2. Read .msg/meta.json for shared context
3. Get changed files via git diff
4. Detect test framework and command:
| Detection | Method |
|-----------|--------|
| Test command | Check package.json scripts, pytest.ini, Makefile |
| Coverage tool | Check for nyc, coverage.py, jest --coverage config |
Common commands: npm test, pytest, go test ./..., cargo test
## Phase 3: Execution + Fix Cycle
**Iterative test-fix cycle** (max 5 iterations):
| Step | Action |
|------|--------|
| 1 | Run test command |
| 2 | Parse results, check pass rate |
| 3 | Pass rate >= 95% -> exit loop (success) |
| 4 | Extract failing test details |
| 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**: 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
1. Run full test suite for regression: `<test-command> --all`
| Check | Method | Pass Criteria |
|-------|--------|---------------|
| Regression | Run full test suite | No FAIL in output |
| Coverage | Run coverage tool | >= 80% (if configured) |
2. Write verification results to `<session>/verify/verify-<num>.json`:
- verify_id, pass_rate, iterations, passed, timestamp, regression_passed
3. Determine message type:
| Condition | Message Type |
|-----------|--------------|
| passRate >= 0.95 | verify_passed |
| passRate < 0.95 && iterations >= MAX | fix_required |
| passRate < 0.95 | verify_failed |
4. Update .msg/meta.json with test_patterns entry
5. Write discoveries to wisdom/issues.md

94
.claude/skills/team-iterdev/specs/pipelines.md Normal file
View File

@@ -0,0 +1,94 @@
# IterDev Pipeline Definitions
## Three-Pipeline Architecture
### Patch Pipeline (2 beats, serial)
```
DEV-001 -> VERIFY-001
[developer] [tester]
```
### Sprint Pipeline (4 beats, with parallel window)
```
DESIGN-001 -> DEV-001 -> [VERIFY-001 + REVIEW-001] (parallel)
[architect] [developer] [tester] [reviewer]
```
### Multi-Sprint Pipeline (N beats, iterative)
```
Sprint 1: DESIGN-001 -> DEV-001 -> DEV-002(incremental) -> VERIFY-001 -> DEV-fix -> REVIEW-001
Sprint 2: DESIGN-002(refined) -> DEV-003 -> VERIFY-002 -> REVIEW-002
...
```
## Generator-Critic Loop (developer <-> reviewer)
```
DEV -> REVIEW -> (if review.critical_count > 0 || review.score < 7)
-> DEV-fix -> REVIEW-2 -> (if still issues) -> DEV-fix-2 -> REVIEW-3
-> (max 3 rounds, then accept with warning)
```
## Pipeline Selection Logic
| Signal | Score |
|--------|-------|
| Changed files > 10 | +3 |
| Changed files 3-10 | +2 |
| Structural change | +3 |
| Cross-cutting concern | +2 |
| Simple fix | -2 |
| Score | Pipeline |
|-------|----------|
| >= 5 | multi-sprint |
| 2-4 | sprint |
| 0-1 | patch |
## Task Metadata Registry
| Task ID | Role | Pipeline | Dependencies | Description |
|---------|------|----------|-------------|-------------|
| DESIGN-001 | architect | sprint/multi | (none) | Technical design and task breakdown |
| DEV-001 | developer | all | DESIGN-001 (sprint/multi) or (none for patch) | Code implementation |
| DEV-002 | developer | multi | DEV-001 | Incremental implementation |
| DEV-fix | developer | sprint/multi | REVIEW-* (GC loop trigger) | Fix issues from review |
| VERIFY-001 | tester | all | DEV-001 (or last DEV) | Test execution and fix cycles |
| REVIEW-001 | reviewer | sprint/multi | DEV-001 (or last DEV) | Code review and quality scoring |
## Checkpoints
| Trigger Condition | Location | Behavior |
|-------------------|----------|----------|
| GC loop exceeds max rounds | After REVIEW-3 | Stop iteration, accept with warning, record in wisdom |
| Sprint transition | End of Sprint N | Pause, retrospective, user confirms `resume` for Sprint N+1 |
| Pipeline stall | No ready + no running tasks | Check missing tasks, report blockedBy chain to user |
## Multi-Sprint Dynamic Downgrade
If Sprint N metrics are strong (velocity >= expected, review avg >= 8), coordinator may downgrade Sprint N+1 from multi-sprint to sprint pipeline for efficiency.
## Task Ledger Schema
| Field | Description |
|-------|-------------|
| `sprint_id` | Current sprint identifier |
| `sprint_goal` | Sprint objective |
| `tasks[]` | Array of task entries |
| `metrics` | Aggregated metrics: total, completed, in_progress, blocked, velocity |
**Task Entry Fields**:
| Field | Description |
|-------|-------------|
| `id` | Task identifier |
| `title` | Task title |
| `owner` | Assigned role |
| `status` | pending / in_progress / completed / blocked |
| `started_at` / `completed_at` | Timestamps |
| `gc_rounds` | Generator-Critic iteration count |
| `review_score` | Reviewer score (null until reviewed) |
| `test_pass_rate` | Tester pass rate (null until tested) |

46
.claude/skills/team-lifecycle-v2/CHANGELOG.md
View File

@@ -1,46 +0,0 @@
# Changelog
## v2.1 - Architecture Fix (2026-03-05)
### Fixed
- **Critical**: Removed subagent calls from worker role-specs
- Workers now correctly use CLI tools instead of attempting Agent() spawn
- Removed subagents directory (workers cannot use it)
- Updated SKILL.md to clarify architectural constraints
### Changed
- Multi-perspective critique: Now uses parallel CLI calls
- Codebase exploration: Now uses `ccw cli --tool gemini`
- Document generation: Now uses `ccw cli --tool gemini --mode write`
### Impact
- No functional change for users
- Implementation now architecturally correct
- Workers will no longer fail with "Unknown skill: Agent"
### Files Modified
- `SKILL.md`: Replaced "Subagent Registry" with "CLI Tool Usage in Workers"
- `role-specs/analyst.md`: Removed `subagents: [discuss]`, replaced discuss subagent call with parallel CLI calls
- `role-specs/writer.md`: Removed `subagents: [discuss]`, replaced discuss subagent call with parallel CLI calls
- `role-specs/reviewer.md`: Removed `subagents: [discuss]`, replaced discuss subagent call with parallel CLI calls
- `role-specs/planner.md`: Updated complexity routing table to reference CLI exploration
- `role-specs/architect.md`: Removed `subagents: [explore]`
- `subagents/`: Directory removed
### Technical Details
**Why Workers Cannot Spawn Subagents**:
When a worker attempts `Agent()`, it fails with "Unknown skill: Agent". Only the Coordinator (main conversation context) can spawn agents.
**Worker Capabilities**:
- ✅ Built-in tools: Read, Write, Edit, Bash, Grep, Glob
- ✅ CLI tools: `ccw cli --tool gemini/codex/qwen`
- ❌ Agent spawn: Cannot call `Agent()` to spawn subagents
**Multi-Perspective Critique Implementation**:
Workers now use parallel CLI calls with `run_in_background: true`:
```bash
Bash(`ccw cli -p "..." --tool gemini --mode analysis`, { run_in_background: true })
Bash(`ccw cli -p "..." --tool codex --mode analysis`, { run_in_background: true })
Bash(`ccw cli -p "..." --tool claude --mode analysis`, { run_in_background: true })
```

295
.claude/skills/team-lifecycle-v2/SKILL.md
View File

@@ -1,295 +0,0 @@
---
name: team-lifecycle-v2
description: Optimized team skill for full lifecycle. Reduced discuss (6→3), progressive spec refinement preserved. team-worker agent architecture. Triggers on "team lifecycle v2".
allowed-tools: TeamCreate(*), TeamDelete(*), SendMessage(*), TaskCreate(*), TaskUpdate(*), TaskList(*), TaskGet(*), Agent(*), AskUserQuestion(*), Read(*), Write(*), Edit(*), Bash(*), Glob(*), Grep(*)
---
# Team Lifecycle v2
Optimized lifecycle: specification → implementation → testing → review. Built on **team-worker agent architecture**. Key optimization: discuss rounds reduced from 6 to 3 (direction, requirements, final gate).
## Architecture
```
+---------------------------------------------------+
| Skill(skill="team-lifecycle-v2") |
| args="task description" |
+-------------------+-------------------------------+
|
Orchestration Mode (auto -> coordinator)
|
Coordinator (inline)
Phase 0-5 orchestration
|
+----+-----+-------+-------+-------+-------+
v v v v v v v
[team-worker agents, each loaded with a role-spec]
analyst writer planner executor tester reviewer
^ ^
on-demand by coordinator
+---------+ +--------+
|architect| |fe-dev |
+---------+ +--------+
+--------+
| fe-qa |
+--------+
⚠️ ARCHITECTURAL CONSTRAINT: Workers CANNOT spawn subagents.
Workers use CLI tools for complex analysis (see "CLI Tool Usage in Workers" section).
```
## Role Router
Coordinator-only. Workers spawned as `team-worker` agents.
### Role Registry
| Role | Spec | Task Prefix | Type | Inner Loop |
|------|------|-------------|------|------------|
| coordinator | [roles/coordinator/role.md](roles/coordinator/role.md) | (none) | orchestrator | - |
| analyst | [role-specs/analyst.md](role-specs/analyst.md) | RESEARCH-* | pipeline | false |
| writer | [role-specs/writer.md](role-specs/writer.md) | DRAFT-* | pipeline | true |
| planner | [role-specs/planner.md](role-specs/planner.md) | PLAN-* | pipeline | true |
| executor | [role-specs/executor.md](role-specs/executor.md) | IMPL-* | pipeline | true |
| tester | [role-specs/tester.md](role-specs/tester.md) | TEST-* | pipeline | false |
| reviewer | [role-specs/reviewer.md](role-specs/reviewer.md) | REVIEW-* + QUALITY-* + IMPROVE-* | pipeline | false |
| architect | [role-specs/architect.md](role-specs/architect.md) | ARCH-* | consulting | false |
| 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 |
### CLI Tool Usage in Workers
**⚠️ ARCHITECTURAL CONSTRAINT**: Workers CANNOT call Agent() to spawn subagents.
Workers must use CLI tools for complex analysis.
| Capability | CLI Command | Used By |
|------------|-------------|---------|
| Multi-perspective critique | `ccw cli --tool gemini --mode analysis` (parallel calls) | analyst, writer, reviewer |
| Codebase exploration | `ccw cli --tool gemini --mode analysis` | analyst, planner |
| Document generation | `ccw cli --tool gemini --mode write` | writer |
### Coordinator-Only Utilities
If Coordinator needs utility members for team-level orchestration, it can spawn them.
Workers cannot spawn utility members.
### Dispatch
Always route to coordinator. Coordinator reads `roles/coordinator/role.md`.
### Orchestration Mode
**Invocation**: `Skill(skill="team-lifecycle-v2", args="task description")`
**Lifecycle**:
```
User provides task description
-> coordinator Phase 1-3: clarify -> TeamCreate -> create task chain
-> coordinator Phase 4: spawn first batch workers (background) -> STOP
-> Worker executes -> SendMessage callback -> coordinator advances
-> Loop until pipeline complete -> Phase 5 report
```
**User Commands**:
| Command | Action |
|---------|--------|
| `check` / `status` | Output execution status, no advancement |
| `resume` / `continue` | Check worker states, advance next step |
| `revise <TASK-ID> [feedback]` | Create revision task + cascade downstream |
| `feedback <text>` | Analyze feedback, create targeted revision |
| `recheck` | Re-run QUALITY-001 quality check |
| `improve [dimension]` | Auto-improve weakest dimension |
---
## Coordinator Spawn Template
```
Agent({
subagent_type: "team-worker",
description: "Spawn <role> worker",
team_name: <team-name>,
name: "<role>",
run_in_background: true,
prompt: `## Role Assignment
role: <role>
role_spec: .claude/skills/team-lifecycle-v2/role-specs/<role>.md
session: <session-folder>
session_id: <session-id>
team_name: <team-name>
requirement: <task-description>
inner_loop: <true|false>
Read role_spec file to load Phase 2-4 domain instructions.
Execute built-in Phase 1 (task discovery) -> role-spec Phase 2-4 -> built-in Phase 5 (report).`
})
```
---
## Pipeline Definitions
### Spec-only (6 tasks, 3 discuss)
```
RESEARCH-001(+D1) -> DRAFT-001 -> DRAFT-002(+D2) -> DRAFT-003 -> DRAFT-004 -> QUALITY-001(+D3)
```
Note: DRAFT-001, DRAFT-003, DRAFT-004 use self-validation only (no discuss).
### Impl-only (4 tasks)
```
PLAN-001 -> IMPL-001 -> TEST-001 + REVIEW-001
```
### Full-lifecycle (10 tasks)
```
[Spec pipeline] -> PLAN-001(blockedBy: QUALITY-001) -> IMPL-001 -> TEST-001 + REVIEW-001
```
### Frontend Pipelines
```
FE-only: PLAN-001 -> DEV-FE-001 -> QA-FE-001
(GC loop: max 2 rounds)
Fullstack: PLAN-001 -> IMPL-001 || DEV-FE-001 -> TEST-001 || QA-FE-001 -> REVIEW-001
Full + FE: [Spec pipeline] -> PLAN-001 -> IMPL-001 || DEV-FE-001 -> TEST-001 || QA-FE-001 -> REVIEW-001
```
### Cadence Control
**Beat model**: Event-driven, each beat = coordinator wake -> process -> spawn -> STOP.
```
Beat Cycle
======================================================================
Event Coordinator Workers
----------------------------------------------------------------------
callback/resume --> +- handleCallback -+
| mark completed |
| check pipeline |
+- handleSpawnNext -+
| find ready tasks |
| spawn workers ---+--> [team-worker] Phase 1-5
+- STOP (idle) -----+ |
|
callback <-----------------------------------------+
Fast-Advance (skips coordinator for simple linear successors)
======================================================================
[Worker A] Phase 5 complete
+- 1 ready task? simple successor?
| --> spawn team-worker B directly
| --> log fast_advance to message bus
+- complex case? --> SendMessage to coordinator
======================================================================
```
### Checkpoints
| Trigger | Position | Behavior |
|---------|----------|----------|
| Spec->Impl transition | QUALITY-001 completed | Display checkpoint, pause for user |
| GC loop max | QA-FE max 2 rounds | Stop iteration, report |
| Pipeline stall | No ready + no running | Report to user |
**Checkpoint Output Template** (QUALITY-001):
```
[coordinator] ══════════════════════════════════════════
[coordinator] SPEC PHASE COMPLETE
[coordinator] Quality Gate: <PASS|REVIEW|FAIL> (<score>%)
[coordinator]
[coordinator] Dimension Scores:
[coordinator] Completeness: <bar> <n>%
[coordinator] Consistency: <bar> <n>%
[coordinator] Traceability: <bar> <n>%
[coordinator] Depth: <bar> <n>%
[coordinator] Coverage: <bar> <n>%
[coordinator]
[coordinator] Available Actions:
[coordinator] resume -> Proceed to implementation
[coordinator] improve -> Auto-improve weakest dimension
[coordinator] revise <TASK-ID> -> Revise specific document
[coordinator] recheck -> Re-run quality check
[coordinator] feedback <text> -> Inject feedback
[coordinator] ══════════════════════════════════════════
```
### Task Metadata Registry
| Task ID | Role | Phase | Dependencies | Discuss |
|---------|------|-------|-------------|---------|
| RESEARCH-001 | analyst | spec | (none) | DISCUSS-001 |
| DRAFT-001 | writer | spec | RESEARCH-001 | self-validate |
| DRAFT-002 | writer | spec | DRAFT-001 | DISCUSS-002 |
| DRAFT-003 | writer | spec | DRAFT-002 | self-validate |
| DRAFT-004 | writer | spec | DRAFT-003 | self-validate |
| QUALITY-001 | reviewer | spec | DRAFT-004 | DISCUSS-003 |
| PLAN-001 | planner | impl | (none or QUALITY-001) | - |
| IMPL-001 | executor | impl | PLAN-001 | - |
| TEST-001 | tester | impl | IMPL-001 | - |
| REVIEW-001 | reviewer | impl | IMPL-001 | - |
| DEV-FE-001 | fe-developer | impl | PLAN-001 | - |
| QA-FE-001 | fe-qa | impl | DEV-FE-001 | - |
---
## Session Directory
```
.workflow/.team/TLS-<slug>-<date>/
+-- team-session.json
+-- spec/
| +-- spec-config.json
| +-- discovery-context.json
| +-- product-brief.md
| +-- requirements/
| +-- architecture/
| +-- epics/
| +-- readiness-report.md
+-- discussions/
+-- plan/
| +-- plan.json
| +-- .task/TASK-*.json
+-- explorations/
+-- .msg/
+-- shared-memory.json
```
## Session Resume
1. Scan `.workflow/.team/TLS-*/team-session.json` for active/paused sessions
2. Multiple matches -> AskUserQuestion
3. Audit TaskList -> reconcile session state
4. Reset in_progress -> pending (interrupted tasks)
5. Rebuild team, spawn needed workers only
6. Kick first executable task
## Shared Resources
| Resource | Path | Usage |
|----------|------|-------|
| Document Standards | [specs/document-standards.md](specs/document-standards.md) | YAML frontmatter, naming, structure |
| Quality Gates | [specs/quality-gates.md](specs/quality-gates.md) | Per-phase quality gates |
| Team Config | [specs/team-config.json](specs/team-config.json) | Role registry, pipeline definitions |
| Product Brief Template | [templates/product-brief.md](templates/product-brief.md) | DRAFT-001 |
| 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) | 3-round discuss protocol |
## Error Handling
| Scenario | Resolution |
|----------|------------|
| 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 |
| Fast-advance spawns wrong task | Coordinator reconciles on next callback |

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

@@ -1,107 +0,0 @@
---
role: analyst
prefix: RESEARCH
inner_loop: false
discuss_rounds: [DISCUSS-001]
message_types:
success: research_ready
progress: research_progress
error: error
---
# Analyst — Phase 2-4
## Phase 2: Seed Analysis
**Objective**: Extract structured seed information from the topic.
1. Extract session folder from task description (`Session: <path>`)
2. Parse topic from task description
3. If topic starts with `@` or ends with `.md`/`.txt` → Read referenced file
4. Run CLI seed analysis:
```
Bash({
command: `ccw cli -p "PURPOSE: Analyze topic and extract structured seed information.
TASK: * Extract problem statement * Identify target users * Determine domain context
* List constraints * Identify 3-5 exploration dimensions * Assess complexity
TOPIC: <topic-content>
MODE: analysis
EXPECTED: JSON with: problem_statement, target_users[], domain, constraints[], exploration_dimensions[], complexity_assessment" --tool gemini --mode analysis`,
run_in_background: false
})
```
5. Parse seed analysis JSON
## Phase 3: Codebase Exploration (conditional)
**Objective**: Gather codebase context if project detected.
| Condition | Action |
|-----------|--------|
| package.json / Cargo.toml / pyproject.toml / go.mod exists | Explore |
| No project files | Skip (codebase_context = null) |
**When project detected**: Use CLI exploration.
```
Bash({
command: `ccw cli -p "PURPOSE: Explore codebase for context to inform spec generation
TASK: • Identify tech stack • Map architecture patterns • Document conventions • List integration points
MODE: analysis
CONTEXT: @**/*
EXPECTED: JSON with: tech_stack[], architecture_patterns[], conventions[], integration_points[]" --tool gemini --mode analysis --rule analysis-analyze-code-patterns`,
run_in_background: false
})
```
## Phase 4: Context Packaging + Discuss
### 4a: Context Packaging
**spec-config.json** → `<session>/spec/spec-config.json`
**discovery-context.json** → `<session>/spec/discovery-context.json`
**design-intelligence.json** → `<session>/analysis/design-intelligence.json` (UI mode only)
### 4b: Inline Discuss (DISCUSS-001)
**Multi-perspective critique via parallel CLI calls**:
```bash
# Product perspective
Bash(`ccw cli -p "PURPOSE: Review discovery context from product perspective
CONTEXT: @<session>/spec/discovery-context.json
EXPECTED: Rating (1-5) + concerns + recommendations
CONSTRAINTS: Focus on market fit, user value, scope clarity" --tool gemini --mode analysis`, { run_in_background: true })
# Risk perspective
Bash(`ccw cli -p "PURPOSE: Review discovery context from risk perspective
CONTEXT: @<session>/spec/discovery-context.json
EXPECTED: Rating (1-5) + risks + mitigation strategies
CONSTRAINTS: Focus on technical risks, dependencies, unknowns" --tool codex --mode analysis`, { run_in_background: true })
# Coverage perspective
Bash(`ccw cli -p "PURPOSE: Review discovery context from coverage perspective
CONTEXT: @<session>/spec/discovery-context.json
EXPECTED: Rating (1-5) + gaps + missing dimensions
CONSTRAINTS: Focus on completeness, edge cases, requirements coverage" --tool claude --mode analysis`, { run_in_background: true })
```
Wait for all results, aggregate ratings and feedback, determine consensus verdict:
- **HIGH**: Any rating <= 2 → User pause required
- **MEDIUM**: All ratings 3-4 → Proceed with caution
- **LOW**: All ratings >= 4 → Proceed
Handle verdict per consensus protocol.
**Report**: complexity, codebase presence, problem statement, dimensions, discuss verdict, output paths.
## Error Handling
| Scenario | Resolution |
|----------|------------|
| CLI failure | Fallback to direct Claude analysis |
| Codebase detection failed | Continue as new project |
| Topic too vague | Report with clarification questions |
| CLI critique fails | Proceed without critique, log warning |

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

@@ -1,75 +0,0 @@
---
role: architect
prefix: ARCH
inner_loop: false
discuss_rounds: []
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 |

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

@@ -1,66 +0,0 @@
---
role: executor
prefix: IMPL
inner_loop: true
discuss_rounds: []
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 |

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

@@ -1,78 +0,0 @@
---
role: fe-developer
prefix: DEV-FE
inner_loop: false
discuss_rounds: []
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 |

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

@@ -1,78 +0,0 @@
---
role: fe-qa
prefix: QA-FE
inner_loop: false
discuss_rounds: []
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 |

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

@@ -1,97 +0,0 @@
---
role: planner
prefix: PLAN
inner_loop: true
discuss_rounds: []
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 CLI exploration |
| High | > 500 chars, refactor/architecture, multi-module | 3-5 angle CLI exploration |
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 |

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

@@ -1,122 +0,0 @@
---
role: reviewer
prefix: REVIEW
additional_prefixes: [QUALITY, IMPROVE]
inner_loop: false
discuss_rounds: [DISCUSS-003]
message_types:
success_review: review_result
success_quality: quality_result
fix: fix_required
error: error
---
# Reviewer — Phase 2-4
## Phase 2: Mode Detection
| Task Prefix | Mode | Dimensions | Discuss |
|-------------|------|-----------|---------|
| REVIEW-* | Code Review | quality, security, architecture, requirements | None |
| QUALITY-* | Spec Quality | completeness, consistency, traceability, depth, coverage | DISCUSS-003 |
| IMPROVE-* | Spec Quality (recheck) | Same as QUALITY | DISCUSS-003 |
## Phase 3: Review Execution
### Code Review (REVIEW-*)
**Inputs**: Plan file, git diff, modified files, test results
**4 dimensions**:
| Dimension | Critical Issues |
|-----------|----------------|
| Quality | Empty catch, any in public APIs, @ts-ignore, console.log |
| Security | Hardcoded secrets, SQL injection, eval/exec, innerHTML |
| Architecture | Circular deps, parent imports >2 levels, files >500 lines |
| Requirements | Missing core functionality, incomplete acceptance criteria |
### Spec Quality (QUALITY-* / IMPROVE-*)
**Inputs**: All spec docs in session folder, quality gate config
**5 dimensions**:
| Dimension | Weight | Focus |
|-----------|--------|-------|
| Completeness | 25% | All sections present with substance |
| Consistency | 20% | Terminology, format, references |
| Traceability | 25% | Goals -> Reqs -> Arch -> Stories chain |
| Depth | 20% | AC testable, ADRs justified, stories estimable |
| Coverage | 10% | Original requirements mapped |
**Quality gate**:
| Gate | Criteria |
|------|----------|
| PASS | Score >= 80% AND coverage >= 70% |
| REVIEW | Score 60-79% OR coverage 50-69% |
| FAIL | Score < 60% OR coverage < 50% |
**Artifacts**: readiness-report.md + spec-summary.md
## Phase 4: Verdict + Discuss
### Code Review Verdict
| Verdict | Criteria |
|---------|----------|
| BLOCK | Critical issues present |
| CONDITIONAL | High/medium only |
| APPROVE | Low or none |
### Spec Quality Discuss (DISCUSS-003)
After generating readiness-report.md, perform multi-perspective critique via parallel CLI calls:
```bash
# Product perspective
Bash(`ccw cli -p "PURPOSE: Review spec readiness from product perspective
CONTEXT: @<session>/spec/readiness-report.md
EXPECTED: Rating (1-5) + product concerns + recommendations
CONSTRAINTS: Focus on market alignment, user value, business viability" --tool gemini --mode analysis`, { run_in_background: true })
# Technical perspective
Bash(`ccw cli -p "PURPOSE: Review spec readiness from technical perspective
CONTEXT: @<session>/spec/readiness-report.md
EXPECTED: Rating (1-5) + technical risks + feasibility assessment
CONSTRAINTS: Focus on architecture soundness, tech debt, implementation complexity" --tool codex --mode analysis`, { run_in_background: true })
# Quality perspective
Bash(`ccw cli -p "PURPOSE: Review spec readiness from quality perspective
CONTEXT: @<session>/spec/readiness-report.md
EXPECTED: Rating (1-5) + quality gaps + improvement areas
CONSTRAINTS: Focus on completeness, testability, consistency" --tool claude --mode analysis`, { run_in_background: true })
# Risk perspective
Bash(`ccw cli -p "PURPOSE: Review spec readiness from risk perspective
CONTEXT: @<session>/spec/readiness-report.md
EXPECTED: Rating (1-5) + risk factors + mitigation strategies
CONSTRAINTS: Focus on dependencies, unknowns, timeline risks" --tool gemini --mode analysis`, { run_in_background: true })
# Coverage perspective
Bash(`ccw cli -p "PURPOSE: Review spec readiness from coverage perspective
CONTEXT: @<session>/spec/readiness-report.md
EXPECTED: Rating (1-5) + coverage gaps + missing requirements
CONSTRAINTS: Focus on edge cases, non-functional requirements, traceability" --tool codex --mode analysis`, { run_in_background: true })
```
Wait for all results, aggregate ratings and feedback, determine consensus verdict per protocol.
> **Note**: DISCUSS-003 HIGH always triggers user pause (final sign-off gate).
**Report**: mode, verdict/gate, dimension scores, discuss verdict (QUALITY only), output paths.
## Error Handling
| Scenario | Resolution |
|----------|------------|
| Missing context | Request from coordinator |
| Invalid mode | Abort with error |
| Analysis failure | Retry, then fallback |
| CLI critique fails | Proceed without critique, log warning |

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

@@ -1,75 +0,0 @@
---
role: tester
prefix: TEST
inner_loop: false
discuss_rounds: []
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 |

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

@@ -1,117 +0,0 @@
---
role: writer
prefix: DRAFT
inner_loop: true
discuss_rounds: [DISCUSS-002]
message_types:
success: draft_ready
revision: draft_revision
error: error
---
# Writer — Phase 2-4
## Phase 2: Context Loading
**Objective**: Load all required inputs for document generation.
### Document type routing
| Task Subject Contains | Doc Type | Template | Validation |
|----------------------|----------|----------|------------|
| Product Brief | product-brief | templates/product-brief.md | self-validate |
| Requirements / PRD | requirements | templates/requirements-prd.md | DISCUSS-002 |
| Architecture | architecture | templates/architecture-doc.md | self-validate |
| Epics | epics | templates/epics-template.md | self-validate |
### Progressive dependency loading
| Doc Type | Requires |
|----------|----------|
| product-brief | discovery-context.json |
| requirements | + product-brief.md |
| architecture | + requirements/_index.md |
| epics | + architecture/_index.md |
**Prior decisions from accumulator**: Pass context_accumulator summaries as "Prior Decisions" to generation.
| Input | Source | Required |
|-------|--------|----------|
| Document standards | `../../specs/document-standards.md` | Yes |
| Template | From routing table | Yes |
| Spec config | `<session>/spec/spec-config.json` | Yes |
| Discovery context | `<session>/spec/discovery-context.json` | Yes |
| Discussion feedback | `<session>/discussions/<discuss-file>` | If exists |
| Prior decisions | context_accumulator (in-memory) | If prior tasks |
## Phase 3: Document Generation
**Objective**: Generate document using CLI tool.
```
Bash({
command: `ccw cli -p "PURPOSE: Generate <doc-type> document following template and standards
TASK: • Load template • Apply spec config and discovery context • Integrate prior feedback • Generate all sections
MODE: write
CONTEXT: @<session>/spec/*.json @<template-path> | Memory: Prior decisions: <accumulator summary>
EXPECTED: Document at <output-path> with: YAML frontmatter, all sections, cross-references
CONSTRAINTS: Follow document-standards.md" --tool gemini --mode write --rule development-implement-feature --cd <session>`,
run_in_background: false
})
```
## Phase 4: Validation
### 4a: Self-Validation (all doc types)
| Check | What to Verify |
|-------|---------------|
| has_frontmatter | Starts with YAML frontmatter |
| sections_complete | All template sections present |
| cross_references | session_id included |
| progressive_consistency | References to upstream docs are valid |
### 4b: Validation Routing
| Doc Type | Validation Method |
|----------|------------------|
| product-brief | Self-validation only → report |
| requirements (PRD) | Self-validation + **DISCUSS-002** |
| architecture | Self-validation only → report |
| epics | Self-validation only → report |
**DISCUSS-002** (PRD only) - Multi-perspective critique via parallel CLI calls:
```bash
# Quality perspective
Bash(`ccw cli -p "PURPOSE: Review requirements document from quality perspective
CONTEXT: @<session>/spec/requirements/_index.md
EXPECTED: Rating (1-5) + quality issues + improvement suggestions
CONSTRAINTS: Focus on completeness, testability, consistency" --tool gemini --mode analysis`, { run_in_background: true })
# Product perspective
Bash(`ccw cli -p "PURPOSE: Review requirements document from product perspective
CONTEXT: @<session>/spec/requirements/_index.md
EXPECTED: Rating (1-5) + product concerns + alignment feedback
CONSTRAINTS: Focus on user value, market fit, scope clarity" --tool codex --mode analysis`, { run_in_background: true })
# Coverage perspective
Bash(`ccw cli -p "PURPOSE: Review requirements document from coverage perspective
CONTEXT: @<session>/spec/requirements/_index.md
EXPECTED: Rating (1-5) + coverage gaps + missing requirements
CONSTRAINTS: Focus on edge cases, non-functional requirements, traceability" --tool claude --mode analysis`, { run_in_background: true })
```
Wait for all results, aggregate ratings and feedback, determine consensus verdict per protocol.
**Report**: doc type, validation status, discuss verdict (PRD only), output path.
## Error Handling
| Scenario | Resolution |
|----------|------------|
| CLI failure | Retry once with alternative tool. Still fails → log, continue next |
| CLI critique fails | Skip critique, 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 |

134
.claude/skills/team-lifecycle-v2/roles/coordinator/commands/dispatch.md
View File

@@ -1,134 +0,0 @@
# Command: dispatch
Create task chains based on execution mode. v2: 3 discuss points instead of 6.
## Phase 2: Context Loading
| Input | Source | Required |
|-------|--------|----------|
| Mode | Phase 1 requirements | Yes |
| Session folder | Phase 2 session init | Yes |
| Scope | User requirements | Yes |
## Phase 3: Task Chain Creation
### Spec Pipeline (6 tasks, 3 discuss)
| # | Subject | Owner | BlockedBy | Description | Validation |
|---|---------|-------|-----------|-------------|------------|
| 1 | RESEARCH-001 | analyst | (none) | Seed analysis and context gathering | DISCUSS-001 |
| 2 | DRAFT-001 | writer | RESEARCH-001 | Generate Product Brief | self-validate |
| 3 | DRAFT-002 | writer | DRAFT-001 | Generate Requirements/PRD | DISCUSS-002 |
| 4 | DRAFT-003 | writer | DRAFT-002 | Generate Architecture Document | self-validate |
| 5 | DRAFT-004 | writer | DRAFT-003 | Generate Epics & Stories | self-validate |
| 6 | QUALITY-001 | reviewer | DRAFT-004 | 5-dimension spec quality + sign-off | DISCUSS-003 |
### Impl Pipeline (4 tasks)
| # | Subject | Owner | BlockedBy | Description |
|---|---------|-------|-----------|-------------|
| 1 | PLAN-001 | planner | (none) | Multi-angle exploration and planning |
| 2 | IMPL-001 | executor | PLAN-001 | Code implementation |
| 3 | TEST-001 | tester | IMPL-001 | Test-fix cycles |
| 4 | REVIEW-001 | reviewer | IMPL-001 | 4-dimension code review |
### FE Pipeline (3 tasks)
| # | Subject | Owner | BlockedBy | Description |
|---|---------|-------|-----------|-------------|
| 1 | PLAN-001 | planner | (none) | Planning (frontend focus) |
| 2 | DEV-FE-001 | fe-developer | PLAN-001 | Frontend implementation |
| 3 | QA-FE-001 | fe-qa | DEV-FE-001 | 5-dimension frontend QA |
### Fullstack Pipeline (6 tasks)
| # | Subject | Owner | BlockedBy | Description |
|---|---------|-------|-----------|-------------|
| 1 | PLAN-001 | planner | (none) | Fullstack planning |
| 2 | IMPL-001 | executor | PLAN-001 | Backend implementation |
| 3 | DEV-FE-001 | fe-developer | PLAN-001 | Frontend implementation |
| 4 | TEST-001 | tester | IMPL-001 | Backend test-fix |
| 5 | QA-FE-001 | fe-qa | DEV-FE-001 | Frontend QA |
| 6 | REVIEW-001 | reviewer | TEST-001, QA-FE-001 | Full code review |
### Composite Modes
| Mode | Construction | PLAN-001 BlockedBy |
|------|-------------|-------------------|
| full-lifecycle | Spec (6) + Impl (4) | QUALITY-001 |
| full-lifecycle-fe | Spec (6) + Fullstack (6) | QUALITY-001 |
### Task Description Template
```
TaskCreate({
subject: "<TASK-ID>",
description: "PURPOSE: <what> | Success: <criteria>
TASK:
- <step 1>
- <step 2>
- <step 3>
CONTEXT:
- Session: <session-folder>
- Scope: <scope>
- Upstream: <artifacts>
EXPECTED: <deliverable> + <quality>
CONSTRAINTS: <scope limits>
---
Validation: <DISCUSS-NNN or self-validate>
InnerLoop: <true|false>",
addBlockedBy: [<deps>]
})
```
### Revision Task Template
```
TaskCreate({
subject: "<ORIGINAL-ID>-R1",
owner: "<same-role>",
description: "PURPOSE: Revision of <ORIGINAL-ID> | Success: Address feedback
TASK:
- Review original + feedback
- Apply fixes
- Validate
CONTEXT:
- Session: <session-folder>
- Original: <artifact-path>
- Feedback: <text>
EXPECTED: Updated artifact + summary
---
Validation: <same-as-original>
InnerLoop: <true|false>",
blockedBy: [<predecessor-R1 if cascaded>]
})
```
**Cascade Rules**:
| Revised Task | Downstream |
|-------------|-----------|
| RESEARCH-001 | DRAFT-001~004-R1, QUALITY-001-R1 |
| DRAFT-001 | DRAFT-002~004-R1, QUALITY-001-R1 |
| DRAFT-002 | DRAFT-003~004-R1, QUALITY-001-R1 |
| DRAFT-003 | DRAFT-004-R1, QUALITY-001-R1 |
| DRAFT-004 | QUALITY-001-R1 |
## Phase 4: Validation
| Check | Criteria |
|-------|----------|
| Task count | Matches mode total |
| Dependencies | Every blockedBy references existing task |
| Owner | Each task owner matches Role Registry |
| Session ref | Every task contains `Session:` |
| Validation field | Spec tasks have Validation field |
## Error Handling
| Scenario | Resolution |
|----------|------------|
| Unknown mode | Reject with supported modes |
| Missing spec for impl-only | Error, suggest spec-only |
| TaskCreate fails | Log error, report |
| Duplicate task | Skip, log warning |

134
.claude/skills/team-lifecycle-v2/roles/coordinator/commands/monitor.md
View File

@@ -1,134 +0,0 @@
# Command: monitor
Event-driven pipeline coordination. v2: 3 discuss points, simplified consensus handling.
## Constants
| Constant | Value |
|----------|-------|
| SPAWN_MODE | background |
| ONE_STEP_PER_INVOCATION | true |
| FAST_ADVANCE_AWARE | true |
| WORKER_AGENT | team-worker |
## Phase 2: Context Loading
| Input | Source | Required |
|-------|--------|----------|
| Session file | team-session.json | Yes |
| Task list | TaskList() | Yes |
| Active workers | session.active_workers[] | Yes |
## Phase 3: Handler Routing
| Priority | Condition | Handler |
|----------|-----------|---------|
| 1 | `[<role-name>]` from worker | handleCallback |
| 2 | "check" or "status" | handleCheck |
| 3 | "resume" / "continue" | handleResume |
| 4 | None (initial spawn) | handleSpawnNext |
| 5 | "revise" + task ID | handleRevise |
| 6 | "feedback" + text | handleFeedback |
| 7 | "recheck" | handleRecheck |
| 8 | "improve" | handleImprove |
---
### handleCallback
```
Receive callback from [<role>]
+- Progress update? -> Update session -> STOP
+- Task completed? -> remove from active_workers -> update session
| +- Handle checkpoints (QUALITY-001)
| +- -> handleSpawnNext
+- No matching worker -> scan all active -> handleSpawnNext or STOP
```
Fast-advance reconciliation: read team_msg fast_advance entries, sync active_workers.
### handleCheck
Read-only status report, no advancement.
```
[coordinator] Pipeline Status (v2)
[coordinator] Mode: <mode> | Progress: <completed>/<total> (<percent>%)
[coordinator] Discuss: <completed-discuss>/<total-discuss> rounds
[coordinator] Execution Graph:
Spec Phase:
[<icon> RESEARCH-001(+D1)] -> [<icon> DRAFT-001] -> [<icon> DRAFT-002(+D2)] -> [<icon> DRAFT-003] -> [<icon> DRAFT-004] -> [<icon> QUALITY-001(+D3)]
Impl Phase:
[<icon> PLAN-001] -> [<icon> IMPL-001] -> [<icon> TEST-001] + [<icon> REVIEW-001]
done=completed >>>=running o=pending
```
Then STOP.
### handleResume
```
Load active_workers
+- No active -> handleSpawnNext
+- Has active -> check each:
+- completed -> mark done
+- in_progress -> still running
+- other -> reset to pending
After: some completed -> handleSpawnNext; all running -> STOP
```
### handleSpawnNext
```
Collect task states from TaskList()
+- readySubjects: pending + all blockedBy completed
+- NONE + work in progress -> STOP
+- NONE + nothing running -> PIPELINE_COMPLETE -> Phase 5
+- HAS ready -> for each:
+- Inner Loop role AND already active? -> SKIP
+- Spawn team-worker (see SKILL.md Spawn Template)
+- Add to active_workers
Update session -> STOP
```
### handleRevise / handleFeedback / handleRecheck / handleImprove
Same as v1 (see dispatch.md for templates). Changes:
- Revision tasks use v2 Validation field ("self-validate" or "DISCUSS-NNN")
---
### Consensus-Blocked Handling (v2 simplified)
Only 3 discuss points to handle:
```
handleCallback receives consensus_blocked:
+- DISCUSS-003 (QUALITY) + HIGH -> PAUSE for user (final gate)
+- Any discuss + HIGH -> Create REVISION task (max 1 per task)
+- MEDIUM -> proceed with warning, log to wisdom/issues.md
+- LOW -> proceed normally
```
### Fast-Advance State Sync
On every coordinator wake:
1. Read team_msg fast_advance entries
2. Sync active_workers with spawned successors
### Worker Failure Handling
1. Reset task -> pending
2. Log via team_msg (type: error)
3. Report to user
## Error Handling
| Scenario | Resolution |
|----------|------------|
| Session not found | Error, suggest re-init |
| Unknown role callback | Log, scan for completions |
| Pipeline stall | Check missing tasks, report |
| Fast-advance orphan | Reset to pending, re-spawn |

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

@@ -1,139 +0,0 @@
# Coordinator Role
Orchestrate team-lifecycle-v2: team creation, task dispatching, progress monitoring, session state. Uses **team-worker agent** for all worker spawns.
## Identity
- **Name**: `coordinator` | **Tag**: `[coordinator]`
- **Responsibility**: Parse requirements -> Create team -> Dispatch tasks -> Monitor progress -> Report
## Boundaries
### MUST
- Parse user requirements and clarify via AskUserQuestion
- Create team and spawn workers using **team-worker** agent type
- Dispatch tasks with proper dependency chains
- Monitor progress via callbacks and route messages
- Maintain session state (team-session.json)
### MUST NOT
- Execute spec/impl/research work directly
- Modify task outputs
- Skip dependency validation
---
## Entry Router
| Detection | Condition | Handler |
|-----------|-----------|---------|
| Worker callback | Message contains `[role-name]` tag | -> handleCallback |
| Status check | "check" or "status" | -> handleCheck |
| Manual resume | "resume" or "continue" | -> handleResume |
| Interrupted session | Active/paused session in `.workflow/.team/TLS-*` | -> Phase 0 |
| New session | None of above | -> Phase 1 |
For callback/check/resume: load `commands/monitor.md`, execute handler, STOP.
---
## Phase 0: Session Resume Check
1. Scan `.workflow/.team/TLS-*/team-session.json` for active/paused
2. No sessions -> Phase 1
3. Single session -> resume (reconciliation)
4. Multiple -> AskUserQuestion
**Session Reconciliation**:
1. Audit TaskList, reconcile with session state
2. Reset in_progress -> pending (interrupted tasks)
3. Rebuild team if disbanded
4. Create missing tasks with correct blockedBy
5. Kick first executable -> Phase 4
---
## Phase 1: Requirement Clarification
1. Parse arguments for mode, scope, focus
2. Ask missing parameters via AskUserQuestion:
- Mode: spec-only / impl-only / full-lifecycle / fe-only / fullstack / full-lifecycle-fe
- Scope: project description
3. Frontend auto-detection (keyword + package.json scanning)
4. Store requirements
---
## Phase 2: Create Team + Initialize Session
1. Generate session ID: `TLS-<slug>-<date>`
2. Create session folder: `.workflow/.team/<session-id>/`
3. TeamCreate
4. Initialize directories (spec/, discussions/, plan/, explorations/)
5. Write team-session.json
6. Initialize meta.json via team_msg state_update:
```
mcp__ccw-tools__team_msg({
operation: "log",
session_id: "<session-id>",
from: "coordinator",
type: "state_update",
summary: "Session initialized",
data: {
pipeline_mode: "<mode>",
pipeline_stages: [<role-list>],
roles: [<all-roles>],
team_name: "lifecycle-v2"
}
})
```
---
## Phase 3: Create Task Chain
Delegate to `commands/dispatch.md`:
1. Read Task Metadata Registry for task definitions
2. Create tasks via TaskCreate with correct blockedBy
3. Include `Session: <session-folder>` in every task
4. Mark discuss rounds (DISCUSS-001, DISCUSS-002, DISCUSS-003) or "self-validate"
---
## Phase 4: Spawn-and-Stop
1. Load `commands/monitor.md`
2. Find ready tasks (pending + blockedBy resolved)
3. Spawn team-worker for each ready task
4. Output summary
5. STOP
### Checkpoint Gate (QUALITY-001)
When QUALITY-001 completes:
1. Read readiness-report.md
2. Parse quality gate and dimension scores
3. Output Checkpoint Template (see SKILL.md)
4. Pause for user command
---
## Phase 5: Report + Next Steps
1. Count completed tasks, duration
2. List deliverables
3. Update session status -> "completed"
4. Offer next steps: exit / view / extend / generate plan
---
## Error Handling
| Error | Resolution |
|-------|------------|
| Task timeout | Log, mark failed, ask user |
| Worker crash | Respawn worker, reassign task |
| Dependency cycle | Detect, report, halt |
| Invalid mode | Reject, ask to clarify |
| Session corruption | Attempt recovery |

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

@@ -1,192 +0,0 @@
# 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
View File

@@ -1,207 +0,0 @@
# 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

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

@@ -1,246 +0,0 @@
{
"team_name": "team-lifecycle-v2",
"team_display_name": "Team Lifecycle v2",
"description": "Optimized team-worker agent architecture: discuss reduced 6→3, progressive refinement preserved",
"version": "6.0.0",
"architecture": "team-worker agent + role-specs",
"role_structure": "role-specs/{name}.md (Phase 2-4 only)",
"worker_agent": "team-worker",
"roles": {
"coordinator": {
"task_prefix": null,
"responsibility": "Pipeline orchestration, requirement clarification, task chain creation",
"message_types": [
"plan_approved",
"plan_revision",
"task_unblocked",
"fix_required",
"error",
"shutdown"
]
},
"analyst": {
"task_prefix": "RESEARCH",
"role_spec": "role-specs/analyst.md",
"responsibility": "Seed analysis, codebase exploration, context gathering + discuss",
"inline_discuss": "DISCUSS-001",
"inner_loop": false,
"message_types": [
"research_ready",
"research_progress",
"error"
]
},
"writer": {
"task_prefix": "DRAFT",
"role_spec": "role-specs/writer.md",
"responsibility": "Product Brief / PRD / Architecture / Epics generation. Discuss at PRD only, self-validate others",
"inner_loop": true,
"inline_discuss": [
"DISCUSS-002"
],
"message_types": [
"draft_ready",
"draft_revision",
"error"
]
},
"planner": {
"task_prefix": "PLAN",
"role_spec": "role-specs/planner.md",
"responsibility": "Multi-angle exploration and structured implementation planning",
"inner_loop": true,
"message_types": [
"plan_ready",
"plan_revision",
"error"
]
},
"executor": {
"task_prefix": "IMPL",
"role_spec": "role-specs/executor.md",
"responsibility": "Code implementation following approved plans",
"inner_loop": true,
"message_types": [
"impl_complete",
"impl_progress",
"error"
]
},
"tester": {
"task_prefix": "TEST",
"role_spec": "role-specs/tester.md",
"responsibility": "Adaptive test-fix cycles, progressive testing",
"inner_loop": false,
"message_types": [
"test_result",
"fix_required",
"error"
]
},
"reviewer": {
"task_prefix": "REVIEW",
"additional_prefixes": [
"QUALITY",
"IMPROVE"
],
"role_spec": "role-specs/reviewer.md",
"responsibility": "Code review (REVIEW-*) + Spec quality (QUALITY-*) + Improvement (IMPROVE-*) + final discuss",
"inline_discuss": "DISCUSS-003",
"inner_loop": false,
"message_types": [
"review_result",
"quality_result",
"quality_recheck",
"fix_required",
"error"
]
},
"architect": {
"task_prefix": "ARCH",
"role_spec": "role-specs/architect.md",
"responsibility": "Architecture assessment, tech feasibility. Consulting role",
"role_type": "consulting",
"inner_loop": false,
"message_types": [
"arch_ready",
"arch_concern",
"error"
]
},
"fe-developer": {
"task_prefix": "DEV-FE",
"role_spec": "role-specs/fe-developer.md",
"responsibility": "Frontend implementation",
"role_type": "frontend-pipeline",
"inner_loop": false,
"message_types": [
"dev_fe_complete",
"dev_fe_progress",
"error"
]
},
"fe-qa": {
"task_prefix": "QA-FE",
"role_spec": "role-specs/fe-qa.md",
"responsibility": "5-dimension frontend review, GC loop",
"role_type": "frontend-pipeline",
"inner_loop": false,
"message_types": [
"qa_fe_passed",
"qa_fe_result",
"fix_required",
"error"
]
}
},
"checkpoint_commands": {
"revise": {
"handler": "handleRevise",
"pattern": "revise <TASK-ID> [feedback]",
"cascade": true
},
"feedback": {
"handler": "handleFeedback",
"pattern": "feedback <text>",
"cascade": true
},
"recheck": {
"handler": "handleRecheck",
"pattern": "recheck",
"cascade": false
},
"improve": {
"handler": "handleImprove",
"pattern": "improve [dimension]",
"cascade": false
}
},
"pipelines": {
"spec-only": {
"description": "Spec pipeline: research(+D1) -> brief -> prd(+D2) -> arch -> epics -> quality(+D3)",
"task_chain": [
"RESEARCH-001",
"DRAFT-001",
"DRAFT-002",
"DRAFT-003",
"DRAFT-004",
"QUALITY-001"
],
"discuss_points": [
"RESEARCH-001",
"DRAFT-002",
"QUALITY-001"
],
"beats": 6
},
"impl-only": {
"description": "Implementation pipeline: plan -> implement -> test + review",
"task_chain": [
"PLAN-001",
"IMPL-001",
"TEST-001",
"REVIEW-001"
],
"beats": 3
},
"full-lifecycle": {
"description": "Full lifecycle: spec + impl (PLAN blockedBy QUALITY)",
"task_chain": "spec-only + impl-only (PLAN-001 blockedBy QUALITY-001)",
"beats": 9
},
"fe-only": {
"description": "Frontend-only: plan -> dev -> qa",
"task_chain": [
"PLAN-001",
"DEV-FE-001",
"QA-FE-001"
],
"gc_loop": {
"max_rounds": 2,
"convergence": "score >= 8 && critical === 0"
}
},
"fullstack": {
"description": "Fullstack: plan -> backend + frontend parallel -> test + qa -> review",
"task_chain": [
"PLAN-001",
"IMPL-001||DEV-FE-001",
"TEST-001||QA-FE-001",
"REVIEW-001"
]
},
"full-lifecycle-fe": {
"description": "Full lifecycle with frontend",
"task_chain": "spec-only + fullstack (PLAN-001 blockedBy QUALITY-001)"
}
},
"frontend_detection": {
"keywords": [
"component",
"page",
"UI",
"frontend",
"CSS",
"HTML",
"React",
"Vue",
"Tailwind",
"Svelte",
"Next.js"
],
"routing_rules": {
"frontend_only": "All tasks match frontend keywords",
"fullstack": "Mix of frontend and backend tasks",
"backend_only": "No frontend keywords (default impl-only)"
}
},
"session_dirs": {
"base": ".workflow/.team/TLS-{slug}-{YYYY-MM-DD}/",
"spec": "spec/",
"discussions": "discussions/",
"plan": "plan/",
"explorations": "explorations/",
"messages": ".msg/"
}
}

223
.claude/skills/team-lifecycle-v3/SKILL.md
View File

@@ -1,223 +0,0 @@
---
name: team-lifecycle-v3
description: Enhanced lifecycle with parallel execution, conditional routing, dynamic role injection, and task priority scheduling. Built on team-worker agent architecture with artifact contracts and automatic discovery.
allowed-tools: TeamCreate(*), TeamDelete(*), SendMessage(*), TaskCreate(*), TaskUpdate(*), TaskList(*), TaskGet(*), Agent(*), AskUserQuestion(*), Read(*), Write(*), Edit(*), Bash(*), Glob(*), Grep(*)
---
# Team Lifecycle v3
Enhanced lifecycle: specification → implementation → testing → review with parallel execution, conditional routing, and dynamic specialist role injection.
## Purpose
Team Lifecycle v3 orchestrates multi-agent software development workflows from initial requirements through implementation, testing, and review. It automatically coordinates specialized agents, manages artifact dependencies, validates quality gates, and dynamically injects expert roles based on task complexity.
**Key Capabilities**:
- Parallel execution of independent tasks
- Dynamic specialist role injection (security, performance, data, devops, ML)
- Artifact-based validation gating
- Conditional routing based on complexity assessment
- Priority-based task scheduling (P0/P1/P2)
- Quality checkpoints with user feedback loops
## Problem Statement
Complex software development tasks require diverse expertise—security audits, performance optimization, data pipeline design, DevOps configuration, and ML model integration. Coordinating multiple specialized agents manually is error-prone, inefficient, and difficult to scale. Developers face several challenges:
1. **Manual Coordination Overhead**: Tracking dependencies between agents, ensuring artifacts are validated before downstream work begins, and managing parallel execution requires constant human oversight.
2. **Expertise Gaps**: Not all tasks require all specialists. Injecting the right expert roles at the right time based on task complexity and keywords is a manual, subjective process prone to under- or over-staffing.
3. **Quality Assurance Bottlenecks**: Without automated quality gates and validation checkpoints, defects propagate downstream, requiring expensive rework.
4. **Lack of Observability**: Understanding where a multi-agent workflow is stalled, which artifacts are blocking progress, and what actions are needed requires manual inspection of scattered state.
Team Lifecycle v3 solves these problems by providing an event-driven orchestration system that automatically manages agent coordination, artifact validation, specialist injection, and quality checkpoints—turning multi-agent workflows into a repeatable, observable, and scalable process.
## Goals
- **Automated Agent Coordination**: Spawn workers based on task dependencies, manage parallel execution, and handle completion callbacks without manual intervention.
- **Artifact-Based Validation Gating**: Block downstream work until upstream artifacts pass validation, preventing defect propagation.
- **Dynamic Specialist Injection**: Analyze task descriptions and complexity to automatically inject expert roles (security, performance, data, devops, ML) when needed.
- **Conditional Routing**: Route tasks to appropriate implementation strategies (direct, orchestrated, architecture-first) based on quantifiable complexity assessment.
- **Priority-Based Scheduling**: Execute critical-path tasks (P0) before dependent tasks (P1/P2), optimizing workflow throughput.
- **Quality Checkpoints**: Pause at key milestones for user review, with actionable commands (resume, improve, revise, recheck) to maintain quality.
- **Session Persistence**: Support pause/resume across process restarts, preserving artifact registry and task state.
- **Observability**: Provide clear status reporting, task state visibility, and actionable error messages.
## Non-Goals
- **General-Purpose Workflow Engine**: Team Lifecycle v3 is specialized for software development workflows with agent coordination. It is not a generic DAG executor or distributed job scheduler.
- **Project Management Tool**: The system does not manage backlogs, sprints, or roadmaps. It executes individual tasks with clear requirements.
- **Prescriptive Agent Implementations**: The skill defines role specifications and contracts but does not mandate specific agent implementations or tools.
- **Ticket/PR Management**: State transitions, comments, and PR creation are the responsibility of individual agents using their own tools, not the orchestrator.
- **Approval/Sandbox Policies**: The skill does not enforce specific approval workflows or sandboxing. Implementations may add these based on their trust model.
- **Real-Time Collaboration**: The system is event-driven with asynchronous agent execution, not a real-time collaborative editing environment.
## Mandatory Reading
Before using this skill, read these documents to understand the foundational concepts:
| Document | Purpose | Priority |
|----------|---------|----------|
| [specs/core-concepts.md](specs/core-concepts.md) | Foundational principles: team-worker architecture, artifact contracts, quality gating, dynamic role injection, priority scheduling | **P0 - Critical** |
| [specs/artifact-contract-spec.md](specs/artifact-contract-spec.md) | Artifact manifest schema and validation rules | **P0 - Critical** |
| [specs/execution-flow.md](specs/execution-flow.md) | End-to-end execution walkthrough with pipeline definitions | **P1 - High** |
## Documentation Structure
This skill is organized into the following directories:
### `/roles` - Agent Role Specifications
- **`coordinator/`**: Orchestrator agent that manages workflow, task dependencies, and role injection
- `role.md`: Coordinator specification
- `commands/`: User command handlers (dispatch, monitor)
- **`pipeline/`**: Core pipeline roles (always present)
- `analyst.md`, `writer.md`, `planner.md`, `executor.md`, `tester.md`, `reviewer.md`
- `architect.md`, `fe-developer.md`, `fe-qa.md` (consulting roles)
- **`specialists/`**: Specialist roles (dynamically injected)
- `orchestrator.role.md`, `security-expert.role.md`, `performance-optimizer.role.md`
- `data-engineer.role.md`, `devops-engineer.role.md`, `ml-engineer.role.md`
### `/specs` - Specifications and Standards
- **`core-concepts.md`**: Foundational principles (mandatory reading)
- **`execution-flow.md`**: End-to-end execution walkthrough
- **`artifact-contract-spec.md`**: Artifact manifest schema
- **`quality-gates.md`**: Quality validation criteria
- **`document-standards.md`**: Document formatting standards
- **`team-config.json`**: Role registry and pipeline definitions
### `/templates` - Document Templates
- `product-brief.md`: DRAFT-001 template
- `requirements-prd.md`: DRAFT-002 template
- `architecture-doc.md`: DRAFT-003 template
- `epics-template.md`: DRAFT-004 template
### `/subagents` - Utility Subagents
- `discuss-subagent.md`: 3-round discussion protocol
- `explorer-subagent.md`: Shared exploration with cache
- `doc-generator-subagent.md`: Template-based doc generation
## Quick Start
### Basic Usage
```
Skill(skill="team-lifecycle-v3", args="<task description>")
```
**Example**:
```
Skill(skill="team-lifecycle-v3", args="Implement user authentication with OAuth2")
```
### Execution Flow
1. **User provides task description** → Coordinator clarifies requirements
2. **Coordinator creates team** → TeamCreate with session folder
3. **Coordinator analyzes complexity** → Injects specialist roles if needed
4. **Coordinator creates task chain** → Based on pipeline selection (spec-only, impl-only, full-lifecycle)
5. **Coordinator spawns first batch** → Workers execute in background
6. **Workers report completion** → SendMessage callback to coordinator
7. **Coordinator advances pipeline** → Spawns next ready tasks
8. **Quality checkpoints** → User can review, improve, or revise
9. **Coordinator generates report** → Final summary and completion action
### User Commands
During execution, you can use these commands:
| Command | Action |
|---------|--------|
| `check` / `status` | View current execution status |
| `resume` / `continue` | Advance to next step |
| `revise <TASK-ID> [feedback]` | Revise specific task with feedback |
| `feedback <text>` | Provide feedback for targeted revision |
| `recheck` | Re-run quality check |
| `improve [dimension]` | Auto-improve weakest quality dimension |
## Pipeline Options
The coordinator selects the appropriate pipeline based on task requirements:
### Spec-only Pipeline (6 tasks)
```
RESEARCH-001 → DRAFT-001 → DRAFT-002 → DRAFT-003 → DRAFT-004 → QUALITY-001
```
Use for: Documentation, requirements gathering, design work
### Impl-only Pipeline (4 tasks)
```
PLAN-001 → IMPL-001 → TEST-001 + REVIEW-001
```
Use for: Quick implementations with clear requirements
### Full-lifecycle Pipeline (10 tasks)
```
[Spec pipeline] → PLAN-001 → IMPL-001 → TEST-001 + REVIEW-001
```
Use for: Complete feature development from requirements to implementation
## Advanced Features
### Dynamic Role Injection
Specialist roles are automatically injected based on keywords in task description:
- **security**, **vulnerability**, **OWASP** → `security-expert`
- **performance**, **optimization**, **bottleneck** → `performance-optimizer`
- **data**, **pipeline**, **ETL**, **schema** → `data-engineer`
- **devops**, **CI/CD**, **deployment**, **docker** → `devops-engineer`
- **ML**, **model**, **training**, **inference** → `ml-engineer`
### Conditional Routing
PLAN-001 assesses complexity and routes to appropriate implementation strategy:
- **Low complexity** (1-2 modules) → Direct implementation
- **Medium complexity** (3-4 modules) → Orchestrated parallel implementation
- **High complexity** (5+ modules) → Architecture design + orchestrated implementation
### Quality Checkpoints
At key milestones, the coordinator pauses for user review:
- **Spec Phase Complete** (QUALITY-001): Review specification quality, choose to proceed, improve, or revise
- **Implementation Complete**: Review code quality and test coverage
## Troubleshooting
### Common Issues
| Issue | Solution |
|-------|----------|
| Pipeline stalled | Use `status` to check task states, `resume` to advance |
| Quality gate failed | Use `improve` to auto-improve or `revise <TASK-ID>` to manually fix |
| Wrong specialist injected | Provide clearer keywords in task description |
| Session lost after restart | Use session resume to restore from `.workflow/.team/TLS-*` |
### Error Handling
| Scenario | Resolution |
|----------|------------|
| Unknown command | Error with available command list |
| Role spec file not found | Error with expected path |
| Artifact validation fails | Block downstream, trigger fix loop |
| Dynamic role injection fails | Log warning, continue with core roles |
| Parallel merge timeout | Report stall, prompt user intervention |
## Reference Documents
For detailed information, see:
- [specs/core-concepts.md](specs/core-concepts.md) - Foundational principles
- [specs/execution-flow.md](specs/execution-flow.md) - Detailed execution walkthrough
- [specs/artifact-contract-spec.md](specs/artifact-contract-spec.md) - Artifact manifest specification
- [specs/quality-gates.md](specs/quality-gates.md) - Quality validation criteria
- [specs/document-standards.md](specs/document-standards.md) - Document formatting standards
- [roles/coordinator/role.md](roles/coordinator/role.md) - Coordinator specification
- [roles/README.md](roles/README.md) - Role directory guide

232
.claude/skills/team-lifecycle-v3/roles/README.md
View File

@@ -1,232 +0,0 @@
# Role Directory Guide
This directory contains all agent role specifications for Team Lifecycle v3.
## Directory Structure
```
roles/
├── README.md # This file
├── coordinator/ # Orchestrator agent
│ ├── role.md # Coordinator specification
│ └── commands/ # User command handlers
│ ├── dispatch.md
│ └── monitor.md
├── pipeline/ # Core pipeline roles (always present)
│ ├── analyst.md # Research and discovery
│ ├── writer.md # Document drafting
│ ├── planner.md # Implementation planning
│ ├── executor.md # Code implementation
│ ├── tester.md # Test generation
│ ├── reviewer.md # Quality review
│ ├── architect.md # Architecture design (consulting)
│ ├── fe-developer.md # Frontend development (consulting)
│ └── fe-qa.md # Frontend QA (consulting)
└── specialists/ # Specialist roles (dynamically injected)
├── orchestrator.role.md # Multi-module coordination
├── security-expert.role.md # Security analysis
├── performance-optimizer.role.md # Performance optimization
├── data-engineer.role.md # Data pipeline work
├── devops-engineer.role.md # DevOps and deployment
└── ml-engineer.role.md # ML/AI implementation
```
## Role Types
### Coordinator (Orchestrator)
**Location**: `coordinator/`
**Purpose**: Manages workflow orchestration, task dependencies, role injection, and artifact registry.
**Key Responsibilities**:
- Parse user requests and clarify requirements
- Create and manage team sessions
- Analyze complexity and inject specialist roles
- Create task chains with dependencies
- Spawn workers and handle callbacks
- Validate artifacts and advance pipeline
- Display checkpoints and handle user commands
**Always Present**: Yes
**Spawned By**: Skill invocation
### Pipeline Roles (Core Team)
**Location**: `pipeline/`
**Purpose**: Execute standard development workflow tasks.
**Always Present**: Yes (based on pipeline selection)
**Spawned By**: Coordinator
#### Core Pipeline Roles
| Role | File | Purpose | Task Prefix |
|------|------|---------|-------------|
| analyst | `analyst.md` | Research and discovery | RESEARCH-* |
| writer | `writer.md` | Document drafting | DRAFT-* |
| planner | `planner.md` | Implementation planning | PLAN-* |
| executor | `executor.md` | Code implementation | IMPL-* |
| tester | `tester.md` | Test generation and execution | TEST-* |
| reviewer | `reviewer.md` | Quality review and improvement | REVIEW-*, QUALITY-*, IMPROVE-* |
#### Consulting Roles
| Role | File | Purpose | Task Prefix | Injection Trigger |
|------|------|---------|-------------|-------------------|
| architect | `architect.md` | Architecture design | ARCH-* | High complexity |
| fe-developer | `fe-developer.md` | Frontend development | DEV-FE-* | Frontend tasks |
| fe-qa | `fe-qa.md` | Frontend QA | QA-FE-* | Frontend tasks |
### Specialist Roles (Dynamic Injection)
**Location**: `specialists/`
**Purpose**: Provide expert capabilities for specific domains.
**Always Present**: No (injected based on task analysis)
**Spawned By**: Coordinator (after complexity/keyword analysis)
| Role | File | Purpose | Task Prefix | Injection Trigger |
|------|------|---------|-------------|-------------------|
| orchestrator | `orchestrator.role.md` | Multi-module coordination | ORCH-* | Medium/High complexity |
| security-expert | `security-expert.role.md` | Security analysis and audit | SECURITY-* | Keywords: security, vulnerability, OWASP, auth |
| performance-optimizer | `performance-optimizer.role.md` | Performance optimization | PERF-* | Keywords: performance, optimization, bottleneck |
| data-engineer | `data-engineer.role.md` | Data pipeline work | DATA-* | Keywords: data, pipeline, ETL, schema |
| devops-engineer | `devops-engineer.role.md` | DevOps and deployment | DEVOPS-* | Keywords: devops, CI/CD, deployment, docker |
| ml-engineer | `ml-engineer.role.md` | ML/AI implementation | ML-* | Keywords: ML, model, training, inference |
## Role Specification Format
All role specifications follow this structure:
```markdown
---
role: <role-name>
type: <coordinator|pipeline|specialist>
task_prefix: <TASK-PREFIX>
priority: <P0|P1|P2>
injection_trigger: <always|complexity|keywords>
---
# Role: <Role Name>
## Purpose
Brief description of role purpose.
## Responsibilities
- Responsibility 1
- Responsibility 2
## Phase Execution
### Phase 1: Task Discovery
...
### Phase 2: Context Gathering
...
### Phase 3: Domain Work
...
### Phase 4: Artifact Generation
...
### Phase 5: Reporting
...
## Tools & Capabilities
- Tool 1
- Tool 2
## Artifact Contract
Expected artifacts and manifest schema.
```
## Worker Execution Model
All workers (pipeline and specialist roles) follow the **5-phase execution model**:
1. **Phase 1: Task Discovery** - Read task metadata, understand requirements
2. **Phase 2: Context Gathering** - Discover upstream artifacts, gather context
3. **Phase 3: Domain Work** - Execute role-specific work
4. **Phase 4: Artifact Generation** - Generate deliverables with manifest
5. **Phase 5: Reporting** - Report completion to coordinator
## CLI Tool Integration
Workers can use CLI tools for complex analysis:
| Capability | CLI Command | Used By |
|------------|-------------|---------|
| Codebase exploration | `ccw cli --tool gemini --mode analysis` | analyst, planner, architect |
| Multi-perspective critique | `ccw cli --tool gemini --mode analysis` (parallel) | analyst, writer, reviewer |
| Document generation | `ccw cli --tool gemini --mode write` | writer |
**Note**: Workers CANNOT spawn utility members (explorer, discussant). Only the coordinator can spawn utility members.
## Utility Members (Coordinator-Only)
Utility members are NOT roles but specialized subagents that can only be spawned by the coordinator:
| Utility | Purpose | Callable By |
|---------|---------|-------------|
| explorer | Parallel multi-angle exploration | Coordinator only |
| discussant | Aggregate multi-CLI critique | Coordinator only |
| doc-generator | Template-based doc generation | Coordinator only |
**Location**: `../subagents/` (not in roles directory)
## Adding New Roles
To add a new specialist role:
1. Create role specification file in `specialists/` directory
2. Follow the role specification format
3. Define injection trigger (keywords or complexity)
4. Update `../specs/team-config.json` role registry
5. Update coordinator's role injection logic
6. Test with sample task descriptions
## Role Selection Logic
### Pipeline Selection
Coordinator selects pipeline based on user requirements:
- **Spec-only**: Documentation, requirements, design work
- **Impl-only**: Quick implementations with clear requirements
- **Full-lifecycle**: Complete feature development
### Specialist Injection
Coordinator analyzes task description for:
1. **Keywords**: Specific domain terms (security, performance, data, etc.)
2. **Complexity**: Module count, dependency depth
3. **Explicit requests**: User mentions specific expertise needed
### Conditional Routing
PLAN-001 assesses complexity and routes to appropriate implementation strategy:
- **Low complexity** → Direct implementation (executor only)
- **Medium complexity** → Orchestrated implementation (orchestrator + parallel executors)
- **High complexity** → Architecture + orchestrated implementation (architect + orchestrator + parallel executors)
## Reference Documents
For detailed information, see:
- [../specs/core-concepts.md](../specs/core-concepts.md) - Foundational principles
- [../specs/execution-flow.md](../specs/execution-flow.md) - Execution walkthrough
- [../specs/artifact-contract-spec.md](../specs/artifact-contract-spec.md) - Artifact manifest specification
- [coordinator/role.md](coordinator/role.md) - Coordinator specification

236
.claude/skills/team-lifecycle-v3/roles/coordinator/commands/dispatch.md
View File

@@ -1,236 +0,0 @@
# Command: dispatch (v3 Enhanced)
Create task chains based on execution mode with conditional routing, dynamic role injection, and priority assignment.
## Phase 2: Context Loading
| Input | Source | Required |
|-------|--------|----------|
| Mode | Phase 1 requirements | Yes |
| Session folder | Phase 2 session init | Yes |
| Scope | User requirements | Yes |
| Injected roles | Phase 1 keyword analysis | No |
| Complexity | Phase 1 assessment | No |
## Phase 3: Task Chain Creation
### Spec Pipeline (6 tasks, 3 discuss)
| # | Subject | Owner | BlockedBy | Description | Validation | Priority |
|---|---------|-------|-----------|-------------|------------|----------|
| 1 | RESEARCH-001 | analyst | (none) | Seed analysis and context gathering | DISCUSS-001 | P0 |
| 2 | DRAFT-001 | writer | RESEARCH-001 | Generate Product Brief | self-validate | P0 |
| 3 | DRAFT-002 | writer | DRAFT-001 | Generate Requirements/PRD | DISCUSS-002 | P0 |
| 4 | DRAFT-003 | writer | DRAFT-002 | Generate Architecture Document | self-validate | P0 |
| 5 | DRAFT-004 | writer | DRAFT-003 | Generate Epics & Stories | self-validate | P0 |
| 6 | QUALITY-001 | reviewer | DRAFT-004 | 5-dimension spec quality + sign-off | DISCUSS-003 | P0 |
### Impl Pipeline - Dynamic Task Creation
Initial dispatch creates **only PLAN-001**. IMPL-*, TEST-001, REVIEW-001 are dynamically created after PLAN-001 completes (see monitor.md handleCallback → PLAN-001).
#### Initial Dispatch (all complexity levels)
| # | Subject | Owner | BlockedBy | Description | Priority |
|---|---------|-------|-----------|-------------|----------|
| 1 | PLAN-001 | planner | (none) | Planning with complexity assessment + TASK-*.json generation | P0 |
#### Dynamic Creation (after PLAN-001 completes)
Coordinator reads planner's output and creates tasks dynamically:
1. Read `<session-folder>/plan/plan.json` → extract `complexity` field
2. Read `<session-folder>/plan/.task/TASK-*.json` → enumerate sub-tasks
3. Apply complexity routing:
| Complexity | Pre-IMPL tasks | Then |
|------------|---------------|------|
| Low | (none) | Create IMPL-* directly, blockedBy PLAN-001 |
| Medium | ORCH-001 (orchestrator, blockedBy PLAN-001) | Create IMPL-* blockedBy ORCH-001 |
| High | ARCH-001 (architect, blockedBy PLAN-001) → ORCH-001 (blockedBy ARCH-001) | Create IMPL-* blockedBy ORCH-001 |
4. For each `TASK-N.json`, create corresponding IMPL task:
```
TaskCreate({
subject: "IMPL-00N",
description: "PURPOSE: <TASK-N.title> | Success: <TASK-N.convergence.criteria>
TASK:
- <steps from TASK-N.json>
CONTEXT:
- Session: <session-folder>
- Task file: <session-folder>/plan/.task/TASK-N.json
- Files: <TASK-N.files[]>
- Priority: P0
EXPECTED: Implementation matching task file specification
CONSTRAINTS: Only modify files listed in task file
---
Validation: self-validate
InnerLoop: false
Priority: P0",
addBlockedBy: [<PLAN-001 or ORCH-001>]
})
```
5. Create TEST-001 (tester, blockedBy all IMPL-*, P1)
6. Create REVIEW-001 (reviewer, blockedBy all IMPL-*, P1)
7. Apply dynamic role injection (see below)
### FE Pipeline (3 tasks)
| # | Subject | Owner | BlockedBy | Description | Priority |
|---|---------|-------|-----------|-------------|----------|
| 1 | PLAN-001 | planner | (none) | Planning (frontend focus) | P0 |
| 2 | DEV-FE-001 | fe-developer | PLAN-001 | Frontend implementation | P0 |
| 3 | QA-FE-001 | fe-qa | DEV-FE-001 | 5-dimension frontend QA | P1 |
### Fullstack Pipeline (6 tasks, parallel execution)
| # | Subject | Owner | BlockedBy | Description | Priority |
|---|---------|-------|-----------|-------------|----------|
| 1 | PLAN-001 | planner | (none) | Fullstack planning | P0 |
| 2 | IMPL-001 | executor | PLAN-001 | Backend implementation | P0 |
| 3 | DEV-FE-001 | fe-developer | PLAN-001 | Frontend implementation (parallel) | P0 |
| 4 | TEST-001 | tester | IMPL-001 | Backend test-fix | P1 |
| 5 | QA-FE-001 | fe-qa | DEV-FE-001 | Frontend QA (parallel) | P1 |
| 6 | REVIEW-001 | reviewer | TEST-001, QA-FE-001 | Full code review | P1 |
### Dynamic Role Injection (v3 NEW)
When specialist roles are injected, add corresponding tasks (blockedBy references the **last IMPL-*** task dynamically):
| Injected Role | Task ID | Owner | BlockedBy | Description | Priority |
|---------------|---------|-------|-----------|-------------|----------|
| security-expert | SECURITY-001 | security-expert | all IMPL-* | Security audit (OWASP Top 10) | P0 |
| performance-optimizer | PERF-001 | performance-optimizer | all IMPL-* | Performance profiling & optimization | P1 |
| data-engineer | DATA-001 | data-engineer | PLAN-001 | Data pipeline implementation (parallel) | P0 |
| devops-engineer | DEVOPS-001 | devops-engineer | all IMPL-* | CI/CD & infrastructure setup | P1 |
| ml-engineer | ML-001 | ml-engineer | PLAN-001 | ML pipeline implementation (parallel) | P0 |
**Injection Rules**:
- Security tasks: P0 priority, block REVIEW-001
- Performance tasks: P1 priority, parallel with TEST-001
- Data/ML tasks: P0 priority, parallel with IMPL-*
- DevOps tasks: P1 priority, after all IMPL-*
### Composite Modes
| Mode | Construction | PLAN-001 BlockedBy |
|------|-------------|-------------------|
| full-lifecycle | Spec (6) + Impl (conditional) | QUALITY-001 |
| full-lifecycle-fe | Spec (6) + Fullstack (6) | QUALITY-001 |
### Task Description Template
```
TaskCreate({
subject: "<TASK-ID>",
description: "PURPOSE: <what> | Success: <criteria>
TASK:
- <step 1>
- <step 2>
- <step 3>
CONTEXT:
- Session: <session-folder>
- Scope: <scope>
- Upstream: <artifacts>
- Priority: <P0|P1|P2>
EXPECTED: <deliverable> + <quality>
CONSTRAINTS: <scope limits>
---
Validation: <DISCUSS-NNN or self-validate>
InnerLoop: <true|false>
Priority: <P0|P1|P2>",
addBlockedBy: [<deps>]
})
```
### Complexity Assessment Logic (v3 NEW)
PLAN-001 task description includes complexity assessment and TASK-*.json generation instructions:
```
PURPOSE: Create implementation plan with complexity assessment and task decomposition | Success: plan.json + TASK-*.json files
TASK:
- Analyze requirements and scope
- Identify modules and dependencies
- Assess complexity (Low/Medium/High)
- Generate plan.json with complexity field
- Generate .task/TASK-*.json files (1 per implementation unit, 2-7 tasks)
- Each TASK-*.json must include: id, title, files[].change, convergence.criteria, depends_on
CONTEXT:
- Session: <session-folder>
- Spec artifacts: <paths>
- Complexity criteria:
* Low: 1-2 modules, shallow deps, single tech stack
* Medium: 3-4 modules, moderate deps, 2 tech stacks
* High: 5+ modules, deep deps, multiple tech stacks
EXPECTED:
<session-folder>/plan/plan.json (with complexity field)
<session-folder>/plan/.task/TASK-001.json ... TASK-00N.json
Priority: P0
```
### Revision Task Template
```
TaskCreate({
subject: "<ORIGINAL-ID>-R1",
owner: "<same-role>",
description: "PURPOSE: Revision of <ORIGINAL-ID> | Success: Address feedback
TASK:
- Review original + feedback
- Apply fixes
- Validate
CONTEXT:
- Session: <session-folder>
- Original: <artifact-path>
- Feedback: <text>
- Priority: <inherit-from-original>
EXPECTED: Updated artifact + summary
---
Validation: <same-as-original>
InnerLoop: <same-as-original>
Priority: <inherit-from-original>",
addBlockedBy: []
})
```
## Phase 4: Artifact Manifest Generation
For each task, include artifact manifest generation instructions in task description:
```
---
Artifact Contract:
Generate artifact-manifest.json in Phase 4:
{
"artifact_id": "<role>-<type>-<timestamp>",
"creator_role": "<role>",
"artifact_type": "<type>",
"version": "1.0.0",
"path": "<relative-path>",
"dependencies": [<upstream-artifact-ids>],
"validation_status": "pending|passed|failed",
"validation_summary": "<summary>",
"metadata": {
"created_at": "<ISO8601>",
"task_id": "<task-id>",
"priority": "<P0|P1|P2>"
}
}
```
## Error Handling
| Error | Resolution |
|-------|------------|
| Invalid mode | Reject, ask to clarify |
| Complexity assessment missing | Default to Low complexity |
| Injected role not found | Log warning, skip injection |
| Priority conflict | P0 > P1 > P2, FIFO within same priority |
| Circular dependency | Detect, report, halt |

68
.claude/skills/team-lifecycle-v3/roles/coordinator/commands/execute.md
View File

@@ -1,68 +0,0 @@
# Command: execute
Spawn executor team-workers for IMPL tasks. All execution routes through executor role (has team interaction protocol). Coordinator only handles spawning — executor internally selects agent or CLI mode.
## Trigger
Called by `monitor.md handleSpawnNext` when IMPL-* tasks become ready.
## Spawn Logic
Each IMPL task = 1 executor team-worker. Coordinator passes task file + executor assignment, executor handles the rest.
```
Agent({
subagent_type: "team-worker",
run_in_background: true,
description: "IMPL-00N: <task title>",
prompt: "## Role Assignment
role: executor
skill: team-lifecycle-v3
session: <session-folder>
session_id: <session-id>
team_name: <team-name>
requirement: <task-description>
inner_loop: false
priority: P0
Task file: <task_file>
Executor: <agent|gemini|codex|qwen>
Session: <session-folder>"
})
```
## Parallel Spawn
When multiple IMPL tasks are ready simultaneously (same blockedBy set), spawn all in a **single message with multiple Agent() calls**:
```
// IMPL-001 (agent), IMPL-002 (codex), IMPL-003 (gemini) all ready
Agent({ subagent_type: "team-worker", description: "IMPL-001: ...", prompt: "...Executor: agent..." })
Agent({ subagent_type: "team-worker", description: "IMPL-002: ...", prompt: "...Executor: codex..." })
Agent({ subagent_type: "team-worker", description: "IMPL-003: ...", prompt: "...Executor: gemini..." })
```
**Rules**:
- Independent IMPL tasks (no mutual blockedBy) → parallel spawn
- Dependent IMPL tasks (TASK-B depends_on TASK-A) → sequential, spawn B after A completes
- Each worker is fully isolated — no shared context between IMPL agents
## Coordinator State Update
After spawning, log to message bus:
```
team_msg({
operation: "log",
session_id: "<session-id>",
from: "coordinator",
type: "impl_dispatched",
summary: "Spawned N executor workers",
data: {
tasks: [
{ id: "IMPL-001", executor: "agent", task_file: "..." },
{ id: "IMPL-002", executor: "codex", task_file: "..." }
]
}
})
```

275
.claude/skills/team-lifecycle-v3/roles/coordinator/commands/monitor.md
View File

@@ -1,275 +0,0 @@
# Command: monitor (v3 Enhanced)
Monitor team progress, handle callbacks, manage artifact registry, spawn next workers with priority scheduling.
## Handlers
| Handler | Trigger | Purpose |
|---------|---------|---------|
| handleCallback | Worker completion message | Process completion, validate artifacts, spawn next |
| handleCheck | User "check" command | Display current status |
| handleResume | User "resume" command | Advance pipeline |
| handleSpawnNext | Internal | Find ready tasks, priority sort, spawn workers |
| handleComplete | All tasks done | Trigger completion action |
---
## handleCallback
### Input
- Worker completion message via SendMessage
- Message contains: role, task_id, status, artifact_path
### Steps
1. **Parse Message**
- Extract role, task_id, status from message
- Load task via TaskGet
2. **Update Task Status**
- TaskUpdate(status="completed")
- Log completion to message bus
3. **Artifact Validation (v3 NEW)**
- Check if artifact-manifest.json exists
- If exists:
- Read manifest
- Check validation_status
- Register artifact in artifact-registry.json
- If validation_status == "failed":
- Block downstream spawn
- Create fix task
- STOP
- If validation_status == "pending":
- Prompt user for manual validation
- STOP
- If not exists (backward compatible):
- Continue without validation gating
4. **Checkpoint Detection**
- If task_id == "QUALITY-001":
- Display checkpoint output (see SKILL.md)
- Pause for user command
- STOP
- If task_id == "PLAN-001" (v3 NEW):
- **Dynamic IMPL Task Creation from Planner DAG**:
1. Read `<session>/plan/plan.json` → extract `complexity` field
2. Glob `<session>/plan/.task/TASK-*.json` → enumerate task files
3. For each TASK file, read `depends_on` field to build DAG
4. Determine complexity routing:
- Low: no pre-IMPL tasks
- Medium: create ORCH-001 (blockedBy PLAN-001)
- High: create ARCH-001 (blockedBy PLAN-001) + ORCH-001 (blockedBy ARCH-001)
5. For each TASK-N.json, create IMPL-00N:
- `blockedBy`: map TASK-N `depends_on` → corresponding IMPL IDs + (PLAN-001 or ORCH-001)
- `description`: include `Task file: <session>/plan/.task/TASK-N.json`
- `Priority`: P0
6. Collect all IMPL-* task IDs
7. Create TEST-001 (tester, blockedBy all IMPL-*, P1)
8. Create REVIEW-001 (reviewer, blockedBy all IMPL-*, P1)
9. Apply dynamic role injection if specialist roles were identified
10. Display routing decision + created task count
- Continue to handleSpawnNext
5. **Spawn Next**
- Call handleSpawnNext
- STOP
---
## handleSpawnNext (v3 Enhanced)
### Steps
1. **Find Ready Tasks**
- TaskList -> filter status="pending"
- For each pending task:
- Check blockedBy dependencies
- All blockedBy tasks completed? -> ready
2. **Priority Sorting (v3 NEW)**
- Sort ready tasks by priority:
- P0 tasks first
- P1 tasks second
- P2 tasks last
- Within same priority: FIFO (creation order)
3. **Parallel Grouping (v3 NEW)**
- Group tasks by stage (same blockedBy set)
- Tasks in same group can spawn in parallel
- Example: IMPL-001 and DEV-FE-001 both blocked by PLAN-001 -> parallel group
4. **Artifact Discovery (v3 NEW)**
- For each ready task:
- Query artifact registry for upstream artifacts
- Generate context-artifacts.json with artifact paths
- Write to session folder for worker Phase 2 consumption
5. **Spawn Workers**
- For each ready task (or parallel group):
- Spawn team-worker agent with role-spec
- Include priority in prompt
- Include context-artifacts.json path
- Log spawn to message bus
6. **Output Summary**
- List spawned tasks with priorities
- Show remaining pending count
- STOP
### Spawn Template (v3 Enhanced)
```
Agent({
subagent_type: "team-worker",
description: "Spawn <role> worker",
team_name: <team-name>,
name: "<role>",
run_in_background: true,
prompt: `## Role Assignment
role: <role>
skill: team-lifecycle-v3
session: <session-folder>
session_id: <session-id>
team_name: <team-name>
requirement: <task-description>
inner_loop: <true|false>
priority: <P0|P1|P2>
context_artifacts: <session-folder>/context-artifacts.json
Execute built-in Phase 1 (task discovery) -> skill routes to role Phase 2-4 -> built-in Phase 5 (report).`
})
```
---
## handleCheck
### Steps
1. **Load Session State**
- Read team-session.json
- TaskList -> count by status
2. **Display Status**
- Session ID
- Mode
- Task counts: completed / in_progress / pending
- Current running workers
- Artifact registry summary (v3 NEW)
- Priority queue status (v3 NEW)
3. **STOP** (no advancement)
---
## handleResume
### Steps
1. **Reconcile State**
- TaskList -> find in_progress tasks
- Check if workers still running
- If worker missing:
- Reset task to pending
- Log orphan detection
2. **Fast-Advance Orphan Detection**
- Check message bus for fast_advance logs
- If fast_advance spawned wrong task:
- Reconcile task chain
- Respawn correct task
3. **Spawn Next**
- Call handleSpawnNext
- STOP
---
## handleComplete (v3 NEW)
### Trigger
- All tasks have status="completed"
- No tasks with status="pending" or "in_progress"
### Steps
1. **Generate Summary**
- Count total tasks, duration
- List deliverables with artifact paths
- Generate artifact registry summary
- Calculate quality metrics (discuss verdicts, review scores)
2. **Completion Action**
- Read completion_action from team-config.json
- If "interactive":
- AskUserQuestion (see coordinator role.md Phase 5)
- Execute user choice
- If "auto_archive":
- Update session status="completed"
- TeamDelete
- Archive artifacts
- If "auto_keep":
- Update session status="paused"
- Output resume instructions
3. **Cleanup**
- Write final session state
- Log completion to message bus
- STOP
---
## Artifact Registry Operations (v3 NEW)
### Register Artifact
```javascript
// Read existing registry
const registry = JSON.parse(Read("<session>/artifact-registry.json"))
// Add new artifact
registry.artifacts[artifact_id] = {
manifest: <artifact-manifest>,
discovered_at: new Date().toISOString(),
consumed_by: []
}
// Write back
Write("<session>/artifact-registry.json", JSON.stringify(registry))
```
### Generate Context Artifacts
```javascript
// Query registry for upstream artifacts
const upstreamArtifacts = []
for (const dep of task.blockedBy) {
const depTask = TaskGet(dep)
const artifactId = findArtifactByTaskId(registry, depTask.id)
if (artifactId) {
upstreamArtifacts.push(registry.artifacts[artifactId].manifest)
}
}
// Write context-artifacts.json for worker consumption
Write("<session>/context-artifacts.json", JSON.stringify({
task_id: task.id,
upstream_artifacts: upstreamArtifacts,
generated_at: new Date().toISOString()
}))
```
---
## Error Handling
| Error | Resolution |
|-------|------------|
| Worker timeout | Mark task failed, ask user to retry |
| Artifact validation fails | Block downstream, create fix task |
| Artifact manifest missing | Continue without validation (backward compatible) |
| Priority conflict | P0 > P1 > P2, FIFO within same priority |
| Parallel spawn fails | Log error, spawn sequentially |
| Registry corruption | Rebuild from task artifacts |
| Completion action fails | Fallback to manual cleanup |

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

@@ -1,270 +0,0 @@
# Coordinator Role (v3 Enhanced)
Orchestrate team-lifecycle-v3: team creation, task dispatching with priority scheduling, dynamic role injection, artifact registry management, progress monitoring. Uses **team-worker agent** for all worker spawns.
## Identity
- **Name**: `coordinator` | **Tag**: `[coordinator]`
- **Responsibility**: Parse requirements -> Inject roles -> Create team -> Dispatch tasks -> Monitor progress -> Manage artifacts -> Report
## v3 Enhancements
| Feature | Description |
|---------|-------------|
| Dynamic Role Injection | Analyze task keywords to inject specialist roles at runtime |
| Priority Scheduling | P0/P1/P2 task prioritization with critical path optimization |
| Artifact Registry | Maintain in-memory registry for automatic artifact discovery |
| Conditional Routing | Route based on complexity assessment from PLAN-001 |
| Parallel Orchestration | Spawn multiple workers in parallel stages |
## Boundaries
### MUST
- Parse user requirements and clarify via AskUserQuestion
- Analyze task description for specialist role injection
- Create team and spawn workers using **team-worker** agent type
- Dispatch tasks with proper dependency chains and priority levels
- Monitor progress via callbacks and route messages
- Maintain artifact registry for validation gating
- Maintain session state (team-session.json)
### MUST NOT
- Execute spec/impl/research work directly
- Modify task outputs
- Skip dependency validation
- Skip artifact validation gating
---
## Entry Router
| Detection | Condition | Handler |
|-----------|-----------|---------|
| Worker callback | Message contains `[role-name]` tag | -> handleCallback |
| Status check | "check" or "status" | -> handleCheck |
| Manual resume | "resume" or "continue" | -> handleResume |
| Interrupted session | Active/paused session in `.workflow/.team/TLS-*` | -> Phase 0 |
| New session | None of above | -> Phase 1 |
For callback/check/resume: load `commands/monitor.md`, execute handler, STOP.
---
## Phase 0: Session Resume Check
1. Scan `.workflow/.team/TLS-*/team-session.json` for active/paused
2. No sessions -> Phase 1
3. Single session -> resume (reconciliation)
4. Multiple -> AskUserQuestion
**Session Reconciliation**:
1. Audit TaskList, reconcile with session state
2. Reset in_progress -> pending (interrupted tasks)
3. Rebuild team if disbanded
4. Restore artifact registry from session
5. Create missing tasks with correct blockedBy
6. Kick first executable -> Phase 4
---
## Phase 1: Requirement Clarification
1. Parse arguments for mode, scope, focus
2. Ask missing parameters via AskUserQuestion:
- Mode: spec-only / impl-only / full-lifecycle / fe-only / fullstack / full-lifecycle-fe
- Scope: project description
3. Frontend auto-detection (keyword + package.json scanning)
4. **v3 NEW**: Keyword analysis for specialist role injection
5. Store requirements
### Keyword Analysis (v3 NEW)
Scan task description for specialist role triggers:
| Keywords | Injected Role | Injection Point |
|----------|---------------|-----------------|
| security, vulnerability, OWASP, audit | security-expert | After PLAN-001 |
| performance, optimization, bottleneck, latency | performance-optimizer | After IMPL-* |
| data, pipeline, ETL, schema, migration | data-engineer | Parallel with IMPL-* |
| devops, CI/CD, deployment, docker, kubernetes | devops-engineer | After IMPL-* |
| ML, model, training, inference, neural | ml-engineer | Parallel with IMPL-* |
| orchestrate, complex, multi-module | orchestrator | Replace IMPL-* with ORCH-* |
---
## Phase 2: Create Team + Initialize Session
1. Generate session ID: `TLS-<slug>-<date>`
2. Create session folder: `.workflow/.team/<session-id>/`
3. **v3 NEW**: Create artifact registry: `<session-id>/artifact-registry.json`
4. TeamCreate
5. Initialize directories (spec/, discussions/, plan/, explorations/, artifacts/)
6. Write team-session.json with injected roles
7. Initialize meta.json via team_msg state_update:
```
mcp__ccw-tools__team_msg({
operation: "log",
session_id: "<session-id>",
from: "coordinator",
type: "state_update",
summary: "Session initialized",
data: {
pipeline_mode: "<mode>",
pipeline_stages: [<role-list>],
roles: [<all-roles>],
injected_roles: [<specialist-roles>],
team_name: "lifecycle-v3",
artifact_registry_enabled: true,
priority_scheduling_enabled: true
}
})
```
---
## Phase 3: Create Task Chain
Delegate to `commands/dispatch.md`:
1. Read Task Metadata Registry for task definitions
2. **v3 NEW**: Assess complexity from requirements (Low/Medium/High)
3. **v3 NEW**: Apply conditional routing based on complexity
4. **v3 NEW**: Inject specialist role tasks based on keywords
5. Create tasks via TaskCreate with correct blockedBy and priority
6. Include `Session: <session-folder>` in every task
7. Mark discuss rounds (DISCUSS-001, DISCUSS-002, DISCUSS-003) or "self-validate"
### Complexity Assessment (v3 NEW)
| Complexity | Indicators | Route |
|------------|-----------|-------|
| Low | 1-2 modules, shallow deps, single tech stack | Direct IMPL-001 |
| Medium | 3-4 modules, moderate deps, 2 tech stacks | ORCH-001 -> parallel IMPL-* |
| High | 5+ modules, deep deps, multiple tech stacks | ARCH-001 -> ORCH-001 -> parallel IMPL-* |
### Priority Assignment (v3 NEW)
| Task Type | Priority | Rationale |
|-----------|----------|-----------|
| Spec pipeline | P0 | Blocking all downstream |
| PLAN-001, ARCH-001 | P0 | Critical path |
| ORCH-001, parallel IMPL-* | P0 | Critical path |
| TEST-*, QA-* | P1 | Validation phase |
| REVIEW-*, specialist analysis | P1 | Quality gate |
| IMPROVE-*, optimization | P2 | Enhancement |
---
## Phase 4: Spawn-and-Stop
1. Load `commands/monitor.md`
2. Find ready tasks (pending + blockedBy resolved)
3. **v3 NEW**: Sort by priority (P0 > P1 > P2), FIFO within same priority
4. **v3 NEW**: Identify parallel groups (same stage, no mutual blockedBy)
5. Spawn team-worker for each ready task (parallel spawn for same group)
6. Output summary with priority levels
7. STOP
### Checkpoint Gate (QUALITY-001)
When QUALITY-001 completes:
1. Read readiness-report.md
2. Parse quality gate and dimension scores
3. Output Checkpoint Template (see SKILL.md)
4. Pause for user command
### Complexity Routing Gate (PLAN-001, v3 NEW)
When PLAN-001 completes:
1. Read plan.json for complexity assessment
2. Apply conditional routing:
- Low: spawn IMPL-001 directly
- Medium: spawn ORCH-001 first
- High: spawn ARCH-001 first
3. Output routing decision
4. Continue
---
## Phase 5: Report + Completion Action
1. Count completed tasks, duration
2. List deliverables with artifact paths
3. **v3 NEW**: Generate artifact registry summary
4. Update session status -> "completed"
5. **v3 NEW**: Trigger completion action (interactive/auto-archive/auto-keep)
### Completion Action (v3 NEW)
```
AskUserQuestion({
questions: [{
question: "Team pipeline complete. What would you like to do?",
header: "Completion",
multiSelect: false,
options: [
{ label: "Archive & Clean", description: "Archive session, clean up tasks and team resources" },
{ label: "Keep Active", description: "Keep session active for follow-up work or inspection" },
{ label: "Export Results", description: "Export deliverables to a specified location, then clean" }
]
}]
})
```
| Choice | Action |
|--------|--------|
| Archive & Clean | Update session status="completed", TeamDelete, archive artifacts |
| Keep Active | Update session status="paused", output resume instructions |
| Export Results | Copy deliverables to user-specified path, then Archive & Clean |
---
## Artifact Registry Management (v3 NEW)
### Registry Structure
```json
{
"artifacts": {
"<artifact-id>": {
"manifest": { ... },
"discovered_at": "timestamp",
"consumed_by": ["<role-name>"]
}
}
}
```
### Registry Operations
| Operation | When | Action |
|-----------|------|--------|
| Register | Worker Phase 5 callback | Add artifact manifest to registry |
| Validate | Before spawning downstream | Check validation_status |
| Discover | Worker Phase 2 request | Generate context-artifacts.json |
| Update | Worker consumes artifact | Add to consumed_by list |
### Validation Gating
Before spawning downstream worker:
1. Read artifact manifest from registry
2. Check validation_status:
- `passed`: spawn next worker
- `failed`: block spawn, trigger fix loop
- `pending`: wait or prompt manual validation
---
## Error Handling
| Error | Resolution |
|-------|------------|
| Task timeout | Log, mark failed, ask user |
| Worker crash | Respawn worker, reassign task |
| Dependency cycle | Detect, report, halt |
| Invalid mode | Reject, ask to clarify |
| Session corruption | Attempt recovery |
| Artifact validation fails | Block downstream, create fix task |
| Role injection fails | Log warning, continue with core roles |
| Priority conflict | P0 > P1 > P2, FIFO within same priority |
| Parallel merge timeout | Report stall, prompt user intervention |

108
.claude/skills/team-lifecycle-v3/roles/pipeline/analyst.md
View File

@@ -1,108 +0,0 @@
---
role: analyst
prefix: RESEARCH
inner_loop: false
discuss_rounds: [DISCUSS-001]
input_artifact_types: []
message_types:
success: research_ready
progress: research_progress
error: error
---
# Analyst — Phase 2-4
## Phase 2: Seed Analysis
**Objective**: Extract structured seed information from the topic.
1. Read upstream artifacts from `context-artifacts.json` (if exists)
2. Extract session folder from task description (`Session: <path>`)
3. Parse topic from task description
4. If topic starts with `@` or ends with `.md`/`.txt` → Read referenced file
5. Run CLI seed analysis:
```
Bash({
command: `ccw cli -p "PURPOSE: Analyze topic and extract structured seed information.
TASK: * Extract problem statement * Identify target users * Determine domain context
* List constraints * Identify 3-5 exploration dimensions * Assess complexity
TOPIC: <topic-content>
MODE: analysis
EXPECTED: JSON with: problem_statement, target_users[], domain, constraints[], exploration_dimensions[], complexity_assessment" --tool gemini --mode analysis`,
run_in_background: false
})
```
6. Parse seed analysis JSON
## Phase 3: Codebase Exploration (conditional)
**Objective**: Gather codebase context if project detected.
| Condition | Action |
|-----------|--------|
| package.json / Cargo.toml / pyproject.toml / go.mod exists | Explore |
| No project files | Skip (codebase_context = null) |
**When project detected**: Use CLI exploration.
```
Bash({
command: `ccw cli -p "PURPOSE: Explore codebase for context to inform spec generation
TASK: • Identify tech stack • Map architecture patterns • Document conventions • List integration points
MODE: analysis
CONTEXT: @**/*
EXPECTED: JSON with: tech_stack[], architecture_patterns[], conventions[], integration_points[]" --tool gemini --mode analysis --rule analysis-analyze-code-patterns`,
run_in_background: false
})
```
## Phase 4: Context Packaging + Discuss
### 4a: Context Packaging
**spec-config.json** → `<session>/spec/spec-config.json`
**discovery-context.json** → `<session>/spec/discovery-context.json`
**design-intelligence.json** → `<session>/analysis/design-intelligence.json` (UI mode only)
### 4b: Generate Artifact Manifest
Create `<session>/artifacts/<task-id>/artifact-manifest.json`:
```json
{
"artifact_id": "uuid-...",
"creator_role": "analyst",
"artifact_type": "spec",
"version": "1.0.0",
"path": "./spec/discovery-context.json",
"dependencies": [],
"validation_status": "passed",
"validation_summary": "Seed analysis complete, codebase explored",
"metadata": {
"complexity": "low | medium | high",
"has_codebase": true | false
}
}
```
### 4c: Inline Discuss (DISCUSS-001)
Call discuss subagent:
- Artifact: `<session>/spec/discovery-context.json`
- Round: DISCUSS-001
- Perspectives: product, risk, coverage
Handle verdict per consensus protocol.
**Report**: complexity, codebase presence, problem statement, dimensions, discuss verdict, output paths.
## Error Handling
| Scenario | Resolution |
|----------|------------|
| CLI failure | Fallback to direct Claude analysis |
| Codebase detection failed | Continue as new project |
| Topic too vague | Report with clarification questions |
| Discuss subagent fails | Proceed without discuss, log warning |

76
.claude/skills/team-lifecycle-v3/roles/pipeline/architect.md
View File

@@ -1,76 +0,0 @@
---
role: architect
prefix: ARCH
inner_loop: false
discuss_rounds: []
input_artifact_types: []
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 |

171
.claude/skills/team-lifecycle-v3/roles/pipeline/executor.md
View File

@@ -1,171 +0,0 @@
---
role: executor
prefix: IMPL
inner_loop: false
discuss_rounds: []
input_artifact_types: [plan, spec, architecture]
message_types:
success: impl_complete
progress: impl_progress
error: error
---
# Executor — Phase 2-4
**Role**: Implementation worker with team interaction protocol. Supports two execution modes: direct agent implementation or CLI delegation. Coordinator assigns mode per task via `Executor:` field.
## Phase 2: Parse Task & Resolve Execution Mode
**Objective**: Load task JSON, execute pre-analysis, resolve execution mode.
### 2.1 Extract from task description
- `Task file:` → `task_file` path
- `Session:` → `session` folder
- `Executor:` → `mode` (`agent` | `gemini` | `codex` | `qwen`)
### 2.2 Load task JSON (read task_file)
```
Task JSON Fields:
├── id, title, scope, action
├── description → Implementation goal
├── files[] → Target files (path, target, change)
├── implementation[] → Step-by-step execution instructions
├── convergence.criteria[] → Done-when checklist
├── pre_analysis[] → Context gathering steps (optional)
│ └── { step, action, commands[], output_to, on_error }
├── reference → Pattern reference (pattern, files[], examples)
├── risks[] → Risk mitigations (optional)
├── rationale → Approach rationale (optional)
└── depends_on[] → (handled by coordinator, not executor)
```
### 2.3 Resolve execution mode (priority order)
| Priority | Source | Resolution |
|----------|--------|------------|
| 1 | Task description `Executor:` | Coordinator assignment |
| 2 | task.meta.execution_config.method | Per-task config from planner |
| 3 | plan.json recommended_execution | Plan-level default |
| 4 | Auto-select | Low complexity → agent; Medium/High → codex |
### 2.4 Execute pre_analysis (if exists, runs locally regardless of mode)
```
For each step in task.pre_analysis[]:
→ Parse step.commands[] using command-to-tool mapping:
"Read(path)" → Read tool
"bash(command)" → Bash tool
"Search(pattern,path)" → Grep tool
"Glob(pattern)" → Glob tool
→ Store output in [step.output_to] variable
→ Handle errors per step.on_error (fail | continue | skip)
```
## Phase 3: Execute Implementation
Route by resolved execution mode:
### Mode: `agent` — Direct Implementation
Executor implements directly using Edit/Write/Bash tools. Follows code-developer patterns.
```
1. Read task.files[] as target files
2. Read task.implementation[] as step-by-step instructions
3. For each implementation step:
- Substitute [variable_name] placeholders with pre_analysis results
- For each file in step:
* New file → Write tool
* Modify file → Edit tool
- Follow task.reference (pattern, files) for consistency
4. Apply task.rationale.chosen_approach
5. Mitigate task.risks[] during implementation
```
**Quality rules** (same as code-developer):
- Verify module/package existence before referencing (use Grep/Glob)
- Incremental progress — small working changes
- Follow existing code patterns from task.reference
- No premature abstractions
- ASCII-only, GBK-compatible
### Mode: `gemini` / `codex` / `qwen` — CLI Delegation
Build structured prompt from task JSON, delegate to CLI tool.
**Build handoff prompt**:
```javascript
function buildCliHandoffPrompt(task, preAnalysisResults) {
const context = Object.entries(preAnalysisResults)
.map(([key, value]) => `### ${key}\n${value}`)
.join('\n\n')
return `
PURPOSE: ${task.title}
${task.description}
## TARGET FILES
${task.files?.map(f => `- **${f.path}** → ${f.change}`).join('\n')}
## IMPLEMENTATION STEPS
${task.implementation?.map((s, i) => `${i+1}. ${s}`).join('\n')}
${context ? `## PRE-ANALYSIS CONTEXT\n${context}` : ''}
${task.reference ? `## REFERENCE\n- Pattern: ${task.reference.pattern}\n- Files: ${task.reference.files?.join(', ')}` : ''}
${task.rationale ? `## APPROACH\n${task.rationale.chosen_approach}` : ''}
${task.risks?.length ? `## RISKS\n${task.risks.map(r => `- ${r.description} → **${r.mitigation}**`).join('\n')}` : ''}
## DONE WHEN
${task.convergence?.criteria?.map(c => `- [ ] ${c}`).join('\n')}
MODE: write
CONSTRAINTS: Only modify files listed above | Follow existing patterns
`.trim()
}
```
**CLI call**:
```
Bash({
command: `ccw cli -p "${buildCliHandoffPrompt(task, preAnalysisResults)}"
--tool <cli_tool> --mode write --rule development-implement-feature`,
run_in_background: false,
timeout: 3600000
})
```
**Resume strategy** (if task.cli_execution exists):
| Strategy | Command |
|----------|---------|
| new | `--id <session>-<task_id>` |
| resume | `--resume <parent_id>` |
| fork | `--resume <parent_id> --id <new_id>` |
| merge_fork | `--resume <id1>,<id2> --id <new_id>` |
## Phase 4: Self-Validation
| Step | Method | Pass Criteria |
|------|--------|--------------|
| Convergence check | Match task.convergence.criteria vs output | All criteria addressed |
| Syntax check | `tsc --noEmit` or language-appropriate (30s) | Exit code 0 |
| Test detection | Find test files for modified files | Tests identified |
**Report**: task ID, status, mode used, files modified, convergence results.
## Error Handling
| Scenario | Resolution |
|----------|------------|
| Agent mode: syntax errors | Retry with error context (max 3) |
| CLI mode: execution failure | Retry, or resume with --resume |
| pre_analysis failure | Follow step.on_error (fail/continue/skip) |
| CLI tool unavailable | Fallback: gemini → qwen → codex |
| Max retries exceeded | Report failure to coordinator |

79
.claude/skills/team-lifecycle-v3/roles/pipeline/fe-developer.md
View File

@@ -1,79 +0,0 @@
---
role: fe-developer
prefix: DEV-FE
inner_loop: false
discuss_rounds: []
input_artifact_types: []
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-v3/roles/pipeline/fe-qa.md
View File

@@ -1,79 +0,0 @@
---
role: fe-qa
prefix: QA-FE
inner_loop: false
discuss_rounds: []
input_artifact_types: []
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 |

145
.claude/skills/team-lifecycle-v3/roles/pipeline/orchestrator.md
View File

@@ -1,145 +0,0 @@
---
prefix: ORCH
inner_loop: false
message_types:
success: orch_complete
error: error
---
# Orchestrator
Decomposes complex multi-module tasks into coordinated sub-tasks with parallel execution and dependency management.
## Phase 2: Context & Complexity Assessment
| Input | Source | Required |
|-------|--------|----------|
| Task description | From coordinator | Yes |
| Plan document | Session plan/ | Yes |
| Exploration cache | Session explorations/ | No |
### Step 1: Load Context
Extract session path from task description. Read plan document to understand scope and requirements.
### Step 2: Complexity Analysis
Assess task complexity across dimensions:
| Dimension | Indicators | Weight |
|-----------|-----------|--------|
| Module count | Number of modules affected | High |
| Dependency depth | Cross-module dependencies | High |
| Technology stack | Multiple tech stacks involved | Medium |
| Integration points | External system integrations | Medium |
### Step 3: Decomposition Strategy
| Complexity | Strategy |
|------------|----------|
| 2-3 modules, shallow deps | Simple parallel split |
| 4-6 modules, moderate deps | Phased parallel with integration checkpoints |
| 7+ modules, deep deps | Hierarchical decomposition with sub-orchestrators |
### Step 4: Exploration
If complexity is High, delegate to explorer utility member for codebase context gathering.
## Phase 3: Task Decomposition & Coordination
### Step 1: Generate Sub-Tasks
Break down into parallel tracks:
| Track Type | Characteristics | Owner Role |
|------------|----------------|------------|
| Frontend | UI components, state management | fe-developer |
| Backend | API, business logic, data access | executor |
| Data | Schema, migrations, ETL | data-engineer |
| Infrastructure | Deployment, CI/CD | devops-engineer |
### Step 2: Dependency Mapping
Create dependency graph:
- Identify shared interfaces (API contracts, data schemas)
- Mark blocking dependencies (schema before backend, API before frontend)
- Identify parallel-safe tracks
### Step 3: Priority Assignment
Assign priority levels:
| Priority | Criteria | Impact |
|----------|----------|--------|
| P0 | Blocking dependencies, critical path | Execute first |
| P1 | Standard implementation | Execute after P0 |
| P2 | Nice-to-have, non-blocking | Execute last |
### Step 4: Spawn Coordination
Create sub-tasks via coordinator message:
```
SendMessage({
type: "spawn_request",
recipient: "coordinator",
content: {
sub_tasks: [
{ id: "IMPL-FE-001", role: "fe-developer", priority: "P1", blockedBy: ["IMPL-BE-001"] },
{ id: "IMPL-BE-001", role: "executor", priority: "P0", blockedBy: [] },
{ id: "DATA-001", role: "data-engineer", priority: "P0", blockedBy: [] }
],
parallel_groups: [
["IMPL-BE-001", "DATA-001"],
["IMPL-FE-001"]
]
}
})
```
## Phase 4: Integration & Validation
### Step 1: Monitor Progress
Track sub-task completion via message bus. Wait for all sub-tasks in current parallel group to complete.
### Step 2: Integration Check
Validate integration points:
| Check | Method | Pass Criteria |
|-------|--------|---------------|
| API contracts | Compare spec vs implementation | All endpoints match |
| Data schemas | Validate migrations applied | Schema version consistent |
| Type consistency | Cross-module type checking | No type mismatches |
### Step 3: Artifact Registry
Generate artifact manifest for orchestration result:
```javascript
Write("artifact-manifest.json", JSON.stringify({
artifact_id: `orchestrator-integration-${Date.now()}`,
creator_role: "orchestrator",
artifact_type: "integration",
version: "1.0.0",
path: "integration-report.md",
dependencies: ["<sub-task-artifact-ids>"],
validation_status: "passed",
validation_summary: "All integration points validated",
metadata: {
created_at: new Date().toISOString(),
task_id: "<current-task-id>",
sub_task_count: <count>,
parallel_groups: <groups>
}
}))
```
### Step 4: Report
Generate integration report with:
- Sub-task completion status
- Integration validation results
- Identified issues and resolutions
- Next steps or recommendations

98
.claude/skills/team-lifecycle-v3/roles/pipeline/planner.md
View File

@@ -1,98 +0,0 @@
---
role: planner
prefix: PLAN
inner_loop: true
discuss_rounds: []
input_artifact_types: [spec, architecture]
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 |

94
.claude/skills/team-lifecycle-v3/roles/pipeline/reviewer.md
View File

@@ -1,94 +0,0 @@
---
role: reviewer
prefix: REVIEW
additional_prefixes: [QUALITY, IMPROVE]
inner_loop: false
discuss_rounds: [DISCUSS-003]
input_artifact_types: []
message_types:
success_review: review_result
success_quality: quality_result
fix: fix_required
error: error
---
# Reviewer — Phase 2-4
## Phase 2: Mode Detection
| Task Prefix | Mode | Dimensions | Discuss |
|-------------|------|-----------|---------|
| REVIEW-* | Code Review | quality, security, architecture, requirements | None |
| QUALITY-* | Spec Quality | completeness, consistency, traceability, depth, coverage | DISCUSS-003 |
| IMPROVE-* | Spec Quality (recheck) | Same as QUALITY | DISCUSS-003 |
## Phase 3: Review Execution
### Code Review (REVIEW-*)
**Inputs**: Plan file, git diff, modified files, test results
**4 dimensions**:
| Dimension | Critical Issues |
|-----------|----------------|
| Quality | Empty catch, any in public APIs, @ts-ignore, console.log |
| Security | Hardcoded secrets, SQL injection, eval/exec, innerHTML |
| Architecture | Circular deps, parent imports >2 levels, files >500 lines |
| Requirements | Missing core functionality, incomplete acceptance criteria |
### Spec Quality (QUALITY-* / IMPROVE-*)
**Inputs**: All spec docs in session folder, quality gate config
**5 dimensions**:
| Dimension | Weight | Focus |
|-----------|--------|-------|
| Completeness | 25% | All sections present with substance |
| Consistency | 20% | Terminology, format, references |
| Traceability | 25% | Goals -> Reqs -> Arch -> Stories chain |
| Depth | 20% | AC testable, ADRs justified, stories estimable |
| Coverage | 10% | Original requirements mapped |
**Quality gate**:
| Gate | Criteria |
|------|----------|
| PASS | Score >= 80% AND coverage >= 70% |
| REVIEW | Score 60-79% OR coverage 50-69% |
| FAIL | Score < 60% OR coverage < 50% |
**Artifacts**: readiness-report.md + spec-summary.md
## Phase 4: Verdict + Discuss
### Code Review Verdict
| Verdict | Criteria |
|---------|----------|
| BLOCK | Critical issues present |
| CONDITIONAL | High/medium only |
| APPROVE | Low or none |
### Spec Quality Discuss (DISCUSS-003)
After generating readiness-report.md, call discuss subagent:
- Artifact: `<session>/spec/readiness-report.md`
- Round: DISCUSS-003
- Perspectives: product, technical, quality, risk, coverage (all 5)
Handle verdict per consensus protocol.
> **Note**: DISCUSS-003 HIGH always triggers user pause (final sign-off gate).
**Report**: mode, verdict/gate, dimension scores, discuss verdict (QUALITY only), output paths.
## Error Handling
| Scenario | Resolution |
|----------|------------|
| Missing context | Request from coordinator |
| Invalid mode | Abort with error |
| Analysis failure | Retry, then fallback |
| Discuss subagent fails | Proceed without discuss, log warning |

76
.claude/skills/team-lifecycle-v3/roles/pipeline/tester.md
View File

@@ -1,76 +0,0 @@
---
role: tester
prefix: TEST
inner_loop: false
discuss_rounds: []
input_artifact_types: []
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 |

139
.claude/skills/team-lifecycle-v3/roles/pipeline/writer.md
View File

@@ -1,139 +0,0 @@
---
role: writer
prefix: DRAFT
inner_loop: true
discuss_rounds: [DISCUSS-002]
input_artifact_types: [spec]
message_types:
success: draft_ready
revision: draft_revision
error: error
---
# Writer — Phase 2-4
## Phase 2: Context Loading
**Objective**: Load all required inputs for document generation.
### 2a: Read Upstream Artifacts
Load `context-artifacts.json` to discover upstream artifacts:
```json
{
"artifacts": [
{
"artifact_id": "uuid-...",
"artifact_type": "spec",
"path": "./spec/discovery-context.json",
"creator_role": "analyst"
}
]
}
```
### 2b: Document Type Routing
| Task Subject Contains | Doc Type | Template | Validation |
|----------------------|----------|----------|------------|
| Product Brief | product-brief | templates/product-brief.md | self-validate |
| Requirements / PRD | requirements | templates/requirements-prd.md | DISCUSS-002 |
| Architecture | architecture | templates/architecture-doc.md | self-validate |
| Epics | epics | templates/epics-template.md | self-validate |
### 2c: Progressive Dependency Loading
| Doc Type | Requires |
|----------|----------|
| product-brief | discovery-context.json |
| requirements | + product-brief.md |
| architecture | + requirements/_index.md |
| epics | + architecture/_index.md |
**Prior decisions from accumulator**: Pass context_accumulator summaries as "Prior Decisions" to generation.
| Input | Source | Required |
|-------|--------|----------|
| Document standards | `../../specs/document-standards.md` | Yes |
| Template | From routing table | Yes |
| Spec config | `<session>/spec/spec-config.json` | Yes |
| Discovery context | `<session>/spec/discovery-context.json` | Yes |
| Discussion feedback | `<session>/discussions/<discuss-file>` | If exists |
| Prior decisions | context_accumulator (in-memory) | If prior tasks |
## Phase 3: Document Generation
**Objective**: Generate document using CLI tool.
```
Bash({
command: `ccw cli -p "PURPOSE: Generate <doc-type> document following template and standards
TASK: • Load template • Apply spec config and discovery context • Integrate prior feedback • Generate all sections
MODE: write
CONTEXT: @<session>/spec/*.json @<template-path> | Memory: Prior decisions: <accumulator summary>
EXPECTED: Document at <output-path> with: YAML frontmatter, all sections, cross-references
CONSTRAINTS: Follow document-standards.md" --tool gemini --mode write --rule development-implement-feature --cd <session>`,
run_in_background: false
})
```
## Phase 4: Validation + Artifact Manifest
### 4a: Self-Validation (all doc types)
| Check | What to Verify |
|-------|---------------|
| has_frontmatter | Starts with YAML frontmatter |
| sections_complete | All template sections present |
| cross_references | session_id included |
| progressive_consistency | References to upstream docs are valid |
### 4b: Generate Artifact Manifest
Create `<session>/artifacts/<task-id>/artifact-manifest.json`:
```json
{
"artifact_id": "uuid-...",
"creator_role": "writer",
"artifact_type": "spec",
"version": "1.0.0",
"path": "./spec/<doc-type>/_index.md",
"dependencies": ["analyst-artifact-id"],
"validation_status": "passed | failed",
"validation_summary": "All sections complete, frontmatter valid",
"metadata": {
"doc_type": "product-brief | requirements | architecture | epics",
"sections_count": 8
}
}
```
### 4c: Validation Routing
| Doc Type | Validation Method |
|----------|------------------|
| product-brief | Self-validation only → report |
| requirements (PRD) | Self-validation + **DISCUSS-002** |
| architecture | Self-validation only → report |
| epics | Self-validation only → report |
**DISCUSS-002** (PRD only):
- Artifact: `<session>/spec/requirements/_index.md`
- Round: DISCUSS-002
- Perspectives: quality, product, coverage
Handle discuss verdict per consensus protocol.
**Report**: doc type, validation status, discuss verdict (PRD only), output path.
## Error Handling
| Scenario | Resolution |
|----------|------------|
| CLI failure | Retry once with alternative tool. Still fails → log, continue next |
| Discuss subagent 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 |

65
.claude/skills/team-lifecycle-v3/roles/specialists/README.md
View File

@@ -1,65 +0,0 @@
# Role Library - Team Lifecycle v3
Dynamic role specification library for team-lifecycle-v3. Role definitions are loaded at runtime to extend the built-in role detection table.
## Purpose
- Extend role inference beyond hardcoded defaults
- Support domain-specific specialist roles
- Enable dynamic role injection based on task keywords
- Maintain backward compatibility with v2 core roles
## Role Categories
### Core Pipeline Roles (v2 inherited)
- analyst, writer, planner, executor, tester, reviewer
- architect, fe-developer, fe-qa
### Specialist Roles (v3 new)
- **orchestrator**: Complex task decomposition and parallel coordination
- **security-expert**: Security analysis and vulnerability scanning
- **performance-optimizer**: Performance profiling and optimization
- **data-engineer**: Data pipeline and schema design
- **devops-engineer**: Infrastructure as code and CI/CD
- **ml-engineer**: Machine learning pipeline implementation
## Dynamic Role Injection
Specialist roles are injected at runtime when coordinator detects matching keywords in task descriptions:
| Keywords | Injected Role |
|----------|---------------|
| security, vulnerability, OWASP | security-expert |
| performance, optimization, bottleneck | performance-optimizer |
| data, pipeline, ETL, schema | data-engineer |
| devops, CI/CD, deployment, docker | devops-engineer |
| machine learning, ML, model, training | ml-engineer |
| orchestrate, complex, multi-module | orchestrator |
## Role Definition Format
Each role definition is a `.role.md` file with YAML frontmatter + description.
### Schema
```yaml
---
role: <role-name>
keywords: [<keyword1>, <keyword2>, ...]
responsibility_type: <Orchestration|Code generation|Validation|Read-only analysis>
task_prefix: <PREFIX>
default_inner_loop: <true|false>
category: <domain-category>
capabilities: [<capability1>, <capability2>, ...]
---
<Role description and responsibilities>
```
## Usage
Role library is loaded by coordinator during Phase 1 (Requirements Collection) to extend role detection capabilities. Custom roles override built-in roles with same `role` identifier.
## Extensibility
Users can add custom role definitions by creating new `.role.md` files in this directory following the schema above.

37
.claude/skills/team-lifecycle-v3/roles/specialists/data-engineer.role.md
View File

@@ -1,37 +0,0 @@
---
role: data-engineer
keywords: [data, pipeline, ETL, database, schema, migration, analytics]
responsibility_type: Code generation
task_prefix: DATA
default_inner_loop: false
category: data
capabilities:
- data_pipeline_design
- schema_design
- etl_implementation
---
# Data Engineer
Designs and implements data pipelines, schemas, and ETL processes.
## Responsibilities
- Design database schemas and data models
- Implement ETL pipelines for data processing
- Create data migration scripts
- Optimize data storage and retrieval
- Implement data validation and quality checks
## Typical Tasks
- Design and implement data warehouse schema
- Build ETL pipeline for analytics
- Create database migration scripts
- Implement data validation framework
## Integration Points
- Called by coordinator when data keywords detected
- Works with executor for backend integration
- Coordinates with planner for data architecture

37
.claude/skills/team-lifecycle-v3/roles/specialists/devops-engineer.role.md
View File

@@ -1,37 +0,0 @@
---
role: devops-engineer
keywords: [devops, CI/CD, deployment, infrastructure, docker, kubernetes, terraform]
responsibility_type: Code generation
task_prefix: DEVOPS
default_inner_loop: false
category: devops
capabilities:
- infrastructure_as_code
- ci_cd_pipeline
- deployment_automation
---
# DevOps Engineer
Implements infrastructure as code, CI/CD pipelines, and deployment automation.
## Responsibilities
- Design and implement CI/CD pipelines
- Create infrastructure as code (Terraform, CloudFormation)
- Implement deployment automation
- Configure monitoring and alerting
- Manage containerization and orchestration
## Typical Tasks
- Set up CI/CD pipeline for new project
- Implement infrastructure as code for cloud resources
- Create Docker containerization strategy
- Configure Kubernetes deployment
## Integration Points
- Called by coordinator when devops keywords detected
- Works with executor for deployment integration
- Coordinates with planner for infrastructure architecture

37
.claude/skills/team-lifecycle-v3/roles/specialists/ml-engineer.role.md
View File

@@ -1,37 +0,0 @@
---
role: ml-engineer
keywords: [machine learning, ML, model, training, inference, neural network, AI]
responsibility_type: Code generation
task_prefix: ML
default_inner_loop: false
category: machine-learning
capabilities:
- model_training
- feature_engineering
- model_deployment
---
# ML Engineer
Implements machine learning pipelines, model training, and inference systems.
## Responsibilities
- Design and implement ML training pipelines
- Perform feature engineering and data preprocessing
- Train and evaluate ML models
- Implement model serving and inference
- Monitor model performance and drift
## Typical Tasks
- Build ML training pipeline
- Implement feature engineering pipeline
- Deploy model serving infrastructure
- Create model monitoring system
## Integration Points
- Called by coordinator when ML keywords detected
- Works with data-engineer for data pipeline integration
- Coordinates with planner for ML architecture

39
.claude/skills/team-lifecycle-v3/roles/specialists/orchestrator.role.md
View File

@@ -1,39 +0,0 @@
---
role: orchestrator
keywords: [orchestrate, coordinate, complex, multi-module, decompose, parallel, dependency]
responsibility_type: Orchestration
task_prefix: ORCH
default_inner_loop: false
category: orchestration
weight: 1.5
capabilities:
- task_decomposition
- parallel_coordination
- dependency_management
---
# Orchestrator
Decomposes complex multi-module tasks into coordinated sub-tasks with dependency management and parallel execution support.
## Responsibilities
- Analyze complex requirements and decompose into manageable sub-tasks
- Coordinate parallel execution of multiple implementation tracks
- Manage dependencies between sub-tasks
- Integrate results from parallel workers
- Validate integration points and cross-module consistency
## Typical Tasks
- Break down large features into frontend + backend + data components
- Coordinate multi-team parallel development
- Manage complex refactoring across multiple modules
- Orchestrate migration strategies with phased rollout
## Integration Points
- Works with planner to receive high-level plans
- Spawns multiple executor/fe-developer workers in parallel
- Integrates with tester for cross-module validation
- Reports to coordinator with integration status

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