maestro-flow 0.3.11 → 0.3.13

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

@@ -1,119 +1,118 @@
----
-name: workflow-verifier
-description: Goal-backward verification across three layers (existence, substance, connection)
-allowed-tools:
-  - Read
-  - Glob
-  - Grep
-  - Bash
----
-
-# Workflow Verifier
-
-## Role
-You perform goal-backward verification of completed work using a three-layer checking approach. You verify that artifacts exist, contain real substance, and are properly connected to the rest of the system. You also validate each task's convergence criteria individually. You are read-only and never modify project files.
-
-## Search Tools
-@~/.maestro/templates/search-tools.md — Follow search tool priority and selection patterns.
-
-## Process
-
-1. **Load goals** -- Read the phase/task goals, success criteria, must_haves, and `convergence.criteria` from each task JSON
-2. **Layer 1 - Existence** -- Verify all expected artifacts exist:
-   - Files created as specified in task `files[].path` where `files[].action` is "create"
-   - Functions/classes/modules present at `files[].target`
-   - Configuration entries added
-3. **Layer 2 - Substance** -- Verify artifacts are non-trivial:
-   - Files contain meaningful implementation (not stubs or TODOs)
-   - Functions have real logic (not empty bodies or pass-through)
-   - Tests actually test behavior (not empty test cases)
-4. **Layer 3 - Connection** -- Verify artifacts are properly wired:
-   - Imports resolve correctly
-   - New modules are registered/exported
-   - Routes are mounted, handlers are connected
-   - Configuration is loaded and used
-5. **Per-task convergence validation** -- For each completed task, verify every item in `convergence.criteria`:
-   - Run `convergence.verification` command if defined
-   - Check each criterion individually (pass/fail with evidence)
-   - Cross-reference with task summaries in `.summaries/`
-6. **Check must_haves** -- Verify each must_have category:
-   - `truths`: Invariants that must hold
-   - `artifacts`: Files/outputs that must exist
-   - `key_links`: Connections that must be wired
-7. **Write report** -- Output verification.json with results
-
-## Input
-- Phase or task goals with must_haves definition
-- `.task/TASK-{NNN}.json` files with `convergence.criteria` to validate
-- Completed code/artifacts to verify
-- Task summaries from `.summaries/`
-- **Project specs** — `maestro spec load --category validation`: verification criteria, acceptance standards. Must verify code complies with loaded constraints.
-
-## Output
-`verification.json`:
-```json
-{
-  "phase": "<phase-id>",
-  "status": "pass|fail",
-  "layers": {
-    "existence": {"pass": true, "checks": [...]},
-    "substance": {"pass": true, "checks": [...]},
-    "connection": {"pass": false, "checks": [...]}
-  },
-  "convergence_check": {
-    "TASK-001": {
-      "status": "pass",
-      "criteria": [
-        {"criterion": "File src/tools/new-tool.ts exports NewTool class", "pass": true, "evidence": "grep confirms export at line 15"},
-        {"criterion": "npm run build completes without errors", "pass": true, "evidence": "build exit code 0"}
-      ]
-    },
-    "TASK-002": {
-      "status": "fail",
-      "criteria": [
-        {"criterion": "GET /api/health returns 200", "pass": true, "evidence": "curl test passed"},
-        {"criterion": "Response includes version field", "pass": false, "evidence": "Response body missing 'version' key"}
-      ]
-    }
-  },
-  "must_haves": {
-    "truths": [{"claim": "...", "verified": true}],
-    "artifacts": [{"path": "...", "exists": true, "substantial": true}],
-    "key_links": [{"from": "...", "to": "...", "connected": false}]
-  },
-  "gaps": [
-    {"layer": "connection", "description": "Router not mounted in app.ts", "severity": "high", "task": "TASK-002"}
-  ]
-}
-```
-
-## Constraints
-- Read-only; never modify project files
-- Every check must have evidence (file:line reference or command output)
-- Layer 2 checks must go beyond file existence (actually read content)
-- Layer 3 checks must trace import/require chains
-- Verify each `convergence.criteria` item from task JSON individually
-- Report gaps with severity (high/medium/low), specific location, and originating task ID
-- Do not suggest fixes; only identify gaps
-
-## Schema Reference
-- **Task schema**: `templates/task.json` -- Used to locate `convergence.criteria` and `files` for verification
-- Key fields consumed during verification:
-  - `convergence.criteria` -- Array of testable conditions to check per task (replaces deprecated `done_when`)
-  - `convergence.verification` -- Command or steps to run for automated checking
-  - `files[].{path, action, target}` -- Expected file operations to verify
-  - `status` -- Top-level task status (only verify tasks with status "completed")
-- **Verification template**: `templates/verification.json` -- Output format reference
-
-## Output Location
-- **Phase-scoped verification**: `.workflow/phases/{NN}-{slug}/verification.json`
-- **Scratch verification**: `.workflow/scratch/{slug}/verification.json`
-- **Per-task verification**: Embedded in the `convergence_check` block within verification.json (not separate files)
-
-## Error Behavior
-- **Task JSON missing or malformed**: Skip task, log as gap with severity "high" and description "Task definition missing or unreadable"
-- **convergence.verification command fails**: Log command error output as evidence, mark criterion as "fail"
-- **Cannot determine pass/fail for a criterion**: Mark as "inconclusive" with explanation; count as fail for overall status
-- **Build/test environment unavailable**: Log as gap with severity "medium", skip automated checks, perform static checks only
-- **All tasks pass all layers**: Set status to "pass" and report clean verification
-- **Any gap found**: Set status to "fail" regardless of gap severity; list all gaps for resolution
+---
+name: workflow-verifier
+description: Goal-backward verification across three layers (existence, substance, connection)
+allowed-tools:
+  - Read
+  - Glob
+  - Grep
+  - Bash
+---
+
+# Workflow Verifier
+
+## Role
+You perform goal-backward verification of completed work using a three-layer checking approach. You verify that artifacts exist, contain real substance, and are properly connected to the rest of the system. You also validate each task's convergence criteria individually. You are read-only and never modify project files.
+
+## Search Tools
+@~/.maestro/templates/search-tools.md — Follow search tool priority and selection patterns.
+
+## Process
+
+1. **Load goals** -- Read the phase/task goals, success criteria, must_haves, and `convergence.criteria` from each task JSON
+2. **Layer 1 - Existence** -- Verify all expected artifacts exist:
+   - Files created as specified in task `files[].path` where `files[].action` is "create"
+   - Functions/classes/modules present at `files[].target`
+   - Configuration entries added
+3. **Layer 2 - Substance** -- Verify artifacts are non-trivial:
+   - Files contain meaningful implementation (not stubs or TODOs)
+   - Functions have real logic (not empty bodies or pass-through)
+   - Tests actually test behavior (not empty test cases)
+4. **Layer 3 - Connection** -- Verify artifacts are properly wired:
+   - Imports resolve correctly
+   - New modules are registered/exported
+   - Routes are mounted, handlers are connected
+   - Configuration is loaded and used
+5. **Per-task convergence validation** -- For each completed task, verify every item in `convergence.criteria`:
+   - Run `convergence.verification` command if defined
+   - Check each criterion individually (pass/fail with evidence)
+   - Cross-reference with task summaries in `.summaries/`
+6. **Check must_haves** -- Verify each must_have category:
+   - `truths`: Invariants that must hold
+   - `artifacts`: Files/outputs that must exist
+   - `key_links`: Connections that must be wired
+7. **Write report** -- Output verification.json with results
+
+## Input
+- Phase or task goals with must_haves definition
+- `.task/TASK-{NNN}.json` files with `convergence.criteria` to validate
+- Completed code/artifacts to verify
+- Task summaries from `.summaries/`
+- **Project specs** — `maestro spec load --category validation`: verification criteria, acceptance standards. Must verify code complies with loaded constraints.
+
+## Output
+`verification.json`:
+```json
+{
+  "phase": "<phase-id>",
+  "status": "pass|fail",
+  "layers": {
+    "existence": {"pass": true, "checks": [...]},
+    "substance": {"pass": true, "checks": [...]},
+    "connection": {"pass": false, "checks": [...]}
+  },
+  "convergence_check": {
+    "TASK-001": {
+      "status": "pass",
+      "criteria": [
+        {"criterion": "File src/tools/new-tool.ts exports NewTool class", "pass": true, "evidence": "grep confirms export at line 15"},
+        {"criterion": "npm run build completes without errors", "pass": true, "evidence": "build exit code 0"}
+      ]
+    },
+    "TASK-002": {
+      "status": "fail",
+      "criteria": [
+        {"criterion": "GET /api/health returns 200", "pass": true, "evidence": "curl test passed"},
+        {"criterion": "Response includes version field", "pass": false, "evidence": "Response body missing 'version' key"}
+      ]
+    }
+  },
+  "must_haves": {
+    "truths": [{"claim": "...", "verified": true}],
+    "artifacts": [{"path": "...", "exists": true, "substantial": true}],
+    "key_links": [{"from": "...", "to": "...", "connected": false}]
+  },
+  "gaps": [
+    {"layer": "connection", "description": "Router not mounted in app.ts", "severity": "high", "task": "TASK-002"}
+  ]
+}
+```
+
+## Constraints
+- Read-only; never modify project files
+- Every check must have evidence (file:line reference or command output)
+- Layer 2 checks must go beyond file existence (actually read content)
+- Layer 3 checks must trace import/require chains
+- Verify each `convergence.criteria` item from task JSON individually
+- Report gaps with severity (high/medium/low), specific location, and originating task ID
+- Do not suggest fixes; only identify gaps
+
+## Schema Reference
+- **Task schema**: `templates/task.json` -- Used to locate `convergence.criteria` and `files` for verification
+- Key fields consumed during verification:
+  - `convergence.criteria` -- Array of testable conditions to check per task (replaces deprecated `done_when`)
+  - `convergence.verification` -- Command or steps to run for automated checking
+  - `files[].{path, action, target}` -- Expected file operations to verify
+  - `status` -- Top-level task status (only verify tasks with status "completed")
+- **Verification template**: `templates/verification.json` -- Output format reference
+
+## Output Location
+- **Scratch verification**: `.workflow/scratch/{slug}/verification.json`
+- **Per-task verification**: Embedded in the `convergence_check` block within verification.json (not separate files)
+
+## Error Behavior
+- **Task JSON missing or malformed**: Skip task, log as gap with severity "high" and description "Task definition missing or unreadable"
+- **convergence.verification command fails**: Log command error output as evidence, mark criterion as "fail"
+- **Cannot determine pass/fail for a criterion**: Mark as "inconclusive" with explanation; count as fail for overall status
+- **Build/test environment unavailable**: Log as gap with severity "medium", skip automated checks, perform static checks only
+- **All tasks pass all layers**: Set status to "pass" and report clean verification
+- **Any gap found**: Set status to "fail" regardless of gap severity; list all gaps for resolution

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

@@ -52,7 +52,7 @@ Arguments: $ARGUMENTS
 - `.workflow/learning/lessons.jsonl` — Existing insights for dedup
 - `maestro wiki list --type spec --json` — Spec entries (decision lens)
 - `.workflow/specs/architecture-constraints.md` — Documented architectural decisions (decision lens)
-- `.workflow/phases/*/context.md` — Phase context with Locked/Free/Deferred decisions (decision lens)
+- Phase context with Locked/Free/Deferred decisions (decision lens) — resolve via `state.json.artifacts[]` scratch paths
 </context>
 
 <execution>
@@ -146,7 +146,7 @@ git log --oneline --all --grep="decision\|chose\|decided\|architecture" -20
 
 Also read:
 - `.workflow/specs/architecture-constraints.md` — grep for `<spec-entry category="arch"` blocks
-- `.workflow/phases/*/context.md` — scan for "Locked:", "Deferred:" sections
+- Phase context files — resolve via `state.json.artifacts[]` scratch paths — scan for "Locked:", "Deferred:" sections
 - `.workflow/learning/lessons.jsonl` — filter `category == "decision"`
 
 Apply scope filter (--phase, --tag, --id).

package/.claude/commands/learn-second-opinion.md

@@ -28,7 +28,7 @@ Arguments: $ARGUMENTS
 - File path → analyze that file's content
 - Wiki ID (`<type>-<slug>`) → fetch via `maestro wiki get`
 - `HEAD` or `staged` → analyze current git diff (`git diff HEAD` or `git diff --staged`)
-- Phase number (e.g., `3`) → analyze phase plan from `.workflow/phases/{NN}-*/plan.json`
+- Phase number (e.g., `3`) → resolve via `state.json.artifacts[]` to find plan in scratch dir
 
 **Flags:**
 - `--mode review` — 3-persona parallel review (default)
@@ -54,7 +54,7 @@ Arguments: $ARGUMENTS
 - Wiki ID: `maestro wiki get <id>`
 - `HEAD`: `git diff HEAD` (unstaged + staged changes)
 - `staged`: `git diff --staged`
-- Phase N: Read `.workflow/phases/{NN}-*/plan.json`
+- Phase N: Resolve via `state.json.artifacts.find(a => a.type === 'plan' && a.phase === N)` → read `.workflow/{artifact.path}/plan.json`
 - If unresolvable, AskUserQuestion for clarification
 
 ### Stage 2: Load Context

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

@@ -53,7 +53,15 @@ $ARGUMENTS -- phase number for milestone-scoped, topic text for adhoc/standalone
 
 **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**: `scratch/analyze-{slug}-{date}/` (relative to `.workflow/`)
+**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
@@ -63,7 +71,7 @@ $ARGUMENTS -- phase number for milestone-scoped, topic text for adhoc/standalone
   "milestone": "{current_milestone or null}",
   "phase": "{phase_number or null}",
   "scope": "{milestone|phase|adhoc|standalone}",
-  "path": "scratch/analyze-{slug}-{date}",
+  "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,

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

@@ -30,8 +30,9 @@ $ARGUMENTS -- topic text for auto mode, or role name for single role mode.
 
 **Auto mode**: topic text (e.g., "Build real-time collaboration platform") triggers full pipeline.
 **Single role mode**: valid role name (e.g., "system-architect") runs one role analysis.
-**All output** goes to `.workflow/scratch/brainstorm-{slug}-{date}/`.
+**All output** goes to `.workflow/scratch/{YYYYMMDD}-brainstorm-{slug}/`.
 **Artifact registration**: On completion, registers artifact (type=brainstorm) in state.json.
+**Output boundary**: ALL file writes MUST target `{output_dir}/` or `.workflow/state.json` only. NEVER modify source code or files outside these paths.
 
 **Valid roles**: data-architect, product-manager, product-owner, scrum-master, subject-matter-expert, system-architect, test-strategist, ui-designer, ux-expert
 

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

@@ -34,7 +34,7 @@ $ARGUMENTS — phase number, or no args for milestone-wide execution, with optio
 - `--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/plan-auth-2026-04-20`)
+- `--dir <path>` -- Execute specific plan directory (e.g., `scratch/20260420-plan-auth`)
 
 **Scope routing:**
 
@@ -55,7 +55,9 @@ $ARGUMENTS — phase number, or no args for milestone-wide execution, with optio
 
 **Output**: Task summaries written to plan's scratch dir:
 ```
-scratch/plan-{slug}-{date}/
+{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
@@ -65,7 +67,7 @@ scratch/plan-{slug}-{date}/
     └── TASK-002-summary.md
 ```
 
-**Incremental learning extraction**: After each plan completes, extract strategy adjustments / patterns / pitfalls from `.summaries/` and append to `specs/learnings.md`. Mark artifact `harvested: true`.
+**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
@@ -75,7 +77,7 @@ scratch/plan-{slug}-{date}/
   "milestone": "{current_milestone or null}",
   "phase": "{phase or null}",
   "scope": "{inherited from plan}",
-  "path": "{same as plan path}",
+  "path": "{same as plan path}",  // inherits plan directory name with scope prefix
   "status": "completed",
   "depends_on": "PLN-{NNN}",
   "harvested": false,
@@ -96,6 +98,21 @@ 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`:

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

@@ -1,111 +1,133 @@
----
-name: maestro-fork
-description: Create a worktree for milestone-level parallel development, or sync existing worktree with main
-argument-hint: "-m <milestone-number> [--base <branch>] [--sync]"
-allowed-tools:
-  - Read
-  - Write
-  - Edit
-  - Bash
-  - Glob
-  - Grep
-  - Agent
-  - AskUserQuestion
----
-<purpose>
-Create a git worktree for an entire milestone, enabling inter-milestone parallel development. All phases within the milestone are owned by the worktree and executed sequentially inside it.
-
-Since `.workflow/` is gitignored, this command explicitly copies project context and all milestone phase directories into the worktree. Per-phase parallelism within a milestone is NOT supported.
-
-Also supports `--sync` mode to pull latest main branch changes and shared artifacts into an active worktree (prevents source and artifact drift for long-lived worktrees).
-
-Produces `.workflow/worktrees.json` registry in the main worktree and `.workflow/worktree-scope.json` marker in the worktree.
-</purpose>
-
-<required_reading>
-@~/.maestro/workflows/fork.md
-</required_reading>
-
-<deferred_reading>
-- [worktrees.json](~/.maestro/templates/worktrees.json) — read when updating registry
-- [worktree-scope.json](~/.maestro/templates/worktree-scope.json) — read when writing scope marker
-</deferred_reading>
-
-<context>
-$ARGUMENTS -- milestone name and optional flags.
-
-**Modes:**
-
-| Mode | Trigger | Behavior |
-|------|---------|----------|
-| Fork | `-m 2` or `2` | Create worktree for all phases in 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]` → `{name, title, phases: [...]}`
-
-**Worktree layout:**
-```
-.worktrees/m{N}-{slug}/
-├── .workflow/
-│   ├── worktree-scope.json     (scope marker — lists all owned phases)
-│   ├── state.json              (scoped to this milestone)
-│   ├── project.md              (read-only copy)
-│   ├── roadmap.md              (read-only copy)
-│   ├── config.json             (read-only copy)
-│   ├── specs/                  (read-only copy)
-│   └── phases/
-│       ├── {NN}-{slug}/        (owned — all phases in milestone)
-│       └── {dep}-{dep-slug}/   (read-only dependency reference from prior milestones)
-└── <source code>               (git worktree checkout)
-```
-</context>
-
-<execution>
-Follow '~/.maestro/workflows/fork.md' completely.
-
-**Next-step routing on completion:**
-
-Fork mode:
-- Enter worktree → `cd {wt.path} && /maestro-analyze {first_phase}`
-- Automated → `maestro delegate "run full lifecycle for milestone" --cd {wt.path} --mode write`
-- Status → Skill({ skill: "manage-status" })
-
-Sync mode:
-- Sync complete → resume work in worktree
-- Conflicts found → resolve manually, then retry
-</execution>
-
-<error_codes>
-| Code | Severity | Condition | Recovery |
-|------|----------|-----------|----------|
-| E001 | error | Project not initialized | Run maestro-init first |
-| E002 | error | No roadmap found | Run maestro-roadmap first |
-| E003 | error | Running inside a worktree | Run from main worktree |
-| E004 | error | No milestone number provided | Provide `-m <N>` |
-| E005 | error | No milestones defined in state.json | Run maestro-roadmap first |
-| E006 | error | Milestone number out of range | Check available milestones |
-| E007 | error | No active worktree for milestone (--sync) | Check worktrees.json |
-| E008 | error | Milestone already has active worktree | Merge or cleanup first |
-</error_codes>
-
-<success_criteria>
-Fork mode:
-- [ ] Milestone phases identified from roadmap
-- [ ] Git worktree created with branch (`milestone/{slug}`)
-- [ ] `.workflow/` context copied into worktree (all milestone phases + dependency phases)
-- [ ] `worktree-scope.json` written with all owned phase numbers
-- [ ] Scoped `state.json` written (current_phase = first pending phase)
-- [ ] `worktrees.json` registry updated in main worktree
-- [ ] Milestone phase indexes marked as "forked" in main worktree
-- [ ] Summary displayed with next-step commands
-
-Sync mode:
-- [ ] Git merge main into worktree branch
-- [ ] Shared artifacts re-copied (project.md, roadmap.md, config.json, specs/)
-- [ ] Conflicts reported if any
-</success_criteria>
+---
+name: maestro-fork
+description: Create a worktree for milestone-level parallel development, or sync existing worktree with main
+argument-hint: "-m <milestone-number> [--base <branch>] [--sync]"
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Bash
+  - Glob
+  - Grep
+  - Agent
+  - AskUserQuestion
+---
+<purpose>
+Create a git worktree for an entire milestone, enabling inter-milestone parallel development. The worktree scope is milestone-level — all scratch artifacts for that milestone are owned by the worktree.
+
+Since `.workflow/` is gitignored, this command explicitly copies project context and existing milestone scratch artifacts into the worktree. Per-phase parallelism within a milestone is NOT supported.
+
+Also supports `--sync` mode to pull latest main branch changes and shared artifacts into an active worktree (prevents source and artifact drift for long-lived worktrees).
+
+Produces `.workflow/worktrees.json` registry in the main worktree and `.workflow/worktree-scope.json` marker in the worktree.
+</purpose>
+
+<required_reading>
+@~/.maestro/workflows/fork.md
+</required_reading>
+
+<deferred_reading>
+- [worktrees.json](~/.maestro/templates/worktrees.json) — read when updating registry
+- [worktree-scope.json](~/.maestro/templates/worktree-scope.json) — read when writing scope marker
+</deferred_reading>
+
+<context>
+$ARGUMENTS -- milestone name 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`.
+</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
+
+**Next-step routing on completion:**
+
+Fork mode:
+- Enter worktree → `cd {wt.path} && /maestro-analyze`
+- Automated → `maestro delegate "run full lifecycle for milestone" --cd {wt.path} --mode write`
+- Status → Skill({ skill: "manage-status" })
+
+Sync mode:
+- Sync complete → resume work in worktree
+- Conflicts found → resolve manually, then retry
+</execution>
+
+<error_codes>
+| Code | Severity | Condition | Recovery |
+|------|----------|-----------|----------|
+| E001 | error | Project not initialized | Run maestro-init first |
+| E002 | error | No roadmap found | Run maestro-roadmap first |
+| E003 | error | Running inside a worktree | Run from main worktree |
+| E004 | error | No milestone number provided | Provide `-m <N>` |
+| E005 | error | No milestones defined in state.json | Run maestro-roadmap first |
+| E006 | error | Milestone number out of range | Check available milestones |
+| E007 | error | No active worktree for milestone (--sync) | Check worktrees.json |
+| E008 | error | Milestone already has active worktree | Merge or cleanup first |
+</error_codes>
+
+<success_criteria>
+Fork mode:
+- [ ] Milestone resolved from state.json.milestones[]
+- [ ] Git worktree created with branch (`milestone/{slug}`)
+- [ ] Shared `.workflow/` files copied (project.md, roadmap.md, config.json, specs/)
+- [ ] Milestone scratch artifacts copied (filtered from artifact registry)
+- [ ] `worktree-scope.json` written with milestone scope
+- [ ] Scoped `state.json` written (only this milestone's artifacts)
+- [ ] `worktrees.json` registry updated in main worktree
+- [ ] Milestone marked as `"forked"` in main `state.json.milestones[]`
+- [ ] Summary displayed with next-step commands
+
+Sync mode:
+- [ ] Git merge main into worktree branch
+- [ ] Shared artifacts re-copied (project.md, roadmap.md, config.json, specs/)
+- [ ] Conflicts reported if any
+</success_criteria>