maestro-flow 0.3.18 → 0.3.20

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

@@ -1,114 +1,114 @@
----
-name: maestro-execute
-description: Execute plan with wave-based parallel execution and atomic commits
-argument-hint: "[phase] [--auto-commit] [--method agent|codex|gemini|cli|auto] [--executor <tool>] [--dir <path>] [-y]"
-allowed-tools:
-  - Read
-  - Write
-  - Edit
-  - Bash
-  - Glob
-  - Grep
-  - Agent
-  - AskUserQuestion
----
-<purpose>
-Execute all tasks in a plan using wave-based parallel execution with dependency-aware ordering. Each plan is executed independently (plans串行, plan内wave并行). Task summaries are written to the plan's scratch directory under `.summaries/`. Registers EXC artifact in state.json.
-
-Invoked after /maestro-plan produces a confirmed plan. When called without args on a milestone, finds all pending plans and executes them sequentially.
-</purpose>
-
-<required_reading>
-@~/.maestro/workflows/execute.md
-</required_reading>
-
-<deferred_reading>
-- [task.json](~/.maestro/templates/task.json) — read when reading task definitions
-- [state.json](~/.maestro/templates/state.json) — read when registering artifact
-</deferred_reading>
-
-<context>
-$ARGUMENTS — phase number, or no args for milestone-wide execution, with optional flags.
-
-Scope routing, flags, resolution logic, output directory format, artifact registration schema, and incremental learning extraction are defined in workflow `execute.md`.
-</context>
-
-<execution>
-### Pre-flight: team conflict check
-
-Before any task execution, run:
-```
-Bash("maestro collab preflight --phase <phase-number>")
-```
-If exit code is 1, present warnings and ask whether to proceed.
-
-Follow '~/.maestro/workflows/execute.md' completely.
-
-### Post-task Knowledge Inquiry
-
-After each task completes, evaluate inquiry triggers:
-
-1. **Execution deviation**: If task summary mentions approach change, dependency swap, or plan deviation:
-   → Ask: "TASK-{NNN} deviated from the plan. Should this decision be recorded as an architecture constraint? (`/spec-add arch`)"
-
-2. **Retry success**: If task required ≥2 retries before completion:
-   → Ask: "TASK-{NNN} succeeded after {N} retries. Should this fix pattern be documented? (`/spec-add debug`)"
-
-3. **Implicit knowledge**: If task summary contains design rationale ("chose X because", "rejected Y due to"):
-   → Ask: "Design decision detected. Should it be recorded as a learning? (`/spec-add learning`)"
-
-If user confirms, invoke `Skill({ skill: "spec-add", args: "<category> <content>" })` with extracted content.
-
-### Issue Status Sync
-
-On each task completion, if `task.issue_id` exists, sync status back to the issue in `.workflow/issues/issues.jsonl`:
-
-```
-For each completed/failed TASK with issue_id:
-  Read issue from issues.jsonl by issue_id
-  Collect all task_refs[] statuses for that issue:
-    all task_refs completed → issue.status = "resolved"
-    any task_ref failed    → issue.status = "in_progress"
-  Append history entry: { action: "executed", at: <ISO>, by: "maestro-execute", summary: "TASK-{NNN} {status}" }
-  Write updated issue back to issues.jsonl
-```
-
-**Report format on completion:**
-
-```
-=== EXECUTION COMPLETE ===
-Plans executed: {plans_count}
-Completed: {completed_count}/{total_count} tasks
-Failed:    {failed_count} tasks
-
-Summaries: {plan_dir}/.summaries/
-Tasks:     {plan_dir}/.task/
-
-Next steps:
-  /maestro-verify              -- Verify execution results
-  /maestro-verify --dir {dir}  -- Verify specific plan
-  /manage-status               -- View project dashboard
-```
-
-If failed tasks exist, suggest /quality-debug for investigation.
-</execution>
-
-<error_codes>
-| Code | Severity | Condition | Recovery |
-|------|----------|-----------|----------|
-| E001 | error | No pending plans found | Verify plans exist, run maestro-plan first |
-| E002 | error | Plan directory not found | Check --dir path |
-| E003 | error | plan.json not found in directory | Verify plan.json exists, run maestro-plan first |
-| E004 | error | No pending tasks, all tasks already completed | Check task statuses, reset if needed |
-| W001 | warning | Executor completed with partial failures | Check task dependencies, retry failed wave |
-</error_codes>
-
-<success_criteria>
-- [ ] All pending plans identified and executed sequentially
-- [ ] Within each plan: waves executed in parallel, waves串行
-- [ ] `.summaries/TASK-{NNN}-summary.md` written for each completed task
-- [ ] `.task/TASK-{NNN}.json` statuses updated (completed|blocked)
-- [ ] EXC artifact registered in state.json for each plan executed
-- [ ] Incremental learnings extracted to specs/learnings.md
-- [ ] state.json updated with execution progress
-</success_criteria>
+---
+name: maestro-execute
+description: Execute plan with wave-based parallel execution and atomic commits
+argument-hint: "[phase] [--auto-commit] [--method agent|codex|gemini|cli|auto] [--executor <tool>] [--dir <path>] [-y]"
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Bash
+  - Glob
+  - Grep
+  - Agent
+  - AskUserQuestion
+---
+<purpose>
+Execute all tasks in a plan using wave-based parallel execution with dependency-aware ordering. Each plan is executed independently (plans串行, plan内wave并行). Task summaries are written to the plan's scratch directory under `.summaries/`. Registers EXC artifact in state.json.
+
+Invoked after /maestro-plan produces a confirmed plan. When called without args on a milestone, finds all pending plans and executes them sequentially.
+</purpose>
+
+<required_reading>
+@~/.maestro/workflows/execute.md
+</required_reading>
+
+<deferred_reading>
+- [task.json](~/.maestro/templates/task.json) — read when reading task definitions
+- [state.json](~/.maestro/templates/state.json) — read when registering artifact
+</deferred_reading>
+
+<context>
+$ARGUMENTS — phase number, or no args for milestone-wide execution, with optional flags.
+
+Scope routing, flags, resolution logic, output directory format, artifact registration schema, and incremental learning extraction are defined in workflow `execute.md`.
+</context>
+
+<execution>
+### Pre-flight: team conflict check
+
+Before any task execution, run:
+```
+Bash("maestro collab preflight --phase <phase-number>")
+```
+If exit code is 1, present warnings and ask whether to proceed.
+
+Follow '~/.maestro/workflows/execute.md' completely.
+
+### Post-task Knowledge Inquiry
+
+After each task completes, evaluate inquiry triggers:
+
+1. **Execution deviation**: If task summary mentions approach change, dependency swap, or plan deviation:
+   → Ask: "TASK-{NNN} deviated from the plan. Should this decision be recorded as an architecture constraint? (`/spec-add arch`)"
+
+2. **Retry success**: If task required ≥2 retries before completion:
+   → Ask: "TASK-{NNN} succeeded after {N} retries. Should this fix pattern be documented? (`/spec-add debug`)"
+
+3. **Implicit knowledge**: If task summary contains design rationale ("chose X because", "rejected Y due to"):
+   → Ask: "Design decision detected. Should it be recorded as a learning? (`/spec-add learning`)"
+
+If user confirms, invoke `Skill({ skill: "spec-add", args: "<category> <content>" })` with extracted content.
+
+### Issue Status Sync
+
+On each task completion, if `task.issue_id` exists, sync status back to the issue in `.workflow/issues/issues.jsonl`:
+
+```
+For each completed/failed TASK with issue_id:
+  Read issue from issues.jsonl by issue_id
+  Collect all task_refs[] statuses for that issue:
+    all task_refs completed → issue.status = "resolved"
+    any task_ref failed    → issue.status = "in_progress"
+  Append history entry: { action: "executed", at: <ISO>, by: "maestro-execute", summary: "TASK-{NNN} {status}" }
+  Write updated issue back to issues.jsonl
+```
+
+**Report format on completion:**
+
+```
+=== EXECUTION COMPLETE ===
+Plans executed: {plans_count}
+Completed: {completed_count}/{total_count} tasks
+Failed:    {failed_count} tasks
+
+Summaries: {plan_dir}/.summaries/
+Tasks:     {plan_dir}/.task/
+
+Next steps:
+  /maestro-verify              -- Verify execution results
+  /maestro-verify --dir {dir}  -- Verify specific plan
+  /manage-status               -- View project dashboard
+```
+
+If failed tasks exist, suggest /quality-debug for investigation.
+</execution>
+
+<error_codes>
+| Code | Severity | Condition | Recovery |
+|------|----------|-----------|----------|
+| E001 | error | No pending plans found | Verify plans exist, run maestro-plan first |
+| E002 | error | Plan directory not found | Check --dir path |
+| E003 | error | plan.json not found in directory | Verify plan.json exists, run maestro-plan first |
+| E004 | error | No pending tasks, all tasks already completed | Check task statuses, reset if needed |
+| W001 | warning | Executor completed with partial failures | Check task dependencies, retry failed wave |
+</error_codes>
+
+<success_criteria>
+- [ ] All pending plans identified and executed sequentially
+- [ ] Within each plan: waves executed in parallel, waves串行
+- [ ] `.summaries/TASK-{NNN}-summary.md` written for each completed task
+- [ ] `.task/TASK-{NNN}.json` statuses updated (completed|blocked)
+- [ ] EXC artifact registered in state.json for each plan executed
+- [ ] Incremental learnings extracted to specs/learnings.md
+- [ ] state.json updated with execution progress
+</success_criteria>

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

@@ -1,140 +1,140 @@
----
-name: maestro-learn
-description: Learning coordinator — route intent to learn commands, execute single or multi-step chains
-argument-hint: "\"intent text\" [-y] [--dry-run] [--chain <name>]"
-allowed-tools:
-  - Read
-  - Write
-  - Bash
-  - Glob
-  - Grep
-  - Agent
-  - AskUserQuestion
----
-<purpose>
-Route learning requests to the optimal learn command or multi-step chain. Supports direct chain selection via `--chain` or intent-based routing via keyword matching.
-
-Executes commands sequentially via Skill() with session tracking.
-</purpose>
-
-<context>
-$ARGUMENTS — user learning intent text, or flags.
-
-**Flags:**
-- `-y` / `--yes` — Auto mode: skip confirmation
-- `--dry-run` — Show planned chain without executing
-- `--chain <name>` — Force a specific chain (bypass intent detection)
-
-**Available learn commands:**
-| Command | Purpose |
-|---------|---------|
-| `learn-follow` | Guided reading with forcing questions, pattern extraction |
-| `learn-investigate` | Hypothesis-driven question investigation |
-| `learn-decompose` | 4-dimension parallel pattern extraction |
-| `learn-second-opinion` | Multi-perspective review/challenge/consult |
-| `learn-retro` | Unified retrospective (git metrics + decision evaluation) |
-
-**Available chains:**
-| Chain | Steps | Use when |
-|-------|-------|----------|
-| `follow` | learn-follow | Read/understand code or docs |
-| `investigate` | learn-investigate | Answer a "how/why" question |
-| `decompose` | learn-decompose | Catalog patterns in a module |
-| `second-opinion` | learn-second-opinion | Get review/challenge on code |
-| `retro` | learn-retro --lens all | Full retrospective (git + decisions) |
-| `deep-understand` | follow → decompose → second-opinion | Thorough module analysis |
-| `pattern-catalog` | decompose --save-spec --save-wiki → second-opinion --mode review | Full pattern extraction + review |
-
-**Storage:**
-- `.workflow/learning/.maestro-learn/{session_id}/status.json` — Session tracking
-- All learn command outputs go to `.workflow/learning/`
-</context>
-
-<execution>
-
-### Step 1: Parse & Route
-
-Parse flags (`-y`, `--dry-run`, `--chain`). Extract intent text.
-
-**If `--chain` specified:** validate against known chains, jump to Step 2.
-
-**Intent routing table** (match first token or keywords):
-
-| Keywords | Route |
-|----------|-------|
-| File path (contains `/` or `\`) | `follow` |
-| Wiki ID (`type-slug` pattern) | `follow` |
-| read, follow, walk through, understand, 阅读, 跟读 | `follow` |
-| why, how, what if, investigate, 为什么, 怎么 | `investigate` |
-| pattern, decompose, catalog, 分解, 模式 | `decompose` |
-| opinion, review, challenge, consult, 评审, 挑战 | `second-opinion` |
-| retro, git, commit, decision, 回顾 | `retro` |
-| thorough, deep, 全面, 深入 | `deep-understand` |
-
-**If no match:** present menu via AskUserQuestion:
-```
-What would you like to do?
-1. Read through code/docs → follow
-2. Investigate a question → investigate
-3. Find patterns in code → decompose
-4. Get a second opinion → second-opinion
-5. Retrospective → retro
-```
-
-Max 1 clarification round. If still unclear: error.
-
-### Step 2: Resolve Target & Build Args
-
-- File path → pass directly
-- Wiki ID → pass directly
-- Topic string → pass as quoted argument
-- Extract any flags (--depth, --days, --lens, --mode, --scope, etc.)
-
-**Chain → command mapping:**
-```
-follow          → Skill("learn-follow", "{target} {flags}")
-investigate     → Skill("learn-investigate", "\"{target}\" {flags}")
-decompose       → Skill("learn-decompose", "{target} {flags}")
-second-opinion  → Skill("learn-second-opinion", "{target} {flags}")
-retro           → Skill("learn-retro", "{flags}")
-deep-understand → [learn-follow --depth deep, learn-decompose --save-spec, learn-second-opinion --mode challenge]
-pattern-catalog → [learn-decompose --save-spec --save-wiki, learn-second-opinion --mode review]
-```
-
-### Step 3: Confirm & Execute
-
-**If `--dry-run`:** display chain plan and exit.
-
-**If not `-y`:** show plan, ask for confirmation.
-
-**Execute:**
-1. Create session dir: `.workflow/learning/.maestro-learn/learn-{timestamp}/`
-2. Write `status.json` with chain steps
-3. Execute each step via `Skill()`:
-   - On success: mark completed, continue
-   - On failure (interactive): ask retry/skip/abort
-   - On failure (auto): skip and continue
-4. Display session summary with artifact list and next-step suggestion
-
-</execution>
-
-<error_codes>
-| Code | Severity | Description | Recovery |
-|------|----------|-------------|----------|
-| E001 | error | No intent provided | Provide a learning goal or use --chain |
-| E002 | error | Cannot determine intent after clarification | Rephrase or use --chain directly |
-| E003 | error | Chain step failed + user chose abort | Partial progress saved in status.json |
-| E005 | error | Invalid --chain name | Show valid chains |
-| W001 | warning | Intent ambiguous between commands | Present options |
-| W002 | warning | Chain step completed with warnings | Log and continue |
-</error_codes>
-
-<success_criteria>
-- [ ] Intent routed to correct chain (or --chain validated)
-- [ ] Target resolved and arguments assembled
-- [ ] Session directory created with status.json
-- [ ] All chain steps executed via Skill()
-- [ ] Error handling: retry/skip/abort per step
-- [ ] Session summary displayed with next-step routing
-- [ ] No files modified outside `.workflow/learning/`
-</success_criteria>
+---
+name: maestro-learn
+description: Learning coordinator — route intent to learn commands, execute single or multi-step chains
+argument-hint: "\"intent text\" [-y] [--dry-run] [--chain <name>]"
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+  - Glob
+  - Grep
+  - Agent
+  - AskUserQuestion
+---
+<purpose>
+Route learning requests to the optimal learn command or multi-step chain. Supports direct chain selection via `--chain` or intent-based routing via keyword matching.
+
+Executes commands sequentially via Skill() with session tracking.
+</purpose>
+
+<context>
+$ARGUMENTS — user learning intent text, or flags.
+
+**Flags:**
+- `-y` / `--yes` — Auto mode: skip confirmation
+- `--dry-run` — Show planned chain without executing
+- `--chain <name>` — Force a specific chain (bypass intent detection)
+
+**Available learn commands:**
+| Command | Purpose |
+|---------|---------|
+| `learn-follow` | Guided reading with forcing questions, pattern extraction |
+| `learn-investigate` | Hypothesis-driven question investigation |
+| `learn-decompose` | 4-dimension parallel pattern extraction |
+| `learn-second-opinion` | Multi-perspective review/challenge/consult |
+| `learn-retro` | Unified retrospective (git metrics + decision evaluation) |
+
+**Available chains:**
+| Chain | Steps | Use when |
+|-------|-------|----------|
+| `follow` | learn-follow | Read/understand code or docs |
+| `investigate` | learn-investigate | Answer a "how/why" question |
+| `decompose` | learn-decompose | Catalog patterns in a module |
+| `second-opinion` | learn-second-opinion | Get review/challenge on code |
+| `retro` | learn-retro --lens all | Full retrospective (git + decisions) |
+| `deep-understand` | follow → decompose → second-opinion | Thorough module analysis |
+| `pattern-catalog` | decompose --save-spec --save-wiki → second-opinion --mode review | Full pattern extraction + review |
+
+**Storage:**
+- `.workflow/learning/.maestro-learn/{session_id}/status.json` — Session tracking
+- All learn command outputs go to `.workflow/learning/`
+</context>
+
+<execution>
+
+### Step 1: Parse & Route
+
+Parse flags (`-y`, `--dry-run`, `--chain`). Extract intent text.
+
+**If `--chain` specified:** validate against known chains, jump to Step 2.
+
+**Intent routing table** (match first token or keywords):
+
+| Keywords | Route |
+|----------|-------|
+| File path (contains `/` or `\`) | `follow` |
+| Wiki ID (`type-slug` pattern) | `follow` |
+| read, follow, walk through, understand, 阅读, 跟读 | `follow` |
+| why, how, what if, investigate, 为什么, 怎么 | `investigate` |
+| pattern, decompose, catalog, 分解, 模式 | `decompose` |
+| opinion, review, challenge, consult, 评审, 挑战 | `second-opinion` |
+| retro, git, commit, decision, 回顾 | `retro` |
+| thorough, deep, 全面, 深入 | `deep-understand` |
+
+**If no match:** present menu via AskUserQuestion:
+```
+What would you like to do?
+1. Read through code/docs → follow
+2. Investigate a question → investigate
+3. Find patterns in code → decompose
+4. Get a second opinion → second-opinion
+5. Retrospective → retro
+```
+
+Max 1 clarification round. If still unclear: error.
+
+### Step 2: Resolve Target & Build Args
+
+- File path → pass directly
+- Wiki ID → pass directly
+- Topic string → pass as quoted argument
+- Extract any flags (--depth, --days, --lens, --mode, --scope, etc.)
+
+**Chain → command mapping:**
+```
+follow          → Skill("learn-follow", "{target} {flags}")
+investigate     → Skill("learn-investigate", "\"{target}\" {flags}")
+decompose       → Skill("learn-decompose", "{target} {flags}")
+second-opinion  → Skill("learn-second-opinion", "{target} {flags}")
+retro           → Skill("learn-retro", "{flags}")
+deep-understand → [learn-follow --depth deep, learn-decompose --save-spec, learn-second-opinion --mode challenge]
+pattern-catalog → [learn-decompose --save-spec --save-wiki, learn-second-opinion --mode review]
+```
+
+### Step 3: Confirm & Execute
+
+**If `--dry-run`:** display chain plan and exit.
+
+**If not `-y`:** show plan, ask for confirmation.
+
+**Execute:**
+1. Create session dir: `.workflow/learning/.maestro-learn/learn-{timestamp}/`
+2. Write `status.json` with chain steps
+3. Execute each step via `Skill()`:
+   - On success: mark completed, continue
+   - On failure (interactive): ask retry/skip/abort
+   - On failure (auto): skip and continue
+4. Display session summary with artifact list and next-step suggestion
+
+</execution>
+
+<error_codes>
+| Code | Severity | Description | Recovery |
+|------|----------|-------------|----------|
+| E001 | error | No intent provided | Provide a learning goal or use --chain |
+| E002 | error | Cannot determine intent after clarification | Rephrase or use --chain directly |
+| E003 | error | Chain step failed + user chose abort | Partial progress saved in status.json |
+| E005 | error | Invalid --chain name | Show valid chains |
+| W001 | warning | Intent ambiguous between commands | Present options |
+| W002 | warning | Chain step completed with warnings | Log and continue |
+</error_codes>
+
+<success_criteria>
+- [ ] Intent routed to correct chain (or --chain validated)
+- [ ] Target resolved and arguments assembled
+- [ ] Session directory created with status.json
+- [ ] All chain steps executed via Skill()
+- [ ] Error handling: retry/skip/abort per step
+- [ ] Session summary displayed with next-step routing
+- [ ] No files modified outside `.workflow/learning/`
+</success_criteria>

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

@@ -1,68 +1,68 @@
----
-name: maestro-milestone-audit
-description: Audit current milestone for cross-phase integration gaps
-argument-hint: "[<milestone>]"
-allowed-tools:
-  - Read
-  - Write
-  - Bash
-  - Glob
-  - Grep
-  - Agent
-  - AskUserQuestion
----
-
-<purpose>
-Audit milestone completion using the artifact registry. Checks:
-1. Phase coverage — every phase in roadmap has plan + execute artifacts (completed)
-2. Ad-hoc completeness — all adhoc artifacts are completed (or explicitly skipped)
-3. Execution completeness — all tasks in executed plans are completed
-4. Cross-artifact integration — interfaces, data contracts, configuration consistency
-
-Data source: `state.json.artifacts[]` filtered by current milestone.
-Produces audit report at `.workflow/milestones/{milestone}/audit-report.md`.
-</purpose>
-
-<required_reading>
-@~/.maestro/workflows/milestone-audit.md
-</required_reading>
-
-<context>
-Milestone: $ARGUMENTS (optional -- defaults to current_milestone from state.json).
-
-**Requires:** All phases in the milestone should have completed execute artifacts.
-
-**Data source:**
-- `.workflow/state.json` — artifacts[], current_milestone, milestones[]
-- `.workflow/roadmap.md` — milestone-to-phase mapping
-- Plan scratch dirs — for task status verification
-</context>
-
-<execution>
-Follow '~/.maestro/workflows/milestone-audit.md' completely.
-
-Audit checklist steps (phase coverage, ad-hoc completeness, execution completeness, cross-artifact integration) are defined in workflow `milestone-audit.md`.
-
-**Next-step routing on completion:**
-- Verdict PASS → `/maestro-milestone-complete {milestone}`
-- Verdict FAIL, integration gaps → `/maestro-plan --gaps`
-- Verdict FAIL, incomplete execution → `/maestro-execute`
-</execution>
-
-<error_codes>
-| Code | Severity | Condition | Recovery |
-|------|----------|-----------|----------|
-| E001 | error | Milestone identifier required | Check arguments format |
-| E002 | error | Milestone not found in state.json | Check milestone ID |
-| E003 | error | No execute artifacts found for milestone | Run maestro-execute first |
-| W001 | warning | Some phases lack complete artifact chains | Review incomplete phases |
-</error_codes>
-
-<success_criteria>
-- [ ] All phases in milestone identified from roadmap
-- [ ] Artifact chains verified (ANL→PLN→EXC) per phase
-- [ ] Ad-hoc artifacts checked for completion
-- [ ] Integration check completed (shared interfaces, data contracts)
-- [ ] Audit report written with clear PASS/FAIL verdict
-- [ ] Next-step routing provided
-</success_criteria>
+---
+name: maestro-milestone-audit
+description: Audit current milestone for cross-phase integration gaps
+argument-hint: "[<milestone>]"
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+  - Glob
+  - Grep
+  - Agent
+  - AskUserQuestion
+---
+
+<purpose>
+Audit milestone completion using the artifact registry. Checks:
+1. Phase coverage — every phase in roadmap has plan + execute artifacts (completed)
+2. Ad-hoc completeness — all adhoc artifacts are completed (or explicitly skipped)
+3. Execution completeness — all tasks in executed plans are completed
+4. Cross-artifact integration — interfaces, data contracts, configuration consistency
+
+Data source: `state.json.artifacts[]` filtered by current milestone.
+Produces audit report at `.workflow/milestones/{milestone}/audit-report.md`.
+</purpose>
+
+<required_reading>
+@~/.maestro/workflows/milestone-audit.md
+</required_reading>
+
+<context>
+Milestone: $ARGUMENTS (optional -- defaults to current_milestone from state.json).
+
+**Requires:** All phases in the milestone should have completed execute artifacts.
+
+**Data source:**
+- `.workflow/state.json` — artifacts[], current_milestone, milestones[]
+- `.workflow/roadmap.md` — milestone-to-phase mapping
+- Plan scratch dirs — for task status verification
+</context>
+
+<execution>
+Follow '~/.maestro/workflows/milestone-audit.md' completely.
+
+Audit checklist steps (phase coverage, ad-hoc completeness, execution completeness, cross-artifact integration) are defined in workflow `milestone-audit.md`.
+
+**Next-step routing on completion:**
+- Verdict PASS → `/maestro-milestone-complete {milestone}`
+- Verdict FAIL, integration gaps → `/maestro-plan --gaps`
+- Verdict FAIL, incomplete execution → `/maestro-execute`
+</execution>
+
+<error_codes>
+| Code | Severity | Condition | Recovery |
+|------|----------|-----------|----------|
+| E001 | error | Milestone identifier required | Check arguments format |
+| E002 | error | Milestone not found in state.json | Check milestone ID |
+| E003 | error | No execute artifacts found for milestone | Run maestro-execute first |
+| W001 | warning | Some phases lack complete artifact chains | Review incomplete phases |
+</error_codes>
+
+<success_criteria>
+- [ ] All phases in milestone identified from roadmap
+- [ ] Artifact chains verified (ANL→PLN→EXC) per phase
+- [ ] Ad-hoc artifacts checked for completion
+- [ ] Integration check completed (shared interfaces, data contracts)
+- [ ] Audit report written with clear PASS/FAIL verdict
+- [ ] Next-step routing provided
+</success_criteria>