maestro-flow 0.1.0

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

@@ -0,0 +1,119 @@
+---
+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

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

@@ -0,0 +1,99 @@
+---
+name: maestro-analyze
+description: Multi-dimensional analysis with CLI exploration, decision extraction, and intent tracking
+argument-hint: "<phase|topic> [-y] [-c] [-q]"
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Bash
+  - Glob
+  - Grep
+  - Agent
+  - AskUserQuestion
+---
+<purpose>
+Perform multi-dimensional analysis of a technical proposal, decision, or architecture choice through iterative CLI-assisted exploration and interactive discussion. Produces a discussion timeline (discussion.md) with evolving understanding, multi-perspective findings, Decision Recording Protocol, Intent Coverage tracking, and a final conclusions package with Go/No-Go recommendation.
+
+Combines structured 6-dimension scoring with iterative deepening and decision extraction. Replaces both analysis and decision-capture workflows — produces analysis.md (scoring) AND context.md (Locked/Free/Deferred decisions for plan).
+
+Use `-q` for quick decision extraction only (skip exploration + scoring).
+</purpose>
+
+<required_reading>
+@~/.maestro/workflows/analyze.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
+</deferred_reading>
+
+<context>
+$ARGUMENTS -- phase number for phase mode, topic text for scratch mode, with optional flags.
+
+**Flags:**
+- `-y` / `--yes`: Auto mode — skip interactive scoping, use recommended defaults, auto-deepen
+- `-c` / `--continue`: Resume from existing session (auto-detect session folder + discussion.md)
+- `-q` / `--quick`: Quick mode — skip exploration + scoring, go straight to decision extraction (context.md only)
+
+**Phase mode** (number): resolves phase directory from state.json + roadmap, updates index.json status to "exploring".
+**Scratch mode** (text): creates `.workflow/scratch/analyze-{slug}-{date}/` with index.json from scratch-index template (type="analyze").
+
+**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) |
+</context>
+
+<execution>
+Follow '~/.maestro/workflows/analyze.md' completely.
+
+**Handoff:** context.md is consumed by maestro-plan (Step 4 loads Locked/Free/Deferred decisions).
+
+**Next-step routing on completion:**
+
+Phase mode:
+- Go recommendation, UI work needed → Skill({ skill: "maestro-ui-design", args: "{phase}" })
+- Go recommendation, ready to plan → Skill({ skill: "maestro-plan", args: "{phase}" })
+- No-Go recommendation → revisit requirements or Skill({ skill: "maestro-brainstorm", args: "{topic}" })
+
+Scratch mode:
+- Ready to plan → Skill({ skill: "maestro-plan", args: "--dir {scratch_dir}" })
+- Need more exploration → Skill({ skill: "maestro-analyze", args: "{topic} -c" })
+</execution>
+
+<error_codes>
+| Code | Severity | Condition | Recovery |
+|------|----------|-----------|----------|
+| E001 | error | Analysis subject required (no arguments provided) | Prompt user for phase number or topic text |
+| E002 | error | Phase directory not found | List available phases, prompt user to select |
+| W001 | warning | CLI exploration failed | Continue with available context, note limitation |
+| W002 | warning | CLI analysis timeout | Retry with shorter prompt, or skip perspective |
+| W003 | warning | Insufficient evidence for scoring dimensions | Note low-confidence dimensions, proceed with available evidence |
+| W004 | warning | Max rounds reached (5) | Force synthesis, offer continuation option |
+</error_codes>
+
+<success_criteria>
+Full mode:
+- [ ] CLI exploration completed with code anchors and call chains
+- [ ] discussion.md created with full timeline, TOC, Current Understanding
+- [ ] analysis.md written with all 6 dimensions scored with evidence
+- [ ] conclusions.json created with recommendations and decision trail
+- [ ] Intent Coverage tracked and verified (no unresolved ❌ items)
+
+Both modes (full + quick):
+- [ ] context.md written with all decisions classified as Locked/Free/Deferred
+- [ ] Gray areas identified through phase-specific analysis
+- [ ] Decision Recording Protocol applied to all decisions
+- [ ] Scope creep redirected to Deferred section
+- [ ] Deferred items auto-created as issues (if any)
+- [ ] project.md Key Decisions updated with Locked decisions (phase mode)
+- [ ] Next step routed (ui-design/plan for Go, brainstorm for No-Go)
+- [ ] index.json timestamps updated
+</success_criteria>

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

@@ -0,0 +1,90 @@
+---
+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
+</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.
+**Phase mode** (number): resolves phase directory, creates .brainstorming/ inside it.
+**Scratch mode** (text): creates `.workflow/scratch/brainstorm-{slug}-{date}/`.
+
+**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-init" })
+- Project initialized, need spec package → Skill({ skill: "maestro-spec-generate", args: "--from-brainstorm {session_id}" })
+- Project initialized, quick roadmap → Skill({ skill: "maestro-roadmap", args: "--from-brainstorm {session_id}" })
+- Need deeper analysis first → Skill({ skill: "maestro-analyze", args: "{topic}" })
+
+Single role mode:
+- More roles needed → Skill({ skill: "maestro-brainstorm", args: "{next_role} --session {session_id}" })
+- All roles done, run synthesis → Skill({ skill: "maestro-brainstorm", args: "{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
+- [ ] Role analysis files for each selected role in `.brainstorming/{role}/`
+- [ ] Feature specs in `.brainstorming/feature-specs/` (or synthesis-specification.md)
+- [ ] feature-index.json and synthesis-changelog.md
+- [ ] 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/commands/maestro-coordinate.md

@@ -0,0 +1,65 @@
+---
+name: maestro-coordinate
+description: CLI-based coordinator - analyze intent → select command chain → execute sequentially via maestro cli with auto-confirm
+argument-hint: "\"intent text\" [-y] [-c] [--dry-run] [--chain <name>] [--tool <tool>]"
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Bash
+  - Glob
+  - Grep
+  - Agent
+  - AskUserQuestion
+---
+<purpose>
+Orchestrate maestro commands via external CLI (`maestro cli`) with async state machine.
+Classifies intent, reads project state, selects command chain, then executes each step
+through `maestro cli --tool <tool> --mode write` with a universal prompt template.
+Auto-confirm injection ensures non-blocking background execution. Structured return
+format enables context propagation between steps.
+</purpose>
+
+<required_reading>
+@~/.maestro/workflows/maestro-coordinate.md
+</required_reading>
+
+<deferred_reading>
+- [coordinate template](~/.maestro/templates/cli/prompts/coordinate-step.txt) — read when filling step prompts
+</deferred_reading>
+
+<context>
+$ARGUMENTS — user intent text, or special keywords (`continue`/`next`/`status`).
+
+**Flags:**
+- `-y` / `--yes` — Auto mode: skip clarification and confirmation
+- `-c` / `--continue` — Resume previous session
+- `--dry-run` — Show planned chain without executing
+- `--chain <name>` — Force a specific chain
+- `--tool <tool>` — CLI tool override (default: claude)
+</context>
+
+<execution>
+Follow '~/.maestro/workflows/maestro-coordinate.md' completely.
+</execution>
+
+<error_codes>
+| Code | Severity | Description | Recovery |
+|------|----------|-------------|----------|
+| E001 | error | No intent and project not initialized | Suggest maestro-init |
+| E002 | error | Clarity too low after 2 rounds | Ask to rephrase |
+| E003 | error | Step failed + abort | Suggest resume with -c |
+| E004 | error | Resume session not found | Show available sessions |
+| E005 | error | CLI tool unavailable | Try fallback tool |
+</error_codes>
+
+<success_criteria>
+- [ ] Intent classified and chain selected via detectTaskType + chainMap
+- [ ] Each step executed via `maestro cli` with coordinate-step template
+- [ ] Auto-confirm injected, structured return parsed
+- [ ] Each completed step analyzed via `maestro cli --tool gemini --mode analysis`
+- [ ] Analysis hints injected into next step prompt via `{{ANALYSIS_HINTS}}`
+- [ ] Gemini sessions chained via `--resume` for accumulated context
+- [ ] Session state at .workflow/.maestro-coordinate/{session_id}/
+- [ ] Completion report with per-step status and quality scores
+</success_criteria>

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

@@ -0,0 +1,86 @@
+---
+name: maestro-execute
+description: Execute phase plan with wave-based parallel execution and atomic commits
+argument-hint: "<phase> [--auto-commit] [--method agent|cli] [--dir <path>]"
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Bash
+  - Glob
+  - Grep
+  - Agent
+  - AskUserQuestion
+---
+<purpose>
+Execute all tasks in a phase plan using wave-based parallel execution with dependency-aware ordering. Invoked after Skill({ skill: "maestro-plan" }) produces a confirmed plan.json. Produces task summaries, updated task statuses, commits, and execution progress in index.json.
+</purpose>
+
+<required_reading>
+@~/.maestro/workflows/execute.md
+</required_reading>
+
+<deferred_reading>
+- [task.json](~/.maestro/templates/task.json) — read when reading task definitions
+- [index.json](~/.maestro/templates/index.json) — read when updating phase index
+</deferred_reading>
+
+<context>
+Phase: $ARGUMENTS (required -- phase number or slug)
+
+**Flags:**
+- `--auto-commit` -- Automatically commit after each task completion
+- `--method agent|cli` -- Override execution method (default: from config.json or index.json)
+- `--dir <path>` -- Use arbitrary directory instead of phase resolution (scratch mode, skip roadmap validation)
+
+Context files resolved from `.workflow/phases/{NN}-{slug}/` (or `--dir` path):
+- index.json (phase metadata + plan.waves + execution progress)
+- plan.json (plan overview)
+- .task/TASK-{NNN}.json (individual task definitions, lazy-loaded per wave)
+
+**executionContext handoff:** If received from Skill({ skill: "maestro-plan" }) confirmation, skip disk reload and use in-memory plan + explorations + clarifications.
+</context>
+
+<execution>
+Follow '~/.maestro/workflows/execute.md' completely.
+
+**Report format on completion:**
+
+```
+=== EXECUTION COMPLETE ===
+Phase:     {phase_name}
+Completed: {completed_count}/{total_count} tasks
+Failed:    {failed_count} tasks
+Waves:     {waves_executed}/{total_waves}
+
+Summaries: {phase_dir}/.summaries/
+Tasks:     {phase_dir}/.task/
+
+Next steps:
+  Skill({ skill: "maestro-verify", args: "{phase}" })  -- Verify execution results
+  Skill({ skill: "manage-status" })          -- View project dashboard
+```
+
+If this was a gap-fix execution (plan originated from `--gaps`), emphasize re-verification:
+  "Gap-fix execution complete. Run Skill({ skill: "maestro-verify", args: "{phase}" }) to confirm gaps are resolved."
+
+If failed tasks exist, suggest Skill({ skill: "quality-debug" }) for investigation.
+</execution>
+
+<error_codes>
+| Code | Severity | Condition | Recovery |
+|------|----------|-----------|----------|
+| E001 | error | Phase argument required | Check arguments format, re-run with correct input |
+| E002 | error | Phase directory not found | Check arguments format, re-run with correct input |
+| E003 | error | plan.json not found in phase 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 tasks executed (completed or explicitly failed)
+- [ ] `.summaries/TASK-{NNN}-summary.md` written for each completed task
+- [ ] `.task/TASK-{NNN}.json` statuses updated
+- [ ] index.json execution progress updated
+- [ ] state.json project progress updated
+</success_criteria>

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

@@ -0,0 +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>

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

@@ -0,0 +1,63 @@
+---
+name: maestro-link-coordinate
+description: Step-mode graph coordinator via maestro coordinate endpoint — executes chain nodes one by one with session tracking
+argument-hint: "\"intent text\" [--list] [-c [sessionId]] [--chain <name>] [--tool <tool>] [-y]"
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Bash
+  - Glob
+  - Grep
+  - Agent
+---
+<purpose>
+Step-mode workflow coordinator using `maestro coordinate` CLI subcommands (start/next/status).
+Walks chain graphs node by node — each command node executed via `maestro cli` internally.
+Decision/gate/eval nodes auto-resolve between steps. Session persisted for resume.
+</purpose>
+
+<required_reading>
+@~/.maestro/workflows/maestro-link-coordinate.md
+</required_reading>
+
+<context>
+$ARGUMENTS — user intent text, or flags.
+
+**Flags:**
+- `--list` — List all available chain graphs
+- `-c` / `--continue [sessionId]` — Resume step_paused session via `coordinate next`
+- `--chain <name>` — Force a specific chain graph
+- `--tool <tool>` — CLI tool override (default: claude)
+- `-y` / `--yes` — Auto mode
+
+**CLI endpoints used:**
+- `maestro coordinate list` — enumerate chains
+- `maestro coordinate start "intent" --chain X` — begin step-mode session
+- `maestro coordinate next [sessionId]` — advance one step
+- `maestro coordinate status [sessionId]` — query state
+- `maestro coordinate run "intent"` — autonomous full run
+</context>
+
+<execution>
+Follow '~/.maestro/workflows/maestro-link-coordinate.md' completely.
+</execution>
+
+<error_codes>
+| Code | Severity | Description | Recovery |
+|------|----------|-------------|----------|
+| E001 | error | No intent and no --list/--chain | Suggest --list |
+| E002 | error | Chain graph not found | Show list output |
+| E003 | error | Step execution failed | Check status, retry next |
+| E004 | error | Resume session not found | List sessions |
+| E005 | error | CLI endpoint unavailable | Check maestro installation |
+</error_codes>
+
+<success_criteria>
+- [ ] Chain graph loaded via `maestro coordinate start`
+- [ ] Each step executed via `maestro coordinate next` loop
+- [ ] JSON output parsed for session tracking
+- [ ] Decision nodes auto-resolved between steps
+- [ ] Session persisted and resumable via `-c`
+- [ ] Completion summary displayed
+</success_criteria>

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

@@ -0,0 +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>