maestro-flow 0.3.8 → 0.3.9

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

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

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

@@ -48,13 +48,13 @@ Created:
   .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)
+  /maestro-spec-generate <idea>                                -- Full spec package + roadmap (heavy)
+  /maestro-roadmap <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
+  /manage-status                                               -- View project dashboard
+  /maestro-brainstorm <topic>                                  -- Explore ideas first
+  /maestro-quick <task>                                        -- Quick ad-hoc task
 ```
 </execution>
 
@@ -70,7 +70,7 @@ Other commands:
 <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/state.json` created with artifacts[] array, 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

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

@@ -0,0 +1,77 @@
+---
+name: maestro-merge
+description: Two-phase merge of milestone worktree branch back — git merge first, artifact sync only on success
+argument-hint: "-m <milestone-number> [--force] [--dry-run] [--no-cleanup] [--continue]"
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Bash
+  - Glob
+  - Grep
+  - Agent
+  - AskUserQuestion
+---
+<purpose>
+Merge a completed milestone worktree branch back into the main branch, sync workflow artifacts for all phases, and reconcile project state. Uses a two-phase approach: git merge first (source code), artifact sync second (only after git succeeds). This prevents partial state corruption when merge conflicts occur.
+
+Includes registry health check, pre-merge rebase (pull main into worktree to minimize conflicts), and atomic state reconciliation (patch, don't overwrite).
+</purpose>
+
+<required_reading>
+@~/.maestro/workflows/merge.md
+</required_reading>
+
+<context>
+$ARGUMENTS -- milestone name and optional flags.
+
+**Flags:**
+- `-m <N>` or bare `<N>`: Milestone number (1-based, maps to registry)
+- `--force`: Merge even if not all phases are completed
+- `--dry-run`: Show what would be merged without executing
+- `--no-cleanup`: Keep worktree and branch after merge (for inspection)
+- `--continue`: Resume a merge that was paused due to git conflict
+
+**Merge sequence:**
+1. Registry health check (remove stale entries)
+2. Validate phase readiness across all owned phases
+3. Pre-merge rebase (`git merge main` in worktree)
+4. Phase 1: Git merge (source code only)
+5. Phase 2: Artifact sync (only after git merge succeeds)
+6. Atomic state reconciliation
+7. Cleanup (worktree remove + branch delete)
+
+**Conflict handling:**
+If git merge fails, the command saves state to `.workflow/.merge-state.json` and exits. User resolves conflicts, then runs `maestro-merge --continue` to resume artifact sync.
+</context>
+
+<execution>
+Follow '~/.maestro/workflows/merge.md' completely.
+
+**Next-step routing on completion:**
+- View dashboard → Skill({ skill: "manage-status" })
+- Audit milestone → Skill({ skill: "maestro-milestone-audit" })
+</execution>
+
+<error_codes>
+| Code | Severity | Condition | Recovery |
+|------|----------|-----------|----------|
+| E001 | error | Running inside a worktree | Run from main worktree |
+| E002 | error | No worktree registry found | Nothing to merge |
+| E003 | error | --continue but no merge state | Start fresh merge |
+| E004 | error | No milestone number provided | Provide `-m <N>` |
+| W001 | warning | Stale registry entries found | Auto-cleaned |
+| W002 | warning | Incomplete phases (without --force) | Confirm or use --force |
+| W003 | warning | Conflict pulling main into worktree | Resolve in worktree first |
+</error_codes>
+
+<success_criteria>
+- [ ] Registry health check passed (stale entries cleaned)
+- [ ] Pre-merge rebase successful (worktree has latest main)
+- [ ] Git merge completed without conflicts (or conflicts resolved via --continue)
+- [ ] All owned phase artifacts synced to main `.workflow/phases/`
+- [ ] `state.json` reconciled (phases_summary, accumulated_context, transition_history patched)
+- [ ] `roadmap.md` completed phases marked
+- [ ] Worktree removed and branch deleted (unless --no-cleanup)
+- [ ] Registry updated (entry removed)
+</success_criteria>

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

@@ -1,60 +1,72 @@
----
-name: maestro-milestone-audit
-description: Audit current milestone for cross-phase integration gaps
-argument-hint: "[<milestone>]"
-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>]"
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+  - Glob
+  - Grep
+  - Agent
+  - AskUserQuestion
+---
+
+<purpose>
+Audit milestone completion using the artifact registry. Checks:
+1. Phase coverage — every phase in roadmap has plan + execute artifacts (completed)
+2. Ad-hoc completeness — all adhoc artifacts are completed (or explicitly skipped)
+3. Execution completeness — all tasks in executed plans are completed
+4. Cross-artifact integration — interfaces, data contracts, configuration consistency
+
+Data source: `state.json.artifacts[]` filtered by current milestone.
+Produces audit report at `.workflow/milestones/{milestone}/audit-report.md`.
+</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 have completed execute artifacts.
+
+**Data source:**
+- `.workflow/state.json` — artifacts[], current_milestone, milestones[]
+- `.workflow/roadmap.md` — milestone-to-phase mapping
+- Plan scratch dirs — for task status verification
+</context>
+
+<execution>
+Follow '~/.maestro/workflows/milestone-audit.md' completely.
+
+**Audit checklist (from architecture):**
+1. Phase coverage: each phase in roadmap has analyze → plan → execute chain
+2. Ad-hoc completeness: all adhoc artifacts completed or skipped
+3. Execution completeness: all tasks in executed plans completed
+4. Cross-artifact integration: interface compatibility, data contracts, config consistency
+
+**Next-step routing on completion:**
+- Verdict PASS → `/maestro-milestone-complete {milestone}`
+- Verdict FAIL, integration gaps → `/maestro-plan --gaps`
+- Verdict FAIL, incomplete execution → `/maestro-execute`
+</execution>
+
+<error_codes>
+| Code | Severity | Condition | Recovery |
+|------|----------|-----------|----------|
+| E001 | error | Milestone identifier required | Check arguments format |
+| E002 | error | Milestone not found in state.json | Check milestone ID |
+| E003 | error | No execute artifacts found for milestone | Run maestro-execute first |
+| W001 | warning | Some phases lack complete artifact chains | Review incomplete phases |
+</error_codes>
+
+<success_criteria>
+- [ ] All phases in milestone identified from roadmap
+- [ ] Artifact chains verified (ANL→PLN→EXC) per phase
+- [ ] Ad-hoc artifacts checked for completion
+- [ ] Integration check completed (shared interfaces, data contracts)
+- [ ] Audit report written with clear PASS/FAIL verdict
+- [ ] Next-step routing provided
+</success_criteria>

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

@@ -1,59 +1,67 @@
----
-name: maestro-milestone-complete
-description: Archive completed milestone and prepare for next
-argument-hint: "[<milestone>]"
-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:**
-- Cut a release for this milestone → Skill({ skill: "maestro-milestone-release" })
-- 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>]"
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+  - Glob
+  - Grep
+  - Agent
+  - AskUserQuestion
+---
+
+<purpose>
+Mark a milestone as complete after its audit has passed. Archives all scratch artifacts to `milestones/{M}/artifacts/`, moves artifact entries from `state.json.artifacts[]` to `milestone_history`, extracts final learnings, and advances to 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:** `/maestro-milestone-audit` should have passed.
+
+**State files:**
+- `.workflow/state.json` — artifacts[], milestones[], current_milestone, milestone_history[]
+- `.workflow/roadmap.md` — milestone structure
+- `.workflow/milestones/{milestone}/audit-report.md` — audit results
+</context>
+
+<execution>
+Follow '~/.maestro/workflows/milestone-complete.md' completely.
+
+**Archive flow:**
+1. Validate audit passed + all artifacts completed
+2. Move scratch dirs to `milestones/{M}/artifacts/`
+3. Move artifact entries to `milestone_history[M].archived_artifacts`
+4. Extract learnings from summaries → `specs/learnings.md`
+5. Update state.json: advance to next milestone, clear artifacts[]
+6. Clean scratch dirs
+
+**Next-step routing on completion:**
+- Cut a release → `/maestro-milestone-release`
+- Next milestone → `/maestro-analyze` or `/maestro-plan 1`
+- View state → `/manage-status`
+</execution>
+
+<error_codes>
+| Code | Severity | Condition | Recovery |
+|------|----------|-----------|----------|
+| E001 | error | Milestone identifier required | Check arguments |
+| E002 | error | Audit not passed | Run maestro-milestone-audit first |
+| E003 | error | Incomplete artifacts remain | Complete remaining work first |
+</error_codes>
+
+<success_criteria>
+- [ ] Audit report verified as PASS
+- [ ] Scratch artifacts moved to milestones/{M}/artifacts/
+- [ ] Artifact entries archived to milestone_history
+- [ ] Learnings extracted to specs/learnings.md
+- [ ] state.json updated: next milestone as current, artifacts[] cleared
+- [ ] Roadmap snapshot saved
+- [ ] project.md Context updated with milestone summary
+</success_criteria>

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

@@ -14,7 +14,7 @@ allowed-tools:
 ---
 
 <purpose>
-Package a completed milestone into a releasable version. Bumps the project version (e.g. `package.json`, `pyproject.toml`, or language-specific manifest), generates or appends a changelog entry from phase/milestone summaries and git log, creates an annotated git tag, and optionally pushes to the remote. Runs after Skill({ skill: "maestro-milestone-complete" }) has archived the milestone; serves as the final delivery step in the SDLC loop.
+Package a completed milestone into a releasable version. Bumps the project version (e.g. `package.json`, `pyproject.toml`, or language-specific manifest), generates or appends a changelog entry from phase/milestone summaries and git log, creates an annotated git tag, and optionally pushes to the remote. Runs after `/maestro-milestone-complete` has archived the milestone; serves as the final delivery step in the SDLC loop.
 </purpose>
 
 <required_reading>
@@ -39,7 +39,7 @@ $ARGUMENTS -- optional explicit version string and flags.
 - Version manifest -- `package.json` / `pyproject.toml` / `Cargo.toml` / etc. (auto-detected)
 
 **Preconditions:**
-- Current milestone must be completed (audit PASS + Skill({ skill: "maestro-milestone-complete" }) run)
+- Current milestone must be completed (audit PASS + `/maestro-milestone-complete` run)
 - Working tree must be clean (no uncommitted changes) unless `--dry-run`
 </context>
 
@@ -65,8 +65,8 @@ Changelog: {N} entries written to CHANGELOG.md
 Manifest:  {file_path} updated
 
 Next steps:
-  Skill({ skill: "maestro-plan", args: "{next_phase}" })  -- Start next milestone's first phase
-  Skill({ skill: "manage-status" })                        -- View project dashboard
+  /maestro-plan {next_phase}   -- Start next milestone's first phase
+  /manage-status               -- View project dashboard
 ```
 
 For `--dry-run`, print the computed version, changelog diff, and tag name without side effects.
@@ -75,8 +75,8 @@ For `--dry-run`, print the computed version, changelog diff, and tag name withou
 <error_codes>
 | Code | Severity | Condition | Recovery |
 |------|----------|-----------|----------|
-| E001 | error | Current milestone not completed (no milestone-complete run) | Run Skill({ skill: "maestro-milestone-complete" }) first |
-| E002 | error | Audit verdict not PASS | Re-run Skill({ skill: "maestro-milestone-audit" }) and resolve findings |
+| E001 | error | Current milestone not completed (no milestone-complete run) | Run `/maestro-milestone-complete` first |
+| E002 | error | Audit verdict not PASS | Re-run `/maestro-milestone-audit` and resolve findings |
 | E003 | error | Working tree not clean (uncommitted changes) | Commit or stash changes, then retry |
 | E004 | error | Version manifest not found / unsupported | Add supported manifest or pass `<version>` explicitly with `--no-tag` |
 | E005 | error | Target version not greater than current (would break semver monotonicity) | Choose a higher version or run with explicit `<version>` |