maestro-flow 0.5.2 → 0.5.31

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

@@ -1,131 +1,130 @@
----
-name: maestro-init
-description: Initialize project with auto state detection
-argument-hint: "[-y] [--from <source>]"
-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-roadmap (light mode, default) or maestro-roadmap --mode full (spec package) as the next step.
-
-Pipeline position: entry point (no upstream). Downstream: `maestro-roadmap` or `maestro-brainstorm`.
-</purpose>
-
-<required_reading>
-@~/.maestro/workflows/init.md
-</required_reading>
-
-<deferred_reading>
-- [project.md](~/.maestro/templates/project.md) — read when generating project description
-- [state.json](~/.maestro/templates/state.json) — read when creating initial state
-- [config.json](~/.maestro/templates/config.json) — read when creating workflow configuration
-</deferred_reading>
-
-<context>
-$ARGUMENTS — none for interactive mode, or `-y` with `@file` reference for auto mode.
-
-**Flags:**
-
-| Flag | Effect | Default |
-|------|--------|---------|
-| `-y` / `--yes` | Automatic mode. After config questions, runs research without further interaction. Expects idea document via @ reference. | `false` |
-| `--from <source>` | Load upstream context package (brainstorm:ID, @file, or path). Consumes context-package.json to pre-fill project vision, goals, constraints, and terminology. Skips interactive questioning. Alias: `--from-brainstorm` | — |
-
-**Load project state if exists:**
-Check for `.workflow/state.json` -- loads context if project already initialized.
-</context>
-
-<interview_protocol>
-Follows @~/.maestro/workflows/interview-mechanics.md standard.
-
-**Interaction mode**: convergent menu-driven
-**Decision tree** (strict order): project type (greenfield / existing codebase onboarding) → tech stack detection and confirmation → directory structure preferences → initial configuration (specs categories, wiki bootstrap)
-**Scope guard**: only init decisions; do not prejudge roadmap structure or plan scope
-**Writeback target**: project.md (project description) + config.json (settings) + state.json (initial state)
-**Additional skip conditions**: --from source (upstream context pre-fills decisions)
-**Exit condition**: all configuration questions settled → proceed to workflow execution
-</interview_protocol>
-
-<execution>
-### Pre-flight
-
-1. Check if `.workflow/` already exists — if so, load state and warn (E002 for greenfield conflicts)
-2. Validate `--from` source is accessible if provided
-
-Follow '~/.maestro/workflows/init.md' completely.
-
-### Artifact Verification (before completion)
-
-```
-REQUIRED_ARTIFACTS = [
-  ".workflow/project.md",    // Core Value, Requirements, Key Decisions
-  ".workflow/state.json",    // artifacts[], initialized to idle state
-  ".workflow/config.json"    // Workflow configuration
-]
-```
-If any artifact is missing: DO NOT report completion. Write the missing file first.
-</execution>
-
-<completion>
-### Standalone report
-
-```
-=== WORKFLOW INITIALIZED ===
-Project: {project_name}
-State:   .workflow/state.json (active)
-
-Created:
-  .workflow/project.md
-  .workflow/state.json
-  .workflow/config.json
-  .workflow/specs/
-```
-
-### Ralph-invoked completion
-
-End the step by calling the CLI (no text block output):
-```
-maestro ralph complete <idx> --status {STATUS} [--evidence {path}]
-```
-
-Status verdicts:
-- **DONE** — Normal completion
-- **DONE_WITH_CONCERNS** — Completed with caveats; pass `--concerns`
-- **NEEDS_RETRY** — Tooling error / transient issue; ralph will retry
-- **BLOCKED** — External hard blocker; pass `--reason`
-
-### Next-step routing
-
-| Condition | Suggestion |
-|-----------|-----------|
-| Roadmap needed (default light) | `/maestro-roadmap <requirement>` |
-| Full spec package + roadmap | `/maestro-roadmap --mode full <idea>` |
-| Explore ideas first | `/maestro-brainstorm <topic>` |
-| View project dashboard | `/manage-status` |
-| Quick ad-hoc task | `/maestro-quick <task>` |
-</completion>
-
-<error_codes>
-| Code | Severity | Condition | Recovery |
-|------|----------|-----------|----------|
-| E001 | error | No arguments provided when -y 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 | Context source not found (--from / --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>
-- [ ] `.workflow/project.md` created with Core Value, Requirements (Validated/Active/Out of Scope), Key Decisions
-- [ ] `.workflow/state.json` created with artifacts[] array, initialized to idle state
-- [ ] `.workflow/config.json` created with workflow / execution / git / gates / codebase / guard / collab / specInjection / dashboard segments
-- [ ] `.workflow/specs/` initialized with convention files
-- [ ] All interview decisions written to project.md / config.json before proceeding
-- [ ] Research completed (if enabled) — parallel agents spawned with results merged
-- [ ] Next-step routing displayed in completion report
-</success_criteria>
+---
+name: maestro-init
+description: Initialize project with auto state detection
+argument-hint: "[-y] [--from <source>]"
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+  - Glob
+  - Grep
+  - Agent
+  - AskUserQuestion
+---
+<purpose>
+Initialize project: detect state, create `.workflow/` with project.md, state.json, config.json.
+Entry point; downstream: maestro-roadmap or maestro-brainstorm.
+</purpose>
+
+<required_reading>
+@~/.maestro/workflows/init.md
+</required_reading>
+
+<deferred_reading>
+- [project.md](~/.maestro/templates/project.md) — read when generating project description
+- [state.json](~/.maestro/templates/state.json) — read when creating initial state
+- [config.json](~/.maestro/templates/config.json) — read when creating workflow configuration
+</deferred_reading>
+
+<context>
+$ARGUMENTS — none for interactive mode, or `-y` with `@file` reference for auto mode.
+
+**Flags:**
+
+| Flag | Effect | Default |
+|------|--------|---------|
+| `-y` / `--yes` | Automatic mode. After config questions, runs research without further interaction. Expects idea document via @ reference. | `false` |
+| `--from <source>` | Load upstream context package (brainstorm:ID, @file, or path). Consumes context-package.json to pre-fill project vision, goals, constraints, and terminology. Skips interactive questioning. Alias: `--from-brainstorm` | — |
+
+**Load project state if exists:**
+Check for `.workflow/state.json` -- loads context if project already initialized.
+</context>
+
+<interview_protocol>
+Follows @~/.maestro/workflows/interview-mechanics.md standard.
+
+**Interaction mode**: convergent menu-driven
+**Decision tree** (strict order): project type (greenfield / existing codebase onboarding) → tech stack detection and confirmation → directory structure preferences → initial configuration (specs categories, wiki bootstrap)
+**Scope guard**: only init decisions; do not prejudge roadmap structure or plan scope
+**Writeback target**: project.md (project description) + config.json (settings) + state.json (initial state)
+**Additional skip conditions**: --from source (upstream context pre-fills decisions)
+**Exit condition**: all configuration questions settled → proceed to workflow execution
+</interview_protocol>
+
+<execution>
+### Pre-flight
+
+1. Check if `.workflow/` already exists — if so, load state and warn (E002 for greenfield conflicts)
+2. Validate `--from` source is accessible if provided
+
+Follow '~/.maestro/workflows/init.md' completely.
+
+### Artifact Verification (before completion)
+
+```
+REQUIRED_ARTIFACTS = [
+  ".workflow/project.md",    // Core Value, Requirements, Key Decisions
+  ".workflow/state.json",    // artifacts[], initialized to idle state
+  ".workflow/config.json"    // Workflow configuration
+]
+```
+If any artifact is missing: DO NOT report completion. Write the missing file first.
+</execution>
+
+<completion>
+### Standalone report
+
+```
+=== WORKFLOW INITIALIZED ===
+Project: {project_name}
+State:   .workflow/state.json (active)
+
+Created:
+  .workflow/project.md
+  .workflow/state.json
+  .workflow/config.json
+  .workflow/specs/
+```
+
+### Ralph-invoked completion
+
+End the step by calling the CLI (no text block output):
+```
+maestro ralph complete <idx> --status {STATUS} [--evidence {path}]
+```
+
+Status verdicts:
+- **DONE** — Normal completion
+- **DONE_WITH_CONCERNS** — Completed with caveats; pass `--concerns`
+- **NEEDS_RETRY** — Tooling error / transient issue; ralph will retry
+- **BLOCKED** — External hard blocker; pass `--reason`
+
+### Next-step routing
+
+| Condition | Suggestion |
+|-----------|-----------|
+| Roadmap needed (default light) | `/maestro-roadmap <requirement>` |
+| Full spec package + roadmap | `/maestro-roadmap --mode full <idea>` |
+| Explore ideas first | `/maestro-brainstorm <topic>` |
+| View project dashboard | `/manage-status` |
+| Quick ad-hoc task | `/maestro-quick <task>` |
+</completion>
+
+<error_codes>
+| Code | Severity | Condition | Recovery |
+|------|----------|-----------|----------|
+| E001 | error | No arguments provided when -y 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 | Context source not found (--from / --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>
+- [ ] `.workflow/project.md` created with Core Value, Requirements (Validated/Active/Out of Scope), Key Decisions
+- [ ] `.workflow/state.json` created with artifacts[] array, initialized to idle state
+- [ ] `.workflow/config.json` created with workflow / execution / git / gates / codebase / guard / collab / specInjection / dashboard segments
+- [ ] `.workflow/specs/` initialized with convention files
+- [ ] All interview decisions written to project.md / config.json before proceeding
+- [ ] Research completed (if enabled) — parallel agents spawned with results merged
+- [ ] Next-step routing displayed in completion report
+</success_criteria>

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

@@ -1,80 +1,87 @@
----
-name: maestro-merge
-description: Merge milestone worktree branch back to main
-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 scratch artifacts, and reconcile the artifact registry. 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 (merge artifact entries, don't overwrite).
-</purpose>
-
-<required_reading>
-@~/.maestro/workflows/merge.md
-</required_reading>
-
-<context>
-$ARGUMENTS -- milestone number and optional flags.
-
-Flags (`-m`, `--force`, `--dry-run`, `--no-cleanup`, `--continue`), merge sequence, artifact sync detail, and conflict handling are defined in workflow `merge.md`.
-</context>
-
-<execution>
-Follow '~/.maestro/workflows/merge.md' completely.
-
-### Phase Gates (MANDATORY, BLOCKING)
-
-**GATE 1: Pre-merge → Git Merge**
-- REQUIRED: Registry health check completed (stale entries cleaned or flagged).
-- REQUIRED: Pre-merge rebase successful (worktree has latest main).
-- BLOCKED if rebase has conflicts: resolve in worktree first (W003).
-
-**GATE 2: Git Merge → Artifact Sync**
-- REQUIRED: Git merge completed without conflicts (or conflicts resolved via --continue).
-- Do NOT sync artifacts until git merge succeeds — prevents partial state corruption.
-
-**GATE 3: Artifact Sync → Completion**
-- REQUIRED: All scratch artifacts synced to main `.workflow/scratch/`.
-- REQUIRED: `state.json.artifacts[]` reconciled (worktree entries merged into main).
-- REQUIRED: Worktree cleaned up (unless --no-cleanup).
-
-**Knowledge inquiry on completion:**
-After successful merge, ask user once: "Record milestone learnings?" If yes, persist via `Skill("spec-add", "learning \"<title>\" \"<insight>\" --keywords <kw1>,<kw2> --description \"<summary>\"")`.
-
-**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 artifacts (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 scratch artifacts synced to main `.workflow/scratch/`
-- [ ] `state.json.artifacts[]` reconciled (worktree entries merged into main)
-- [ ] Milestone `"forked"` flag removed in `state.json.milestones[]`
-- [ ] `roadmap.md` completed phases marked
-- [ ] Worktree removed and branch deleted (unless --no-cleanup)
-- [ ] `worktrees.json` registry updated (entry removed)
-</success_criteria>
+---
+name: maestro-merge
+description: Merge milestone worktree branch back to main
+argument-hint: "-m <milestone-number> [--force] [--dry-run] [--no-cleanup] [--continue]"
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Bash
+  - Glob
+  - Grep
+  - Agent
+  - AskUserQuestion
+---
+<purpose>
+Merge a milestone worktree branch back into main, sync scratch artifacts, and reconcile the artifact registry.
+Two-phase: git merge first, artifact sync second (only after git succeeds).
+</purpose>
+
+<required_reading>
+@~/.maestro/workflows/merge.md
+</required_reading>
+
+<context>
+$ARGUMENTS -- milestone number and optional flags.
+
+Flags (`-m`, `--force`, `--dry-run`, `--no-cleanup`, `--continue`), merge sequence, artifact sync detail, and conflict handling are defined in workflow `merge.md`.
+</context>
+
+<execution>
+Follow '~/.maestro/workflows/merge.md' completely.
+
+### Phase Gates (MANDATORY, BLOCKING)
+
+**GATE 1: Pre-merge → Git Merge**
+- REQUIRED: Registry health check completed (stale entries cleaned or flagged).
+- REQUIRED: Pre-merge rebase successful (worktree has latest main).
+- BLOCKED if rebase has conflicts: resolve in worktree first (W003).
+
+**GATE 2: Git Merge → Artifact Sync**
+- REQUIRED: Git merge completed without conflicts (or conflicts resolved via --continue).
+- BLOCKED if: merge has unresolved conflicts — do NOT sync artifacts until git merge succeeds (prevents partial state corruption).
+
+**GATE 3: Artifact Sync → Completion**
+- REQUIRED: All scratch artifacts synced to main `.workflow/scratch/`.
+- REQUIRED: `state.json.artifacts[]` reconciled (worktree entries merged into main).
+- REQUIRED: Worktree cleaned up (unless --no-cleanup).
+- BLOCKED if missing: artifacts not synced or registry not reconciled — main worktree would have incomplete state.
+
+</execution>
+
+<completion>
+### Knowledge inquiry
+
+After successful merge, ask user once: "Record milestone learnings?" If yes, persist via `Skill("spec-add", "learning \"<title>\" \"<insight>\" --keywords <kw1>,<kw2> --description \"<summary>\"")`.
+
+### Next-step routing
+
+| Condition | Suggestion |
+|-----------|-----------|
+| Merge complete | Skill({ skill: "manage-status" }) |
+| Audit needed | Skill({ skill: "maestro-milestone-audit" }) |
+</completion>
+
+<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 artifacts (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 scratch artifacts synced to main `.workflow/scratch/`
+- [ ] `state.json.artifacts[]` reconciled (worktree entries merged into main)
+- [ ] Milestone `"forked"` flag removed in `state.json.milestones[]`
+- [ ] `roadmap.md` completed phases marked
+- [ ] Worktree removed and branch deleted (unless --no-cleanup)
+- [ ] `worktrees.json` registry updated (entry removed)
+</success_criteria>

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

@@ -13,16 +13,8 @@ allowed-tools:
 ---
 
 <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`.
-
-Pipeline position: downstream of maestro-execute (which includes verification), upstream of maestro-milestone-complete.
+Audit milestone for phase coverage, execution completeness, and integration gaps.
+Produces audit-report.md with PASS/FAIL verdict.
 </purpose>
 
 <required_reading>
@@ -69,11 +61,13 @@ Audit checklist steps (phase coverage, ad-hoc completeness, execution completene
 **GATE 2: Phase Coverage → Integration Check**
 - REQUIRED: Every phase checked for artifact chain completeness (ANL→PLN→EXC for standard, PLN→EXC for adhoc).
 - REQUIRED: Execution completeness verified — all tasks in executed plans checked for status.
+- BLOCKED if missing: phase coverage check incomplete — do not proceed to integration check with unchecked phases.
 - Do NOT skip incomplete chains — each gap MUST be logged in audit report.
 
 **GATE 3: Integration Check → Report**
 - REQUIRED: Cross-artifact integration check completed (shared interfaces, data contracts, configuration consistency).
 - REQUIRED: Clear PASS/FAIL verdict determined with evidence for each check.
+- BLOCKED if missing: integration check not completed — do not write report without cross-artifact verification.
 
 ### Artifact Verification (before completion)
 

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

@@ -13,13 +13,8 @@ allowed-tools:
 ---
 
 <purpose>
-Mark a milestone as complete after its audit has passed. Performs 6-step archival:
-validation → directory archival → artifact history → knowhow extraction → state advancement → cleanup.
-
-Produces `milestones/{M}/artifacts/` archive and `specs/learnings.md` knowhow entries.
-Supports two milestone types: standard (advances to next milestone) and adhoc (self-contained, sets idle).
-
-Pipeline position: downstream of `maestro-milestone-audit` (requires PASS verdict). Upstream of `maestro-milestone-release` (cut a release) or next milestone planning (`maestro-analyze` / `maestro-plan`).
+Archive passed milestone: validate, archive artifacts, extract knowhow, advance state.
+Requires audit PASS; produces milestone archive and learnings.
 </purpose>
 
 <required_reading>
@@ -51,18 +46,22 @@ Archive flow steps (validation, directory archival, artifact history, knowhow ex
 **GATE 1: Validation → Archival**
 - REQUIRED: Audit report verified as PASS (E002 if not).
 - REQUIRED: No incomplete artifacts remain (E003 if any).
+- BLOCKED if: audit not passed (E002) or incomplete artifacts remain (E003) — cannot archive unvalidated milestone.
 
 **GATE 2: Archival → Knowhow Extraction**
 - REQUIRED: Scratch artifacts moved to `milestones/{M}/artifacts/`.
 - REQUIRED: Artifact entries archived to milestone_history in state.json.
+- BLOCKED if missing: artifacts not moved or history not updated — knowhow extraction needs archived artifacts as input.
 
 **GATE 3: Knowhow Extraction → State Advancement**
 - REQUIRED: Knowhow extraction attempted (may produce 0 entries — W001).
 - REQUIRED: `project.md` Context updated with milestone summary.
+- BLOCKED if missing: knowhow extraction not attempted or project.md not updated — state advancement requires completed knowledge capture.
 
 **GATE 4: State Advancement → Completion**
 - REQUIRED: state.json updated — next milestone as current (standard) or current_milestone=null (adhoc).
 - REQUIRED: Roadmap snapshot saved (standard only).
+- BLOCKED if missing: state.json not advanced — project remains stuck on completed milestone.
 
 ### Knowledge Promotion Inquiry