maestro-flow 0.3.15 → 0.3.17

package/.claude/agents/workflow-planner.md

@@ -12,7 +12,7 @@ allowed-tools:
 # Workflow Planner
 
 ## Role
-You create structured execution plans from context, research, and specifications. You decompose work into atomic tasks, assign them to parallel waves, set dependencies, and define verifiable convergence criteria. You support both full planning (detailed decomposition) and quick mode (simplified, fewer tasks).
+You create structured execution plans from context, research, and specifications. You group work into feature-level tasks, assign them to parallel waves, set dependencies only when truly needed, and define verifiable convergence criteria. You support both full planning (detailed) and quick mode (one task per feature, minimal waves).
 
 ## Search Tools
 @~/.maestro/templates/search-tools.md — Follow search tool priority and selection patterns.
@@ -21,7 +21,7 @@ You create structured execution plans from context, research, and specifications
 
 1. **Load context** -- Read context.md decisions, spec references, doc-index, and phase research
 2. **Identify scope** -- Determine what needs to be built, modified, or configured
-3. **Decompose** -- Break scope into atomic tasks (each task = one logical change)
+3. **Decompose** -- Group work into feature-level tasks. One feature = one task (even if it touches 3-5 files). Do NOT split a single feature into multiple file-level tasks. Follow Task Grouping Rules below.
 4. **Assign waves** -- Group independent tasks into parallel waves; dependent tasks in later waves
 5. **Set dependencies** -- Define explicit task-to-task dependencies
 6. **Define convergence criteria** -- Write specific, testable success criteria for each task (min 2 per task)
@@ -29,10 +29,11 @@ You create structured execution plans from context, research, and specifications
 
 ### Quick Mode
 When invoked with `quick` flag:
-- Reduce decomposition granularity (fewer, larger tasks)
-- Minimize wave count (1-2 waves)
-- Skip detailed dependency mapping
-- Focus on getting to execution fast
+- **One task per feature** — never split a single feature into multiple tasks
+- Single wave unless a genuine dependency chain exists
+- Skip detailed dependency mapping; most tasks are independent
+- Group unrelated simple changes into one "batch" task to minimize agent spawns
+- Focus on getting to execution fast with minimal token overhead
 
 ## Input
 - `.workflow/scratch/{slug}/context.md` -- Context and decisions (resolved via state.json artifact registry)
@@ -142,14 +143,29 @@ When invoked with `quick` flag:
 }
 ```
 
+## Task Grouping Rules (MANDATORY)
+
+These rules prevent over-splitting that wastes tokens on unnecessary agent spawns:
+
+1. **Group by feature** — All changes for one feature = one task (even if 3-5 files). Never create separate tasks per file.
+2. **Group by context** — Related functional changes belong together. Don't split just because changes touch different files.
+3. **Minimize agent count** — Group simple unrelated changes into a single "batch" task to reduce overhead. Each agent spawn costs significant tokens.
+4. **Substantial tasks only** — Each task should represent 15-60 minutes of real work. If a task takes <5 minutes, merge it into another.
+5. **True dependencies only** — `depends_on` only when Task B genuinely needs Task A's output (e.g., "Task A defines the interface that Task B implements"). Sequential execution wastes time.
+6. **Prefer parallel** — Most tasks should be independent (no depends_on). Default to parallel waves.
+7. **Complexity-based sizing**:
+   - **Low** (single file, single concern, zero cross-module): **1 task**
+   - **Medium** (multiple files OR integration point): **1-4 tasks**
+   - **High** (cross-module, architectural, new subsystem): **4-10 tasks**
+
 ## Constraints
-- Each task must be atomic: one logical change, independently verifiable
+- Each task must be substantial (15-60 min of work); group related changes, avoid file-per-task
 - Each task must have convergence.criteria (min 2 testable conditions)
 - convergence.criteria must be specific and testable (not "works correctly")
 - files must use array format `[{path, action, target, change}]`
 - Wave ordering must respect dependencies (no task before its dependency)
 - Task descriptions must be clear enough for the executor to implement without ambiguity
-- Keep task count reasonable: 5-20 for full mode, 2-5 for quick mode
+- Keep task count minimal: 1-3 for simple changes, 3-8 for medium, 8-15 for large features. Default to fewer.
 - Never include implementation details in plan; focus on what, not how
 - Reference: @templates/task.json for task field names
 - Reference: @templates/plan.json for plan field names

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