maestro-flow 0.3.14 → 0.3.16

package/.claude/commands/maestro-plan.md

@@ -36,66 +36,15 @@ All plan output goes to `.workflow/scratch/{YYYYMMDD}-plan-[P{N}-|M{N}-]{slug}/`
 <context>
 $ARGUMENTS — phase number, or no args for milestone-wide planning, with optional flags.
 
-**Flags:**
-- `--collab` -- Multi-planner collaborative mode (spawn N workflow-collab-planner agents with pre-allocated TASK ID ranges)
-- `--spec SPEC-xxx` -- Reference a task-spec for requirements input
-- `--auto` -- Skip interactive clarification (P2), use defaults
-- `--gaps` -- Gap closure mode: load verification/issue gaps, skip exploration, plan only gap fixes
-- `--dir <path>` -- Use arbitrary scratch directory as context source (e.g., from analyze session)
-- `--revise [instructions]` -- Revise existing plan. Auto-discovers latest plan for current phase from state.json, or use with `--dir` to target specific plan. If instructions provided, apply directly (e.g. `--revise "add TASK-005 for error handling"`). If omitted, ask user via AskUserQuestion. Skips P1-P3 (exploration/clarification/planning), loads existing plan.json + tasks, applies targeted modifications, re-runs P4 (plan-checker).
-- `--check <plan-dir>` -- Standalone plan verification. Run plan-checker (P4 only) against existing plan without modification. Also checks roadmap consistency and collision detection. Read-only.
+Scope routing, base flags (`--collab`, `--spec`, `--auto`, `--gaps`, `--dir`), output directory format, and artifact registration are defined in workflow plan.md.
 
-**Scope routing:**
-
-| Invocation | Precondition | Scope | Behavior |
-|-----------|-------------|-------|----------|
-| `plan` (no args) | init + roadmap | milestone | Plan all phases in current milestone |
-| `plan 1` | init + roadmap | phase | Plan phase 1 only |
-| `plan --dir scratch/analyze-xxx` | none | inherited | Plan against specified analyze session |
-| `plan --revise "instructions"` | existing plan | revise | Modify existing plan with instructions |
-| `plan --revise` | existing plan | revise | Modify existing plan, ask user for instructions |
-| `plan --check scratch/plan-xxx` | existing plan | check | Verify existing plan (read-only) |
+**Command-level flags** (extensions beyond workflow base):
+- `--revise [instructions]` -- See workflow plan.md § Revise Mode
+- `--check <plan-dir>` -- See workflow plan.md § Check Mode
 
 **Upstream context:**
 - Reads `context.md` from prior analyze artifact (auto-discovered from state.json or via --dir)
 - Reads `conclusions.json` if available (implementation_scope seeds task generation)
-
-**Output directory** (relative to `.workflow/`):
-
-| Scope | Directory format | Example |
-|-------|-----------------|---------|
-| Phase | `scratch/{YYYYMMDD}-plan-P{N}-{slug}/` | `20260420-plan-P1-auth` |
-| Milestone | `scratch/{YYYYMMDD}-plan-M{N}-{slug}/` | `20260420-plan-M1-mvp` |
-| Adhoc/Standalone | `scratch/{YYYYMMDD}-plan-{slug}/` | `20260420-plan-caching` |
-
-**Output structure:**
-```
-{YYYYMMDD}-plan-P{N}-{slug}/
-├── plan.json            # summary, task_ids[], waves[] with phase labels
-└── .task/
-    ├── TASK-001.json    # { phase: 1, phase_slug: "auth", ... }
-    ├── TASK-002.json
-    └── ...
-```
-
-**Collision detection**: After plan generation, before user confirmation, check for file overlaps with existing plans in same milestone. Non-blocking warning only.
-
-**Artifact registration**: On completion, register in `state.json.artifacts[]`:
-```jsonc
-{
-  "id": "PLN-{NNN}",
-  "type": "plan",
-  "milestone": "{current_milestone or null}",
-  "phase": "{phase_number or null}",
-  "scope": "{milestone|phase|adhoc|standalone}",
-  "path": "scratch/{YYYYMMDD}-plan-P{N}-{slug}",  // P{N} for phase, M{N} for milestone, omit for adhoc/standalone
-  "status": "completed",
-  "depends_on": "{ANL-NNN or null}",
-  "harvested": false,
-  "created_at": "...",
-  "completed_at": "..."
-}
-```
 </context>
 
 <execution>
@@ -158,79 +107,9 @@ Next steps:
   /maestro-plan {phase}         -- Re-plan with modifications
 ```
 
-### Mode: Revise (`--revise [instructions]`)
-
-Incrementally modify an existing plan without rebuilding from scratch.
-
-**Plan discovery:**
-- With `--dir`: use specified plan directory
-- Without `--dir`: auto-discover latest completed plan for current phase from `state.json.artifacts[]` (type=plan, status=completed, matching phase)
-
-**Execution flow:**
-
-1. **Load existing plan**
-   - Read `plan.json` + all `.task/TASK-*.json` from discovered directory
-   - Show current plan summary: task count, waves, status per task
-
-2. **Obtain revision instructions**
-   - If `--revise "instructions"` provided → parse as change directive
-   - If `--revise` without instructions → AskUserQuestion for what to change:
-     - Add/remove tasks
-     - Modify task scope, action, implementation
-     - Reorder waves or adjust dependencies
-     - Update convergence criteria
-   - Parse instructions into concrete changes
-
-3. **Apply targeted changes**
-   - Modify affected TASK files in-place
-   - If tasks added/removed: re-sequence task IDs, regenerate wave assignments
-   - Update plan.json summary (task count, wave structure)
-   - Preserve unmodified tasks completely
-
-4. **Re-run plan-checker (P4)**
-   - Validate modified plan with same checker as create mode
-   - Re-run collision detection against same-milestone plans
-   - Present check results for confirmation
-
-5. **Update artifact**
-   - Overwrite plan files in existing scratch directory
-   - Update artifact timestamp in state.json (no new artifact created)
-
-### Mode: Check (`--check <plan-dir>`)
-
-Read-only plan verification without modification.
-
-**Execution flow:**
-
-1. **Load plan**
-   - Read `plan.json` + `.task/TASK-*.json` from specified directory
-   - Read `.workflow/roadmap.md` for consistency comparison
-
-2. **Run checks**
-   - Plan-checker (P4 pipeline stage) — task quality, convergence criteria
-   - Roadmap consistency — plan tasks align with phase scope and requirements
-   - Collision detection — file overlaps with other plans in same milestone
-   - Dependency integrity — no broken cross-task dependencies
-
-3. **Produce check report**
-   ```
-   === PLAN CHECK ===
-   Plan: {plan_dir}/plan.json
-   Tasks: {total} ({completed} done, {pending} pending)
-
-   Checker: {PASS|WARN|FAIL} ({issues} issues)
-   Roadmap: {aligned|drift detected}
-   Collision: {clear|{N} overlaps}
-
-   Issues:
-     1. [{severity}] {description}
-
-   Suggested actions:
-     /maestro-plan --revise "fix instructions"  -- Apply fixes
-     /maestro-execute --dir {plan_dir}          -- Execute as-is
-   ```
+### Mode: Revise / Check
 
-**No file modifications.** Pure verification + report.
+Follow workflow plan.md § "Revise Mode" and § "Check Mode" respectively. These modes bypass the standard P1-P5 create pipeline.
 </execution>
 
 <error_codes>

package/.claude/commands/maestro-player.md

@@ -0,0 +1,404 @@
+---
+name: maestro-player
+description: Workflow template player — load JSON template, bind variables, execute DAG nodes in order, persist state at checkpoints, support resume
+argument-hint: "<template-slug|path> [--context key=value...] [-c [session-id]] [--list] [--dry-run]"
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Bash
+  - Glob
+  - Grep
+  - Agent
+  - AskUserQuestion
+  - Skill
+---
+<purpose>
+Load a workflow template (produced by maestro-composer) → bind context variables →
+execute DAG nodes in topological order → persist state at checkpoints → support resume.
+
+Node execution mechanisms:
+- `skill` node → `Skill()` (synchronous)
+- `command` node → `Skill()` with namespace (synchronous)
+- `cli` node → `maestro delegate` (background + wait for callback)
+- `agent` node → `Agent()` (sync or background per config)
+- `checkpoint` node → state save, optional user pause
+
+Session state persisted at `.workflow/.maestro/<session_id>/status.json` (same tracking
+location as maestro.md), enabling resume from any checkpoint via `-c`.
+</purpose>
+
+<context>
+$ARGUMENTS — template slug/path, or flags.
+
+**Flags:**
+- `--context key=value` — Bind context variables (repeatable)
+- `-c` / `--continue [session-id]` — Resume paused/interrupted session (consistent with maestro.md)
+- `--list` — List available templates from `~/.maestro/templates/workflows/index.json`
+- `--dry-run` — Show execution plan without executing
+
+**Entry routing:**
+
+| Detection | Condition | Handler |
+|-----------|-----------|---------|
+| List templates | `--list` in args | handleList |
+| Resume session | `-c [session-id]` | Phase 0: Resume |
+| Dry run | `--dry-run` in args | Phase 1 + 2, print plan, exit |
+| Normal | Template slug/path provided | Phase 1 |
+| No args | Empty args | handleList + AskUserQuestion |
+
+**Shared constants (aligned with maestro.md tracking):**
+
+| Constant | Value |
+|----------|-------|
+| Session prefix | `player` |
+| Session dir | `.workflow/.maestro/player-<YYYYMMDD>-<HHmmss>/` |
+| State file | `status.json` |
+| Template dir (global) | `~/.maestro/templates/workflows/` |
+| Template index (global) | `~/.maestro/templates/workflows/index.json` |
+
+**Session status.json schema (aligned with maestro.md):**
+
+```json
+{
+  "session_id": "player-<YYYYMMDD>-<HHmmss>",
+  "created_at": "<ISO>",
+  "intent": "<template_name> with context",
+  "task_type": "player",
+  "chain_name": "<template_id>",
+  "template_id": "wft-<slug>-<date>",
+  "template_path": "~/.maestro/templates/workflows/<slug>.json",
+  "template_name": "<name>",
+  "auto_mode": false,
+  "status": "running | paused | completed | failed | aborted",
+  "context": { "goal": "...", "scope": "..." },
+  "steps": [
+    {
+      "index": 0,
+      "node_id": "N-001",
+      "skill": "<executor>",
+      "args": "<resolved_args>",
+      "type": "skill | cli | command | agent | checkpoint",
+      "status": "pending | running | completed | skipped | failed",
+      "started_at": null,
+      "completed_at": null,
+      "session_id": null,
+      "output_path": null,
+      "artifacts": [],
+      "error": null
+    }
+  ],
+  "current_step": 0,
+  "last_checkpoint": null,
+  "updated_at": "<ISO>",
+  "completed_at": null
+}
+```
+
+**Session directory structure (under .workflow/.maestro/):**
+
+```
+.workflow/.maestro/player-<YYYYMMDD>-<HHmmss>/
+├── status.json             # Main state file (maestro.md compatible)
+├── checkpoints/
+│   ├── CP-01.json
+│   └── CP-02.json
+└── artifacts/
+    └── N-001-output.md
+```
+
+**Node execution mechanisms:**
+
+| Node type | Mechanism | Blocking |
+|-----------|-----------|----------|
+| skill | `Skill(skill=executor, args=resolved_args)` | sync |
+| command | `Skill(skill=executor, args=resolved_args)` | sync |
+| cli | `maestro delegate "prompt" --to tool --mode mode --rule rule` via `Bash(run_in_background: true)` | async, wait for callback |
+| agent | `Agent(subagent_type=executor, prompt=resolved_args)` | configurable |
+| checkpoint | State save + optional user pause | — |
+
+**Runtime reference resolution:**
+
+Before executing each node, resolve `{ref}` patterns in `args_template`:
+
+| Reference | Resolves To |
+|-----------|-------------|
+| `{variable}` | `session_state.context[variable]` |
+| `{N-001.session_id}` | `node_states["N-001"].session_id` |
+| `{N-001.output_path}` | `node_states["N-001"].output_path` |
+| `{prev_session_id}` | session_id of previous non-checkpoint node |
+| `{prev_output_path}` | output_path of previous non-checkpoint node |
+
+Fallback: if referenced field is null, substitution results in empty string.
+</context>
+
+<execution>
+
+### handleList
+
+Scan `~/.maestro/templates/workflows/index.json`. Display:
+```
+Available workflow templates:
+  feature-tdd-review    [feature, complex]   3 work nodes, 2 checkpoints
+  quick-bugfix          [bugfix, simple]     2 work nodes, 1 checkpoint
+
+Run: /maestro-player <slug> --context goal="..."
+```
+
+If index not found, output: "No templates found. Create one with /maestro-composer"
+
+---
+
+### Phase 0: Resume — Session Reconciliation
+
+**Trigger**: `-c [session-id]`
+
+1. If session-id provided: load `.workflow/.maestro/<session-id>/status.json`
+2. If no session-id: scan `.workflow/.maestro/player-*/status.json` for `status = "running" | "paused"`
+3. Multiple found → AskUserQuestion for selection
+4. None found → error E004
+5. Reset any `running` steps back to `pending` (interrupted mid-execution)
+6. Determine next executable step from `steps[]` after `last_checkpoint`
+7. Set `current_step` to resume point
+8. Resume at Phase 3 (Execute Loop) from that step
+
+---
+
+### Phase 1: Load & Bind
+
+**Objective**: Load template, collect missing variables, bind all references.
+
+**Step 1.1** — Resolve template path:
+1. Absolute path → use as-is
+2. Relative path (`.` prefix) → resolve from cwd
+3. Slug only → look up in `~/.maestro/templates/workflows/index.json`
+4. Partial match → scan index, confirm with user
+5. Not found → show available templates, AskUserQuestion
+
+**Step 1.2** — Parse `--context key=value` pairs into `bound_context`.
+
+**Step 1.3** — Load and validate template JSON (`template_id`, `nodes`, `edges`, `context_schema` must be present).
+
+**Step 1.4** — Collect missing required variables:
+- For each `context_schema` entry where `required: true` and not in `bound_context`:
+  AskUserQuestion to collect value
+- For optional variables: use `default` or empty string
+
+**Step 1.5** — Bind variables: replace `{variable_name}` with values in all `args_template` strings. Leave `{N-xxx.field}` and `{prev_*}` unresolved (runtime Phase 3).
+
+**Step 1.6** — If `--dry-run`: print execution plan and exit:
+```
+Workflow: <template.name>
+Context:  goal = "<value>"
+
+Execution Plan:
+  [1] N-001  [skill]       maestro-plan        "<goal>"
+  [2] CP-01  [checkpoint]  After Plan          auto-continue
+  [3] N-002  [skill]       maestro-execute     --resume-session {N-001.session_id}
+
+To execute: /maestro-player <slug> --context goal="..."
+```
+
+---
+
+### Phase 2: Instantiate — Init Session State
+
+**Objective**: Create session directory, init state, compute execution plan.
+
+**Step 2.1** — Generate session ID: `player-<YYYYMMDD>-<HHmmss>`. Create directory at `.workflow/.maestro/<session_id>/`.
+
+**Step 2.2** — Topological sort via Kahn's algorithm. Flatten nodes into `steps[]` array (maestro.md format). Parallel nodes get same batch index.
+
+**Step 2.3** — Init all steps as `status: "pending"`.
+
+**Step 2.4** — Write `status.json` (see schema in Context section).
+
+**Step 2.5** — Show execution start banner:
+```
+============================================================
+  MAESTRO PLAYER
+============================================================
+  Template: <template.name>
+  Session:  <session_id>
+  Context:  goal="<value>"
+
+  Pipeline:
+    1. N-001 [skill]      maestro-plan
+    2. CP-01 [checkpoint] After Plan
+    3. N-002 [skill]      maestro-execute
+============================================================
+```
+
+---
+
+### Phase 3: Execute Loop
+
+**Objective**: Execute each step in order. Save state after every step.
+
+**CRITICAL**: After each step status change, write `status.json` immediately. This enables resume on interruption.
+
+**For each step starting at `current_step`:**
+
+**3a. Display step banner** (consistent with maestro.md):
+```
+------------------------------------------------------------
+  STEP {i+1}/{total}: {node_id} [{type}] {executor}
+------------------------------------------------------------
+  Args: {resolved_args}
+```
+
+**3b. Update status.json**: Set step status = `"running"`, started_at = now.
+
+**3c. Execute by node type:**
+
+**skill / command node**:
+```
+resolved_args = resolveArgs(step.args_template, status)
+Skill(skill=step.skill, args=resolved_args)
+
+Extract from result: session_id (WFS-*), output_path, artifacts
+Update step: status="completed", session_id, output_path, artifacts, completed_at
+Write status.json
+```
+
+**cli node — CRITICAL: background + stop**:
+```
+resolved_args = resolveArgs(step.args_template, status)
+
+Bash({
+  command: `maestro delegate "${resolved_args}" --to ${step.cli_tool} --mode ${step.cli_mode} --rule ${step.cli_rule}`,
+  run_in_background: true
+})
+
+Write status.json  // persist "running" state
+STOP — wait for background callback
+```
+
+On callback:
+```
+Load status.json
+Find step with status "running"
+Retrieve output: maestro delegate output <exec_id>
+Update step: status="completed", output_path, completed_at
+Write status.json
+Advance to next step
+```
+
+**agent node**:
+```
+resolved_args = resolveArgs(step.args_template, status)
+
+Agent({
+  subagent_type: step.skill,
+  prompt: resolved_args,
+  run_in_background: step.run_in_background ?? false,
+  description: step.node_id
+})
+
+Update step: status="completed", output_path, completed_at
+Write status.json
+```
+
+**checkpoint node**:
+```
+// 1. Write checkpoint snapshot
+Write <session_dir>/checkpoints/<step.node_id>.json with:
+  session_id, checkpoint_id, saved_at, steps_snapshot, last_completed_step
+
+// 2. Update status.json
+status.last_checkpoint = step.node_id
+Mark step completed, write status.json
+
+// 3. If auto_continue == false: pause for user
+AskUserQuestion:
+  - Continue → proceed
+  - Pause → set status="paused", write status.json, output resume command, EXIT
+  - Abort → set status="aborted", EXIT
+```
+
+**3d. Handle result** (consistent with maestro.md):
+
+On success: update step status = `"completed"`, advance `current_step`.
+
+On failure:
+```
+on_fail = step.on_fail || "abort"
+
+skip   → mark "skipped", log warning, advance
+retry  → retry once, if still fails → fall to abort
+abort  → AskUserQuestion: Retry / Skip / Abort
+         On Abort: save progress, display: "Resume with: /maestro-player -c"
+```
+
+**3e. Context cleanup hint** (after step 3+, consistent with maestro.md):
+```
+  ⚡ 已执行 {i} 步，上下文较重。可随时 /maestro-player -c 在新上下文中恢复。
+```
+
+---
+
+### Phase 4: Complete — Archive + Summary
+
+**Objective**: Mark session complete, output summary.
+
+**Step 4.1** — Set `status = "completed"`, `completed_at = <ISO>`, write `status.json`.
+
+**Step 4.2** — Collect all artifacts from steps.
+
+**Step 4.3** — Display execution summary (consistent with maestro.md):
+```
+============================================================
+  MAESTRO PLAYER SESSION COMPLETE
+============================================================
+  Session:   <session_id>
+  Template:  <template_name> (<template_id>)
+  Steps:     <completed>/<total> completed
+  Context:   goal="<value>"
+
+  Results:
+    [✓] 1. N-001 maestro-plan         — completed (WFS-plan-xxx)
+    [✓] 2. CP-01 After Plan           — completed (checkpoint)
+    [✓] 3. N-002 maestro-execute      — completed (WFS-exec-xxx)
+    [✓] 4. N-003 quality-test    — completed (WFS-test-xxx)
+
+  Artifacts:
+    - IMPL_PLAN.md         (N-001)
+    - src/auth/index.ts    (N-002)
+    - test/auth.test.ts    (N-003)
+
+  Session dir: .workflow/.maestro/<session_id>/
+============================================================
+```
+
+**Step 4.4** — AskUserQuestion completion action:
+- **Keep session** → leave at current path
+- **Run again** → AskUserQuestion for same/new context, re-enter Phase 1
+- **Nothing** → done
+</execution>
+
+<error_codes>
+| Code | Severity | Description | Recovery |
+|------|----------|-------------|----------|
+| E001 | error | Template not found | Show --list output, suggest closest match |
+| E002 | error | Template JSON invalid (missing required fields) | Point to template file for fix |
+| E003 | error | Required context variable missing and user declined | Cannot proceed without required vars |
+| E004 | error | Resume session not found | Scan `.workflow/.maestro/player-*/`, list available |
+| E005 | error | DAG cycle in template | Point to template for fix, suggest maestro-composer --edit |
+| E006 | error | Node execution failed + abort chosen | Save state, suggest --resume |
+| W001 | warning | Node completed with warnings | Log and continue |
+| W002 | warning | Runtime reference resolved to empty string | Log, executor handles gracefully |
+</error_codes>
+
+<success_criteria>
+- [ ] Template loaded from `~/.maestro/templates/workflows/` and validated
+- [ ] All required context variables bound (from --context or user input)
+- [ ] Session directory created at `.workflow/.maestro/player-*/` with `status.json`
+- [ ] Steps array computed via topological sort (maestro.md compatible format)
+- [ ] Each step executed with correct mechanism (Skill/delegate/Agent)
+- [ ] Runtime references ({N-xxx.field}, {prev_*}) resolved before each step
+- [ ] `status.json` written after every step status change (resume-safe)
+- [ ] Checkpoints saved with snapshots under `checkpoints/`
+- [ ] CLI nodes use `maestro delegate` with `Bash(run_in_background: true)` + stop pattern
+- [ ] Step banners and completion report match maestro.md format
+- [ ] Resume via `-c` scans `.workflow/.maestro/player-*/status.json`
+</success_criteria>

package/.claude/commands/maestro-roadmap.md

@@ -59,15 +59,7 @@ Alternative heavy path (skip maestro-roadmap):
 maestro-init → maestro-spec-generate → spec package + roadmap.md
 ```
 
-**Dual modes:**
-| Mode | Strategy | Best For |
-|------|----------|----------|
-| Progressive | MVP → Usable → Refined (as **Milestones**, each with 1-2 phases) | High uncertainty, need validation |
-| Direct | Topological task sequence (1-2 phases, wave DAG handles ordering) | Clear requirements, confirmed tech |
-
-Auto-selection: ≥3 high uncertainty factors → Progressive, ≥3 low → Direct, else → ask user.
-
-**Minimum-phase principle:** Default 1 phase per milestone. Only split into 2 phases when hard dependency exists (runtime + not parallelizable + full barrier). Max 2 phases, exceptional 3 with justification.
+Dual modes (Progressive vs Direct), auto-selection criteria, and minimum-phase principle are defined in workflow roadmap.md (Steps 2-3).
 </context>
 
 <execution>
@@ -84,101 +76,11 @@ Follow '~/.maestro/workflows/roadmap.md' completely.
 
 ### Mode: Revise (`--revise [instructions]`)
 
-Revise an existing roadmap while preserving completed phase progress.
-
-**Pre-conditions:**
-- `.workflow/roadmap.md` exists
-- `.workflow/state.json` exists (for progress tracking)
-
-**Execution flow:**
-
-1. **Load current state**
-   - Read `.workflow/roadmap.md` — parse milestones, phases, dependencies, progress markers
-   - Read `.workflow/state.json` — get artifact registry, current milestone
-   - Identify completed vs in-progress vs pending phases
-
-2. **Obtain revision instructions**
-   - If `--revise "instructions text"` provided → use directly as change directive
-   - If `--revise` without instructions → use AskUserQuestion to ask user what to change
-     - Show current roadmap summary with phase statuses
-     - Present options: add/remove/reorder phases, modify scope/criteria/deps, move between milestones
-     - Capture change instructions from response
-
-3. **Impact analysis**
-   - For each proposed change, assess impact on:
-     - Phase dependency chain (re-validate no circular deps)
-     - Requirement coverage (every Active requirement still mapped)
-     - Completed phases (warn if change invalidates completed work)
-     - Existing plan artifacts (warn if plan exists for affected phase)
-   - Present impact summary for confirmation
-
-4. **Apply revisions**
-   - Update `.workflow/roadmap.md` preserving:
-     - Completed phase progress markers (✓, completion dates)
-     - Phase numbering for completed phases (renumber only pending phases)
-     - Cross-references from state.json artifacts
-   - Update `state.json` if milestone structure changed
-   - Add revision log entry to roadmap.md metadata section
-
-5. **Post-revision validation**
-   - Re-check dependency integrity (no circular deps)
-   - Re-check requirement coverage (every Active req mapped)
-   - Verify completed phases unaffected
-
-**Next-step routing on completion:**
-- Phases changed, need re-analysis → `/maestro-analyze {phase}`
-- Phases changed, ready to plan → `/maestro-plan {phase}`
-- Only pending phases adjusted → `/maestro-plan` (continue from where left off)
+Follow workflow roadmap.md "Mode: Revise" section for full algorithm (load state, obtain instructions, impact analysis, apply revisions, post-validation).
 
 ### Mode: Review (`--review`)
 
-Read-only health assessment of the current roadmap.
-
-**Pre-conditions:**
-- `.workflow/roadmap.md` exists
-
-**Execution flow:**
-
-1. **Load roadmap + execution history**
-   - Read `.workflow/roadmap.md` — full structure
-   - Read `.workflow/state.json` — artifact registry, milestone progress
-   - Cross-reference: for each phase, check ANL/PLN/EXC/VRF artifact status
-
-2. **Assessment dimensions**
-   - **Progress tracking**: Actual vs planned per phase, milestone velocity
-   - **Drift detection**: Completed phases deviating from original scope (via verify/audit findings)
-   - **Relevance check**: Pending phases still aligned with current project goals (from project.md)
-   - **Dependency health**: Pending phase dependencies still valid given completed work
-   - **Risk assessment**: Identify phases at risk (blocked, scope creep, dependency failures)
-
-3. **Produce review report**
-   - Write to `.workflow/scratch/{YYYYMMDD}-roadmap-review.md`
-   - Format:
-     ```
-     === ROADMAP REVIEW ===
-     Date: {date}
-     Milestone: {current}
-
-     Progress: {completed}/{total} phases ({percentage}%)
-     Drift: {none|minor|significant}
-     Risk: {low|medium|high}
-
-     Phase Assessment:
-       [✓] Phase 1: {name} — completed, on-scope
-       [~] Phase 2: {name} — in-progress, {status notes}
-       [ ] Phase 3: {name} — pending, {risk/notes}
-
-     Recommendations:
-       1. {actionable recommendation}
-       2. ...
-
-     Suggested actions:
-       /maestro-roadmap --revise   — Apply recommended changes
-       /maestro-plan {phase}       — Plan next phase
-       /manage-status              — View full dashboard
-     ```
-
-**No state modifications.** Pure assessment + recommendations.
+Follow workflow roadmap.md "Mode: Review" section for full algorithm (load state, assess dimensions, produce report).
 </execution>
 
 <error_codes>