Team Roadmap Dev

Team Roadmap Dev

Roadmap-driven development with phased execution pipeline. Coordinator discusses roadmap with the user and manages phase transitions. Workers are spawned as team-worker agents.

Architecture

Skill(skill="team-roadmap-dev", args="<task-description>")
                    |
         SKILL.md (this file) = Router
                    |
     +--------------+--------------+
     |                             |
  no --role flag              --role <name>
     |                             |
  Coordinator                  Worker
  roles/coordinator/role.md    roles/<name>/role.md
     |
     +-- roadmap-discuss -> dispatch -> spawn workers -> STOP
                                    |
                    +-------+-------+-------+
                    v       v       v
                 [planner] [executor] [verifier]
                 (team-worker agents)

Pipeline (per phase):
  PLAN-N01 -> EXEC-N01 -> VERIFY-N01 (gap closure loop if needed)

Multi-phase:
  Phase 1 -> Phase 2 -> ... -> Phase N -> Complete

Role Registry

Role Router

Parse $ARGUMENTS:

• Has --role <name> → Read roles/<name>/role.md, execute Phase 2-4
• No --role → @roles/coordinator/role.md, execute entry router

Shared Constants

• Session prefix: RD
• Session path: .workflow/.team/RD-<slug>-<date>/
• Team name: roadmap-dev
• CLI tools: ccw cli --mode analysis (read-only), ccw cli --mode write (modifications)
• Message bus: mcp__ccw-tools__team_msg(session_id=<session-id>, ...)

Worker Spawn Template

Coordinator spawns workers using this template:

Agent({
  subagent_type: "team-worker",
  description: "Spawn <role> worker",
  team_name: "roadmap-dev",
  name: "<role>",
  run_in_background: true,
  prompt: `## Role Assignment
role: <role>
role_spec: <skill_root>/roles/<role>/role.md
session: <session-folder>
session_id: <session-id>
team_name: roadmap-dev
requirement: <task-description>
inner_loop: true

## Progress Milestones
session_id: <session-id>
Report progress via team_msg at natural phase boundaries (context loaded -> core work done -> verification).
Report blockers immediately via team_msg type="blocker".
Report completion via team_msg type="task_complete" after final SendMessage.

Read role_spec file (@<skill_root>/roles/<role>/role.md) to load Phase 2-4 domain instructions.
Execute built-in Phase 1 (task discovery) -> role Phase 2-4 -> built-in Phase 5 (report).`
})

All worker roles (planner, executor, verifier): Set inner_loop: true.

User Commands

Session Directory

.workflow/.team/RD-<slug>-<date>/
+-- roadmap.md                 # Phase plan with requirements and success criteria
+-- state.md                   # Living memory (<100 lines)
+-- config.json                # Session settings (mode, depth, gates)
+-- wisdom/                    # Cross-task knowledge accumulation
|   +-- 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-N/
|   +-- ...
+-- .msg/
    +-- messages.jsonl          # Team message bus log
    +-- meta.json               # Session metadata + shared state

Completion Action

When the pipeline completes:

AskUserQuestion({
  questions: [{
    question: "Roadmap Dev 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" }
    ]
  }]
})

Specs Reference

• specs/pipelines.md — Pipeline definitions and task registry

Error Handling

Analyze Task

Parse user task description for roadmap-dev domain signals. Detect phase count, depth preference, gate configuration, and pipeline mode.

CONSTRAINT: Text-level analysis only. NO source code reading, NO codebase exploration.

Signal Detection

Phase Count

Depth Setting

Gate Configuration

Pipeline Mode

Output

Write coordinator state to memory (not a file). Structure:

{
  "pipeline_mode": "auto | interactive",
  "phase_count": 1,
  "depth": "quick | standard | comprehensive",
  "gates": {
    "plan_check": false,
    "phase_check": false
  },
  "task_description": "<original task text>",
  "notes": ["<any detected constraints or special requirements>"]
}

This state is passed to commands/dispatch.md and written to config.json in the session directory.

Command: dispatch

Create task chain for a specific phase. Each phase gets a PLAN -> EXEC -> VERIFY pipeline with dependency ordering.

Purpose

Read the roadmap and create a linked task chain (PLAN -> EXEC -> VERIFY) for a given phase number. Tasks are assigned to the appropriate worker roles and linked via blockedBy dependencies.

Parameters

Execution Steps

Step 1: Read Roadmap and Extract Phase Requirements

const roadmap = Read(`${sessionFolder}/roadmap.md`)
const config = JSON.parse(Read(`${sessionFolder}/config.json`))

// Parse phase section from roadmap
// Extract: goal, requirements (REQ-IDs), success criteria
const phaseGoal = extractPhaseGoal(roadmap, phaseNumber)
const phaseRequirements = extractPhaseRequirements(roadmap, phaseNumber)
const phaseSuccessCriteria = extractPhaseSuccessCriteria(roadmap, phaseNumber)

Step 2: Create Phase Directory

Bash(`mkdir -p "${sessionFolder}/phase-${phaseNumber}"`)

Step 3: Create PLAN Task (Assigned to Planner)

const planTaskId = TaskCreate({
  subject: `PLAN-${phaseNumber}01: Plan phase ${phaseNumber} - ${phaseGoal}`,
  description: `[coordinator] Plan creation for phase ${phaseNumber}.

## Session
- Folder: ${sessionFolder}
- Phase: ${phaseNumber}
- Depth: ${config.depth}

## Phase Goal
${phaseGoal}

## Requirements
${phaseRequirements.map(r => `- ${r}`).join('\n')}

## Success Criteria
${phaseSuccessCriteria.map(c => `- ${c}`).join('\n')}

## Deliverables
- ${sessionFolder}/phase-${phaseNumber}/context.md (research context)
- ${sessionFolder}/phase-${phaseNumber}/plan-01.md (execution plan with waves and must_haves)

## Instructions
1. Invoke Skill(skill="team-roadmap-dev", args="--role=planner")
2. Follow planner role.md research + create-plans commands
3. Use roadmap requirements as input for plan generation
4. TaskUpdate this task to completed when plan is written`,
  activeForm: `Planning phase ${phaseNumber}`
})

Step 4: Create EXEC Task (Assigned to Executor, Blocked by PLAN)

const execTaskId = TaskCreate({
  subject: `EXEC-${phaseNumber}01: Execute phase ${phaseNumber} - ${phaseGoal}`,
  description: `[coordinator] Execute plans for phase ${phaseNumber}.

## Session
- Folder: ${sessionFolder}
- Phase: ${phaseNumber}

## Phase Goal
${phaseGoal}

## Plan Reference
- ${sessionFolder}/phase-${phaseNumber}/plan-01.md (and any additional plans)

## Instructions
1. Invoke Skill(skill="team-roadmap-dev", args="--role=executor")
2. Follow executor role.md implement command
3. Execute all plans in wave order
4. Write summary to ${sessionFolder}/phase-${phaseNumber}/summary-01.md
5. TaskUpdate this task to completed when all plans executed`,
  activeForm: `Executing phase ${phaseNumber}`
})

// Set dependency: EXEC blocked by PLAN
TaskUpdate({ taskId: execTaskId, addBlockedBy: [planTaskId] })

Step 5: Create VERIFY Task (Assigned to Verifier, Blocked by EXEC)

const verifyTaskId = TaskCreate({
  subject: `VERIFY-${phaseNumber}01: Verify phase ${phaseNumber} - ${phaseGoal}`,
  description: `[coordinator] Verify phase ${phaseNumber} against success criteria.

## Session
- Folder: ${sessionFolder}
- Phase: ${phaseNumber}

## Phase Goal
${phaseGoal}

## Success Criteria (from roadmap)
${phaseSuccessCriteria.map(c => `- ${c}`).join('\n')}

## References
- Roadmap: ${sessionFolder}/roadmap.md
- Plans: ${sessionFolder}/phase-${phaseNumber}/plan-*.md
- Summaries: ${sessionFolder}/phase-${phaseNumber}/summary-*.md

## Instructions
1. Invoke Skill(skill="team-roadmap-dev", args="--role=verifier")
2. Follow verifier role.md verify command
3. Check each success criterion against actual implementation
4. Write verification to ${sessionFolder}/phase-${phaseNumber}/verification.md
5. If gaps found: list them with gap IDs in verification.md
6. TaskUpdate this task to completed with result (passed/gaps_found)`,
  activeForm: `Verifying phase ${phaseNumber}`
})

// Set dependency: VERIFY blocked by EXEC
TaskUpdate({ taskId: verifyTaskId, addBlockedBy: [execTaskId] })

Step 6: Update state.md

Edit(`${sessionFolder}/state.md`, {
  old_string: `- Phase: ${phaseNumber}\n- Status: ready_to_dispatch`,
  new_string: `- Phase: ${phaseNumber}\n- Status: in_progress\n- Tasks: PLAN-${phaseNumber}01 → EXEC-${phaseNumber}01 → VERIFY-${phaseNumber}01`
})

Step 7: Log Dispatch Message

mcp__ccw-tools__team_msg({
  operation: "log", session_id: sessionId,
  from: "coordinator", to: "all",
  type: "phase_started",
  data: { ref: `${sessionFolder}/roadmap.md` }
})

Task Description Format

All dispatched tasks follow this structure:

[coordinator] {action} for phase {N}.

## Session
- Folder: {sessionFolder}
- Phase: {N}
- Depth: {config.depth} (PLAN only)

## Phase Goal
{goal from roadmap}

## Requirements / Success Criteria
{from roadmap}

## Deliverables
{expected output files}

## Instructions
{step-by-step for the worker role}

Task Naming Convention

Dependency Chain

PLAN-{N}01  ←──  EXEC-{N}01  ←──  VERIFY-{N}01
(planner)        (executor)        (verifier)

Each task is blocked by its predecessor. Workers pick up tasks only when their blockedBy list is empty.

Output

Returns the three task IDs as a structured result:

{
  planTaskId: planTaskId,
  execTaskId: execTaskId,
  verifyTaskId: verifyTaskId
}

Command: Monitor

Handle all coordinator monitoring events for the roadmap-dev pipeline using the async Spawn-and-Stop pattern. Multi-phase execution with gap closure expressed as event-driven state machine transitions. One operation per invocation, then STOP and wait for the next callback.

Constants

Role-Worker Map

Pipeline Structure

Per-phase task chain: PLAN-{phase}01 -> EXEC-{phase}01 -> VERIFY-{phase}01

Gap closure creates: PLAN-{phase}0N -> EXEC-{phase}0N -> VERIFY-{phase}0N (N = iteration + 1)

Multi-phase: Phases execute sequentially. Each phase completes its full PLAN/EXEC/VERIFY cycle (including gap closure) before the next phase is dispatched.

State Machine Coordinates

The coordinator tracks its position using these state variables in meta.json:

session.coordinates = {
  current_phase: <number>,     // Active phase (1-based)
  total_phases: <number>,      // Total phases from roadmap
  gap_iteration: <number>,     // Current gap closure iteration within phase (0 = initial)
  step: <string>,              // Current step: "plan" | "exec" | "verify" | "gap_closure" | "transition"
  status: <string>             // "running" | "paused" | "complete"
}

Phase 2: Context Loading

Load session state:
  1. Read <session-folder>/.msg/meta.json -> session
  2. Read <session-folder>/config.json -> config
  3. TaskList() -> allTasks
  4. Extract coordinates from session (current_phase, gap_iteration, step)
  5. Extract active_workers[] from session (default: [])
  6. Parse $ARGUMENTS to determine trigger event

Phase 3: Event Handlers

Wake-up Source Detection

Parse $ARGUMENTS to determine handler:

---

Handler: handleCallback

Worker completed a task. Determine which step completed via prefix, apply pipeline logic, advance.

Receive callback from [<role>]
  +- Find matching active worker by role tag
  +- Is this a progress update (not final)? (Inner Loop intermediate)
  |   +- YES -> Update session state -> STOP
  +- Task status = completed?
  |   +- YES -> remove from active_workers -> update session
  |   |   +- Determine completed step from task prefix:
  |   |   |
  |   |   +- PLAN-* completed:
  |   |   |   +- Update coordinates.step = "plan_done"
  |   |   |   +- Is this initial plan (gap_iteration === 0)?
  |   |   |   |   +- YES + config.gates.plan_check?
  |   |   |   |   |   +- AskUserQuestion:
  |   |   |   |   |       question: "Phase <N> plan ready. Proceed with execution?"
  |   |   |   |   |       header: "Plan Review"
  |   |   |   |   |       options:
  |   |   |   |   |         - "Proceed": -> handleSpawnNext (spawns EXEC)
  |   |   |   |   |         - "Revise": Create new PLAN task with incremented suffix
  |   |   |   |   |           blockedBy: [] (immediate), -> handleSpawnNext
  |   |   |   |   |         - "Skip phase": Delete all phase tasks
  |   |   |   |   |           -> advanceToNextPhase
  |   |   |   |   +- NO (gap closure plan) -> handleSpawnNext (spawns EXEC)
  |   |   |   +- -> handleSpawnNext
  |   |   |
  |   |   +- EXEC-* completed:
  |   |   |   +- Update coordinates.step = "exec_done"
  |   |   |   +- -> handleSpawnNext (spawns VERIFY)
  |   |   |
  |   |   +- VERIFY-* completed:
  |   |       +- Update coordinates.step = "verify_done"
  |   |       +- Read verification result from:
  |   |       |   <session-folder>/phase-<N>/verification.md
  |   |       +- Parse gaps from verification
  |   |       +- Gaps found?
  |   |           +- NO -> Phase passed
  |   |           |   +- -> advanceToNextPhase
  |   |           +- YES + gap_iteration < MAX_GAP_ITERATIONS?
  |   |           |   +- -> triggerGapClosure
  |   |           +- YES + gap_iteration >= MAX_GAP_ITERATIONS?
  |   |               +- AskUserQuestion:
  |   |                   question: "Phase <N> still has <count> gaps after <max> attempts."
  |   |                   header: "Gap Closure Limit"
  |   |                   options:
  |   |                     - "Continue anyway": Accept, -> advanceToNextPhase
  |   |                     - "Retry once more": Increment max, -> triggerGapClosure
  |   |                     - "Stop": -> pauseSession
  |   |
  |   +- NO -> progress message -> STOP
  +- No matching worker found
      +- Scan all active workers for completed tasks
      +- Found completed -> process each (same logic above) -> handleSpawnNext
      +- None completed -> STOP

Sub-procedure: advanceToNextPhase

advanceToNextPhase:
  +- Update state.md: mark current phase completed
  +- current_phase < total_phases?
  |   +- YES:
  |   |   +- config.mode === "interactive"?
  |   |   |   +- AskUserQuestion:
  |   |   |       question: "Phase <N> complete. Proceed to phase <N+1>?"
  |   |   |       header: "Phase Transition"
  |   |   |       options:
  |   |   |         - "Proceed": Dispatch next phase tasks, -> handleSpawnNext
  |   |   |         - "Review results": Output phase summary, re-ask
  |   |   |         - "Stop": -> pauseSession
  |   |   +- Auto mode: Dispatch next phase tasks directly
  |   |   +- Update coordinates:
  |   |       current_phase++, gap_iteration=0, step="plan"
  |   |   +- Dispatch new phase tasks (PLAN/EXEC/VERIFY with blockedBy)
  |   |   +- -> handleSpawnNext
  |   +- NO -> All phases done -> handleComplete

Sub-procedure: triggerGapClosure

triggerGapClosure:
  +- Increment coordinates.gap_iteration
  +- suffix = "0" + (gap_iteration + 1)
  +- phase = coordinates.current_phase
  +- Read gaps from verification.md
  +- Log: team_msg gap_closure
  +- Create gap closure task chain:
  |
  |   TaskCreate: PLAN-{phase}{suffix}
  |     subject: "PLAN-{phase}{suffix}: Gap closure for phase {phase} (iteration {gap_iteration})"
  |     description: includes gap list, references to previous verification
  |     blockedBy: [] (immediate start)
  |
  |   TaskCreate: EXEC-{phase}{suffix}
  |     subject: "EXEC-{phase}{suffix}: Execute gap fixes for phase {phase}"
  |     blockedBy: [PLAN-{phase}{suffix}]
  |
  |   TaskCreate: VERIFY-{phase}{suffix}
  |     subject: "VERIFY-{phase}{suffix}: Verify gap closure for phase {phase}"
  |     blockedBy: [EXEC-{phase}{suffix}]
  |
  +- Set owners: planner, executor, verifier
  +- Update coordinates.step = "gap_closure"
  +- -> handleSpawnNext (picks up the new PLAN task)

Sub-procedure: pauseSession

pauseSession:
  +- Save coordinates to meta.json (phase, step, gap_iteration)
  +- Update coordinates.status = "paused"
  +- Update state.md with pause marker
  +- team_msg log -> session_paused
  +- Output: "Session paused at phase <N>, step <step>. Resume with 'resume'."
  +- STOP

---

Handler: handleSpawnNext

Find all ready tasks, spawn team-worker agent in background, update session, STOP.

Collect task states from TaskList()
  +- completedSubjects: status = completed
  +- inProgressSubjects: status = in_progress
  +- readySubjects: status = pending
      AND (no blockedBy OR all blockedBy in completedSubjects)

Ready tasks found?
  +- NONE + work in progress -> report waiting -> STOP
  +- NONE + nothing in progress:
  |   +- More phases to dispatch? -> advanceToNextPhase
  |   +- No more phases -> handleComplete
  +- HAS ready tasks -> take first ready task:
      +- Is task owner an Inner Loop role AND that role already has active_worker?
      |   +- YES -> SKIP spawn (existing worker picks it up via inner loop)
      |   +- NO -> normal spawn below
      +- Determine role from prefix:
      |   PLAN-*   -> planner
      |   EXEC-*   -> executor
      |   VERIFY-* -> verifier
      +- TaskUpdate -> in_progress
      +- team_msg log -> task_unblocked (team_session_id=<session-id>)
      +- Spawn team-worker (see spawn call below)
      +- Add to session.active_workers
      +- Update session file
      +- Output: "[coordinator] Spawned <role> for <subject>"
      +- STOP

Spawn worker tool call (one per ready task):

Agent({
  subagent_type: "team-worker",
  description: "Spawn <role> worker for <subject>",
  team_name: "roadmap-dev",
  name: "<role>",
  run_in_background: true,
  prompt: `## Role Assignment
role: <role>
role_spec: ~  or <project>/.claude/skills/team-roadmap-dev/roles/<role>/role.md
session: <session-folder>
session_id: <session-id>
team_name: roadmap-dev
requirement: <task-description>
inner_loop: true

## Current Task
- Task ID: <task-id>
- Task: <subject>
- Phase: <current_phase>
- Gap Iteration: <gap_iteration>

## Progress Milestones
session_id: <session-id>
Report progress via team_msg at natural phase boundaries (context loaded -> core work done -> verification).
Report blockers immediately via team_msg type="blocker".
Report completion via team_msg type="task_complete" after final SendMessage.

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.`
})

---

Handler: handleCheck

Read-only status report. No pipeline advancement.

Worker Progress (from message bus):

Before generating status output, read worker milestones:

const progressMsgs = mcp__ccw-tools__team_msg({
  operation: "list", session_id: sessionId, type: "progress", last: 50
})
const blockerMsgs = mcp__ccw-tools__team_msg({
  operation: "list", session_id: sessionId, type: "blocker", last: 10
})

// Aggregate latest milestone per task
const taskProgress = {}
for (const msg of (progressMsgs.result?.messages || [])) {
  const tid = msg.data?.task_id
  if (tid && (!taskProgress[tid] || msg.ts > taskProgress[tid].ts)) {
    taskProgress[tid] = { phase: msg.data.phase, pct: msg.data.progress_pct, ts: msg.ts }
  }
}

Include in status output:

• Per-worker latest milestone (phase + progress_pct) next to task status
• Active blockers section (if any blockerMsgs found)

Output format:

[coordinator] Roadmap Pipeline Status
[coordinator] Phase: <current>/<total> | Gap Iteration: <N>/<max>
[coordinator] Progress: <completed>/<total tasks> (<percent>%)

[coordinator] Current Phase <N> Graph:
  PLAN-{N}01:   <status-icon> <summary>
  EXEC-{N}01:   <status-icon> <summary>
  VERIFY-{N}01: <status-icon> <summary>
  [PLAN-{N}02:  <status-icon> (gap closure #1)]
  [EXEC-{N}02:  <status-icon>]
  [VERIFY-{N}02:<status-icon>]

  done=completed  >>>=running  o=pending  x=deleted  .=not created

[coordinator] Phase Summary:
  Phase 1: completed
  Phase 2: in_progress (step: exec)
  Phase 3: not started

[coordinator] Active Workers:
  > <subject> (<role>) - running [inner-loop: N/M tasks done]

[coordinator] Ready to spawn: <subjects>
[coordinator] Coordinates: phase=<N> step=<step> gap=<iteration>
[coordinator] Commands: 'resume' to advance | 'check' to refresh

Then STOP.

---

Handler: handleResume

Check active worker completion, process results, advance pipeline. Also handles resume from paused state.

Check coordinates.status:
  +- "paused" -> Restore coordinates, resume from saved position
  |   Reset coordinates.status = "running"
  |   -> handleSpawnNext (picks up where it left off)
  +- "running" -> Normal resume:
      Load active_workers from session
        +- No active workers -> handleSpawnNext
        +- Has active workers -> check each:
            +- status = completed -> mark done, remove from active_workers, log
            +- status = in_progress -> still running, log
            +- other status -> worker failure -> reset to pending
            After processing:
              +- Some completed -> handleSpawnNext
              +- All still running -> report status -> STOP
              +- All failed -> handleSpawnNext (retry)

---

Handler: handleComplete

All phases done. Generate final project summary and finalize session.

All phases completed (no pending, no in_progress across all phases)
  +- Generate project-level summary:
  |   - Roadmap overview (phases completed)
  |   - Per-phase results:
  |     - Gap closure iterations used
  |     - Verification status
  |     - Key deliverables
  |   - Overall stats (tasks completed, phases, total gap iterations)
  |
  +- Update session:
  |   coordinates.status = "complete"
  |   session.completed_at = <timestamp>
  |   Write meta.json
  |
  +- Update state.md: mark all phases completed
  +- team_msg log -> project_complete
  +- Output summary to user
  +- STOP

---

Worker Failure Handling

When a worker has unexpected status (not completed, not in_progress):

1. Reset task -> pending via TaskUpdate 2. Remove from active_workers 3. Log via team_msg (type: error) 4. Report to user: task reset, will retry on next resume

Phase 4: State Persistence

After every handler action, before STOP:

Persist:
  1. Update coordinates in meta.json
  2. Reconcile active_workers with actual TaskList states
  3. Remove entries for completed/deleted tasks
  4. Write updated meta.json
  5. Update state.md if phase status changed
  6. Verify consistency
  7. STOP (wait for next callback)

State Machine Diagram

[dispatch] -> PLAN-{N}01 spawned
                |
          [planner callback]
                |
         plan_check gate? --YES--> AskUser --> "Revise" --> new PLAN task --> [spawn]
                |                              "Skip"   --> advanceToNextPhase
                | "Proceed" / no gate
                v
          EXEC-{N}01 spawned
                |
          [executor callback]
                |
                v
          VERIFY-{N}01 spawned
                |
          [verifier callback]
                |
          gaps found? --NO--> advanceToNextPhase
                |
                YES + iteration < MAX
                |
                v
          triggerGapClosure:
            PLAN-{N}02 -> EXEC-{N}02 -> VERIFY-{N}02
                |
          [repeat verify check]
                |
          gaps found? --NO--> advanceToNextPhase
                |
                YES + iteration >= MAX
                |
                v
          AskUser: "Continue anyway" / "Retry" / "Stop"

advanceToNextPhase:
  +- phase < total? --YES--> interactive gate? --> dispatch phase+1 --> [spawn PLAN]
  +- phase = total? --> handleComplete

Error Handling

Command: pause

Save session state and exit cleanly. Allows resumption later via resume command.

Purpose

Persist the current execution state (phase, step, pending tasks) to state.md so the session can be resumed from exactly where it stopped. This is the coordinator's mechanism for handling user "Stop" requests at phase boundaries or gap closure gates.

When to Use

• User selects "Stop" at any interactive gate in monitor.md
• User requests pause during roadmap discussion
• External interruption requires graceful shutdown

Parameters

Execution Steps

Step 1: Capture Current State

const state = Read(`${sessionFolder}/state.md`)
const timestamp = new Date().toISOString().slice(0, 19)

// Capture pending task states
const allTasks = TaskList()
const pendingTasks = allTasks.filter(t =>
  t.status === 'pending' || t.status === 'in_progress'
)

Step 2: Update state.md with Pause Marker

// Find the current phase status line and update it
Edit(`${sessionFolder}/state.md`, {
  old_string: `- Status: in_progress`,
  new_string: `- Status: paused
- Paused At: ${timestamp}
- Paused Phase: ${currentPhase}
- Paused Step: ${currentStep}
- Gap Iteration: ${gapIteration}
- Pending Tasks: ${pendingTasks.map(t => t.subject).join(', ')}`
})

Step 3: Log Pause Event

mcp__ccw-tools__team_msg({
  operation: "log", session_id: sessionId,
  from: "coordinator", to: "all",
  type: "phase_paused",
  data: { ref: `${sessionFolder}/state.md` }
})

Step 4: Report to User

// Output pause summary
const summary = `[coordinator] Session paused.
- Phase: ${currentPhase}
- Step: ${currentStep}
- Gap Iteration: ${gapIteration}
- Pending Tasks: ${pendingTasks.length}

To resume: Skill(skill="team-roadmap-dev", args="--resume ${sessionFolder}")
`

Output

Error Handling

Command: resume

Resume a paused roadmap-dev session from its saved state. Reads pause coordinates from state.md and re-enters the monitor loop at the exact phase and step where execution was paused.

Purpose

Restore execution context from a paused session and continue the monitor loop. This is the coordinator's mechanism for resuming long-running projects across sessions.

When to Use

• User invokes Skill(skill="team-roadmap-dev", args="--resume {sessionFolder}")
• Coordinator detects a paused session during init

Parameters

Execution Steps

Step 1: Validate Session State

const stateContent = Read(`${sessionFolder}/state.md`)

// Check for paused status
if (!stateContent.includes('Status: paused')) {
  // Session is not paused — check if it's in_progress or completed
  if (stateContent.includes('Status: completed')) {
    // Session already finished
    return { error: "Session already completed", sessionFolder }
  }
  // Not paused, not completed — treat as fresh continue
}

// Parse resume coordinates
const pausedPhase = parseInt(stateContent.match(/Paused Phase: (\d+)/)?.[1] || '1')
const pausedStep = stateContent.match(/Paused Step: (\w+)/)?.[1] || 'plan'
const gapIteration = parseInt(stateContent.match(/Gap Iteration: (\d+)/)?.[1] || '0')

Step 2: Load Session Context

const roadmap = Read(`${sessionFolder}/roadmap.md`)
const config = JSON.parse(Read(`${sessionFolder}/config.json`))

// Load project context
const projectTech = JSON.parse(Read('.workflow/project-tech.json'))

Step 3: Update State to In-Progress

const timestamp = new Date().toISOString().slice(0, 19)

Edit(`${sessionFolder}/state.md`, {
  old_string: `- Status: paused`,
  new_string: `- Status: in_progress
- Resumed At: ${timestamp}
- Resumed From Phase: ${pausedPhase}, Step: ${pausedStep}`
})

Step 4: Log Resume Event

mcp__ccw-tools__team_msg({
  operation: "log", session_id: sessionId,
  from: "coordinator", to: "all",
  type: "phase_started",
  data: { ref: `${sessionFolder}/state.md` }
})

Step 5: Re-enter Monitor Loop

// Delegate to monitor.md with resume context
// monitor.md receives:
//   - startPhase: pausedPhase (instead of 1)
//   - startStep: pausedStep (plan/exec/verify/gap_closure)
//   - gapIteration: gapIteration (for gap closure continuity)

Read("commands/monitor.md")
// Monitor will:
//   1. Skip phases before pausedPhase
//   2. Within pausedPhase, skip steps before pausedStep
//   3. Continue normal execution from that point

Step 6: Determine Resume Entry Point

// Map pausedStep to monitor entry point
switch (pausedStep) {
  case 'plan':
    // Re-dispatch planner for current phase
    // Check if PLAN task exists and is pending/incomplete
    break

  case 'exec':
    // Re-dispatch executor for current phase
    // Check if EXEC task exists and is pending/incomplete
    break

  case 'verify':
    // Re-dispatch verifier for current phase
    break

  case 'gap_closure':
    // Re-enter gap closure loop at gapIteration
    break

  case 'transition':
    // Phase was complete, proceed to next phase
    break
}

Output

Error Handling

Command: roadmap-discuss

Interactive roadmap discussion with the user. This is the KEY coordinator command -- no work begins until the roadmap is agreed upon.

Purpose

Discuss project roadmap with the user using project-tech.json + specs/*.md as context. Elicit phases, requirements, success criteria, and execution preferences. Produces roadmap.md and config.json as session artifacts.

When to Use

• Phase 2 of coordinator lifecycle (after init prerequisites, before dispatch)
• Called exactly once per session (re-entry updates existing roadmap)

Strategy

Direct interaction via AskUserQuestion. No delegation to workers or CLI tools. Coordinator handles this entirely.

Parameters

Execution Steps

Step 1: Load Project Context

// Already loaded by coordinator Phase 1, but verify availability
const projectTech = JSON.parse(Read('.workflow/project-tech.json'))
let projectGuidelines = null
try {
  projectGuidelines = JSON.parse(Read('.workflow/specs/*.md'))
} catch {}

Step 2: Present Project Overview to User

// Summarize what we know about the project
const overview = `[coordinator] Project context loaded.
- Project: ${projectTech.project_name}
- Tech Stack: ${projectTech.tech_stack?.join(', ')}
- Task: ${taskDescription}
${projectGuidelines ? `- Guidelines: ${projectGuidelines.conventions?.length || 0} conventions loaded` : '- Guidelines: not configured'}`

// Display overview (via direct output, not AskUserQuestion)

Step 3: Confirm Project Goal and Scope

// Skip if taskDescription is already detailed enough, or autoYes
if (!autoYes && !taskDescription) {
  AskUserQuestion({
    questions: [{
      question: "What is the project goal and scope for this session?",
      header: "Goal",
      multiSelect: false,
      options: [] // Free-form text input
    }]
  })
}
// Store response as `projectGoal`
const projectGoal = taskDescription || userResponse

Step 4: Ask Execution Mode

if (!autoYes) {
  AskUserQuestion({
    questions: [{
      question: "How should phase transitions be handled?",
      header: "Execution Mode",
      multiSelect: false,
      options: [
        { label: "interactive", description: "Ask for confirmation at each phase transition" },
        { label: "yolo", description: "Auto-execute all phases without stopping" },
        { label: "custom", description: "Choose which gates require confirmation" }
      ]
    }]
  })
} else {
  mode = "yolo"
}

// If "custom" selected, follow up with gate selection:
if (mode === "custom") {
  AskUserQuestion({
    questions: [{
      question: "Which gates should require confirmation?",
      header: "Custom Gates",
      multiSelect: true,
      options: [
        { label: "plan_check", description: "Review plan before execution" },
        { label: "verifier", description: "Review verification results before next phase" },
        { label: "gap_closure", description: "Confirm gap closure before re-execution" }
      ]
    }]
  })
}

Step 5: Ask Analysis Depth

if (!autoYes) {
  AskUserQuestion({
    questions: [{
      question: "How thorough should the analysis be?",
      header: "Analysis Depth",
      multiSelect: false,
      options: [
        { label: "quick", description: "Fast scan, minimal context gathering (small tasks)" },
        { label: "standard", description: "Balanced analysis with key context (default)" },
        { label: "comprehensive", description: "Deep analysis, full codebase exploration (large refactors)" }
      ]
    }]
  })
} else {
  depth = "standard"
}

Step 6: Analyze Codebase and Generate Phased Roadmap

// Use Gemini CLI (or CLI exploration tool) to analyze the codebase
// and generate a phased breakdown based on goal + project context
Bash({
  command: `ccw cli -p "PURPOSE: Analyze codebase and generate phased execution roadmap for: ${projectGoal}
TASK: \
  - Scan project structure and identify affected modules \
  - Break goal into sequential phases (max 5) \
  - Each phase: goal, requirements (REQ-IDs), success criteria (2-5 testable behaviors) \
  - Order phases by dependency (foundational first)
MODE: analysis
CONTEXT: @**/* | Memory: Tech stack: ${projectTech.tech_stack?.join(', ')}
EXPECTED: Phased roadmap in markdown with REQ-IDs and testable success criteria
CONSTRAINTS: Max 5 phases | Each phase independently verifiable | No implementation details" \
  --tool gemini --mode analysis --rule planning-breakdown-task-steps`,
  run_in_background: false,
  timeout: 300000
})

// Parse the CLI output into structured phases

Step 7: Present Roadmap Draft for Confirmation

// Display the generated roadmap to user
// Output the roadmap content directly, then ask for adjustments

AskUserQuestion({
  questions: [{
    question: "Review the roadmap above. Any adjustments needed?",
    header: "Roadmap Review",
    multiSelect: false,
    options: [
      { label: "Looks good, proceed", description: "Accept roadmap as-is" },
      { label: "Adjust phases", description: "I want to modify the phase breakdown" },
      { label: "Add requirements", description: "I want to add missing requirements" },
      { label: "Change scope", description: "Narrow or expand the scope" }
    ]
  }]
})

// If user requests adjustments, incorporate feedback and re-present
// Loop until user confirms "Looks good, proceed"

Step 8: Generate Session Artifacts

roadmap.md

Write(`${sessionFolder}/roadmap.md`, roadmapContent)

roadmap.md format:

# Roadmap: {projectGoal}

Generated: {date}
Session: {sessionFolder}
Depth: {depth}

## Phase 1: {phase title}

**Goal**: {one-line goal}

**Requirements**:
- REQ-101: {requirement description}
- REQ-102: {requirement description}

**Success Criteria**:
- [ ] {testable behavior 1}
- [ ] {testable behavior 2}
- [ ] {testable behavior 3}

**Plan Count**: TBD

---

## Phase 2: {phase title}

**Goal**: {one-line goal}

**Requirements**:
- REQ-201: {requirement description}

**Success Criteria**:
- [ ] {testable behavior 1}
- [ ] {testable behavior 2}

**Plan Count**: TBD

---

(... additional phases ...)

REQ-ID Convention: REQ-{phase}{seq} (e.g., REQ-101 = Phase 1, requirement 1)

config.json

Write(`${sessionFolder}/config.json`, JSON.stringify({
  mode: mode,           // "interactive" | "yolo" | "custom"
  depth: depth,         // "quick" | "standard" | "comprehensive"
  auto_advance: mode === "yolo",
  gates: {
    plan_check: mode === "interactive" || (mode === "custom" && customGates.includes("plan_check")),
    verifier: mode === "interactive" || (mode === "custom" && customGates.includes("verifier")),
    gap_closure: mode === "interactive" || (mode === "custom" && customGates.includes("gap_closure"))
  }
}, null, 2))

config.json format:

{
  "mode": "interactive",
  "depth": "standard",
  "auto_advance": false,
  "gates": {
    "plan_check": true,
    "verifier": true,
    "gap_closure": true
  }
}

Step 9: Update state.md

// Transition Phase 0 → Phase 1
Edit(`${sessionFolder}/state.md`, {
  old_string: "- Phase: 0 (Roadmap Discussion)\n- Status: initializing",
  new_string: `- Phase: 1\n- Status: ready_to_dispatch\n- Roadmap: confirmed (${phaseCount} phases)\n- Mode: ${mode}\n- Depth: ${depth}`
})

Output

Error Handling

Coordinator Role

Orchestrate the roadmap-driven development workflow: init prerequisites -> roadmap discussion with user -> phase dispatch -> monitoring -> transitions -> completion. Coordinator is the ONLY role that interacts with humans.

Identity

• Name: coordinator | Tag: [coordinator]
• Responsibility: Orchestration (parse requirements -> discuss roadmap -> create team -> dispatch tasks -> monitor progress -> report results)

Boundaries

MUST

• All outputs must carry [coordinator] prefix
• Handle ALL human interaction (AskUserQuestion) -- workers never interact with user
• Ensure init prerequisites before starting (project-tech.json)
• Discuss roadmap with user before dispatching work
• Manage state.md updates at every phase transition
• Route verifier gap results to planner for closure
• Parse user requirements and clarify ambiguous inputs via AskUserQuestion
• Create team and spawn worker team members in background
• Dispatch tasks with proper dependency chains
• Monitor progress via worker callbacks and route messages
• Maintain session state persistence

MUST NOT

• Execute any business tasks (code, analysis, testing, verification)
• Call CLI tools for code generation, exploration, or planning
• Modify source code or generate implementation artifacts
• Bypass worker roles to do work directly
• Skip roadmap discussion phase
• Modify task outputs (workers own their deliverables)
• Skip dependency validation when creating task chains

Core principle: coordinator is the orchestrator, not the executor. All actual work must be delegated to worker roles via TaskCreate.

---

Command Execution Protocol

When coordinator needs to execute a command (dispatch, monitor, pause, resume):

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

---

Entry Router

When coordinator is invoked, detect invocation type:

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/RD-*/.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", "--resume" keywords

3. Route to handler:

• For monitor handlers: Read commands/monitor.md, execute matched handler, STOP
• For --resume: Read @commands/resume.md, execute resume flow
• For Phase 0: Execute Session Resume Check
• For Phase 1: Execute Init Prerequisites below

---

Toolbox

Available Commands

Tool Capabilities

---

Message Types

Message Bus

Before every SendMessage, log via mcp__ccw-tools__team_msg:

mcp__ccw-tools__team_msg({
  operation: "log",
  session_id: <session-id>,
  from: "coordinator",
  to: <target-role>,
  type: <message-type>,
  data: { ref: <artifact-path> }
})

CLI fallback (when MCP unavailable):

Bash("ccw team log --session-id <session-id> --from coordinator --type <type> --json")

---

Execution (5-Phase)

Phase 1: Init Prerequisites + Requirement Parsing

Objective: Ensure prerequisites and parse user requirements.

Workflow:

1. Parse arguments for flags: --resume, --yes, task description 2. If --resume present -> load @commands/resume.md and execute resume flow 3. Ensure project-tech.json exists:

4. Load project context from project-tech.json 5. Create session directory: .workflow/.team/RD-<slug>-<date>/ 6. Initialize state.md with project reference, current position, task description

Success: Session directory created, state.md initialized.

Phase 2: Roadmap Discussion (via command)

Objective: Discuss roadmap with user and generate phase plan.

Delegate to @commands/roadmap-discuss.md:

Produces: <session>/roadmap.md, <session>/config.json

Command: commands/roadmap-discuss.md

Phase 3: Create Team + Dispatch First Phase

Objective: Initialize team and dispatch first phase task.

Workflow:

1. Resolve workspace paths (MUST do first):

• project_root = result of Bash({ command: "pwd" })
• skill_root = <project_root>/.claude/skills/team-roadmap-dev

2. Call TeamCreate({ team_name: "roadmap-dev" })

3. Initialize meta.json with pipeline metadata:

// 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: "roadmap-driven",
    pipeline_stages: ["planner", "executor", "verifier"],
    roles: ["coordinator", "planner", "executor", "verifier"],
    team_name: "roadmap-dev"
  }
})

4. Spawn worker roles (see SKILL.md Coordinator Spawn Template) 5. Load @commands/dispatch.md for task chain creation

Produces: PLAN-101 task created, workers spawned

Command: commands/dispatch.md

Phase 4: Coordination Loop (Stop-Wait per phase)

Objective: Monitor phase execution, handle callbacks, advance pipeline.

Design: Spawn-and-Stop + Callback pattern.

• Spawn workers with Task(run_in_background: true) -> immediately return
• Worker completes -> SendMessage callback -> auto-advance
• User can use "check" / "resume" to manually advance
• Coordinator does one operation per invocation, then STOPS

Delegate to @commands/monitor.md:

Pipeline advancement driven by three wake sources:

• Worker callback (automatic) -> handleCallback
• User "check" -> handleCheck (status only)
• User "resume" -> handleContinue (advance)

Command: commands/monitor.md

Phase 5: Report + Persist

Objective: Completion report and follow-up options.

Workflow:

Next step options:

• Submit code (git add + commit)
• Continue next milestone (new roadmap discussion)
• Complete (end session)

---

Error Handling

Executor

Wave-based code implementation per phase. Reads IMPL-*.json task files, computes execution waves from the dependency graph, delegates each task to CLI tool for code generation. Produces summary-{IMPL-ID}.md per task.

Phase 2: Context Loading

1. Glob <session>/phase-{N}/.task/IMPL-*.json, error if none found 2. Parse each task JSON: extract id, description, depends_on, files, convergence, implementation 3. Compute execution waves from dependency graph:

• Wave 1: tasks with no dependencies
• Wave N: tasks whose all deps are in waves 1..N-1
• Force-assign if circular (break at lowest-numbered task)

4. Load prior phase summaries for cross-task context

Phase 3: Wave-Based Implementation

Execute waves sequentially, tasks within each wave can be parallel.

Strategy selection:

Per task: 1. Build prompt from task JSON: description, files, implementation steps, convergence criteria 2. Include prior summaries and wisdom as context 3. Delegate to CLI tool (run_in_background: false):

   Bash({
     command: `ccw cli -p "PURPOSE: Implement task ${taskId}: ${description}
   TASK: ${implementationSteps}
   MODE: write
   CONTEXT: @${files.join(' @')} | Memory: ${priorSummaries}
   EXPECTED: Working code changes matching convergence criteria
   CONSTRAINTS: ${convergenceCriteria}" --tool gemini --mode write`,
     run_in_background: false
   })

4. Write <session>/phase-{N}/summary-{IMPL-ID}.md with: task ID, affected files, changes made, status

Between waves: report wave progress via team_msg (type: exec_progress)

Phase 4: Self-Validation

Log errors via team_msg but do NOT fix — verifier handles gap detection.

Planner

Research and plan creation per roadmap phase. Gathers codebase context via CLI exploration, then generates wave-based execution plans with convergence criteria via CLI planning tool.

Phase 2: Context Loading + Research

1. Read roadmap.md, extract phase goal, requirements (REQ-IDs), success criteria 2. Read config.json for depth setting (quick/standard/comprehensive) 3. Load prior phase summaries for dependency context 4. Detect gap closure mode (task description contains "Gap closure") 5. Launch CLI exploration with phase requirements as exploration query:

   Bash({
     command: `ccw cli -p "PURPOSE: Explore codebase for phase requirements
   TASK: • Identify files needing modification • Map patterns and dependencies • Assess test infrastructure • Identify risks
   MODE: analysis
   CONTEXT: @**/* | Memory: Phase goal: ${phaseGoal}
   EXPECTED: Structured exploration results with file lists, patterns, risks
   CONSTRAINTS: Read-only analysis" --tool gemini --mode analysis`,
     run_in_background: false
   })

• Target: files needing modification, patterns, dependencies, test infrastructure, risks

6. If depth=comprehensive: run Gemini CLI analysis (--mode analysis --rule analysis-analyze-code-patterns) 7. Write <session>/phase-{N}/context.md combining roadmap requirements + exploration results

Phase 3: Plan Creation

1. Load context.md from Phase 2 2. Create output directory: <session>/phase-{N}/.task/ 3. Delegate to CLI planning tool with:

   Bash({
     command: `ccw cli -p "PURPOSE: Generate wave-based execution plan for phase ${phaseNum}
   TASK: • Break down requirements into tasks • Define convergence criteria • Build dependency graph • Assign waves
   MODE: write
   CONTEXT: @${contextMd} | Memory: ${priorSummaries}
   EXPECTED: IMPL_PLAN.md + IMPL-*.json files + TODO_LIST.md
   CONSTRAINTS: <= 10 tasks | Valid DAG | Measurable convergence criteria" --tool gemini --mode write`,
     run_in_background: false
   })

4. CLI tool produces: IMPL_PLAN.md, .task/IMPL-*.json, TODO_LIST.md 5. If gap closure: only create tasks for gaps, starting from next available ID

Tech Profile Scan

After plan creation, emit context-aware trigger signals (based on detected codebase characteristics):

1. Check plan scope → signals (data_migration, breaking_change, scaling_concern) 2. Check tech stack from exploration → signals (sql_detected, auth_detected, ml_detected) 3. Include tech_profile in Phase 5 state_update data

Phase 4: Self-Validation

After validation, compute wave structure from dependency graph for reporting:

• Wave count = topological layers of DAG
• Report: task count, wave count, file list

Verifier

Goal-backward verification per phase. Reads convergence criteria from IMPL-*.json task files and checks against actual codebase state. Read-only — never modifies code. Produces verification.md with pass/fail and structured gap lists.

Phase 2: Context Loading

1. Glob IMPL-.json files, extract convergence criteria from each task 2. Glob summary-.md files, parse frontmatter (task, affects, provides) 3. If no task JSONs or summaries found → error to coordinator

Phase 3: Goal-Backward Verification

For each task's convergence criteria, execute appropriate check:

Per task scoring:

Collect all gaps from partial/failed tasks with structured format:

• task ID, criteria type, expected value, actual value

Phase 4: Compile Results

1. Aggregate per-task results: count passed, partial, failed 2. Determine overall status:

• passed if gaps.length === 0
• gaps_found otherwise

3. Write <session>/phase-{N}/verification.md:

---
phase: <N>
status: passed | gaps_found
tasks_checked: <count>
tasks_passed: <count>
gaps:
  - task: "<task-id>"
    type: "<criteria-type>"
    item: "<description>"
    expected: "<expected>"
    actual: "<actual>"
---

4. Update .msg/meta.json with verification summary

Pipeline Definitions — Team Roadmap Dev

Pipeline Mode

Single Phase Pipeline

PLAN-101 --> EXEC-101 --> VERIFY-101
[planner]    [executor]   [verifier]
                              |
                         gap found?
                         YES (< 3x)
                              |
                         PLAN-102 --> EXEC-102 --> VERIFY-102
                              |
                         gap found?
                         YES (>= 3x) -> AskUser: continue/retry/stop
                         NO -> Complete

Multi-Phase Pipeline

Phase 1: PLAN-101 --> EXEC-101 --> VERIFY-101
                                      |
                               [gap closure loop]
                                      |
                               Phase 1 passed
                                      |
Phase 2: PLAN-201 --> EXEC-201 --> VERIFY-201
                                      |
                               [gap closure loop]
                                      |
                               Phase 2 passed
                                      |
Phase N: PLAN-N01 --> EXEC-N01 --> VERIFY-N01
                                      |
                               [gap closure loop]
                                      |
                               All phases done -> Complete

Task Metadata Registry

Task Naming Rules

Checkpoints

State Machine Coordinates

{
  "current_phase": 1,
  "total_phases": 3,
  "gap_iteration": 0,
  "step": "plan | exec | verify | gap_closure | transition",
  "status": "running | paused | complete"
}

Role-Worker Map