maestro-flow 0.3.11 → 0.3.13

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

@@ -1,77 +1,85 @@
----
-name: maestro-merge
-description: Two-phase merge of milestone worktree branch back — git merge first, artifact sync only on success
-argument-hint: "-m <milestone-number> [--force] [--dry-run] [--no-cleanup] [--continue]"
-allowed-tools:
-  - Read
-  - Write
-  - Edit
-  - Bash
-  - Glob
-  - Grep
-  - Agent
-  - AskUserQuestion
----
-<purpose>
-Merge a completed milestone worktree branch back into the main branch, sync workflow artifacts for all phases, and reconcile project state. Uses a two-phase approach: git merge first (source code), artifact sync second (only after git succeeds). This prevents partial state corruption when merge conflicts occur.
-
-Includes registry health check, pre-merge rebase (pull main into worktree to minimize conflicts), and atomic state reconciliation (patch, don't overwrite).
-</purpose>
-
-<required_reading>
-@~/.maestro/workflows/merge.md
-</required_reading>
-
-<context>
-$ARGUMENTS -- milestone name and optional flags.
-
-**Flags:**
-- `-m <N>` or bare `<N>`: Milestone number (1-based, maps to registry)
-- `--force`: Merge even if not all phases are completed
-- `--dry-run`: Show what would be merged without executing
-- `--no-cleanup`: Keep worktree and branch after merge (for inspection)
-- `--continue`: Resume a merge that was paused due to git conflict
-
-**Merge sequence:**
-1. Registry health check (remove stale entries)
-2. Validate phase readiness across all owned phases
-3. Pre-merge rebase (`git merge main` in worktree)
-4. Phase 1: Git merge (source code only)
-5. Phase 2: Artifact sync (only after git merge succeeds)
-6. Atomic state reconciliation
-7. Cleanup (worktree remove + branch delete)
-
-**Conflict handling:**
-If git merge fails, the command saves state to `.workflow/.merge-state.json` and exits. User resolves conflicts, then runs `maestro-merge --continue` to resume artifact sync.
-</context>
-
-<execution>
-Follow '~/.maestro/workflows/merge.md' completely.
-
-**Next-step routing on completion:**
-- View dashboard → Skill({ skill: "manage-status" })
-- Audit milestone → Skill({ skill: "maestro-milestone-audit" })
-</execution>
-
-<error_codes>
-| Code | Severity | Condition | Recovery |
-|------|----------|-----------|----------|
-| E001 | error | Running inside a worktree | Run from main worktree |
-| E002 | error | No worktree registry found | Nothing to merge |
-| E003 | error | --continue but no merge state | Start fresh merge |
-| E004 | error | No milestone number provided | Provide `-m <N>` |
-| W001 | warning | Stale registry entries found | Auto-cleaned |
-| W002 | warning | Incomplete phases (without --force) | Confirm or use --force |
-| W003 | warning | Conflict pulling main into worktree | Resolve in worktree first |
-</error_codes>
-
-<success_criteria>
-- [ ] Registry health check passed (stale entries cleaned)
-- [ ] Pre-merge rebase successful (worktree has latest main)
-- [ ] Git merge completed without conflicts (or conflicts resolved via --continue)
-- [ ] All owned phase artifacts synced to main `.workflow/phases/`
-- [ ] `state.json` reconciled (phases_summary, accumulated_context, transition_history patched)
-- [ ] `roadmap.md` completed phases marked
-- [ ] Worktree removed and branch deleted (unless --no-cleanup)
-- [ ] Registry updated (entry removed)
-</success_criteria>
+---
+name: maestro-merge
+description: Two-phase merge of milestone worktree branch back — git merge first, scratch artifact sync only on success
+argument-hint: "-m <milestone-number> [--force] [--dry-run] [--no-cleanup] [--continue]"
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Bash
+  - Glob
+  - Grep
+  - Agent
+  - AskUserQuestion
+---
+<purpose>
+Merge a completed milestone worktree branch back into the main branch, sync scratch artifacts, and reconcile the artifact registry. Uses a two-phase approach: git merge first (source code), artifact sync second (only after git succeeds). This prevents partial state corruption when merge conflicts occur.
+
+Includes registry health check, pre-merge rebase (pull main into worktree to minimize conflicts), and atomic state reconciliation (merge artifact entries, don't overwrite).
+</purpose>
+
+<required_reading>
+@~/.maestro/workflows/merge.md
+</required_reading>
+
+<context>
+$ARGUMENTS -- milestone name and optional flags.
+
+**Flags:**
+- `-m <N>` or bare `<N>`: Milestone number (1-based, maps to registry)
+- `--force`: Merge even if milestone has incomplete artifacts
+- `--dry-run`: Show what would be merged without executing
+- `--no-cleanup`: Keep worktree and branch after merge (for inspection)
+- `--continue`: Resume a merge that was paused due to git conflict
+
+**Merge sequence:**
+1. Registry health check (remove stale worktree entries)
+2. Validate milestone artifact completeness (all EXC artifacts completed)
+3. Pre-merge rebase (`git merge main` in worktree)
+4. Phase 1: Git merge (source code only)
+5. Phase 2: Scratch artifact sync (only after git merge succeeds)
+6. Atomic artifact registry reconciliation
+7. Cleanup (worktree remove + branch delete)
+
+**Phase 2 — Artifact sync detail:**
+- Copy worktree `scratch/*` dirs back to main `.workflow/scratch/`
+- Merge worktree `state.json.artifacts[]` entries into main `state.json.artifacts[]`
+  - Dedup by artifact id; worktree version wins for same id
+- Update milestone status in main `state.json.milestones[]` (remove "forked" flag)
+- Mark `harvested` status from worktree artifacts
+
+**Conflict handling:**
+If git merge fails, the command saves state to `.workflow/.merge-state.json` and exits. User resolves conflicts, then runs `maestro-merge --continue` to resume artifact sync.
+</context>
+
+<execution>
+Follow '~/.maestro/workflows/merge.md' completely.
+
+**Next-step routing on completion:**
+- View dashboard → Skill({ skill: "manage-status" })
+- Audit milestone → Skill({ skill: "maestro-milestone-audit" })
+</execution>
+
+<error_codes>
+| Code | Severity | Condition | Recovery |
+|------|----------|-----------|----------|
+| E001 | error | Running inside a worktree | Run from main worktree |
+| E002 | error | No worktree registry found | Nothing to merge |
+| E003 | error | --continue but no merge state | Start fresh merge |
+| E004 | error | No milestone number provided | Provide `-m <N>` |
+| W001 | warning | Stale registry entries found | Auto-cleaned |
+| W002 | warning | Incomplete artifacts (without --force) | Confirm or use --force |
+| W003 | warning | Conflict pulling main into worktree | Resolve in worktree first |
+</error_codes>
+
+<success_criteria>
+- [ ] Registry health check passed (stale entries cleaned)
+- [ ] Pre-merge rebase successful (worktree has latest main)
+- [ ] Git merge completed without conflicts (or conflicts resolved via --continue)
+- [ ] All scratch artifacts synced to main `.workflow/scratch/`
+- [ ] `state.json.artifacts[]` reconciled (worktree entries merged into main)
+- [ ] Milestone `"forked"` flag removed in `state.json.milestones[]`
+- [ ] `roadmap.md` completed phases marked
+- [ ] Worktree removed and branch deleted (unless --no-cleanup)
+- [ ] `worktrees.json` registry updated (entry removed)
+</success_criteria>

package/.claude/commands/maestro-milestone-complete.md

@@ -42,6 +42,20 @@ Follow '~/.maestro/workflows/milestone-complete.md' completely.
 5. Update state.json: advance to next milestone, clear artifacts[]
 6. Clean scratch dirs
 
+### Knowledge Promotion Inquiry
+
+After learning extraction (step 4), scan `learnings.md` for promotion candidates:
+
+1. **High-frequency pattern detection**: Scan all `<spec-entry category="learning">` entries for keyword overlap (≥2 entries sharing keywords):
+   → Ask: "Keyword '{keyword}' appears in {N} learning entries. Should this be promoted to a formal coding convention? (`/spec-add coding`)"
+
+2. **Convention drift detection**: Compare executed task summaries against `coding-conventions.md` and `architecture-constraints.md`:
+   → Ask: "Were any established conventions bypassed during this milestone? Should conventions be updated?"
+
+3. **Wiki island check**: Auto-trigger `wiki-connect --fix` to link newly extracted knowledge.
+
+If user confirms promotion, invoke `Skill({ skill: "spec-add", args: "<category> <content>" })` with promoted content, preserving original date and source traceability.
+
 **Next-step routing on completion:**
 - Cut a release → `/maestro-milestone-release`
 - Next milestone → `/maestro-analyze` or `/maestro-plan 1`

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

@@ -1,7 +1,7 @@
 ---
 name: maestro-plan
 description: Explore, clarify, plan, check, and confirm a phase execution plan
-argument-hint: "[phase] [--collab] [--spec SPEC-xxx] [--auto] [--gaps] [--dir <path>]"
+argument-hint: "[phase] [--collab] [--spec SPEC-xxx] [--auto] [--gaps] [--dir <path>] [--revise [instructions]] [--check <plan-dir>]"
 allowed-tools:
   - Read
   - Write
@@ -13,9 +13,14 @@ allowed-tools:
   - AskUserQuestion
 ---
 <purpose>
-Create a verified execution plan (plan.json + .task/TASK-*.json) through a 5-stage pipeline: Exploration, Clarification, Planning, Plan Checking, and Confirmation. Produces plan.json with waves, task definitions, and user-confirmed execution strategy.
+Create, revise, or verify an execution plan through a 5-stage pipeline: Exploration, Clarification, Planning, Plan Checking, and Confirmation. Produces plan.json with waves, task definitions, and user-confirmed execution strategy.
 
-All plan output goes to `.workflow/scratch/plan-{slug}-{date}/`. Registers PLN artifact in state.json. Performs collision detection against other plans in same milestone.
+Supports three modes:
+- **Create** (default): Build plan from analysis context or phase requirements
+- **Revise** (`--revise`): Incrementally modify existing plan — edit tasks, adjust waves, add/remove tasks
+- **Check** (`--check`): Standalone plan verification — run plan-checker against existing plan
+
+All plan output goes to `.workflow/scratch/{YYYYMMDD}-plan-[P{N}-|M{N}-]{slug}/`. Date-first ordering enables chronological sorting. Scope prefix in directory name (`P{N}` for phase, `M{N}` for milestone, omit for adhoc/standalone) enables fallback identification. Registers PLN artifact in state.json. Performs collision detection against other plans in same milestone.
 </purpose>
 
 <required_reading>
@@ -37,6 +42,8 @@ $ARGUMENTS — phase number, or no args for milestone-wide planning, with option
 - `--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:**
 
@@ -45,16 +52,25 @@ $ARGUMENTS — phase number, or no args for milestone-wide planning, with option
 | `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) |
 
 **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**: `scratch/plan-{slug}-{date}/` (relative to `.workflow/`)
+**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:**
 ```
-scratch/plan-{slug}-{date}/
+{YYYYMMDD}-plan-P{N}-{slug}/
 ├── plan.json            # summary, task_ids[], waves[] with phase labels
 └── .task/
     ├── TASK-001.json    # { phase: 1, phase_slug: "auth", ... }
@@ -72,7 +88,7 @@ scratch/plan-{slug}-{date}/
   "milestone": "{current_milestone or null}",
   "phase": "{phase_number or null}",
   "scope": "{milestone|phase|adhoc|standalone}",
-  "path": "scratch/plan-{slug}-{date}",
+  "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,
@@ -133,14 +149,88 @@ Tasks: {task_count} tasks in {wave_count} waves
 Check: {checker_status} (iteration {check_count}/{max_checks})
 Collision: {collision_status}
 
-Plan: {scratch_dir}/plan.json
-Tasks: {scratch_dir}/.task/TASK-*.json
+Plan: scratch/{YYYYMMDD}-plan-P{N}-{slug}/plan.json
+Tasks: scratch/{YYYYMMDD}-plan-P{N}-{slug}/.task/TASK-*.json
 
 Next steps:
   /maestro-execute              -- Execute the plan
   /maestro-execute --dir {dir}  -- Execute specific plan
   /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
+   ```
+
+**No file modifications.** Pure verification + report.
 </execution>
 
 <error_codes>
@@ -148,6 +238,8 @@ Next steps:
 |------|----------|-----------|----------|
 | E001 | error | No args and no roadmap (cannot determine scope) | Provide phase number or topic, or create roadmap |
 | E003 | error | --gaps requires prior verification/issues to exist | Run maestro-verify first |
+| E004 | error | No plan found to revise (--revise without target) | Use --dir to specify plan, or create plan first |
+| E005 | error | Plan directory not found (--check) | Check path, use --dir |
 | W001 | warning | Exploration agent returned incomplete results | Retry exploration or proceed with available context |
 | W002 | warning | Plan-checker found minor issues, continuing | Review plan-checker feedback, adjust plan if needed |
 | W003 | warning | Wiki search unavailable or returned no results | Continue without prior knowledge context |

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

@@ -1,7 +1,7 @@
 ---
 name: maestro-roadmap
 description: Interactive roadmap creation with iterative refinement — lightweight alternative to spec-generate
-argument-hint: "<requirement> [-y] [-c] [-m progressive|direct|auto] [--from-brainstorm SESSION-ID]"
+argument-hint: "<requirement> [-y] [-c] [-m progressive|direct|auto] [--from-brainstorm SESSION-ID] [--revise [instructions]] [--review]"
 allowed-tools:
   - Read
   - Write
@@ -13,7 +13,12 @@ allowed-tools:
   - AskUserQuestion
 ---
 <purpose>
-Create a project roadmap through interactive requirement decomposition and iterative refinement. This is the lightweight path for structured decomposition — directly from requirements to roadmap without full specification documents. For the heavy path with formal specs, use maestro-spec-generate instead.
+Create or revise a project roadmap through interactive requirement decomposition and iterative refinement. This is the lightweight path for structured decomposition — directly from requirements to roadmap without full specification documents. For the heavy path with formal specs, use maestro-spec-generate instead.
+
+Supports three modes:
+- **Create** (default): Build roadmap from requirements
+- **Revise** (`--revise`): Modify existing roadmap while preserving completed phase progress
+- **Review** (`--review`): Health assessment of current roadmap — actual vs planned, drift detection, adjustment recommendations (read-only)
 
 Produces `.workflow/roadmap.md` with milestone/phase structure ready for maestro-plan.
 </purpose>
@@ -31,11 +36,14 @@ $ARGUMENTS -- requirement text, @file reference, or brainstorm session reference
 - `-c` / `--continue`: Resume from last checkpoint
 - `-m progressive|direct|auto`: Decomposition strategy (default: auto)
 - `--from-brainstorm SESSION-ID`: Import guidance-specification.md from a brainstorm session as seed
+- `--revise [instructions]`: Revise existing roadmap. If instructions provided, apply directly (e.g. `--revise "add phase 4 for perf optimization"` or `--revise "split phase 2 into 2a and 2b"`). If omitted, ask user for revision instructions via AskUserQuestion. Preserves completed phase progress.
+- `--review`: Roadmap health assessment — compare actual vs planned progress, detect drift, assess remaining phases (read-only, produces review report)
 
 **Input types:**
 - Direct text: `"Implement user authentication system with OAuth and 2FA"`
 - File reference: `@requirements.md`
 - Brainstorm import: `--from-brainstorm WFS-xxx`
+- No args + `--revise` / `--review`: Operate on existing `.workflow/roadmap.md`
 
 **Relationship to pipeline:**
 ```
@@ -63,6 +71,9 @@ Auto-selection: ≥3 high uncertainty factors → Progressive, ≥3 low → Dire
 </context>
 
 <execution>
+
+### Mode: Create (default)
+
 Follow '~/.maestro/workflows/roadmap.md' completely.
 
 **Next-step routing on completion:**
@@ -70,6 +81,104 @@ Follow '~/.maestro/workflows/roadmap.md' completely.
 - Simple project, skip analysis → /maestro-plan 1
 - Need UI design first → /maestro-ui-design 1
 - View project dashboard → /manage-status
+
+### 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)
+
+### 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.
 </execution>
 
 <error_codes>
@@ -78,6 +187,8 @@ Follow '~/.maestro/workflows/roadmap.md' completely.
 | E001 | error | Requirement text or @file required | Prompt user for input |
 | E002 | error | Brainstorm session not found (--from-brainstorm) | Show available sessions |
 | E003 | error | Circular dependency detected in phases | Prompt user to re-decompose |
+| E004 | error | roadmap.md not found (--revise/--review) | Run maestro-roadmap first |
+| E005 | error | Revision invalidates completed phase work | Warn user, ask to confirm or adjust |
 | W001 | warning | CLI analysis failed, using fallback | Continue with available data |
 | W002 | warning | Max refinement rounds (5) reached | Force proceed with current roadmap |
 | W005 | warning | External research agent failed | Continue without apiResearchContext |

package/.claude/commands/maestro-ui-design.md

@@ -49,7 +49,7 @@ $ARGUMENTS — phase number for phase mode, topic text for scratch mode, with op
 - Flags `--layouts N` and `--refine` are only effective with `ui-design.md` (full pipeline)
 
 **Phase mode** (number): resolves phase directory, reads context.md/brainstorm for requirements.
-**Scratch mode** (text): creates `.workflow/scratch/ui-design-{slug}-{date}/` for standalone exploration.
+**Scratch mode** (text): creates `.workflow/scratch/{YYYYMMDD}-ui-design-{slug}/` for standalone exploration.
 
 **Output artifacts (in phase or scratch directory):**
 | Artifact | Description |
@@ -101,12 +101,12 @@ Stack:   {stack}
 Matrix:  {S x L x T} = {total} prototypes
 
 Design System:
-  MASTER.md:        {phase_dir}/design-ref/MASTER.md
-  Tokens:           {phase_dir}/design-ref/design-tokens.json
-  Animation:        {phase_dir}/design-ref/animation-tokens.json
-  Layout Templates: {phase_dir}/design-ref/layout-templates/
-  Prototypes:       {phase_dir}/design-ref/prototypes/
-  Compare:          {phase_dir}/design-ref/prototypes/compare.html
+  MASTER.md:        {scratch_dir}/design-ref/MASTER.md
+  Tokens:           {scratch_dir}/design-ref/design-tokens.json
+  Animation:        {scratch_dir}/design-ref/animation-tokens.json
+  Layout Templates: {scratch_dir}/design-ref/layout-templates/
+  Prototypes:       {scratch_dir}/design-ref/prototypes/
+  Compare:          {scratch_dir}/design-ref/prototypes/compare.html
 
 Next steps:
   /maestro-plan {phase}              -- Plan with design reference