maestro-flow 0.5.31 → 0.5.33

package/.agents/skills/team-roadmap-dev/roles/coordinator/role.md

@@ -0,0 +1,302 @@
+# 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 (ask_user) -- 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 ask_user
+- Create team and spawn worker team members in background
+- Dispatch tasks with proper dependency chains
+- monitor_process 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 create_task.
+
+---
+
+## 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:
+
+| Detection | Condition | Handler |
+|-----------|-----------|---------|
+| Worker callback | Message contains role tag [planner], [executor], [verifier] | -> handleCallback |
+| Resume mode | Arguments contain `--resume` | -> @commands/resume.md: load session, re-enter monitor |
+| 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 (Session Resume Check) |
+| New session | None of above | -> Phase 1 (Init Prerequisites) |
+
+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
+
+| Command | File | Phase | Description |
+|---------|------|-------|-------------|
+| `analyze` | [commands/analyze.md](commands/analyze.md) | Phase 1 | Detect depth/phase-count/gate signals from task description |
+| `roadmap-discuss` | [commands/roadmap-discuss.md](commands/roadmap-discuss.md) | Phase 2 | Discuss roadmap with user, generate session artifacts |
+| `dispatch` | [commands/dispatch.md](commands/dispatch.md) | Phase 3 | Create task chain per phase |
+| `monitor` | [commands/monitor.md](commands/monitor.md) | Phase 4 | Stop-Wait phase execution loop |
+| `pause` | [commands/pause.md](commands/pause.md) | Any | Save state and exit cleanly |
+| `resume` | [commands/resume.md](commands/resume.md) | Any | Resume from paused session |
+
+### Tool Capabilities
+
+| Tool | Type | Used By | Purpose |
+|------|------|---------|---------|
+| `ask_user` | Human interaction | coordinator | Clarify requirements, roadmap discussion |
+| `create_team` | Team management | coordinator | Create roadmap-dev team |
+| `create_task` | Task dispatch | coordinator | Create PLAN-*, EXEC-*, VERIFY-* tasks |
+| `send_message` | Worker communication | coordinator | Receive worker callbacks |
+| `mcp__maestro__team_msg` | Message bus | coordinator | Log all communications |
+| `Read/Write` | File operations | coordinator | Session state management |
+
+---
+
+## Message Types
+
+| Type | Direction | Trigger | Description |
+|------|-----------|---------|-------------|
+| `phase_started` | coordinator -> workers | Phase dispatch | New phase initiated |
+| `phase_complete` | coordinator -> user | All phase tasks done | Phase results summary |
+| `gap_closure` | coordinator -> planner | Verifier found gaps | Trigger re-plan for gaps |
+| `project_complete` | coordinator -> user | All phases done | Final report |
+| `error` | coordinator -> user | Critical failure | Error report |
+
+## Message Bus
+
+Before every send_message, log via `mcp__maestro__team_msg`:
+
+```
+mcp__maestro__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):
+
+```
+shell("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:
+
+| Condition | Action |
+|-----------|--------|
+| `.workflow/project-tech.json` exists | Continue to step 4 |
+| File not found | Invoke `invoke_skill(skill="workflow:init")` |
+
+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`:
+
+| Step | Action |
+|------|--------|
+| 1 | Load commands/roadmap-discuss.md |
+| 2 | Execute interactive discussion with user |
+| 3 | Produce roadmap.md with phase requirements |
+| 4 | Produce config.json with session settings |
+| 5 | Update state.md with roadmap reference |
+
+**Produces**: `<session>/roadmap.md`, `<session>/config.json`
+
+**Command**: [commands/roadmap-discuss.md](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 `shell({ command: "pwd" })`
+   - `skill_root` = `<project_root>/.claude/skills/team-roadmap-dev`
+
+2. Call `create_team({ team_name: "roadmap-dev" })`
+
+3. Initialize meta.json with pipeline metadata:
+```typescript
+// Use team_msg to write pipeline metadata to .msg/meta.json
+mcp__maestro__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
+
+| Step | Action |
+|------|--------|
+| 1 | Read roadmap.md for phase definitions |
+| 2 | Create PLAN-101 task for first phase |
+| 3 | Set proper owner and dependencies |
+| 4 | Include `Session: <session-folder>` in task description |
+
+**Produces**: PLAN-101 task created, workers spawned
+
+**Command**: [commands/dispatch.md](commands/dispatch.md)
+
+### Phase 4: Coordination Loop (Stop-Wait per phase)
+
+**Objective**: monitor_process phase execution, handle callbacks, advance pipeline.
+
+**Design**: Spawn-and-Stop + Callback pattern.
+- Spawn workers with `Task(run_in_background: true)` -> immediately return
+- Worker completes -> send_message callback -> auto-advance
+- User can use "check" / "resume" to manually advance
+- Coordinator does one operation per invocation, then STOPS
+
+Delegate to `@commands/monitor.md`:
+
+| Step | Action |
+|------|--------|
+| 1 | Load commands/monitor.md |
+| 2 | Find tasks with: status=pending, blockedBy all resolved |
+| 3 | For each ready task -> spawn worker (see SKILL.md Spawn Template) |
+| 4 | Handle worker callbacks -> advance pipeline |
+| 5 | Phase complete -> transition to next phase or gap closure |
+| 6 | STOP after each operation |
+
+**Pipeline advancement** driven by three wake sources:
+- Worker callback (automatic) -> handleCallback
+- User "check" -> handleCheck (status only)
+- User "resume" -> handleContinue (advance)
+
+**Command**: [commands/monitor.md](commands/monitor.md)
+
+### Phase 5: Report + Persist
+
+**Objective**: Completion report and follow-up options.
+
+**Workflow**:
+
+| Step | Action |
+|------|--------|
+| 1 | Load session state -> count completed tasks, duration |
+| 2 | List deliverables with output paths |
+| 3 | Update state.md status -> "completed" |
+| 4 | Offer next steps via ask_user |
+
+**Next step options**:
+- Submit code (git add + commit)
+- Continue next milestone (new roadmap discussion)
+- Complete (end session)
+
+---
+
+## Error Handling
+
+| Scenario | Resolution |
+|----------|------------|
+| project-tech.json missing | Invoke /workflow:spec:setup  automatically |
+| User cancels roadmap discussion | Save session state, exit gracefully |
+| Planner fails | Retry once, then ask user for guidance |
+| Executor fails on plan | Mark plan as failed, continue with next |
+| Verifier finds gaps (<=3 iterations) | Trigger gap closure: re-plan -> re-execute -> re-verify |
+| Verifier gaps persist (>3 iterations) | Report to user, ask for manual intervention |
+| Worker timeout | Kill worker, report partial results |
+| Task timeout | Log, mark failed, ask user to retry or skip |
+| Worker crash | Respawn worker, reassign task |
+| Dependency cycle | Detect, report to user, halt |
+| Invalid mode | Reject with error, ask to clarify |
+| Session corruption | Attempt recovery, fallback to manual reconciliation |

package/.agents/skills/team-roadmap-dev/roles/executor/role.md

@@ -0,0 +1,74 @@
+---
+role: executor
+prefix: EXEC
+inner_loop: true
+cli_tools:
+  - gemini --mode write
+message_types:
+  success: exec_complete
+  progress: exec_progress
+  error: error
+---
+<!-- Open-standard mirror generated by scripts/build-agents-standard.mjs — do not edit; re-run after editing .claude/ source. -->
+
+
+# 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
+
+| Input | Source | Required |
+|-------|--------|----------|
+| Task JSONs | <session>/phase-{N}/.task/IMPL-*.json | Yes |
+| Prior summaries | <session>/phase-{1..N-1}/summary-*.md | No |
+| Wisdom | <session>/wisdom/ | No |
+
+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**:
+
+| Task Count | Strategy |
+|------------|----------|
+| <= 2 | Direct: inline Edit/Write |
+| 3-5 | Single CLI tool call for all |
+| > 5 | Batch: one CLI tool call per module group |
+
+**Per task**:
+1. Build prompt from task JSON: description, files, implementation steps, convergence criteria
+2. Include prior summaries and wisdom as context
+3. Delegate to CLI tool (`run_in_background: false`):
+   ```
+   shell({
+     command: `maestro delegate "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
+
+| Check | Method | Pass Criteria |
+|-------|--------|---------------|
+| Affected files exist | `test -f <path>` for each file in summary | All present |
+| TypeScript syntax | `npx tsc --noEmit` (if tsconfig.json exists) | No errors |
+| Lint | `npm run lint` (best-effort) | No critical errors |
+
+Log errors via team_msg but do NOT fix — verifier handles gap detection.

package/.agents/skills/team-roadmap-dev/roles/planner/role.md

@@ -0,0 +1,88 @@
+---
+role: planner
+prefix: PLAN
+inner_loop: true
+cli_tools:
+  - gemini --mode analysis
+message_types:
+  success: plan_ready
+  progress: plan_progress
+  error: error
+---
+<!-- Open-standard mirror generated by scripts/build-agents-standard.mjs — do not edit; re-run after editing .claude/ source. -->
+
+
+# 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
+
+| Input | Source | Required |
+|-------|--------|----------|
+| roadmap.md | <session>/roadmap.md | Yes |
+| config.json | <session>/config.json | Yes |
+| Prior summaries | <session>/phase-{1..N-1}/summary-*.md | No |
+| Wisdom | <session>/wisdom/ | No |
+
+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:
+   ```
+   shell({
+     command: `maestro delegate "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:
+   ```
+   shell({
+     command: `maestro delegate "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
+
+| Check | Pass Criteria | Action on Failure |
+|-------|---------------|-------------------|
+| Task JSON files exist | >= 1 IMPL-*.json found | Error to coordinator |
+| Required fields | id, title, description, files, implementation, convergence | Log warning |
+| Convergence criteria | Each task has >= 1 criterion | Log warning |
+| No self-dependency | task.id not in task.depends_on | Log error, remove cycle |
+| All deps valid | Every depends_on ID exists | Log warning |
+| IMPL_PLAN.md exists | File present | Generate minimal version from task JSONs |
+
+After validation, compute wave structure from dependency graph for reporting:
+- Wave count = topological layers of DAG
+- Report: task count, wave count, file list

package/.agents/skills/team-roadmap-dev/roles/verifier/role.md

@@ -0,0 +1,76 @@
+---
+role: verifier
+prefix: VERIFY
+inner_loop: true
+cli_tools:
+  - gemini --mode analysis
+message_types:
+  success: verify_passed
+  failure: gaps_found
+  error: error
+---
+<!-- Open-standard mirror generated by scripts/build-agents-standard.mjs — do not edit; re-run after editing .claude/ source. -->
+
+
+# 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
+
+| Input | Source | Required |
+|-------|--------|----------|
+| Task JSONs | <session>/phase-{N}/.task/IMPL-*.json | Yes |
+| Summaries | <session>/phase-{N}/summary-*.md | Yes |
+| Wisdom | <session>/wisdom/ | No |
+
+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:
+
+| Criteria Type | Method |
+|---------------|--------|
+| File existence | `test -f <path>` |
+| Command execution | Run command, check exit code |
+| Pattern match | Grep for pattern in specified files |
+| Semantic check | Optional: Gemini CLI (`--mode analysis --rule analysis-review-code-quality`) |
+
+**Per task scoring**:
+
+| Result | Condition |
+|--------|-----------|
+| pass | All criteria met |
+| partial | Some criteria met |
+| fail | No criteria met or critical check failed |
+
+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`:
+
+```yaml
+---
+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

package/.agents/skills/team-roadmap-dev/specs/pipelines.md

@@ -0,0 +1,93 @@
+# 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 ID | Role | Phase | Dependencies | Description |
+|---------|------|-------|-------------|-------------|
+| PLAN-N01 | planner | phase N | (none or previous VERIFY) | Context research + IMPL-*.json task generation |
+| EXEC-N01 | executor | phase N | PLAN-N01 | Wave-based code implementation following IMPL-*.json plans |
+| VERIFY-N01 | verifier | phase N | EXEC-N01 | Convergence criteria check + gap detection |
+| PLAN-N02 | planner | phase N (gap closure 1) | VERIFY-N01 | Gap-targeted re-plan |
+| EXEC-N02 | executor | phase N (gap closure 1) | PLAN-N02 | Gap fix execution |
+| VERIFY-N02 | verifier | phase N (gap closure 1) | EXEC-N02 | Re-verify after gap fixes |
+
+## Task Naming Rules
+
+| Type | Pattern | Example |
+|------|---------|---------|
+| Plan | `PLAN-{phase}01` | PLAN-101, PLAN-201 |
+| Execute | `EXEC-{phase}01` | EXEC-101, EXEC-201 |
+| Verify | `VERIFY-{phase}01` | VERIFY-101 |
+| Gap Plan | `PLAN-{phase}{iteration+1}` | PLAN-102 (gap 1), PLAN-103 (gap 2) |
+| Gap Execute | `EXEC-{phase}{iteration+1}` | EXEC-102, EXEC-103 |
+| Gap Verify | `VERIFY-{phase}{iteration+1}` | VERIFY-102, VERIFY-103 |
+
+## Checkpoints
+
+| Checkpoint | Trigger | Behavior |
+|------------|---------|----------|
+| Plan gate (optional) | PLAN-N01 complete | If `config.gates.plan_check=true`: AskUser to approve/revise/skip |
+| Phase transition | VERIFY-N01 complete, no gaps | If `config.mode=interactive`: AskUser to proceed/review/stop |
+| Gap closure | VERIFY-N01 complete, gaps found | Auto-create PLAN-N02/EXEC-N02/VERIFY-N02 (max 3 iterations) |
+| Gap limit | gap_iteration >= 3 | AskUser: continue anyway / retry once more / stop |
+| Pipeline complete | All phases passed | AskUser: archive & clean / keep active / export results |
+
+## State Machine Coordinates
+
+```json
+{
+  "current_phase": 1,
+  "total_phases": 3,
+  "gap_iteration": 0,
+  "step": "plan | exec | verify | gap_closure | transition",
+  "status": "running | paused | complete"
+}
+```
+
+## Role-Worker Map
+
+| Prefix | Role | Role Spec | Inner Loop |
+|--------|------|-----------|------------|
+| PLAN | planner | `~  or <project>/.claude/skills/team-roadmap-dev/roles/planner/role.md` | true |
+| EXEC | executor | `~  or <project>/.claude/skills/team-roadmap-dev/roles/executor/role.md` | true |
+| VERIFY | verifier | `~  or <project>/.claude/skills/team-roadmap-dev/roles/verifier/role.md` | true |