maestro-flow 0.3.21 → 0.3.23

package/workflows/execute.md

@@ -48,16 +48,30 @@ For each PLAN_DIR in PLAN_DIRS (sequential):
 
 ## E0.5: Execution Options Confirmation
 
-**Purpose:** Let user choose how tasks execute. Supports both menu selection and natural language intent (e.g., "前端用gemini，后端用codex，其余agent"). Skipped when `-y` flag or executionContext already confirmed.
+**Purpose:** Let user choose how tasks execute. Reads available tools from `delegate-config show --json` to build dynamic options. Supports both menu selection and natural language intent. Skipped when `-y` flag or executionContext already confirmed.
 
 ### Skip conditions
 
 - `-y` flag → use resolved defaults, skip prompt
 - `executionContext.executionMethod` already set → skip (confirmed in /maestro-plan)
 
+### Pre-step: Load tool config
+
+```
+Run: maestro delegate-config show --json
+Parse: { tools, roles } — extract enabled tool names and domain tags
+Build dynamic options from enabled tools (exclude agent which is always available)
+```
+
 ### Tool Call
 
+Build AskUserQuestion dynamically from enabled tools:
+
 ```
+// availableTools = enabled tools from delegate-config (e.g. ["gemini", "claude", "codex"])
+// frontendTool = first tool with "frontend" tag, fallback first enabled
+// backendTool = first tool with "backend" tag, fallback first enabled
+
 AskUserQuestion({
   questions: [
     {
@@ -65,10 +79,10 @@ AskUserQuestion({
       header: "Executor",
       multiSelect: false,
       options: [
-        { label: "Auto (Recommended)", description: "Per-task domain routing: frontend→gemini, backend→codex, general→agent" },
+        { label: "Auto (Recommended)", description: `Per-task domain routing: frontend→${frontendTool}, backend→${backendTool}, general→agent` },
         { label: "Agent", description: "Claude Code agent for all tasks (fastest)" },
-        { label: "Codex", description: "Codex CLI for all tasks (strong for complex backend)" },
-        { label: "Gemini", description: "Gemini CLI for all tasks (strong for frontend/UI)" }
+        // One option per enabled CLI tool:
+        ...availableTools.map(t => ({ label: t, description: `${t} CLI for all tasks` }))
       ]
     },
     {
@@ -77,8 +91,8 @@ AskUserQuestion({
       multiSelect: false,
       options: [
         { label: "Skip (Recommended)", description: "No code review, proceed to verification" },
-        { label: "Gemini Review", description: "Gemini CLI: git diff quality review" },
-        { label: "Codex Review", description: "Codex CLI: git-aware code review" }
+        // One option per enabled CLI tool with review capability:
+        ...availableTools.map(t => ({ label: `${t} Review`, description: `${t} CLI: git diff quality review` }))
       ]
     }
   ]
@@ -91,11 +105,11 @@ AskUserQuestion({
 
 | Answer | executionMethod | domainRouting |
 |--------|----------------|---------------|
-| "Auto" | `"auto"` | `{ frontend: "gemini", backend: "codex", default: "agent" }` |
-| "Agent" / "Codex" / "Gemini" | that value | not used |
-| Other text with domain rules | `"auto"` | Parse from user text (see examples below) |
+| "Auto" | `"auto"` | `{ frontend: frontendTool, backend: backendTool, default: "agent" }` |
+| "Agent" / tool name | that value | not used |
+| Other text with domain rules | `"auto"` | Parse from user text |
 
-Other text parsing examples:
+Other text parsing — match tool names dynamically from enabled tools:
 
 | User types | domainRouting |
 |------------|---------------|
@@ -134,9 +148,9 @@ If executionContext is available in memory:
 Read ${PLAN_DIR}/plan.json
 
 executionMethod = E0.5 selection || --method flag || config.json.execution.method || "auto"
-defaultExecutor = --executor flag || config.json.execution.default_executor || "gemini"
+defaultExecutor = --executor flag || config.json.execution.default_executor || first enabled tool from delegate-config
 executorAssignments = plan.json.executor_assignments || {}
-domainRouting = E0.5 domainRouting || { frontend: "gemini", backend: "codex", default: "agent" }
+domainRouting = E0.5 domainRouting || built from delegate-config domain tags (frontend→tag match, backend→tag match, default→"agent")
 codeReviewTool = E0.5 selection || "Skip"
 ```
 
@@ -340,9 +354,9 @@ If none critical: log "passed" and continue to E2.6
 If codeReviewTool == "Skip": continue to E3
 
 Dispatch review via maestro delegate (run_in_background: true):
-  --to gemini|codex (per codeReviewTool selection) --mode analysis
+  --to ${codeReviewTool} --mode analysis
   Prompt: review git diff (execution start → HEAD) for correctness, style, bugs
-  Rule: analysis-review-code-quality (gemini only)
+  Rule: analysis-review-code-quality
   Expected: severity-ranked issues with file:line references and fix suggestions
 
 Wait for completion, log findings summary

package/workflows/init.md

@@ -1,6 +1,6 @@
 # Workflow: init
 
-Project initialization with automatic state detection. Creates project infrastructure only — roadmap creation is handled by maestro-spec-generate or maestro-roadmap.
+Project initialization with automatic state detection. Creates project infrastructure only — roadmap creation is handled by maestro-roadmap (light or full mode).
 
 ---
 
@@ -143,7 +143,7 @@ Verify all required directories and files exist:
    - Config highlights (mode, granularity, execution method, enabled agents)
    - Research summary (if research was run)
 3. Route next steps:
-   - "Run `/maestro-spec-generate` to create full spec package with roadmap (heavy path)"
+   - "Run `/maestro-roadmap --mode full` to create full spec package with roadmap (heavy path)"
    - "Run `/maestro-roadmap` to create interactive roadmap directly (light path)"
    - "Run `/manage-status` to view project dashboard"
    - "Run `/maestro-brainstorm` to explore ideas first"

package/workflows/issue-discover.md

@@ -109,7 +109,7 @@ Per perspective → delegate analysis:
   CONTEXT: @**/*
   EXPECTED: JSON array: [{ title, severity, description, location, fix_direction, affected_components[] }]
   CONSTRAINTS: Evidence-backed findings only
-  " --to gemini --mode analysis
+  " --role analyze --mode analysis
 
 Results → .workflow/issues/discoveries/{SESSION_ID}/{PERSPECTIVE}-findings.json
 Update discovery-state.json: perspectives_completed += ["{PERSPECTIVE}"]
@@ -170,7 +170,7 @@ Delegate to decompose USER_PROMPT into 3-5 exploration dimensions:
 
   maestro delegate "Decompose into searchable dimensions: {USER_PROMPT}
   EXPECTED: JSON array: [{ name, description, search_patterns[], file_patterns[], finding_criteria }]
-  " --to gemini --mode analysis
+  " --role analyze --mode analysis
 
 Store → .workflow/issues/discoveries/{SESSION_ID}/exploration-plan.json
 ```

package/workflows/maestro-super.md

@@ -0,0 +1,120 @@
+# Super Mode (`--super`)
+
+Goal: deliver a production-ready, complete software system from user requirements. No user decisions needed — maestro autonomously expands, refines, and implements until the system meets mainstream quality standards.
+
+Super mode implies `-y` (all auto flags propagated) plus these additional behaviors:
+
+## 1. Requirement Expansion
+
+On receiving user intent, autonomously expand incomplete requirements into a complete product scope. Delegate via role (`maestro delegate --role analyze --mode analysis`) for requirement completeness analysis and gap-filling. Accept requirements that add real user value; discard noise.
+
+## 2. Progressive Document Loading
+
+Read execution documents (workflow maestro.md, chain steps) incrementally per-phase rather than loading all upfront. Each milestone loads only the relevant section to preserve context window.
+
+## 3. Autonomous Decision-Making
+
+All design/architecture/scope decisions are made via Gemini delegate (`--mode analysis`). No AskUserQuestion calls. Decision criteria: mainstream industry standards, pragmatism, simplicity.
+
+## 4. Auto-Advance Milestones
+
+After each milestone completes and passes verification, automatically advance to the next milestone without user confirmation. Run `maestro-milestone-complete` → next milestone chain automatically.
+
+## 5. Quality Gate Scoring
+
+Each milestone must pass a readiness score before advancing. Prevents premature exit.
+
+| Dimension | Weight | Minimum |
+|-----------|--------|---------|
+| Code completeness (features implemented vs planned) | 25% | 90% |
+| Test coverage (lines + branches) | 20% | 70% |
+| Build & run success (clean build, app starts) | 20% | 100% |
+| Code quality (lint clean, no ts errors) | 15% | 90% |
+| Integration coherence (cross-module contracts) | 10% | 80% |
+| Documentation (API docs, README, setup guide) | 10% | 60% |
+| **Weighted total** | | **≥ 80%** |
+
+Score is computed via `maestro-verify` + Gemini analysis. If score < 80%, generate fix plan and re-execute until threshold is met (max 3 retries per milestone, then report blockers).
+
+## 6. Completion Criteria
+
+Super mode only terminates when:
+- All roadmap milestones completed and scored ≥ 80%
+- Final system builds, starts, and passes all tests
+- Gemini confirms the system is production-ready via final audit
+
+## 7. State Tracking
+
+Super mode extends the standard session `status.json` (`.workflow/.maestro/{session_id}/status.json`). No extra files — all state in one place.
+
+### 7a. status.json 扩展字段
+
+```json
+{
+  "session_id": "...",
+  "status": "running",
+  "super": true,
+  "super_state": "expanding|planning|executing|scoring|advancing|completed|blocked",
+  "current_milestone": 1,
+  "total_milestones": 3,
+  "expanded_requirements": "...",
+  "milestones": [
+    {
+      "index": 1,
+      "name": "...",
+      "status": "pending|executing|scoring|completed|blocked",
+      "chain_session_id": null,
+      "retries": 0,
+      "max_retries": 3,
+      "scores": {
+        "code_completeness": null,
+        "test_coverage": null,
+        "build_success": null,
+        "code_quality": null,
+        "integration_coherence": null,
+        "documentation": null,
+        "weighted_total": null
+      },
+      "score_history": [],
+      "decisions": []
+    }
+  ],
+  "decision_log": [],
+  "steps": [ ... ]
+}
+```
+
+`super_state` values:
+- `expanding` — requirement expansion via Gemini
+- `planning` — roadmap/spec/plan generation
+- `executing` — milestone chain execution (plan → execute → verify)
+- `scoring` — quality gate evaluation
+- `advancing` — milestone-complete + next milestone setup
+- `completed` — all milestones passed
+- `blocked` — max retries exceeded, needs user intervention
+
+### 7b. State transitions
+
+```
+[start] → expanding → planning → executing(M1) → scoring(M1)
+  → score ≥ 80% → advancing → executing(M2) → ...
+  → score < 80% → retries < 3 → executing(M1) (retry)
+  → score < 80% → retries = 3 → blocked
+  → all milestones completed → completed
+```
+
+### 7c. Resume (`-c` or `continue`)
+
+On resume, read `status.json`:
+1. Check `super: true` → enter super mode resume
+2. Read `super_state` + `current_milestone` → determine resume point
+3. Read milestone's `status` → resume from exact phase (e.g., interrupted during `scoring` → re-run scoring)
+4. Load `decision_log` for Gemini continuity
+
+### 7d. State update discipline
+
+Update `status.json` at every state transition:
+- Before milestone chain → set milestone `status: "executing"`, increment retries if retry
+- After scoring → write scores to milestone, append to `score_history`
+- After advancing → set previous milestone `status: "completed"`, bump `current_milestone`
+- On block → set milestone `status: "blocked"`, set `super_state: "blocked"`

package/workflows/maestro.codex.md

@@ -138,7 +138,7 @@ const chainMap = {
   // ── Multi-step chains ────────────────────────────────────────────────────
   'spec-driven': [
     { cmd: 'maestro-init' },
-    { cmd: 'maestro-spec-generate', args: '"{description}"' },
+    { cmd: 'maestro-roadmap', args: '--mode full "{description}"' },
     { cmd: 'maestro-plan',          args: '{phase}' },
     { cmd: 'maestro-execute',       args: '{phase}' },
     { cmd: 'maestro-verify',        args: '{phase}' }
@@ -306,9 +306,9 @@ MAESTRO-COORDINATE: {chain_name}  (dry run)
 
 Create session directory `.workflow/.maestro/maestro-{timestamp}/`.
 
-**Barrier skills** (solo wave, coordinator analyzes artifacts after): `maestro-analyze`, `maestro-plan`, `maestro-brainstorm`, `maestro-spec-generate`, `maestro-execute`.
+**Barrier skills** (solo wave, coordinator analyzes artifacts after): `maestro-analyze`, `maestro-plan`, `maestro-brainstorm`, `maestro-roadmap`, `maestro-execute`.
 
-**Auto-flag injection** (when AUTO_YES): `maestro-analyze/-brainstorm/-ui-design/-spec-generate` → `-y`, `maestro-plan` → `--auto`, `quality-test` → `--auto-fix`, `quality-retrospective` → `--auto-yes`.
+**Auto-flag injection** (when AUTO_YES): `maestro-analyze/-brainstorm/-roadmap/-ui-design` → `-y`, `maestro-plan` → `--auto`, `quality-test` → `--auto-fix`, `quality-retrospective` → `--auto-yes`.
 
 Initialize `state.json` with: session_id, intent, chain_name, auto_yes, context (phase, dirs, issue_id, gaps), waves[], and steps[] (each with index, cmd, args, status=pending).
 
@@ -352,7 +352,7 @@ Context updates per barrier skill:
 | `maestro-analyze` | `analysis_dir`, gaps (from context.md markers), phase (if detected) |
 | `maestro-plan` | `plan_dir`, task/wave count (from plan.json) |
 | `maestro-brainstorm` | `brainstorm_dir` |
-| `maestro-spec-generate` | `spec_session_id` (SPEC-* pattern) |
+| `maestro-roadmap` | `spec_session_id` (SPEC-* pattern) |
 | `maestro-execute` | `exec_completed`/`exec_failed` counts (from results.csv) |
 
 **Key principle**: The coordinator owns all context assembly. Sub-agents receive a fully-resolved `skill_call`.

package/workflows/maestro.md

@@ -1,7 +1,7 @@
 # Workflow: maestro
 
 Intelligent coordinator that routes user intent to optimal command chain based on project state.
-Dual execution engines: **Skill()** (in-process, synchronous) and **CLI delegate** (via `maestro delegate`, async with gemini quality analysis).
+Dual execution engines: **Skill()** (in-process, synchronous) and **CLI delegate** (via `maestro delegate`, async with role-based tool selection).
 Default `auto` mode selects engine based on chain complexity.
 
 **Prerequisites:**
@@ -222,7 +222,7 @@ resolvePhase — priority order:
   3. From project state artifacts: in-progress execute → first incomplete phase → latest artifact phase
   4. null if chain is 'analyze-plan-execute' (uses {scratch_dir} instead)
   5. null if all chain commands are phase-independent:
-     manage-status, manage-issue, manage-issue-discover, maestro-init, maestro-spec-generate,
+     manage-status, manage-issue, manage-issue-discover, maestro-init,
      maestro-fork, maestro-merge, maestro-roadmap, spec-setup, manage-knowhow, manage-knowhow-capture,
      manage-learn, manage-codebase-rebuild, manage-codebase-refresh, maestro-milestone-audit,
      maestro-milestone-complete
@@ -245,7 +245,7 @@ Engine is selected **per step**, not per chain.
 ```
 If execMode is 'cli' or 'skill' → force that engine for all steps.
 In 'auto' mode, select per step:
-  CLI steps (heavy, context-isolated): maestro-plan, maestro-execute, maestro-analyze, maestro-brainstorm, maestro-spec-generate, maestro-roadmap, maestro-ui-design, quality-refactor
+  CLI steps (heavy, context-isolated): maestro-plan, maestro-execute, maestro-analyze, maestro-brainstorm, maestro-roadmap, maestro-ui-design, quality-refactor
   Skill steps (everything else): observable, interactive, lightweight (verify, review, test, debug, milestone-*, manage-*, spec-*, quick, etc.)
 ```
 
@@ -282,7 +282,7 @@ Context object tracks: current_phase, user_intent, issue_id, spec_session_id, sc
 
 assembleArgs: substitute placeholders {phase}, {description}, {issue_id}, {spec_session_id}, {scratch_dir} in step.args.
   In auto_mode, append per-command flag if not already present:
-    maestro-analyze/brainstorm/roadmap/ui-design/spec-generate → -y
+    maestro-analyze/brainstorm/roadmap/ui-design → -y
     maestro-plan → --auto
     quality-test → --auto-fix
     quality-retrospective → --auto-yes
@@ -425,7 +425,7 @@ const chainMap = {
 
   // ── Multi-step chains ──
   'full-lifecycle':       [{ cmd: 'maestro-plan', args: '{phase}' }, { cmd: 'maestro-execute', args: '{phase}' }, { cmd: 'maestro-verify', args: '{phase}' }, { cmd: 'quality-review', args: '{phase}' }, { cmd: 'quality-test', args: '{phase}' }, { cmd: 'maestro-milestone-audit' }],
-  'spec-driven':          [{ cmd: 'maestro-init' }, { cmd: 'maestro-spec-generate', args: '"{description}"' }, { cmd: 'maestro-plan', args: '{phase}' }, { cmd: 'maestro-execute', args: '{phase}' }, { cmd: 'maestro-verify', args: '{phase}' }],
+  'spec-driven':          [{ cmd: 'maestro-init' }, { cmd: 'maestro-roadmap', args: '--mode full "{description}"' }, { cmd: 'maestro-plan', args: '{phase}' }, { cmd: 'maestro-execute', args: '{phase}' }, { cmd: 'maestro-verify', args: '{phase}' }],
   'roadmap-driven':       [{ cmd: 'maestro-init' }, { cmd: 'maestro-roadmap', args: '"{description}"' }, { cmd: 'maestro-plan', args: '{phase}' }, { cmd: 'maestro-execute', args: '{phase}' }, { cmd: 'maestro-verify', args: '{phase}' }],
   'brainstorm-driven':    [{ cmd: 'maestro-brainstorm', args: '"{description}"' }, { cmd: 'maestro-plan', args: '{phase}' }, { cmd: 'maestro-execute', args: '{phase}' }, { cmd: 'maestro-verify', args: '{phase}' }],
   'ui-design-driven':     [{ cmd: 'maestro-ui-design', args: '{phase}' }, { cmd: 'maestro-plan', args: '{phase}' }, { cmd: 'maestro-execute', args: '{phase}' }, { cmd: 'maestro-verify', args: '{phase}' }],

package/workflows/roadmap-common.md

@@ -0,0 +1,197 @@
+# Workflow: Roadmap Common
+
+Shared logic for roadmap generation — used by both light mode (roadmap.md) and full mode (spec-generate.md).
+
+---
+
+## Worktree Guard
+
+Block if `.workflow/worktree-scope.json` exists — must run from main worktree.
+
+---
+
+## Load Project Context
+
+### Load Specs
+
+```
+specs_content = maestro spec load --category arch
+```
+
+Ensure phases respect architectural constraints.
+
+### Load Project History (if `.workflow/` exists)
+
+Read project artifacts to understand what has already been built:
+
+- `project.md` → already_shipped (Validated), current_scope (Active), project_history (Context), locked_decisions (Key Decisions)
+- `state.json.accumulated_context` → deferred[] (candidate reqs), key_decisions[] (constraints), blockers[] (risks)
+- `.workflow/codebase/` → feature inventory from codebase docs
+
+**Context assembly** — pass downstream as `project_context`:
+```json
+{
+  "already_shipped": ["REQ-001: User auth", "REQ-002: API layer"],
+  "current_scope": ["REQ-003: Payments", "REQ-004: i18n"],
+  "deferred_from_previous": ["Internationalization deferred from v1.0"],
+  "locked_decisions": ["JWT stateless auth", "PostgreSQL"],
+  "learnings": ["JWT has perf issues at scale — consider caching"],
+  "project_history": "Milestone v1.0 completed 2026-03-15: auth + API layer shipped"
+}
+```
+
+**Rules**:
+- NEVER re-plan features listed in `already_shipped` — they are done
+- `deferred_from_previous` items are HIGH PRIORITY candidates for new phases
+- `locked_decisions` constrain technology choices in decomposition
+- `learnings` inform risk assessment and phase sizing
+
+---
+
+## Codebase Exploration (conditional)
+
+- Detect if project has source files
+- If yes: spawn `cli-explore-agent` for context discovery
+  - If `project_context.already_shipped` exists: include as "feature audit" directive — agent should verify which shipped features are present in code and identify integration points for new work
+- Output: relevant files, patterns, tech stack, feature_audit
+
+---
+
+## External Research — API & Technology Details (Optional)
+
+Spawn `workflow-external-researcher` agent when requirement mentions specific technologies, APIs, or external services.
+
+**Trigger**: Technology keywords detected in requirement or codebase exploration found external dependencies. Auto-trigger in auto mode (`-y`). Skip if requirement is purely organizational/conceptual.
+
+Extract named technologies/APIs/frameworks/protocols from requirement + codebase exploration.
+
+If topics found → spawn `workflow-external-researcher` agent for API research:
+- Per technology: stable version, core API surface, auth model, integration patterns, limitations, effort signals
+- Focus on details affecting phase decomposition and dependency ordering
+- Output → `apiResearchContext` (in-memory)
+
+If no topics or research fails → `apiResearchContext = null`, continue.
+
+---
+
+## Minimum-Phase Principle (MANDATORY)
+
+**Core rule: Phase = synchronization barrier.** Each Phase triggers a full plan→execute→verify→transition serial cycle. More phases = slower delivery. The wave DAG inside each Phase already handles task ordering and parallelism, so only create a new Phase when tasks **cannot** start until a previous Phase's entire output exists.
+
+**Default: 1 Phase.** Put everything into a single Phase unless a hard dependency forces a split.
+
+| Rule | Constraint |
+|------|-----------|
+| **Default** | **1 Phase**. All work in one plan→execute cycle; wave DAG handles internal ordering. |
+| **Maximum** | **2 Phases**. Only when a hard dependency boundary exists that cannot be resolved. |
+| **Exceptional** | **3 Phases**. Must explicitly justify why 2 is insufficient. |
+| **Minimum tasks per phase** | 5 tasks/stories. If a phase would have fewer, merge it into an adjacent phase. |
+| **Merge principle** | Same-module, same-concern, or tightly-coupled work belongs in ONE phase. Infra + core logic + API in one phase is fine. Multiple Epics → one phase is normal. |
+| **Split principle** | Only split when ALL three hard-dependency conditions are met (see below). |
+
+**Hard dependency — all three conditions required to justify a Phase split:**
+1. **Runtime dependency**: Phase B code at runtime MUST call Phase A's real output (cannot mock/stub).
+2. **Not parallelizable**: A and B cannot develop concurrently via contract/interface/type agreement.
+3. **Full barrier**: ALL of Phase A's tasks must complete before ANY of Phase B's tasks can start.
+
+If only 1-2 conditions are met → keep in the same Phase, use wave dependencies instead.
+
+**Phase sizing checklist (applied after decomposition, before presenting to user):**
+1. Count total phases. If > 2 → justify each split against the 3 hard-dependency conditions, merge if unjustified.
+2. Count estimated tasks per phase. Any phase < 5 tasks → merge into neighbor.
+3. Verify each phase has a meaningful deliverable boundary (not just "setup" or "cleanup").
+
+**Scope escalation:**
+- **Single project** (any size): 1-2 Phases. Use wave DAG for internal parallelism.
+- **Large scope** (monorepo with 2+ independently deployable services): Use **Milestones** to divide scope. Each Milestone follows the 1-2 Phase limit independently.
+
+**Progressive mode**:
+- Progressive layers (MVP → Usable → Refined) map to **Milestones**, not Phases.
+- Each Milestone contains 1-2 Phases following the minimum-phase principle.
+- MVP must be self-contained (no external dependencies)
+- Each feature in exactly ONE milestone (no overlap)
+
+**Direct mode**:
+- Topologically-sorted task sequence
+- Each task: title, type, scope, inputs, outputs, convergence, depends_on
+- parallel_group for truly independent tasks
+
+**Phase format** (both modes):
+```markdown
+### Phase {N}: {Title}
+- **Goal**: <what this phase achieves>
+- **Depends on**: <prerequisite phases or "Nothing">
+- **Requirements**: <REQ-IDs mapped from project.md Active requirements>
+- **Success Criteria** (what must be TRUE):
+  1. <observable behavior from user perspective>
+  2. <observable behavior from user perspective>
+```
+
+Phase numbering: integers (1, 2, 3) for planned work, decimals (2.1, 2.2) for inserted phases.
+Decimal phases count toward the total phase limit.
+Phase directories use `{NN}-{slug}` format (e.g., `01-auth`, `02-api`).
+
+**Requirements traceability**: Every Active requirement from project.md MUST appear in exactly one phase's Requirements field. If a requirement maps to no phase, surface it as a gap.
+
+---
+
+## Roadmap Write Logic
+
+### Roadmap Template
+
+Write `roadmap.md` to `.workflow/roadmap.md` using `@templates/roadmap.md`:
+
+```markdown
+# Roadmap: {project_name}
+
+## Overview
+<one paragraph describing the journey>
+
+## Phases
+- [ ] **Phase 1: {Title}** - {one-line description}
+
+## Phase Details
+
+### Phase 1: {Title}
+**Goal**: {what this phase delivers}
+**Depends on**: Nothing (first phase)
+**Requirements**: {REQ-IDs}
+**Success Criteria** (what must be TRUE):
+  1. {observable behavior from user perspective}
+  2. {observable behavior from user perspective}
+
+## Scope Decisions
+- **In scope**: <included>
+- **Deferred**: <later milestones>
+- **Out of scope**: <excluded>
+
+## Progress
+| Phase | Status | Completed |
+|-------|--------|-----------|
+| 1. {Title} | Not started | - |
+```
+
+**Requirements traceability**: Cross-check that every Active requirement from project.md maps to exactly one phase. Surface unmapped requirements as gaps.
+
+### Overwrite vs Edit Rules (MANDATORY)
+
+Before writing `.workflow/roadmap.md`, check existing state:
+
+| Scenario | Action |
+|----------|--------|
+| `roadmap.md` does not exist | Create (write) |
+| `roadmap.md` exists, no completed phases in Progress table | Overwrite (with `-y` auto-confirm, otherwise ask user) |
+| `roadmap.md` exists, has completed phases | **Refuse overwrite** → instruct user to use `--revise` mode |
+
+### state.json Update Rules
+
+After writing roadmap.md, update state.json consistently regardless of mode:
+
+| Scenario | Action |
+|----------|--------|
+| `state.json` exists | Update `milestones` array and `current_milestone` field from roadmap phases (partial update, not overwrite) |
+| `state.json` does not exist | Do not create (leave to maestro-init) |
+
+### Scratch Directory
+
+Ensure scratch directory exists: `mkdir -p .workflow/scratch/`