maestro-flow-one 0.1.0

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

@@ -0,0 +1,100 @@
+---
+name: maestro-brainstorm
+description: Unified brainstorming with dual-mode operation - auto pipeline and single role analysis
+argument-hint: "[topic|role-name] [--yes] [--count N] [--session ID] [--update] [--skip-questions] [--include-questions] [--style-skill PKG]"
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+  - Glob
+  - Grep
+  - Agent
+  - AskUserQuestion
+---
+<purpose>
+Unified brainstorming combining interactive framework generation, multi-role parallel analysis, and cross-role synthesis. Two modes: Auto (full pipeline with guidance-specification → parallel role analysis → synthesis) and Single Role (individual role analysis for an existing session). Outputs structured artifacts in .brainstorming/ directory ready for downstream planning.
+</purpose>
+
+<required_reading>
+@~/.maestro/workflows/brainstorm.md
+</required_reading>
+
+<deferred_reading>
+- [scratch-index.json](~/.maestro/templates/scratch-index.json) — read when operating in scratch mode
+- [index.json](~/.maestro/templates/index.json) — read when operating in phase mode
+- [brainstorm-visualize.md](~/.maestro/workflows/brainstorm-visualize.md) — read when html-prototypes/ produced and user wants to browse them
+</deferred_reading>
+
+<context>
+$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/{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
+
+**Flags**:
+- `--yes` / `-y`: Auto mode, skip interactive questions, use defaults
+- `--count N`: Number of roles to select (default 3, max 9)
+- `--session ID`: Use existing session
+- `--update`: Update existing analysis (single role)
+- `--skip-questions`: Skip context gathering questions
+- `--include-questions`: Force context gathering even if analysis exists
+- `--style-skill PKG`: Style package for ui-designer role
+</context>
+
+<execution>
+Follow '~/.maestro/workflows/brainstorm.md' completely.
+
+**Next-step routing on completion:**
+
+Auto mode:
+- Project not initialized → Skill({ skill: "maestro-flow", args: "--cmd maestro-init" })
+- Project initialized, need spec package → Skill({ skill: "maestro-flow", args: "--cmd maestro-roadmap --mode full --from-brainstorm {session_id}" })
+- Project initialized, quick roadmap → Skill({ skill: "maestro-flow", args: "--cmd maestro-roadmap --from-brainstorm {session_id}" })
+- Need deeper analysis first → Skill({ skill: "maestro-flow", args: "--cmd maestro-analyze {topic}" })
+- `html-prototypes/` produced with 2+ files and user wants to browse → load `~/.maestro/workflows/brainstorm-visualize.md` and launch visualizer server (optional, user-triggered)
+
+Single role mode:
+- More roles needed → Skill({ skill: "maestro-flow", args: "--cmd maestro-brainstorm {next_role} --session {session_id}" })
+- All roles done, run synthesis → Skill({ skill: "maestro-flow", args: "--cmd maestro-brainstorm {topic} --session {session_id}" })
+</execution>
+
+<error_codes>
+| Code | Severity | Condition | Recovery |
+|------|----------|-----------|----------|
+| E001 | error | Topic or role argument required | Prompt user for topic text or role name |
+| E002 | error | No active session for single role mode | Guide user to run auto mode first |
+| E003 | error | Invalid role name | Show valid roles list |
+| W001 | warning | Fewer than 10 ideas in divergent phase | Proceed with available ideas |
+| W002 | warning | Project context (.workflow/) not found | Continue without project context |
+| W003 | warning | Role template not found | Use generic analysis structure |
+| W004 | warning | Validation score < 60 | Log warning, suggest manual review |
+| W005 | warning | External research agent failed | Continue without designResearchContext |
+</error_codes>
+
+<success_criteria>
+**Auto mode**:
+- [ ] guidance-specification.md with RFC 2119 keywords, terminology, non-goals, feature decomposition
+- [ ] design-research.md persisted when Step 1.7 external research ran (fail-soft: absence not a failure)
+- [ ] Spec Review Gate passed (Step 3.5) or `--yes` bypassed
+- [ ] Role analysis files for each selected NON-UI role in `.brainstorming/{role}/`
+- [ ] If `ui-designer` in selected_roles: `ui-designer/analysis.md` exists AND exactly one of `html-prototypes/` / `ascii-mockups/` / `api-sketches/` exists with `README.md` + ≥1 prototype file
+- [ ] ui-designer/analysis.md references each prototype via `@-notation`
+- [ ] HTML prototypes are self-contained (no external `<link>`/`<script src>` URLs — warn only)
+- [ ] Feature specs in `.brainstorming/feature-specs/` (or synthesis-specification.md)
+- [ ] UI-bearing feature specs reference the corresponding prototype in Section 3 (Interface Contract)
+- [ ] feature-index.json and synthesis-changelog.md
+- [ ] Final Output Gate passed (Step 5.5) or `--yes` bypassed
+- [ ] All user decisions captured with Decision Recording Protocol
+- [ ] Session metadata updated with completion status
+
+**Single role mode**:
+- [ ] analysis.md written to `{output_dir}/{role}/`
+- [ ] Feature-point organization used when feature list available
+- [ ] Framework reference included when guidance-specification.md exists
+- [ ] Session metadata updated
+</success_criteria>

package/claude/maestro-flow/commands/lifecycle/composer.md

@@ -0,0 +1,354 @@
+---
+name: maestro-composer
+description: Semantic workflow composer — parse natural language into DAG of skill/CLI/agent nodes, auto-inject checkpoints, persist as reusable JSON template
+argument-hint: "\"workflow description\" [--resume] [--edit <template-path>]"
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Bash
+  - Glob
+  - Grep
+  - Agent
+  - AskUserQuestion
+---
+<purpose>
+Interactive workflow template composer. Parses natural language into a reusable DAG template
+via 5 phases with user confirmation at each boundary. Templates saved globally at
+`~/.maestro/templates/workflows/`. Progressive disclosure — specs loaded only when phase needs them.
+
+Three entry modes:
+1. **New design**: Parse → [confirm] → Resolve → [confirm] → Enrich → Confirm pipeline → Persist
+2. **Resume design**: Load in-progress draft from `.workflow/templates/design-drafts/`
+3. **Edit template**: Load existing template, modify, re-save
+</purpose>
+
+<deferred_reading>
+- [node-catalog](~/.maestro/templates/workflows/specs/node-catalog.md) — read at Phase 2 (Resolve) when mapping steps to executors
+- [template-schema](~/.maestro/templates/workflows/specs/template-schema.md) — read at Phase 5 (Persist) when assembling final JSON
+</deferred_reading>
+
+<context>
+$ARGUMENTS — natural language workflow description, or flags.
+
+**Flags:**
+- `--resume` — Resume in-progress design session
+- `--edit <template-path>` — Edit an existing template
+
+**Shared constants:**
+
+| Constant | Value |
+|----------|-------|
+| Session prefix | `WFD` |
+| Template dir (global) | `~/.maestro/templates/workflows/` |
+| Template index (global) | `~/.maestro/templates/workflows/index.json` |
+| Design drafts dir (local) | `.workflow/templates/design-drafts/` |
+| Template ID format | `wft-<slug>-<YYYYMMDD>` |
+| Node ID format | `N-<seq>` (e.g. N-001), `CP-<seq>` for checkpoints |
+| Max nodes | 20 |
+
+**Entry routing:**
+
+| Detection | Condition | Handler |
+|-----------|-----------|---------|
+| Resume design | `--resume` flag or existing WFD session | Phase 0: Resume |
+| Edit template | `--edit <template-path>` | Phase 0: Load + Edit |
+| New design | Default | Phase 1: Parse |
+</context>
+
+<execution>
+
+### Phase 0: Resume / Edit (conditional)
+
+**Resume design session** (if `--resume`):
+1. Scan `.workflow/templates/design-drafts/WFD-*/` for in-progress designs
+2. Multiple found → AskUserQuestion for selection
+3. Load draft → skip to last incomplete phase
+
+**Edit existing template** (if `--edit <path>`):
+1. Load template from `--edit` path
+2. Show current pipeline visualization (Phase 4 format)
+3. AskUserQuestion: which nodes to modify/add/remove
+4. Re-enter at Phase 3 with edits applied
+
+---
+
+### Phase 1: Parse — Semantic Intent Extraction
+
+**Step 1.1** — Parse `$ARGUMENTS` as description. If empty, AskUserQuestion:
+```
+"Describe the workflow you want to automate.
+Include: what steps to run, in what order, and what varies each time (inputs).
+Example: 'analyze the code, then plan, implement, and test the feature'"
+```
+
+**Step 1.2** — Extract sequential actions as candidate nodes using semantic understanding:
+
+| Signal | Candidate Type |
+|--------|---------------|
+| "analyze", "review", "explore" | analysis (cli) |
+| "plan", "design", "spec" | planning (skill) |
+| "implement", "build", "code", "fix" | execution (skill) |
+| "test", "validate", "verify" | testing (skill) |
+| "brainstorm", "ideate" | brainstorm (skill) |
+| "review code" | review (skill) |
+| "then", "next", "after" | sequential edge |
+| "parallel", "simultaneously" | parallel edge |
+
+**Step 1.3** — Extract variables (inputs that vary per run). Detect from: direct mentions, `{var}` patterns, implicit from task type.
+
+**Step 1.4** — Classify task type: `bugfix | feature | tdd | review | brainstorm | spec-driven | roadmap | refactor | auto-test | quick-task | custom`
+
+**Step 1.5** — Assess complexity: `simple` (1-3 nodes), `medium` (4-7), `complex` (8+)
+
+**Step 1.6** — Write `intent.json` to `.workflow/templates/design-drafts/WFD-<slug>-<date>/`.
+
+**Step 1.7 — Interactive confirmation**:
+
+Display parsed intent summary:
+```
+============================================================
+  COMPOSER — Intent Parsed
+============================================================
+  Description: "<original input>"
+  Task type:   <type>
+  Complexity:  <level>
+
+  Detected steps:
+    1. <description>  →  <type_hint>
+    2. <description>  →  <type_hint>
+    3. <description>  →  <type_hint>
+
+  Variables:
+    - goal (required): <inferred description>
+
+  Draft: .workflow/templates/design-drafts/WFD-<slug>-<date>/
+============================================================
+```
+
+AskUserQuestion:
+```
+options:
+  - "Looks good, continue to resolution"  → Phase 2
+  - "Edit steps"                           → re-describe, re-parse
+  - "Add a step"                           → append, re-parse
+  - "Cancel"                               → save draft, exit
+```
+
+---
+
+### Phase 2: Resolve — Map Steps to Executor Nodes
+
+**Read deferred**: `~/.maestro/templates/workflows/specs/node-catalog.md` — load node catalog for executor mapping.
+
+If the spec file does not exist, use the built-in fallback mapping:
+
+| type_hint | Default executor type | Default executor |
+|-----------|----------------------|------------------|
+| `planning` | skill | `maestro-plan` |
+| `execution` | skill | `maestro-execute` |
+| `testing` | skill | `quality-test` |
+| `review` | skill | `quality-review` |
+| `brainstorm` | skill | `maestro-brainstorm` |
+| `analysis` | cli | `maestro delegate --role analyze --mode analysis` |
+| `verify` | skill | `maestro-verify` |
+| `refactor` | skill | `quality-refactor` |
+| `debug` | skill | `quality-debug` |
+| `spec` | skill | `maestro-roadmap --mode full` |
+| `checkpoint` | checkpoint | — |
+
+**Step 2.1** — Load `intent.json`.
+
+**Step 2.2** — Map each step to executor. Resolution: match `type_hint` → catalog → semantic fit → fallback `cli`.
+
+**Step 2.3** — Build `args_template` with variable placeholders. Context injection:
+- Planning after analysis → `--context {prev_output_path}`
+- Execution after planning → `--resume-session {prev_session_id}`
+- Testing after execution → `--session {prev_session_id}`
+
+**Step 2.4** — Assign `parallel_group` for steps with `parallel_with` set.
+
+**Step 2.5** — Write `nodes.json`.
+
+**Step 2.6 — Interactive confirmation**:
+
+Display resolved nodes:
+```
+============================================================
+  COMPOSER — Nodes Resolved
+============================================================
+  N-001  [skill]    maestro-plan          "{goal}"
+  N-002  [skill]    maestro-execute       {phase}
+  N-003  [skill]    quality-test          {phase}
+
+  Parallel groups: none
+============================================================
+```
+
+AskUserQuestion:
+```
+options:
+  - "Continue to checkpoint injection"  → Phase 3
+  - "Change executor for a node"        → select node, pick new executor
+  - "Change node type"                  → skill/cli/agent/command
+  - "Back to intent"                    → Phase 1
+  - "Cancel"                            → save draft, exit
+```
+
+---
+
+### Phase 3: Enrich — Inject Checkpoints + Build DAG
+
+**Step 3.1** — Load `nodes.json`.
+
+**Step 3.2** — Build sequential edges (N-001 → N-002 → ...). For parallel groups: fan-out/fan-in.
+
+**Step 3.3** — Auto-inject checkpoint nodes. Inject if ANY rule triggers:
+
+| Rule | Condition |
+|------|-----------|
+| Artifact boundary | Source output_ports: plan, spec, analysis, review-findings |
+| Execution gate | Target executor contains `execute` |
+| Agent spawn | Target type is `agent` |
+| Long-running | Target is maestro-plan, maestro-roadmap --mode full |
+| User-defined | Step had `type_hint: checkpoint` |
+| Post-testing | Source executor contains `test` or `auto-test` |
+
+Set `auto_continue: false` for checkpoints before user-facing deliverables.
+
+**Step 3.4** — Insert checkpoint edges (A → B becomes A → CP-X → B).
+
+**Step 3.5** — Finalize `context_schema` from all `{variable}` references.
+
+**Step 3.6** — Validate: no cycles, no orphans, all nodes reachable.
+
+**Step 3.7** — Write `dag.json`.
+
+→ Proceed directly to Phase 4 (confirm is the pipeline visualization).
+
+---
+
+### Phase 4: Confirm — Visualize + User Approval
+
+**Step 4.1** — Render ASCII pipeline from `dag.json`:
+```
+============================================================
+  COMPOSER — Pipeline Review
+============================================================
+Pipeline: <template-name>
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ N-001  [skill]       maestro-plan              "{goal}"
+   |
+ CP-01  [checkpoint]  After Plan                auto-continue
+   |
+ N-002  [skill]       maestro-execute           {phase}
+   |
+ CP-02  [checkpoint]  Before Tests              pause-for-user
+   |
+ N-003  [skill]       quality-test              {phase}
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Variables (required):  goal
+Checkpoints:           2  (1 auto, 1 pause)
+Nodes:                 3 work + 2 checkpoints
+============================================================
+```
+
+For parallel groups show fan-out/fan-in:
+```
+ N-003a [skill]  quality-review  ─┐
+                                   ├─ N-004 [skill] quality-test
+ N-003b [cli]    cli analysis     ─┘
+```
+
+**Step 4.2** — AskUserQuestion:
+```
+options:
+  - "Confirm & Save"                    → Phase 5
+  - "Edit a node"                       → select node ID, modify executor/args, re-render
+  - "Add a node"                        → insert position + description, re-resolve + re-enrich, re-render
+  - "Remove a node"                     → select node, re-wire edges, re-render
+  - "Rename template"                   → new name
+  - "Re-run checkpoint injection"       → back to Phase 3.3
+  - "Cancel"                            → save draft, output resume command
+```
+
+**Step 4.3** — On edit: apply change, re-render, re-ask. Loop until Confirm or Cancel.
+
+**Step 4.4** — On Confirm: freeze dag.json, proceed to Phase 5. On Cancel: save draft, output `/maestro-composer --resume`.
+
+---
+
+### Phase 5: Persist — Assemble + Save Template
+
+**Read deferred**: `~/.maestro/templates/workflows/specs/template-schema.md` — load full JSON schema for template assembly.
+
+If the spec file does not exist, use the built-in template structure:
+```json
+{
+  "template_id": "wft-<slug>-<YYYYMMDD>",
+  "name": "<name>", "description": "<desc>", "version": "1.0",
+  "created_at": "<ISO>", "source_session": "WFD-<slug>-<date>",
+  "tags": [], "context_schema": {},
+  "nodes": [], "edges": [], "checkpoints": [],
+  "execution_mode": "serial",
+  "metadata": { "node_count": 0, "checkpoint_count": 0 }
+}
+```
+
+**Step 5.1** — Load `intent.json` + `dag.json`.
+
+**Step 5.2** — Determine template name (from Phase 4 or derive from task_type + description). Slug = kebab-case. If file exists with different content, append `-v2`, `-v3`.
+
+**Step 5.3** — Assemble template JSON.
+
+**Step 5.4** — Ensure `~/.maestro/templates/workflows/` exists. Write `<slug>.json`.
+
+**Step 5.5** — Update `~/.maestro/templates/workflows/index.json`.
+
+**Step 5.6** — Output summary:
+```
+============================================================
+  COMPOSER — Template Saved
+============================================================
+  Path:      ~/.maestro/templates/workflows/<slug>.json
+  ID:        wft-<slug>-<date>
+  Nodes:     <n> work + <n> checkpoints
+  Variables: <required vars>
+
+  To execute:
+    /maestro-player <slug> --context goal="<your goal>"
+
+  To edit later:
+    /maestro-composer --edit ~/.maestro/templates/workflows/<slug>.json
+
+  To list all templates:
+    /maestro-player --list
+============================================================
+```
+
+**Step 5.7** — Clean up design draft directory.
+</execution>
+
+<error_codes>
+| Code | Severity | Description | Recovery |
+|------|----------|-------------|----------|
+| E001 | error | Empty description and no flags | AskUserQuestion for workflow description |
+| E002 | error | Step extraction found 0 steps | Ask user to rephrase with action verbs |
+| E003 | error | Node count exceeds max (20) | Suggest splitting into sub-workflows |
+| E004 | error | DAG cycle detected | Show cycle, ask user to resolve |
+| E005 | error | Resume session not found | Show available design drafts |
+| E006 | error | Edit template not found | Show available templates |
+| W001 | warning | Ambiguous step-to-executor mapping | Show candidates, let user choose |
+| W002 | warning | No checkpoint injection rules triggered | Warn user, offer to add manually |
+| W003 | warning | Deferred spec file not found | Use built-in fallback, continue |
+</error_codes>
+
+<success_criteria>
+- [ ] Intent parsed and confirmed by user (Phase 1 interactive gate)
+- [ ] Nodes resolved and confirmed by user (Phase 2 interactive gate)
+- [ ] DAG built with auto-injected checkpoints
+- [ ] Pipeline visualized and confirmed by user (Phase 4 interactive gate)
+- [ ] Template JSON written to `~/.maestro/templates/workflows/<slug>.json`
+- [ ] Template index updated at `~/.maestro/templates/workflows/index.json`
+- [ ] Deferred specs loaded only when phase needs them (not upfront)
+</success_criteria>

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

@@ -0,0 +1,114 @@
+---
+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>] [-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: "maestro-flow", args: "--cmd spec-add <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/maestro-flow/commands/lifecycle/fork.md

@@ -0,0 +1,86 @@
+---
+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 number and optional flags.
+
+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 and sync algorithm steps are defined in workflow `fork.md`.
+
+**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: "maestro-flow", args: "--cmd 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>