maestro-flow 0.3.7 → 0.3.9

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>` |

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

@@ -1,130 +1,151 @@
----
-name: maestro-plan
-description: Explore, clarify, plan, check, and confirm a phase execution plan
-argument-hint: "<phase> [--collab] [--spec SPEC-xxx] [--auto] [--gaps] [--dir <path>]"
-allowed-tools:
-  - Read
-  - Write
-  - Edit
-  - Bash
-  - Glob
-  - Grep
-  - Agent
-  - AskUserQuestion
----
-<purpose>
-Create a verified execution plan (plan.json + .task/TASK-*.json) for a roadmap phase through a 5-stage pipeline: Exploration, Clarification, Planning, Plan Checking, and Confirmation. Invoked when a phase is ready to be planned after init/brainstorm. Produces plan.json with waves, task definitions, and user-confirmed execution strategy.
-</purpose>
-
-<required_reading>
-@~/.maestro/workflows/plan.md
-</required_reading>
-
-<deferred_reading>
-- [plan.json](~/.maestro/templates/plan.json) — read when generating plan output
-- [task.json](~/.maestro/templates/task.json) — read when generating task files
-- [index.json](~/.maestro/templates/index.json) — read when updating phase index
-</deferred_reading>
-
-<context>
-Phase: $ARGUMENTS (required -- phase number or slug)
-
-**Flags:**
-- `--collab` -- Multi-planner collaborative mode (spawn N workflow-collab-planner agents with pre-allocated TASK ID ranges)
-- `--spec SPEC-xxx` -- Reference a task-spec for requirements input
-- `--auto` -- Skip interactive clarification (P2), use defaults
-- `--gaps` -- Gap closure mode: load verification.json gaps, skip exploration, plan only gap fixes
-- `--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):
-- context.md (user decisions from Skill({ skill: "maestro-analyze" }))
-- index.json (phase metadata)
-- spec-ref from index.json (if set)
-- codebase/doc-index.json (if exists)
-- Wiki prior knowledge via `maestro wiki search` (offline, graceful degradation)
-</context>
-
-<execution>
-### Pre-flight: team conflict check
-
-Before starting the plan pipeline, run:
-```
-Bash("maestro team preflight --phase <phase-number>")
-```
-If exit code is 1, the command prints warnings about teammates active on the same phase. Present the warnings to the user and ask whether to proceed. If the user confirms or says "force", continue. If they decline, abort with a clear message.
-
-If exit code is 0, or `maestro team preflight` is unavailable (e.g., team mode not enabled), continue normally.
-
-Follow '~/.maestro/workflows/plan.md' completely.
-
-### Wiki Knowledge Search (P1 addition)
-
-During P1 Context Collection, after loading context files and before parallel exploration (step 5), search the wiki for prior knowledge related to the phase:
-
-```
-// Extract search keywords from phase goal/title in index.json
-phase_keywords = extract key terms from index.json goal + title (2-5 terms)
-
-// Run wiki search (offline mode, no --live flag)
-wiki_result = Bash("maestro wiki search ${phase_keywords} --json 2>/dev/null")
-
-IF wiki_result exit code != 0 OR wiki_result is empty OR parse fails:
-  display "W003: Wiki search unavailable, continuing without prior knowledge"
-  wiki_context = ""
-ELSE:
-  entries = JSON.parse(wiki_result).entries (limit to first 10)
-  IF entries.length == 0:
-    wiki_context = "## Wiki Prior Knowledge\nNo related wiki entries found."
-  ELSE:
-    wiki_context = "## Wiki Prior Knowledge\n"
-    FOR each entry in entries:
-      wiki_context += "- [${entry.type}] ${entry.id}: ${entry.title}"
-      IF entry.summary:
-        wiki_context += " — ${entry.summary}"
-      wiki_context += "\n"
-
-// Inject wiki_context into exploration context alongside other P1 outputs
-```
-
-This step uses offline mode by default (no `--live` flag) so it works without the dashboard running. The structured `## Wiki Prior Knowledge` block is passed to downstream planning stages as additional context.
-
-**Report format on completion:**
-
-```
-=== PLAN READY ===
-Phase: {phase_name}
-Tasks: {task_count} tasks in {wave_count} waves
-Check: {checker_status} (iteration {check_count}/{max_checks})
-
-Plan: {phase_dir}/plan.json
-Tasks: {phase_dir}/.task/TASK-*.json
-
-Next steps:
-  Skill({ skill: "maestro-execute", args: "{phase}" })  -- Execute the plan
-  Skill({ skill: "maestro-plan", args: "{phase}" })     -- Re-plan with modifications
-
-Note: If this was a --gaps plan, after execute run Skill({ skill: "maestro-verify", args: "{phase}" }) to confirm gaps are closed.
-```
-</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 | --gaps requires verification.json to exist | Check arguments format, re-run with correct input |
-| W001 | warning | Exploration agent returned incomplete results | Retry exploration or proceed with available context |
-| W002 | warning | Plan-checker found minor issues, continuing | Review plan-checker feedback, adjust plan if needed |
-| W003 | warning | Wiki search unavailable or returned no results | Continue without prior knowledge context |
-</error_codes>
-
-<success_criteria>
-- [ ] plan.json written to phase directory with summary, approach, task_ids, waves
-- [ ] .task/TASK-*.json files created for each task
-- [ ] Every task has `read_first[]` with at least the file being modified + source of truth files
-- [ ] Every task has `convergence.criteria[]` with grep-verifiable conditions (no subjective language)
-- [ ] Every task `action` and `implementation` contain concrete values (no "align X with Y")
-- [ ] Plan-checker passed (or minor issues acknowledged)
-- [ ] User confirmation captured (execute/modify/cancel)
-- [ ] index.json updated with plan status and timestamps
-</success_criteria>
+---
+name: maestro-plan
+description: Explore, clarify, plan, check, and confirm a phase execution plan
+argument-hint: "[phase] [--collab] [--spec SPEC-xxx] [--auto] [--gaps] [--dir <path>]"
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Bash
+  - Glob
+  - Grep
+  - Agent
+  - AskUserQuestion
+---
+<purpose>
+Create a verified execution plan (plan.json + .task/TASK-*.json) through a 5-stage pipeline: Exploration, Clarification, Planning, Plan Checking, and Confirmation. Produces plan.json with waves, task definitions, and user-confirmed execution strategy.
+
+All plan output goes to `.workflow/scratch/plan-{slug}-{date}/`. Registers PLN artifact in state.json. Performs collision detection against other plans in same milestone.
+</purpose>
+
+<required_reading>
+@~/.maestro/workflows/plan.md
+</required_reading>
+
+<deferred_reading>
+- [plan.json](~/.maestro/templates/plan.json) — read when generating plan output
+- [task.json](~/.maestro/templates/task.json) — read when generating task files
+- [state.json](~/.maestro/templates/state.json) — read when registering artifact
+</deferred_reading>
+
+<context>
+$ARGUMENTS — phase number, or no args for milestone-wide planning, with optional flags.
+
+**Flags:**
+- `--collab` -- Multi-planner collaborative mode (spawn N workflow-collab-planner agents with pre-allocated TASK ID ranges)
+- `--spec SPEC-xxx` -- Reference a task-spec for requirements input
+- `--auto` -- Skip interactive clarification (P2), use defaults
+- `--gaps` -- Gap closure mode: load verification/issue gaps, skip exploration, plan only gap fixes
+- `--dir <path>` -- Use arbitrary scratch directory as context source (e.g., from analyze session)
+
+**Scope routing:**
+
+| Invocation | Precondition | Scope | Behavior |
+|-----------|-------------|-------|----------|
+| `plan` (no args) | init + roadmap | milestone | Plan all phases in current milestone |
+| `plan 1` | init + roadmap | phase | Plan phase 1 only |
+| `plan --dir scratch/analyze-xxx` | none | inherited | Plan against specified analyze session |
+
+**Upstream context:**
+- Reads `context.md` from prior analyze artifact (auto-discovered from state.json or via --dir)
+- Reads `conclusions.json` if available (implementation_scope seeds task generation)
+
+**Output directory**: `scratch/plan-{slug}-{date}/` (relative to `.workflow/`)
+
+**Output structure:**
+```
+scratch/plan-{slug}-{date}/
+├── plan.json            # summary, task_ids[], waves[] with phase labels
+└── .task/
+    ├── TASK-001.json    # { phase: 1, phase_slug: "auth", ... }
+    ├── TASK-002.json
+    └── ...
+```
+
+**Collision detection**: After plan generation, before user confirmation, check for file overlaps with existing plans in same milestone. Non-blocking warning only.
+
+**Artifact registration**: On completion, register in `state.json.artifacts[]`:
+```jsonc
+{
+  "id": "PLN-{NNN}",
+  "type": "plan",
+  "milestone": "{current_milestone or null}",
+  "phase": "{phase_number or null}",
+  "scope": "{milestone|phase|adhoc|standalone}",
+  "path": "scratch/plan-{slug}-{date}",
+  "status": "completed",
+  "depends_on": "{ANL-NNN or null}",
+  "harvested": false,
+  "created_at": "...",
+  "completed_at": "..."
+}
+```
+</context>
+
+<execution>
+### Pre-flight: team conflict check
+
+Before starting the plan pipeline, run:
+```
+Bash("maestro collab preflight --phase <phase-number>")
+```
+If exit code is 1, present warnings and ask whether to proceed.
+
+Follow '~/.maestro/workflows/plan.md' completely.
+
+### Wiki Knowledge Search (P1 addition)
+
+During P1 Context Collection, after loading context files and before parallel exploration (step 5), search the wiki for prior knowledge related to the phase:
+
+```
+phase_keywords = extract key terms from goal/title (2-5 terms)
+wiki_result = Bash("maestro wiki search ${phase_keywords} --json 2>/dev/null")
+
+IF wiki_result exit code != 0 OR empty:
+  display "W003: Wiki search unavailable, continuing without prior knowledge"
+ELSE:
+  entries = JSON.parse(wiki_result).entries (limit to first 10)
+  wiki_context = structured block for downstream stages
+```
+
+**Report format on completion:**
+
+```
+=== PLAN READY ===
+Phase: {phase_name}
+Tasks: {task_count} tasks in {wave_count} waves
+Check: {checker_status} (iteration {check_count}/{max_checks})
+Collision: {collision_status}
+
+Plan: {scratch_dir}/plan.json
+Tasks: {scratch_dir}/.task/TASK-*.json
+
+Next steps:
+  /maestro-execute              -- Execute the plan
+  /maestro-execute --dir {dir}  -- Execute specific plan
+  /maestro-plan {phase}         -- Re-plan with modifications
+```
+</execution>
+
+<error_codes>
+| Code | Severity | Condition | Recovery |
+|------|----------|-----------|----------|
+| E001 | error | No args and no roadmap (cannot determine scope) | Provide phase number or topic, or create roadmap |
+| E003 | error | --gaps requires prior verification/issues to exist | Run maestro-verify first |
+| W001 | warning | Exploration agent returned incomplete results | Retry exploration or proceed with available context |
+| W002 | warning | Plan-checker found minor issues, continuing | Review plan-checker feedback, adjust plan if needed |
+| W003 | warning | Wiki search unavailable or returned no results | Continue without prior knowledge context |
+| W004 | warning | Collision detected with existing plan | Review colliding files, confirm or adjust scope |
+</error_codes>
+
+<success_criteria>
+- [ ] plan.json written to scratch directory with summary, approach, task_ids, waves (with phase labels)
+- [ ] .task/TASK-*.json files created for each task
+- [ ] Every task has `read_first[]` with at least the file being modified + source of truth files
+- [ ] Every task has `convergence.criteria[]` with grep-verifiable conditions (no subjective language)
+- [ ] Every task `action` and `implementation` contain concrete values (no "align X with Y")
+- [ ] Collision detection executed against same-milestone plans (non-blocking)
+- [ ] Plan-checker passed (or minor issues acknowledged)
+- [ ] User confirmation captured (execute/modify/cancel)
+- [ ] Artifact registered in state.json with correct scope/milestone/phase/depends_on
+</success_criteria>

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

@@ -33,10 +33,10 @@ Parse for:
 Follow '~/.maestro/workflows/quick.md' completely.
 
 **Next-step routing on completion:**
-- Task done, --full verification passed → Skill({ skill: "manage-status" })
-- Task done, verification found gaps → Skill({ skill: "quality-debug", args: "{issue}" })
-- Task done, want to sync docs → Skill({ skill: "quality-sync" })
-- Need a full phase workflow instead → Skill({ skill: "maestro-plan", args: "{phase}" })
+- Task done, --full verification passed → /manage-status
+- Task done, verification found gaps → /quality-debug {issue}
+- Task done, want to sync docs → /quality-sync
+- Need a full phase workflow instead → /maestro-plan {phase}
 </execution>
 
 <error_codes>

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

@@ -66,10 +66,10 @@ Auto-selection: ≥3 high uncertainty factors → Progressive, ≥3 low → Dire
 Follow '~/.maestro/workflows/roadmap.md' completely.
 
 **Next-step routing on completion:**
-- Roadmap approved → Skill({ skill: "maestro-analyze", args: "1" })
-- Simple project, skip analysis → Skill({ skill: "maestro-plan", args: "1" })
-- Need UI design first → Skill({ skill: "maestro-ui-design", args: "1" })
-- View project dashboard → Skill({ skill: "manage-status" })
+- Roadmap approved → /maestro-analyze 1
+- Simple project, skip analysis → /maestro-plan 1
+- Need UI design first → /maestro-ui-design 1
+- View project dashboard → /manage-status
 </execution>
 
 <error_codes>
@@ -91,5 +91,5 @@ Follow '~/.maestro/workflows/roadmap.md' completely.
 - [ ] No circular dependencies in phase ordering
 - [ ] User approved roadmap (or auto-approved with -y)
 - [ ] `.workflow/roadmap.md` written with phase details, scope decisions, and progress table
-- [ ] Phase directories created under `.workflow/phases/`
+- [ ] No phase directories created (phases are labels in roadmap, not directories)
 </success_criteria>

package/.claude/commands/maestro-spec-generate.md

@@ -38,7 +38,7 @@ $ARGUMENTS -- idea text, @file reference to requirements document, or brainstorm
 **Input types:**
 - Direct text: `"Build a real-time collaboration platform"`
 - File reference: `@requirements.md` or `@design-brief.txt`
-- Brainstorm import: `--from-brainstorm WFS-xxx` (reads `.workflow/scratch/brainstorm-*/` or `.workflow/phases/*/`)
+- Brainstorm import: `--from-brainstorm WFS-xxx` (reads `.workflow/scratch/brainstorm-*/`)
 
 **Output location:** `.workflow/.spec/SPEC-{slug}-{YYYY-MM-DD}/`
 
@@ -62,10 +62,10 @@ maestro-init → maestro-roadmap → roadmap.md directly
 Follow '~/.maestro/workflows/spec-generate.md' completely.
 
 **Next-step routing on completion:**
-- Roadmap generated, ready to plan → Skill({ skill: "maestro-plan", args: "1" })
-- Need UI design first → Skill({ skill: "maestro-ui-design", args: "1" })
-- Need analysis before planning → Skill({ skill: "maestro-analyze", args: "1" })
-- View project dashboard → Skill({ skill: "manage-status" })
+- Roadmap generated, ready to plan → /maestro-plan 1
+- Need UI design first → /maestro-ui-design 1
+- Need analysis before planning → /maestro-analyze 1
+- View project dashboard → /manage-status
 </execution>
 
 <error_codes>

package/.claude/commands/maestro-ui-design.md

@@ -109,9 +109,9 @@ Design System:
   Compare:          {phase_dir}/design-ref/prototypes/compare.html
 
 Next steps:
-  Skill({ skill: "maestro-plan", args: "{phase}" })              -- Plan with design reference
-  Skill({ skill: "maestro-ui-design", args: "{phase} --refine" }) -- Refine selected design
-  Skill({ skill: "maestro-analyze", args: "{phase}" })           -- Analyze before planning
+  /maestro-plan {phase}              -- Plan with design reference
+  /maestro-ui-design {phase} --refine -- Refine selected design
+  /maestro-analyze {phase}           -- Analyze before planning
 ```
 </execution>