maestro-flow 0.1.3 → 0.2.0

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

@@ -1,78 +1,78 @@
----
-name: maestro-init
-description: Initialize project with auto state detection (empty/code/existing)
-argument-hint: "[--auto] [--from-brainstorm SESSION-ID]"
-allowed-tools:
-  - Read
-  - Write
-  - Bash
-  - Glob
-  - Grep
-  - Agent
-  - AskUserQuestion
----
-<purpose>
-Initialize a new project through auto state detection and unified flow. Invoked when starting a fresh project or onboarding an existing codebase into workflow management. Produces the `.workflow/` directory structure with project.md, state.json, config.json, and specs. Does NOT create roadmap — use maestro-spec-generate or maestro-roadmap as the next step.
-</purpose>
-
-<required_reading>
-@~/.maestro/workflows/init.md
-@~/.maestro/templates/project.md
-@~/.maestro/templates/state.json
-@~/.maestro/templates/config.json
-</required_reading>
-
-<context>
-**Flags:**
-- `--auto` -- Automatic mode. After config questions, runs research without further interaction. Expects idea document via @ reference.
-- `--from-brainstorm SESSION-ID` -- Import from a brainstorm session. Reads guidance-specification.md to pre-fill project vision, goals, constraints, and terminology. Skips interactive questioning.
-
-**Load project state if exists:**
-Check for `.workflow/state.json` -- loads context if project already initialized.
-</context>
-
-<execution>
-Follow '~/.maestro/workflows/init.md' completely.
-
-**Report format on completion:**
-
-```
-=== WORKFLOW INITIALIZED ===
-Project: {project_name}
-State:   .workflow/state.json (active)
-
-Created:
-  .workflow/project.md
-  .workflow/state.json
-  .workflow/config.json
-  .workflow/specs/
-
-Next steps (choose one path to create roadmap):
-  Skill({ skill: "maestro-spec-generate", args: "<idea>" })   -- Full spec package + roadmap (heavy)
-  Skill({ skill: "maestro-roadmap", args: "<requirement>" })   -- Direct interactive roadmap (light)
-
-Other commands:
-  Skill({ skill: "manage-status" })                            -- View project dashboard
-  Skill({ skill: "maestro-brainstorm", args: "<topic>" })     -- Explore ideas first
-  Skill({ skill: "maestro-quick", args: "<task>" })           -- Quick ad-hoc task
-```
-</execution>
-
-<error_codes>
-| Code | Severity | Condition | Recovery |
-|------|----------|-----------|----------|
-| E001 | error | No arguments provided when --auto requires @ reference | Check arguments format, re-run with correct input |
-| E002 | error | .workflow/ already exists for greenfield init | Check .workflow/ directory state, resolve conflicts |
-| E003 | error | Brainstorm session not found (--from-brainstorm) | Check arguments format, re-run with correct input |
-| W001 | warning | Research agent failed, continuing with partial results | Retry research or proceed with partial results |
-</error_codes>
-
-<success_criteria>
-- [ ] Deep questioning completed (threads followed, not rushed) — or extracted from document/brainstorm
-- [ ] `.workflow/project.md` created with Core Value, Requirements (Validated/Active/Out of Scope), Key Decisions
-- [ ] `.workflow/state.json` created and initialized to idle state
-- [ ] `.workflow/config.json` created with user-selected granularity, workflow agents, gate preferences
-- [ ] `.workflow/specs/` initialized with convention files
-- [ ] Research completed (if enabled) — 4 parallel agents spawned
-- [ ] User knows next step is `/maestro-roadmap` or `/maestro-spec-generate`
-</success_criteria>
+---
+name: maestro-init
+description: Initialize project with auto state detection (empty/code/existing)
+argument-hint: "[--auto] [--from-brainstorm SESSION-ID]"
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+  - Glob
+  - Grep
+  - Agent
+  - AskUserQuestion
+---
+<purpose>
+Initialize a new project through auto state detection and unified flow. Invoked when starting a fresh project or onboarding an existing codebase into workflow management. Produces the `.workflow/` directory structure with project.md, state.json, config.json, and specs. Does NOT create roadmap — use maestro-spec-generate or maestro-roadmap as the next step.
+</purpose>
+
+<required_reading>
+@~/.maestro/workflows/init.md
+@~/.maestro/templates/project.md
+@~/.maestro/templates/state.json
+@~/.maestro/templates/config.json
+</required_reading>
+
+<context>
+**Flags:**
+- `--auto` -- Automatic mode. After config questions, runs research without further interaction. Expects idea document via @ reference.
+- `--from-brainstorm SESSION-ID` -- Import from a brainstorm session. Reads guidance-specification.md to pre-fill project vision, goals, constraints, and terminology. Skips interactive questioning.
+
+**Load project state if exists:**
+Check for `.workflow/state.json` -- loads context if project already initialized.
+</context>
+
+<execution>
+Follow '~/.maestro/workflows/init.md' completely.
+
+**Report format on completion:**
+
+```
+=== WORKFLOW INITIALIZED ===
+Project: {project_name}
+State:   .workflow/state.json (active)
+
+Created:
+  .workflow/project.md
+  .workflow/state.json
+  .workflow/config.json
+  .workflow/specs/
+
+Next steps (choose one path to create roadmap):
+  Skill({ skill: "maestro-spec-generate", args: "<idea>" })   -- Full spec package + roadmap (heavy)
+  Skill({ skill: "maestro-roadmap", args: "<requirement>" })   -- Direct interactive roadmap (light)
+
+Other commands:
+  Skill({ skill: "manage-status" })                            -- View project dashboard
+  Skill({ skill: "maestro-brainstorm", args: "<topic>" })     -- Explore ideas first
+  Skill({ skill: "maestro-quick", args: "<task>" })           -- Quick ad-hoc task
+```
+</execution>
+
+<error_codes>
+| Code | Severity | Condition | Recovery |
+|------|----------|-----------|----------|
+| E001 | error | No arguments provided when --auto requires @ reference | Check arguments format, re-run with correct input |
+| E002 | error | .workflow/ already exists for greenfield init | Check .workflow/ directory state, resolve conflicts |
+| E003 | error | Brainstorm session not found (--from-brainstorm) | Check arguments format, re-run with correct input |
+| W001 | warning | Research agent failed, continuing with partial results | Retry research or proceed with partial results |
+</error_codes>
+
+<success_criteria>
+- [ ] Deep questioning completed (threads followed, not rushed) — or extracted from document/brainstorm
+- [ ] `.workflow/project.md` created with Core Value, Requirements (Validated/Active/Out of Scope), Key Decisions
+- [ ] `.workflow/state.json` created and initialized to idle state
+- [ ] `.workflow/config.json` created with user-selected granularity, workflow agents, gate preferences
+- [ ] `.workflow/specs/` initialized with convention files
+- [ ] Research completed (if enabled) — 4 parallel agents spawned
+- [ ] User knows next step is `/maestro-roadmap` or `/maestro-spec-generate`
+</success_criteria>

package/.claude/commands/maestro-link-coordinate.md

@@ -37,6 +37,14 @@ $ARGUMENTS — user intent text, or flags.
 - `maestro coordinate next [sessionId]` — advance one step
 - `maestro coordinate status [sessionId]` — query state
 - `maestro coordinate run "intent"` — autonomous full run
+- `maestro coordinate watch <sessionId> [--follow]` — read-only event tail (separate from driver loop)
+- `maestro coordinate report` — agent-invoked command-node result writer (authoritative result channel)
+
+**Internal walker capabilities (invisible to driver loop):**
+- Prompt assembly owned by the walker (main flow) for both command and decision nodes
+- Decision nodes auto-resolve via `strategy: 'expr'` (fast path) with LLM decider fallback when expr has no match and no default edge, or explicit `strategy: 'llm'`
+- Walker events published to a file/SQLite broker for `watch` observers
+- LLM decision in step mode is synchronous — avoid tight per-step deadlines
 </context>
 
 <execution>

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

@@ -1,60 +1,60 @@
----
-name: maestro-milestone-audit
-description: Audit current milestone for cross-phase integration gaps
-argument-hint: "[milestone, e.g., 'v1.0']"
-allowed-tools:
-  - Read
-  - Write
-  - Bash
-  - Glob
-  - Grep
-  - Agent
-  - AskUserQuestion
----
-
-<purpose>
-Audit milestone completion with cross-phase integration checks. Identifies which phases belong to the milestone, spawns a workflow-integration-checker agent to validate that all phases work together correctly (shared interfaces, data contracts, dependency chains), and produces an audit report with gap analysis and fix suggestions.
-</purpose>
-
-<required_reading>
-@~/.maestro/workflows/milestone-audit.md
-</required_reading>
-
-<context>
-Milestone: $ARGUMENTS (optional -- defaults to current_milestone from state.json).
-
-**Requires:** All phases in the milestone should be completed or verifying.
-
-**State files:**
-- `.workflow/state.json` -- current_milestone, phases_completed
-- `.workflow/roadmap.md` -- milestone-to-phase mapping
-- `.workflow/phases/{NN}-{slug}/index.json` -- phase metadata per phase
-- `.workflow/phases/{NN}-{slug}/verification.json` -- phase verification results
-</context>
-
-<execution>
-Follow '~/.maestro/workflows/milestone-audit.md' completely.
-
-**Next-step routing on completion:**
-- Verdict PASS → Skill({ skill: "maestro-milestone-complete", args: "{milestone}" })
-- Verdict FAIL, integration gaps → Skill({ skill: "maestro-plan", args: "{affected_phase} --gaps" })
-- Verdict FAIL, incomplete phases → Skill({ skill: "maestro-execute", args: "{incomplete_phase}" })
-- Gaps fixed, need re-audit → Skill({ skill: "maestro-milestone-audit", args: "{milestone}" })
-</execution>
-
-<error_codes>
-| Code | Severity | Condition | Recovery |
-|------|----------|-----------|----------|
-| E001 | error | Milestone identifier required | Check arguments format, re-run with correct input |
-| E002 | error | Milestone not found in roadmap | Check arguments format, re-run with correct input |
-| E003 | error | Phases incomplete for this milestone | Complete remaining phases before audit |
-| W001 | warning | Phase lacks completed_at — may not have been formally transitioned | Run phase-transition for the phase first |
-</error_codes>
-
-<success_criteria>
-- [ ] All phases in milestone identified and status checked
-- [ ] Integration check completed via workflow-integration-checker agent
-- [ ] Audit report written with gap analysis and fix suggestions
-- [ ] Cross-phase integration issues identified and categorized
-- [ ] Clear verdict (PASS/FAIL) with next-step routing
-</success_criteria>
+---
+name: maestro-milestone-audit
+description: Audit current milestone for cross-phase integration gaps
+argument-hint: "[milestone, e.g., 'v1.0']"
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+  - Glob
+  - Grep
+  - Agent
+  - AskUserQuestion
+---
+
+<purpose>
+Audit milestone completion with cross-phase integration checks. Identifies which phases belong to the milestone, spawns a workflow-integration-checker agent to validate that all phases work together correctly (shared interfaces, data contracts, dependency chains), and produces an audit report with gap analysis and fix suggestions.
+</purpose>
+
+<required_reading>
+@~/.maestro/workflows/milestone-audit.md
+</required_reading>
+
+<context>
+Milestone: $ARGUMENTS (optional -- defaults to current_milestone from state.json).
+
+**Requires:** All phases in the milestone should be completed or verifying.
+
+**State files:**
+- `.workflow/state.json` -- current_milestone, phases_completed
+- `.workflow/roadmap.md` -- milestone-to-phase mapping
+- `.workflow/phases/{NN}-{slug}/index.json` -- phase metadata per phase
+- `.workflow/phases/{NN}-{slug}/verification.json` -- phase verification results
+</context>
+
+<execution>
+Follow '~/.maestro/workflows/milestone-audit.md' completely.
+
+**Next-step routing on completion:**
+- Verdict PASS → Skill({ skill: "maestro-milestone-complete", args: "{milestone}" })
+- Verdict FAIL, integration gaps → Skill({ skill: "maestro-plan", args: "{affected_phase} --gaps" })
+- Verdict FAIL, incomplete phases → Skill({ skill: "maestro-execute", args: "{incomplete_phase}" })
+- Gaps fixed, need re-audit → Skill({ skill: "maestro-milestone-audit", args: "{milestone}" })
+</execution>
+
+<error_codes>
+| Code | Severity | Condition | Recovery |
+|------|----------|-----------|----------|
+| E001 | error | Milestone identifier required | Check arguments format, re-run with correct input |
+| E002 | error | Milestone not found in roadmap | Check arguments format, re-run with correct input |
+| E003 | error | Phases incomplete for this milestone | Complete remaining phases before audit |
+| W001 | warning | Phase lacks completed_at — may not have been formally transitioned | Run phase-transition for the phase first |
+</error_codes>
+
+<success_criteria>
+- [ ] All phases in milestone identified and status checked
+- [ ] Integration check completed via workflow-integration-checker agent
+- [ ] Audit report written with gap analysis and fix suggestions
+- [ ] Cross-phase integration issues identified and categorized
+- [ ] Clear verdict (PASS/FAIL) with next-step routing
+</success_criteria>

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

@@ -1,58 +1,58 @@
----
-name: maestro-milestone-complete
-description: Archive completed milestone and prepare for next
-argument-hint: "[milestone, e.g., 'v1.0']"
-allowed-tools:
-  - Read
-  - Write
-  - Bash
-  - Glob
-  - Grep
-  - Agent
-  - AskUserQuestion
----
-
-<purpose>
-Mark a milestone as complete after its audit has passed. Validates that the audit report exists and shows a passing verdict, archives the milestone by updating state.json, generates a milestone summary document capturing key outcomes and learnings, and prepares the project state for the next milestone.
-</purpose>
-
-<required_reading>
-@~/.maestro/workflows/milestone-complete.md
-</required_reading>
-
-<context>
-Milestone: $ARGUMENTS (optional -- defaults to current_milestone from state.json).
-
-**Requires:** Skill({ skill: "maestro-milestone-audit" }) should have passed (all phases completed, no integration gaps).
-
-**State files:**
-- `.workflow/state.json` -- current_milestone, milestones array
-- `.workflow/roadmap.md` -- milestone structure
-- `.workflow/milestones/{milestone}/audit-report.md` -- audit results
-</context>
-
-<execution>
-Follow '~/.maestro/workflows/milestone-complete.md' completely.
-
-**Next-step routing on completion:**
-- Next milestone has phases → Skill({ skill: "maestro-plan", args: "{next_milestone_first_phase}" })
-- Need to capture learnings → Skill({ skill: "manage-memory-capture", args: "compact" })
-- View updated project state → Skill({ skill: "manage-status" })
-</execution>
-
-<error_codes>
-| Code | Severity | Condition | Recovery |
-|------|----------|-----------|----------|
-| E001 | error | Milestone identifier required | Check arguments format, re-run with correct input |
-| E002 | error | Audit not passed (report missing or verdict FAIL) | Run maestro-milestone-audit first |
-| E003 | error | Incomplete phases remain in this milestone | Complete remaining phases before milestone completion |
-</error_codes>
-
-<success_criteria>
-- [ ] Audit report verified as PASS before proceeding
-- [ ] Milestone marked complete in state.json with timestamp
-- [ ] Milestone summary generated with outcomes and learnings
-- [ ] Roadmap snapshot saved to milestones directory
-- [ ] project.md Context updated with milestone summary and key learnings
-- [ ] state.json updated with next milestone as current
-</success_criteria>
+---
+name: maestro-milestone-complete
+description: Archive completed milestone and prepare for next
+argument-hint: "[milestone, e.g., 'v1.0']"
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+  - Glob
+  - Grep
+  - Agent
+  - AskUserQuestion
+---
+
+<purpose>
+Mark a milestone as complete after its audit has passed. Validates that the audit report exists and shows a passing verdict, archives the milestone by updating state.json, generates a milestone summary document capturing key outcomes and learnings, and prepares the project state for the next milestone.
+</purpose>
+
+<required_reading>
+@~/.maestro/workflows/milestone-complete.md
+</required_reading>
+
+<context>
+Milestone: $ARGUMENTS (optional -- defaults to current_milestone from state.json).
+
+**Requires:** Skill({ skill: "maestro-milestone-audit" }) should have passed (all phases completed, no integration gaps).
+
+**State files:**
+- `.workflow/state.json` -- current_milestone, milestones array
+- `.workflow/roadmap.md` -- milestone structure
+- `.workflow/milestones/{milestone}/audit-report.md` -- audit results
+</context>
+
+<execution>
+Follow '~/.maestro/workflows/milestone-complete.md' completely.
+
+**Next-step routing on completion:**
+- Next milestone has phases → Skill({ skill: "maestro-plan", args: "{next_milestone_first_phase}" })
+- Need to capture learnings → Skill({ skill: "manage-memory-capture", args: "compact" })
+- View updated project state → Skill({ skill: "manage-status" })
+</execution>
+
+<error_codes>
+| Code | Severity | Condition | Recovery |
+|------|----------|-----------|----------|
+| E001 | error | Milestone identifier required | Check arguments format, re-run with correct input |
+| E002 | error | Audit not passed (report missing or verdict FAIL) | Run maestro-milestone-audit first |
+| E003 | error | Incomplete phases remain in this milestone | Complete remaining phases before milestone completion |
+</error_codes>
+
+<success_criteria>
+- [ ] Audit report verified as PASS before proceeding
+- [ ] Milestone marked complete in state.json with timestamp
+- [ ] Milestone summary generated with outcomes and learnings
+- [ ] Roadmap snapshot saved to milestones directory
+- [ ] project.md Context updated with milestone summary and key learnings
+- [ ] state.json updated with next milestone as current
+</success_criteria>

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

@@ -0,0 +1,122 @@
+---
+name: maestro-overlay
+description: Create or edit a non-invasive overlay that augments existing slash commands based on natural-language intent
+argument-hint: "<intent> | --list | --remove <name>"
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+  - Glob
+  - Grep
+  - AskUserQuestion
+---
+<purpose>
+Turn a user's natural-language instruction into a command overlay — a JSON patch file that augments one or more `.claude/commands/*.md` files non-invasively. Overlays live at `~/.maestro/overlays/` and are auto-applied by every `maestro install` run, so injected steps survive reinstalls. Use this skill when the user says things like "always run CLI verification after `/maestro-execute`", "require reading doc X before `/maestro-plan`", or "add a `ccw cli` quality check at the end of every quality-review".
+</purpose>
+
+<required_reading>
+@~/.maestro/workflows/overlays.md
+@~/.maestro/cli-tools.json
+</required_reading>
+
+<context>
+**Overlay model** — an overlay is a JSON file with a `name`, one or more `targets` (command names without `.md`), and a list of `patches`. Each patch targets an XML section (`execution`, `required_reading`, `context`, `success_criteria`, etc.), a mode (`append`, `prepend`, `replace`, `new-section`), and `content`. On apply, the patcher wraps the content in hashed HTML-comment markers so re-apply is idempotent and removal is surgical.
+
+**Where overlays live**
+- User overlays: `~/.maestro/overlays/*.json` — created by this skill
+- Shared docs: `~/.maestro/overlays/docs/*.md` — referenced via `@~/.maestro/overlays/docs/*.md` inside patch content
+- Shipped examples: `~/.maestro/overlays/_shipped/` — read-only, do not edit
+
+**Flags**
+- `--list` — show installed overlays and their applied state via `maestro overlay list`
+- `--remove <name>` — strip an overlay from targets and delete its file via `maestro overlay remove`
+
+**Available sections** (for `section:` in patches): `purpose`, `required_reading`, `deferred_reading`, `context`, `execution`, `error_codes`, `success_criteria`.
+</context>
+
+<execution>
+### 1. Parse user intent
+
+If the user passed `--list`, run `maestro overlay list` and stop.
+If the user passed `--remove <name>`, run `maestro overlay remove <name>` and stop.
+
+Otherwise treat the argument as natural-language intent. If unclear, ask up to 2 questions with AskUserQuestion: (a) which command(s) to target, (b) where in the command flow the injection should happen.
+
+### 2. Identify targets and injection points
+
+For each likely target command, read the pristine source from `$PKG_ROOT/.claude/commands/<name>.md` (preferred — untouched by overlays) or fall back to `~/.claude/commands/<name>.md`. Inspect the XML sections and pick the right one:
+
+- **New step after execution** → `section: execution`, `mode: append`
+- **Required reading** → `section: required_reading`, `mode: append`
+- **Preconditions / gating** → `section: context`, `mode: append`
+- **Output quality gate** → `section: success_criteria`, `mode: append`
+
+If the user wants a whole new section, use `mode: new-section` with `afterSection: execution` (or whichever anchor makes sense).
+
+### 3. Draft the overlay JSON
+
+Build a slug from the user's intent (kebab-case, lowercase). Write to `~/.maestro/overlays/<slug>.json`:
+
+```json
+{
+  "name": "<slug>",
+  "description": "<short summary of what and why>",
+  "targets": ["maestro-execute"],
+  "priority": 50,
+  "enabled": true,
+  "patches": [
+    {
+      "section": "execution",
+      "mode": "append",
+      "content": "## CLI Verification (overlay)\n\nAfter execution, run:\n```\nccw cli -p \"PURPOSE: ...\" --mode analysis --rule analysis-review-code-quality\n```"
+    }
+  ]
+}
+```
+
+**Content guidelines**
+- Lead the injected block with a heading that includes `(overlay)` so readers see it's machine-injected
+- Keep content concise — overlays should add a step, not rewrite the command
+- `@~/.maestro/...` references are encouraged for pointing at docs
+- Escape `\n` in JSON strings; use a HEREDOC via Bash if content is long
+
+### 4. Install via `maestro overlay add`
+
+Run:
+
+```bash
+maestro overlay add ~/.maestro/overlays/<slug>.json
+```
+
+This validates the overlay, copies it into place (idempotent), and applies it across all known install scopes. On validation failure, fix the JSON and re-run.
+
+### 5. Report
+
+Show the user:
+- Path of the saved overlay JSON
+- Which targets were patched and which were skipped (missing/disabled)
+- A reminder that `maestro install` will auto-reapply on every run
+- How to remove: `maestro overlay remove <slug>`
+
+**Report format**
+
+```
+=== OVERLAY INSTALLED ===
+Name:    <slug>
+Path:    ~/.maestro/overlays/<slug>.json
+Targets: maestro-execute (applied), maestro-plan (skipped: missing)
+Scopes:  [global]
+
+Re-apply: maestro overlay apply
+Remove:   maestro overlay remove <slug>
+Inspect:  maestro overlay list
+```
+</execution>
+
+<success_criteria>
+- [ ] Overlay JSON written to `~/.maestro/overlays/<slug>.json` and validates
+- [ ] `maestro overlay add` exited successfully and applied to at least one scope
+- [ ] Target command file(s) contain `<!-- maestro-overlay:<slug>#N hash=... -->` markers
+- [ ] Re-running `maestro overlay apply` produces no file changes (idempotent)
+- [ ] User shown the report with target list and removal instructions
+</success_criteria>

package/.claude/commands/maestro-phase-add.md

@@ -1,55 +1,55 @@
----
-name: maestro-phase-add
-description: Add or insert a new phase into the project roadmap with automatic renumbering
-argument-hint: "<slug> <title> [--after N]"
-allowed-tools: [Read, Write, Edit, Bash, Glob, Grep, Agent, AskUserQuestion]
----
-
-<purpose>
-Add a new phase to the project roadmap, either appending it at the end or inserting it after a specified phase number. Handles automatic renumbering of subsequent phase directories, updates roadmap.md with the new entry, and initializes the phase directory with an index.json so it is ready for planning.
-</purpose>
-
-<required_reading>
-@~/.maestro/workflows/phase-add.md
-</required_reading>
-
-<deferred_reading>
-- [index.json](~/.maestro/templates/index.json) — read when creating new phase index
-</deferred_reading>
-
-<context>
-$ARGUMENTS -- phase slug and title (required), optional --after N flag.
-
-**Flags:**
-- `--after N` -- Insert after phase N (renumbers subsequent phases). If omitted, appends at end.
-
-**State files:**
-- `.workflow/roadmap.md` -- milestone and phase structure
-- `.workflow/state.json` -- project-level state
-- `.workflow/phases/` -- existing phase directories
-</context>
-
-<execution>
-Follow '~/.maestro/workflows/phase-add.md' completely.
-
-**Next-step routing on completion:**
-- Plan the new phase → Skill({ skill: "maestro-plan", args: "{new_phase_number}" })
-- Analyze before planning → Skill({ skill: "maestro-analyze", args: "{new_phase_number}" })
-- View updated roadmap → Skill({ skill: "manage-status" })
-</execution>
-
-<error_codes>
-| Code | Meaning                          |
-|------|----------------------------------|
-| E001 | Phase name/slug required         |
-| E002 | roadmap.md not found             |
-| E003 | Duplicate phase name/slug exists |
-</error_codes>
-
-<success_criteria>
-- [ ] Phase directory created with NN-slug format
-- [ ] roadmap.md updated with new phase entry at correct position
-- [ ] index.json initialized in new phase directory with status = "pending"
-- [ ] Subsequent phases renumbered correctly (if --after N used)
-- [ ] state.json updated if renumbering affected tracked phases
-</success_criteria>
+---
+name: maestro-phase-add
+description: Add or insert a new phase into the project roadmap with automatic renumbering
+argument-hint: "<slug> <title> [--after N]"
+allowed-tools: [Read, Write, Edit, Bash, Glob, Grep, Agent, AskUserQuestion]
+---
+
+<purpose>
+Add a new phase to the project roadmap, either appending it at the end or inserting it after a specified phase number. Handles automatic renumbering of subsequent phase directories, updates roadmap.md with the new entry, and initializes the phase directory with an index.json so it is ready for planning.
+</purpose>
+
+<required_reading>
+@~/.maestro/workflows/phase-add.md
+</required_reading>
+
+<deferred_reading>
+- [index.json](~/.maestro/templates/index.json) — read when creating new phase index
+</deferred_reading>
+
+<context>
+$ARGUMENTS -- phase slug and title (required), optional --after N flag.
+
+**Flags:**
+- `--after N` -- Insert after phase N (renumbers subsequent phases). If omitted, appends at end.
+
+**State files:**
+- `.workflow/roadmap.md` -- milestone and phase structure
+- `.workflow/state.json` -- project-level state
+- `.workflow/phases/` -- existing phase directories
+</context>
+
+<execution>
+Follow '~/.maestro/workflows/phase-add.md' completely.
+
+**Next-step routing on completion:**
+- Plan the new phase → Skill({ skill: "maestro-plan", args: "{new_phase_number}" })
+- Analyze before planning → Skill({ skill: "maestro-analyze", args: "{new_phase_number}" })
+- View updated roadmap → Skill({ skill: "manage-status" })
+</execution>
+
+<error_codes>
+| Code | Meaning                          |
+|------|----------------------------------|
+| E001 | Phase name/slug required         |
+| E002 | roadmap.md not found             |
+| E003 | Duplicate phase name/slug exists |
+</error_codes>
+
+<success_criteria>
+- [ ] Phase directory created with NN-slug format
+- [ ] roadmap.md updated with new phase entry at correct position
+- [ ] index.json initialized in new phase directory with status = "pending"
+- [ ] Subsequent phases renumbered correctly (if --after N used)
+- [ ] state.json updated if renumbering affected tracked phases
+</success_criteria>