maestro-flow 0.3.15 → 0.3.16

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

@@ -0,0 +1,300 @@
+---
+name: maestro-amend
+description: Collect deficiency signals from workflow artifacts, sessions, and user reports, then generate overlays to amend workflow commands
+argument-hint: "[description] [--from-verify <dir>] [--from-review <dir>] [--from-session <id>] [--from-issues ISS-xxx,...] [--scan] [--dry-run]"
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+  - Glob
+  - Grep
+  - AskUserQuestion
+---
+<purpose>
+Signal-driven overlay generator — collects workflow deficiency signals from heterogeneous sources (verification gaps, review findings, debug sessions, open issues, user feedback), diagnoses which commands need amendment, and batch-generates targeted overlays to fix them.
+
+Differs from `/maestro-overlay` which takes a single explicit intent. This command **discovers** what needs amending by analyzing workflow artifacts, then proposes and applies overlay fixes automatically.
+
+**Mechanism**: All amendments use the overlay system (`~/.maestro/overlays/*.json`) — non-invasive, idempotent, survives reinstall.
+</purpose>
+
+<required_reading>
+@~/.maestro/workflows/overlays.md
+@~/.maestro/cli-tools.json
+</required_reading>
+
+<context>
+$ARGUMENTS — optional description and/or source flags.
+
+### Signal Sources
+
+| Flag | Source | What it collects |
+|------|--------|------------------|
+| `--from-verify <dir>` | `verification.json` | Workflow gaps exposed by verify failures |
+| `--from-review <dir>` | `review.json` | Process deficiencies from code review |
+| `--from-session <id>` | Session artifacts | Problems encountered during workflow execution |
+| `--from-issues ISS-xxx,...` | `issues.jsonl` | Issues that trace to command deficiency |
+| `--scan` | Auto-scan `.workflow/` | Discover all workflow-related signals |
+| _(positional text)_ | User description | Direct observation of command deficiency |
+
+Multiple sources combinable. No flags and no description → interactive mode.
+
+### Control Flags
+
+| Flag | Description |
+|------|-------------|
+| `--dry-run` | Generate overlay JSON, show preview, don't install |
+| `-y` | Skip confirmations |
+
+### Signal-to-Overlay Classification
+
+A signal becomes an overlay candidate when it identifies a **workflow command deficiency** — a missing step, missing precondition, absent reading, or gap in success criteria. Signals about code bugs (not command gaps) are out of scope; suggest `/maestro-quick` or `/maestro-plan --gaps` for those.
+
+### CLI Targeting
+
+Overlays support the `cli` field to target different workflow systems:
+- `"cli": "claude"` (default) → patches `.claude/commands/{name}.md`
+- `"cli": "codex"` → patches `.codex/skills/{name}/SKILL.md`
+- `"cli": "both"` → patches both paths
+
+When diagnosing signals, determine which CLI's workflow is affected and set the `cli` field accordingly.
+
+### Output
+- Overlay files: `~/.maestro/overlays/amend-{slug}.json`
+- Optional docs: `~/.maestro/overlays/docs/amend-{slug}.md`
+</context>
+
+<execution>
+### 1. Collect signals
+
+Parse $ARGUMENTS for source flags and description text.
+
+**If no sources and no description** → interactive mode:
+Scan `.workflow/` for recent artifacts containing workflow-level signals:
+
+```
+candidates = []
+
+# Verification: workflow gaps (not code bugs)
+for each verification.json in .workflow/scratch/*-verify-*/
+  extract must_have_failures, anti_pattern items
+  filter for items whose fix_direction points at a command gap
+  (e.g., "missing pre-check step", "no reading for X", "success criteria incomplete")
+
+# Review: process findings
+for each review.json in .workflow/scratch/*-review-*/
+  extract findings tagged as "process" or "workflow"
+
+# Debug sessions: root causes tracing to command omission
+for each understanding.md in .workflow/scratch/*-debug-*/
+  extract root causes where cause_type mentions workflow/command
+
+# Open issues: workflow-tagged
+issues = read .workflow/issues/issues.jsonl
+  | filter status == "open" AND tags include "workflow" or "command"
+
+# Execution summaries: deviations
+for each summary in .workflow/scratch/*-plan-*/.summaries/
+  extract plan deviations that suggest a missing command step
+```
+
+Display scan results and use AskUserQuestion (multiSelect) to let user pick sources. Also allow user to add a freeform description.
+
+**If source flags** → extract signals from each specified source.
+
+**If only description** → user's text is the sole signal. Parse for:
+- Which command(s) are affected
+- What's missing or broken in the command flow
+- What the expected behavior should be
+
+### 2. Diagnose: map signals to command patches
+
+For each signal, determine:
+
+```
+{
+  signal_id: "SIG-001",
+  source: "verify:scratch/20260426-verify-M1/",
+  description: "maestro-execute skipped pre-flight when no test suite exists",
+  target_command: "maestro-execute",
+  target_section: "execution",
+  patch_mode: "append",
+  fix_direction: "Add fallback verification when no test suite detected",
+  severity: "medium"
+}
+```
+
+**Diagnosis heuristics:**
+
+| Signal pattern | Target section | Mode |
+|---------------|----------------|------|
+| Missing pre-check / gate | `execution` | `prepend` |
+| Missing post-step / verification | `execution` | `append` |
+| Missing reading / context | `required_reading` or `deferred_reading` | `append` |
+| Incomplete success criteria | `success_criteria` | `append` |
+| Missing error handling | `error_codes` | `append` |
+| Scope/context gap | `context` | `append` |
+| Entirely new concern | _(new section)_ | `new-section` |
+
+If target command is ambiguous, read the pristine source from `$PKG_ROOT/.claude/commands/<name>.md` (preferred) or `~/.claude/commands/<name>.md` to confirm the right section.
+
+### 3. Group and plan overlays
+
+Group signals by target command. Signals hitting the same command **and** same section merge into one patch. Different sections on the same command stay as separate patches in one overlay.
+
+Decide overlay granularity:
+- **Single-concern** (1–2 signals on same command) → one overlay per command: `patch-{command}-{slug}.json`
+- **Multi-concern** (3+ signals across commands) → one umbrella overlay: `amend-{slug}.json`
+
+For each planned overlay, read the target command's pristine source to:
+- Verify the section exists
+- Check for existing overlays (via `<!-- maestro-overlay:` markers)
+- Confirm the injection point makes sense
+
+### 4. Preview injection points
+
+For each target command, render a section map with injection points (same format as `/maestro-overlay`):
+
+```
+=== maestro-execute.md (1 existing overlay) ===
+
+  <purpose>
+  <required_reading>
+     ├─ [existing] require-spec-before-plan #0
+  <context>
+  <execution>
+     ├─ [existing] require-spec-before-plan #1  "Pre-check: Load Spec"
+     ├─ [existing] cli-verify-after-execute #0  "CLI Verification"
+     >>> NEW: prepend — SIG-001 "Fallback verify when no tests"
+     >>> NEW: append  — SIG-003 "Issue sync retry on failure"
+  <error_codes>
+  <success_criteria>
+     >>> NEW: append  — SIG-002 "Verify issue status updated"
+
+=== maestro-plan.md (0 existing overlays) ===
+
+  <purpose>
+  <required_reading>
+  <context>
+     >>> NEW: append  — SIG-004 "Load prior patch history"
+  <execution>
+  <success_criteria>
+```
+
+Use AskUserQuestion to confirm:
+- **"Apply all"** — proceed with all patches
+- **"Select patches"** — per-signal confirmation
+- **"Edit"** — modify a specific signal's target/section before proceeding
+- **"Cancel"** — abort
+
+### 5. Draft overlay JSON
+
+For each overlay, build the JSON following the overlay schema:
+
+```json
+{
+  "name": "amend-execute-verify-fallback",
+  "description": "Add fallback verification and issue sync retry to maestro-execute [from: AMEND-20260426]",
+  "targets": ["maestro-execute"],
+  "cli": "claude",
+  "priority": 60,
+  "enabled": true,
+  "patches": [
+    {
+      "section": "execution",
+      "mode": "prepend",
+      "content": "## Fallback Verification (patch: SIG-001)\n\nIf no test suite exists for the affected module, run a structural verification instead:\n..."
+    },
+    {
+      "section": "execution",
+      "mode": "append",
+      "content": "## Issue Sync Retry (patch: SIG-003)\n\nIf issue status sync fails, retry once before logging as warning:\n..."
+    },
+    {
+      "section": "success_criteria",
+      "mode": "append",
+      "content": "- [ ] Issue statuses confirmed synced after execution (patch: SIG-002)"
+    }
+  ]
+}
+```
+
+**Content rules:**
+- Heading includes `(patch: SIG-NNN)` for traceability
+- Content is concise — fix the gap, nothing more
+- `@~/.maestro/overlays/docs/` references for anything longer than 10 lines
+- If supplementary doc needed, write it to `~/.maestro/overlays/docs/amend-{slug}.md` first
+
+Write overlay JSON to `~/.maestro/overlays/amend-{slug}.json`.
+
+If `--dry-run`, show the JSON and section map preview, then stop.
+
+### 6. Install overlays
+
+For each generated overlay:
+
+```bash
+maestro overlay add ~/.maestro/overlays/amend-{slug}.json
+```
+
+On validation failure, fix the JSON and retry (max 2 attempts).
+
+### 7. Report
+
+```
+=== AMEND OVERLAYS INSTALLED ===
+Session:   AMEND-20260426
+Signals:   5 collected, 4 applied, 1 skipped (code bug, not command gap)
+Overlays:  2 created
+
+  amend-execute-verify-fallback
+    Targets:  maestro-execute (3 patches: exec prepend, exec append, criteria append)
+    Path:     ~/.maestro/overlays/amend-execute-verify-fallback.json
+    Source:   SIG-001, SIG-002, SIG-003
+
+  amend-plan-context-history
+    Targets:  maestro-plan (1 patch: context append)
+    Path:     ~/.maestro/overlays/amend-plan-context-history.json
+    Source:   SIG-004
+
+Skipped:
+  SIG-005   "Missing null check in auth.ts" → code bug, use /maestro-quick
+
+Re-apply:  maestro overlay apply
+Remove:    maestro overlay remove amend-execute-verify-fallback
+Inspect:   maestro overlay list
+```
+
+### Post-patch routing
+
+Use AskUserQuestion:
+- **"Test commands"** — run affected commands to verify patches work
+- **"View overlays"** — `maestro overlay list`
+- **"Continue"** — done
+</execution>
+
+<error_codes>
+| Code | Severity | Condition | Recovery |
+|------|----------|-----------|----------|
+| E001 | error | No signals found from any source | Verify artifact paths, or provide description |
+| E002 | error | Source artifact not found | Check path exists |
+| E003 | error | No signals map to command deficiencies (all are code bugs) | Use `/maestro-quick` or `/maestro-plan --gaps` instead |
+| E004 | error | Overlay validation failed after 2 retries | Review generated JSON manually |
+| W001 | warning | Some signals skipped (code bugs, not command gaps) | Route to appropriate fix command |
+| W002 | warning | Target command has many existing overlays (≥3) | Consider consolidating overlays |
+| W003 | warning | Scan found no recent workflow artifacts | Check `.workflow/` or provide explicit source |
+</error_codes>
+
+<success_criteria>
+- [ ] Signal sources resolved and signals collected
+- [ ] Each signal classified: command deficiency vs. code bug (only command deficiencies proceed)
+- [ ] Signals mapped to target command + section + mode
+- [ ] Pristine command sources read to verify sections and check existing overlays
+- [ ] Section map with injection points shown and confirmed by user
+- [ ] Overlay JSON written to `~/.maestro/overlays/amend-{slug}.json`
+- [ ] Supplementary docs written to `~/.maestro/overlays/docs/` if needed
+- [ ] `maestro overlay add` exited successfully for each overlay
+- [ ] Target command files contain `<!-- maestro-overlay:amend-{slug}#N hash=... -->` markers
+- [ ] Report shown with overlay details, source traceability, and skipped signals
+- [ ] Skipped code-bug signals routed to appropriate alternative command
+</success_criteria>

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

@@ -40,55 +40,7 @@ $ARGUMENTS -- phase number for milestone-scoped, topic text for adhoc/standalone
 - `-q` / `--quick`: Quick mode — skip exploration + scoring, go straight to decision extraction (context.md only)
 - `--gaps [ISS-ID]`: Issue root cause analysis mode. If ISS-ID provided, analyze single issue. If omitted, analyze all open/registered issues from issues.jsonl.
 
-**Scope routing (per architecture):**
-
-| Invocation | Precondition | Scope | Behavior |
-|-----------|-------------|-------|----------|
-| `analyze` (no args) | init + roadmap | milestone | Analyze current milestone's all phases |
-| `analyze 1` | init + roadmap | phase | Analyze phase 1 only |
-| `analyze "topic"` (has milestone) | none | adhoc | Analyze topic, affiliated with current milestone |
-| `analyze "topic"` (no milestone) | none | standalone | Analyze topic, no milestone affiliation |
-| `analyze --gaps` | issues.jsonl exists | gaps | Load open issues, explore root causes, write analysis records |
-| `analyze --gaps ISS-xxx` | issue exists | gaps | Analyze single issue root cause |
-
-**Scope detection rule**: Text argument + `state.json.current_milestone` non-null → adhoc. Text argument + no milestone → standalone. No args + no roadmap → error (need topic or roadmap). `--gaps` → gaps scope (bypasses standard scope routing).
-
-**Output directory** (relative to `.workflow/`):
-
-| Scope | Directory format | Example |
-|-------|-----------------|---------|
-| Phase | `scratch/{YYYYMMDD}-analyze-P{N}-{slug}/` | `20260420-analyze-P1-auth` |
-| Milestone | `scratch/{YYYYMMDD}-analyze-M{N}-{slug}/` | `20260420-analyze-M1-mvp` |
-| Adhoc/Standalone | `scratch/{YYYYMMDD}-analyze-{slug}/` | `20260420-analyze-caching` |
-
-Scope prefix (`P{N}` / `M{N}`) enables directory-level identification as fallback when state.json is unavailable.
-
-**Artifact registration**: On completion, register artifact in `state.json.artifacts[]`:
-```jsonc
-{
-  "id": "ANL-{NNN}",
-  "type": "analyze",
-  "milestone": "{current_milestone or null}",
-  "phase": "{phase_number or null}",
-  "scope": "{milestone|phase|adhoc|standalone}",
-  "path": "scratch/{YYYYMMDD}-analyze-P{N}-{slug}",  // P{N} for phase, M{N} for milestone, omit for adhoc/standalone
-  "status": "completed",
-  "depends_on": null,
-  "harvested": false,
-  "created_at": "...",
-  "completed_at": "..."
-}
-```
-
-**Output artifacts:**
-| Artifact | Mode | Description |
-|----------|------|-------------|
-| `context.md` | both | Locked/Free/Deferred decisions for downstream plan |
-| `discussion.md` | full | Full discussion timeline with TOC, Current Understanding, rounds, decisions, intent coverage |
-| `analysis.md` | full | Executive summary with 6-dimension scores and risk matrix |
-| `conclusions.json` | full | Final synthesis with recommendations, decision trail, intent coverage |
-| `explorations.json` | full | Codebase exploration findings (single perspective) |
-| `perspectives.json` | full | Multi-perspective findings with synthesis (if multi-perspective) |
+Scope routing, output directory format, artifact registration schema, and output artifact listing are defined in workflow analyze.md (Scope Routing and Output Structure sections).
 </context>
 
 <execution>

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

@@ -1,7 +1,7 @@
 ---
 name: maestro-execute
 description: Execute plan with wave-based parallel execution and atomic commits
-argument-hint: "[phase] [--auto-commit] [--method agent|cli|auto] [--executor <tool>] [--dir <path>]"
+argument-hint: "[phase] [--auto-commit] [--method agent|codex|gemini|cli|auto] [--executor <tool>] [--dir <path>] [-y]"
 allowed-tools:
   - Read
   - Write
@@ -30,61 +30,7 @@ Invoked after /maestro-plan produces a confirmed plan. When called without args
 <context>
 $ARGUMENTS — phase number, or no args for milestone-wide execution, with optional flags.
 
-**Flags:**
-- `--auto-commit` -- Automatically commit after each task completion
-- `--method agent|cli|auto` -- Override execution method (default: from config.json)
-- `--executor <tool>` -- Default CLI tool: gemini|codex|qwen|opencode|claude
-- `--dir <path>` -- Execute specific plan directory (e.g., `scratch/20260420-plan-auth`)
-
-**Scope routing:**
-
-| Invocation | Behavior |
-|-----------|----------|
-| `execute` (no args) | Find all pending plans for current milestone, execute sequentially |
-| `execute 1` | Find pending plans for phase 1, execute sequentially |
-| `execute --dir scratch/plan-xxx` | Execute the specific plan |
-
-**Resolution logic (no-args / phase):**
-```
-1. Read state.json.artifacts
-2. Filter: milestone=target, type=plan, status=completed, AND no corresponding EXC artifact
-3. If phase specified: further filter by phase=target
-4. Sort by phase dependency order (roadmap phase order), adhoc last
-5. Execute each plan sequentially
-```
-
-**Output**: Task summaries written to plan's scratch dir:
-```
-{YYYYMMDD}-plan-P{N}-{slug}/            # phase-scoped
-{YYYYMMDD}-plan-M{N}-{slug}/           # milestone-wide
-{YYYYMMDD}-plan-{slug}/                # adhoc/standalone
-├── plan.json
-├── .task/
-│   ├── TASK-001.json    # status updated to completed|blocked
-│   └── TASK-002.json
-└── .summaries/          ← execute writes here
-    ├── TASK-001-summary.md
-    └── TASK-002-summary.md
-```
-
-**Incremental learning extraction**: After each plan completes, extract strategy adjustments / patterns / pitfalls from `.summaries/` and append to `specs/learnings.md` using `<spec-entry>` closed-tag format (category=`learning`, auto-extract keywords, date=today, source=`execute`). Mark artifact `harvested: true`.
-
-**Artifact registration**: For each plan executed, register in `state.json.artifacts[]`:
-```jsonc
-{
-  "id": "EXC-{NNN}",
-  "type": "execute",
-  "milestone": "{current_milestone or null}",
-  "phase": "{phase or null}",
-  "scope": "{inherited from plan}",
-  "path": "{same as plan path}",  // inherits plan directory name with scope prefix
-  "status": "completed",
-  "depends_on": "PLN-{NNN}",
-  "harvested": false,
-  "created_at": "...",
-  "completed_at": "..."
-}
-```
+Scope routing, flags, resolution logic, output directory format, artifact registration schema, and incremental learning extraction are defined in workflow `execute.md`.
 </context>
 
 <execution>

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

@@ -32,62 +32,15 @@ Produces `.workflow/worktrees.json` registry in the main worktree and `.workflow
 </deferred_reading>
 
 <context>
-$ARGUMENTS -- milestone name and optional flags.
+$ARGUMENTS -- milestone number and optional flags.
 
-**Modes:**
-
-| Mode | Trigger | Behavior |
-|------|---------|----------|
-| Fork | `-m 2` or `2` | Create worktree for milestone 2 |
-| Sync | `-m 2 --sync` | Sync existing milestone 2 worktree with main branch |
-
-**Flags:**
-- `-m <N>` or bare `<N>`: Milestone number (1-based, maps to `state.json.milestones[]`)
-- `--base <branch>`: Override base branch for worktree creation (default: HEAD)
-- `--sync`: Sync mode — pull main into existing worktree, re-copy shared artifacts
-
-**Milestone resolution:** `state.json.milestones[N-1]` → `{id, name, status}`
-
-**Worktree layout:**
-```
-.worktrees/m{N}-{slug}/
-├── .workflow/
-│   ├── worktree-scope.json     (milestone scope marker)
-│   ├── state.json              (scoped — only this milestone's artifacts)
-│   ├── project.md              (read-only copy)
-│   ├── roadmap.md              (read-only copy)
-│   ├── config.json             (read-only copy)
-│   ├── specs/                  (read-only copy)
-│   └── scratch/                (milestone's existing + new artifacts)
-│       ├── analyze-auth-2026-04-20/
-│       ├── plan-auth-2026-04-20/
-│       └── ...
-└── <source code>               (git worktree checkout)
-```
-
-**Artifact scoping:**
-Fork copies scratch artifacts that belong to the target milestone (filtered from `state.json.artifacts[]` where `milestone == target`). New work in the worktree creates scratch artifacts normally; they are registered in the worktree's local `state.json`.
+Modes (`Fork` / `Sync`), flags (`-m`, `--base`, `--sync`), milestone resolution, worktree layout, and artifact scoping are defined in workflow `fork.md`.
 </context>
 
 <execution>
 Follow '~/.maestro/workflows/fork.md' completely.
 
-**Fork flow:**
-1. Validate: project initialized, roadmap exists, not inside worktree, milestone not already forked
-2. Resolve milestone: `state.json.milestones[N-1]`
-3. Create git worktree: `git worktree add -b milestone/{slug} .worktrees/m{N}-{slug} HEAD`
-4. Copy `.workflow/` into worktree:
-   - Shared files (read-only): `project.md`, `roadmap.md`, `config.json`, `specs/`
-   - Milestone scratch artifacts: filter `state.json.artifacts[]` by `milestone == target`, copy each `scratch/{path}`
-5. Write scope marker: `worktree-scope.json` with milestone number and main path
-6. Write scoped `state.json`: only this milestone's artifacts, `current_milestone` set
-7. Update main: `worktrees.json` registry, mark milestone as `"forked"` in `state.json.milestones[]`
-
-**Sync flow:**
-1. Find worktree from `worktrees.json`
-2. `cd worktree && git merge main`
-3. Re-copy shared files: `project.md`, `roadmap.md`, `config.json`, `specs/`
-4. Report conflicts if any
+Fork and sync algorithm steps are defined in workflow `fork.md`.
 
 **Next-step routing on completion:**
 

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

@@ -23,33 +23,9 @@ Includes registry health check, pre-merge rebase (pull main into worktree to min
 </required_reading>
 
 <context>
-$ARGUMENTS -- milestone name and optional flags.
+$ARGUMENTS -- milestone number 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.
+Flags (`-m`, `--force`, `--dry-run`, `--no-cleanup`, `--continue`), merge sequence, artifact sync detail, and conflict handling are defined in workflow `merge.md`.
 </context>
 
 <execution>

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

@@ -41,11 +41,7 @@ Milestone: $ARGUMENTS (optional -- defaults to current_milestone from state.json
 <execution>
 Follow '~/.maestro/workflows/milestone-audit.md' completely.
 
-**Audit checklist (from architecture):**
-1. Phase coverage: each phase in roadmap has analyze → plan → execute chain
-2. Ad-hoc completeness: all adhoc artifacts completed or skipped
-3. Execution completeness: all tasks in executed plans completed
-4. Cross-artifact integration: interface compatibility, data contracts, config consistency
+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}`

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

@@ -34,13 +34,7 @@ Milestone: $ARGUMENTS (optional -- defaults to current_milestone from state.json
 <execution>
 Follow '~/.maestro/workflows/milestone-complete.md' completely.
 
-**Archive flow:**
-1. Validate audit passed + all artifacts completed
-2. Move scratch dirs to `milestones/{M}/artifacts/`
-3. Move artifact entries to `milestone_history[M].archived_artifacts`
-4. Extract learnings from summaries → `specs/learnings.md`
-5. Update state.json: advance to next milestone, clear artifacts[]
-6. Clean scratch dirs
+Archive flow steps (validation, directory archival, artifact history, learning extraction, state advancement, cleanup) are defined in workflow `milestone-complete.md`.
 
 ### Knowledge Promotion Inquiry