Claude-Code-Workflow/.claude/skills/team-roadmap-dev/SKILL.md

---
name: team-roadmap-dev
description: Unified team skill for roadmap-driven development workflow. Coordinator discusses roadmap with user, then dispatches phased execution pipeline (plan -> execute -> verify). All roles invoke this skill with --role arg. Triggers on "team roadmap-dev".
allowed-tools: TeamCreate(*), TeamDelete(*), SendMessage(*), TaskCreate(*), TaskUpdate(*), TaskList(*), TaskGet(*), Task(*), AskUserQuestion(*), Read(*), Write(*), Edit(*), Bash(*), Glob(*), Grep(*)
---

# Team Roadmap Dev

Unified team skill: roadmap-driven development with phased execution pipeline. Coordinator discusses roadmap with the user and manages phase transitions. All team members invoke with `--role=xxx` to route to role-specific execution.

## Architecture Overview

```
┌───────────────────────────────────────────────┐
│  Skill(skill="team-roadmap-dev")              │
│  args="<task-description>" or args="--role=xxx"│
└───────────────────┬───────────────────────────┘
                    │ Role Router
         ┌──── --role present? ────┐
         │ NO                      │ YES
         ↓                         ↓
  Orchestration Mode         Role Dispatch
  (auto → coordinator)      (route to role.md)
         │
    ┌────┴────┬───────────┬───────────┐
    ↓         ↓           ↓           ↓
┌──────────┐┌─────────┐┌──────────┐┌──────────┐
│coordinator││ planner ││ executor ││ verifier │
│ (human   ││ PLAN-*  ││ EXEC-*   ││ VERIFY-* │
│  交互)   ││         ││          ││          │
└──────────┘└─────────┘└──────────┘└──────────┘
```

## Command Architecture

```
roles/
├── coordinator/
│   ├── role.md                # Orchestrator: roadmap discussion + phase management
│   └── commands/
│       ├── roadmap-discuss.md # Discuss roadmap with user, generate phase plan
│       ├── dispatch.md        # Create task chain per phase
│       ├── monitor.md         # Stop-Wait phase execution loop
│       ├── pause.md           # Save state and exit cleanly
│       └── resume.md          # Resume from paused session
├── planner/
│   ├── role.md                # Research + task JSON generation per phase
│   └── commands/
│       ├── research.md        # Context gathering + codebase exploration
│       └── create-plans.md    # action-planning-agent delegation → IMPL-*.json
├── executor/
│   ├── role.md                # Task execution with wave parallelism
│   └── commands/
│       └── implement.md       # Code implementation via code-developer
└── verifier/
    ├── role.md                # Goal-backward verification
    └── commands/
        └── verify.md          # Convergence criteria checking + gap detection
```

## Role Router

### Input Parsing

Parse `$ARGUMENTS` to extract `--role`. If absent → Orchestration Mode (auto route to coordinator). If `--resume` present → coordinator handles resume via commands/resume.md.

### Role Registry

| Role | File | Task Prefix | Type | Compact |
|------|------|-------------|------|---------|
| coordinator | [roles/coordinator/role.md](roles/coordinator/role.md) | (none) | orchestrator | **⚠️ 压缩后必须重读** |
| planner | [roles/planner/role.md](roles/planner/role.md) | PLAN-* | pipeline | 压缩后必须重读 |
| executor | [roles/executor/role.md](roles/executor/role.md) | EXEC-* | pipeline | 压缩后必须重读 |
| verifier | [roles/verifier/role.md](roles/verifier/role.md) | VERIFY-* | pipeline | 压缩后必须重读 |

> **⚠️ 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 task description.

**Invocation**: `Skill(skill="team-roadmap-dev", args="<task-description>")`

**Lifecycle**:
```
User provides task description
  → coordinator: Roadmap discussion → TeamCreate → Create phase task chain
  → coordinator Phase 4: spawn first batch workers (background) → STOP
  → Worker executes → SendMessage callback → coordinator advances next step
  → Loop until phase pipeline complete → transition to next phase or complete
```

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

### Artifact System

**Fixed Artifacts** (session-level, persist throughout session):

| Artifact | Path | Created By | Purpose |
|----------|------|------------|---------|
| roadmap.md | `<session>/roadmap.md` | coordinator (roadmap-discuss) | Phase plan with requirements and success criteria |
| state.md | `<session>/state.md` | coordinator | Living memory (<100 lines), updated every significant action |
| config.json | `<session>/config.json` | coordinator | Session settings: mode, depth, gates |

**Dynamic Artifacts** (per-phase, form execution history):

| Artifact | Path | Created By | Purpose |
|----------|------|------------|---------|
| context.md | `<session>/phase-N/context.md` | planner (research) | Phase context and requirements |
| IMPL_PLAN.md | `<session>/phase-N/IMPL_PLAN.md` | planner (create-plans) | Implementation overview with task dependency graph |
| IMPL-*.json | `<session>/phase-N/.task/IMPL-*.json` | planner (create-plans) | Task JSON files (unified flat schema with convergence criteria) |
| TODO_LIST.md | `<session>/phase-N/TODO_LIST.md` | planner (create-plans) | Checklist tracking for all tasks |
| summary-{ID}.md | `<session>/phase-N/summary-{IMPL-ID}.md` | executor (implement) | Execution record with requires/provides/convergence-met |
| verification.md | `<session>/phase-N/verification.md` | verifier (verify) | Convergence criteria check results + gap list |

### Init Prerequisite

Coordinator **must** ensure `.workflow/project-tech.json` exists before starting. If not found, invoke `/workflow:init`.

### Team Configuration

| Setting | Value |
|---------|-------|
| Team name | roadmap-dev |
| Session directory | `.workflow/.team/RD-<slug>-<date>/` |
| Message directory | `.workflow/.team-msg/roadmap-dev/` |

### 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", team="roadmap-dev", from=<role>, to="coordinator", type=<message-type>, summary="[<role>] <summary>", ref=<artifact-path>
   - **CLI fallback**: When MCP unavailable → `ccw team log --team roadmap-dev --from <role> --to coordinator --type <type> --summary "[<role>] ..." --json`
2. **SendMessage**: Send result to coordinator (content and summary both prefixed with `[<role>]`)
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

#### Output Tagging

All outputs must carry `[role_name]` prefix.

#### Coordinator Isolation

| Allowed | Forbidden |
|---------|-----------|
| Discuss roadmap with user (AskUserQuestion) | Direct code writing/modification |
| Create task chain (TaskCreate) | Calling implementation subagents |
| Dispatch tasks to workers | Direct analysis/testing/verification |
| Monitor progress (message bus) | Bypassing workers |
| Report results to user | Modifying source code |

#### Worker Isolation

| Allowed | Forbidden |
|---------|-----------|
| Process own-prefix tasks only | Process other roles' tasks |
| SendMessage to coordinator only | Direct worker-to-worker communication |
| Use Toolbox-declared tools | TaskCreate for other roles |
| Delegate to commands/*.md | Modify resources outside scope |

### Message Bus & Task Lifecycle

Each role's role.md contains self-contained Message Bus and Task Lifecycle. See `roles/<role>/role.md`.

---

## Pipeline

```
Phase N lifecycle:
  Coordinator (roadmap-discuss → dispatch phase N)
    → PLAN-N01: Planner (research → action-planning-agent → IMPL-*.json)
    → EXEC-N01: Executor (load IMPL-*.json → wave-based code-developer)
    → VERIFY-N01: Verifier (convergence criteria check)
    → Coordinator (transition: gap closure or next phase)

Cross-phase flow:
  Init → Roadmap Discussion → Phase 1 → Phase 2 → ... → Phase N → Complete
                                   ↑                          |
                                   └── gap closure loop ──────┘

Session lifecycle:
  Running → Pause (save coordinates) → Resume (re-enter monitor at coordinates)
```

### Cadence Control

**Beat model**: Event-driven, each beat = coordinator wake → process → spawn → STOP. Phase beat: PLAN → EXEC → VERIFY per phase.

```
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
                      └─ STOP (idle) ─────┘         │
                                                     │
  callback ←─────────────────────────────────────────┘
  (next beat)              SendMessage + TaskUpdate(completed)
═══════════════════════════════════════════════════════════
```

**Phase beat view**:

```
Single Phase (3 beats, strictly serial)
──────────────────────────────────────────────────────────
Beat  1         2              3
      │         │              │
      PLAN → EXEC ──→ VERIFY
      ▲                        ▲
   phase                    phase
    start                    done

PLAN=planner  EXEC=executor  VERIFY=verifier

Multi-Phase (N x 3 beats, with gap closure loop)
──────────────────────────────────────────────────────────
Phase 1:  PLAN-101 → EXEC-101 → VERIFY-101
                                    │
                              ⏸ CHECKPOINT ── gap closure or next phase
                                    │
Phase 2:  PLAN-201 → EXEC-201 → VERIFY-201
                                    │
                              ⏸ CHECKPOINT
                                    │
Phase N:  PLAN-N01 → EXEC-N01 → VERIFY-N01 → Complete
```

**Checkpoints**:

| Trigger | Location | Behavior |
|---------|----------|----------|
| Phase transition | VERIFY-N01 complete | Evaluate gaps: if gaps found → gap closure loop; if clean → next phase |
| Gap closure limit | 3 iterations | Stop iteration, report current state to user |
| 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 |
| Phase verification fails | Gaps detected in VERIFY | Coordinator triggers gap closure loop (max 3 iterations) |

### Task Metadata Registry

| Task ID | Role | Phase | Dependencies | Description |
|---------|------|-------|-------------|-------------|
| PLAN-N01 | planner | phase N | (none or previous VERIFY) | Research + context gathering + task JSON generation |
| EXEC-N01 | executor | phase N | PLAN-N01 | Wave-based code implementation following plans |
| VERIFY-N01 | verifier | phase N | EXEC-N01 | Convergence criteria verification + gap detection |

---

## Coordinator Spawn Template

When coordinator spawns workers, use background mode (Spawn-and-Stop):

```
Task({
  subagent_type: "general-purpose",
  description: "Spawn <role> worker",
  team_name: "roadmap-dev",
  name: "<role>",
  run_in_background: true,
  prompt: `You are team "roadmap-dev" <ROLE>.

## Primary Directive
All your work must be executed through Skill to load role definition:
Skill(skill="team-roadmap-dev", args="--role=<role>")

Current requirement: <task-description>
Session: <session-folder>

## Role Guidelines
- Only process <PREFIX>-* tasks, do not execute other role work
- All output prefixed with [<role>] identifier
- Only communicate with coordinator
- Do not use TaskCreate for other roles
- Call mcp__ccw-tools__team_msg before every SendMessage

## Workflow
1. Call Skill -> load role definition and execution logic
2. Follow role.md 5-Phase flow
3. team_msg + SendMessage results to coordinator
4. TaskUpdate completed -> check next task`
})
```

## Session Directory

```
.workflow/.team/RD-<slug>-<date>/
├── roadmap.md                 # Phase plan with requirements
├── state.md                   # Living memory (<100 lines)
├── config.json                # Session settings
├── wisdom/                    # Cross-task knowledge
│   ├── learnings.md
│   ├── decisions.md
│   ├── conventions.md
│   └── issues.md
├── phase-1/                   # Per-phase artifacts
│   ├── context.md
│   ├── IMPL_PLAN.md
│   ├── TODO_LIST.md
│   ├── .task/IMPL-*.json
│   ├── summary-*.md
│   └── verification.md
├── phase-2/
│   └── ...
└── shared-memory.json         # Cross-role state
```

## Session Resume

Coordinator supports `--resume` / `--continue` for interrupted sessions:

1. Scan `.workflow/.team/RD-*/` 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

## 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>/role.md) |
| project-tech.json missing | Coordinator invokes /workflow:init |
| Phase verification fails with gaps | Coordinator triggers gap closure loop |
| Max gap closure iterations (3) | Report to user, ask for guidance |