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

⚠️ 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):

Shared Infrastructure

Artifact System

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

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

Init Prerequisite

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

Team Configuration

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=, to=”coordinator”, type=, summary=”[] “, ref=
   • 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

Worker Isolation

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:

Stall Detection (coordinator handleCheck executes):

Task Metadata Registry

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