maestro-flow 0.3.9 → 0.3.11

package/.codex/skills/maestro-milestone-audit/SKILL.md

@@ -1,103 +1,108 @@
----
-name: maestro-milestone-audit
-description: Audit current milestone using artifact registry for cross-phase integration gaps and produce verdict report
-argument-hint: "[milestone, e.g., 'M1']"
-allowed-tools: Read, Write, Bash, Glob, Grep, Agent
----
-
-# Maestro Milestone Audit (Single Agent)
-
-## Usage
-
-```bash
-$maestro-milestone-audit ""
-$maestro-milestone-audit "M1"
-```
-
-**Output**: Audit report with artifact chain verification, integration analysis, and PASS/FAIL verdict
-
----
-
-## Overview
-
-Sequential audit based on artifact registry in state.json. Checks phase coverage (ANL→PLN→EXC chains), ad-hoc completeness, execution completeness, and cross-artifact integration.
-
----
-
-## Implementation
-
-### Step 1: Parse Arguments
-
-Extract milestone identifier from arguments.
-If empty: read `current_milestone` from `.workflow/state.json`.
-If still empty: error E001.
-
-### Step 2: Load Artifact Registry
-
-```bash
-cat .workflow/state.json
-cat .workflow/roadmap.md
-```
-
-- Parse `state.json.artifacts[]` filtered by milestone
-- Parse `roadmap.md` for phase list in this milestone
-- Group artifacts by type and phase
-
-### Step 3: Phase Coverage Check
-
-For each phase in roadmap:
-- Check for completed analyze artifact (optional but noted)
-- Check for completed plan artifact (required)
-- Check for completed execute artifact (required)
-
-Report coverage matrix.
-
-### Step 4: Ad-hoc & Execution Completeness
-
-- Check all adhoc-scoped artifacts are completed
-- For each execute artifact, verify tasks in plan dir are all completed
-
-### Step 5: Integration Check
-
-Spawn Agent for cross-phase integration validation:
-- Shared interfaces compatibility
-- Dependency chain satisfaction
-- Data contract consistency
-- API endpoint consistency
-
-Write report to `.workflow/milestones/{milestone}/audit-report.md`
-
-### Step 6: Verdict
-
-```
-PASS if:
-  - All phases have EXC artifacts (completed)
-  - No critical integration gaps
-  - All adhoc artifacts completed
-
-FAIL if:
-  - Missing EXC artifacts for any phase
-  - Critical integration gaps found
-```
-
-Display structured audit report with next-step routing.
-
----
-
-## Error Handling
-
-| Code | Severity | Description | Recovery |
-|------|----------|-------------|----------|
-| E001 | error | Milestone identifier required | Specify milestone or ensure current_milestone is set |
-| E002 | error | Milestone not found in state.json | Check milestone ID |
-| E003 | error | No execute artifacts found | Run maestro-execute first |
-| W001 | warning | Some phases lack analyze artifacts | Note: analysis optional but recommended |
-
----
-
-## Core Rules
-
-1. **Artifact registry is source of truth** — don't scan directories, read state.json
-2. **Non-blocking warnings** — missing analyze is warning, missing execute is error
-3. **Integration check is required** — always spawn checker agent
-4. **Clear verdict** — PASS or FAIL with specific reasons
+---
+name: maestro-milestone-audit
+description: Audit current milestone using artifact registry for cross-phase integration gaps and produce verdict report
+argument-hint: "[milestone, e.g., 'M1']"
+allowed-tools: Read, Write, Bash, Glob, Grep, Agent
+---
+
+<purpose>
+Sequential audit based on artifact registry in state.json. Checks phase coverage (ANL->PLN->EXC chains), ad-hoc completeness, execution completeness, and cross-artifact integration. Produces PASS/FAIL verdict report.
+</purpose>
+
+<context>
+
+```bash
+$maestro-milestone-audit ""
+$maestro-milestone-audit "M1"
+```
+
+**Output**: Audit report with artifact chain verification, integration analysis, and PASS/FAIL verdict
+
+</context>
+
+<invariants>
+1. **Artifact registry is source of truth** — don't scan directories, read state.json
+2. **Non-blocking warnings** — missing analyze is warning, missing execute is error
+3. **Integration check is required** — always spawn checker agent
+4. **Clear verdict** — PASS or FAIL with specific reasons
+</invariants>
+
+<execution>
+
+### Step 1: Parse Arguments
+
+Extract milestone identifier from arguments.
+If empty: read `current_milestone` from `.workflow/state.json`.
+If still empty: error E001.
+
+### Step 2: Load Artifact Registry
+
+```bash
+cat .workflow/state.json
+cat .workflow/roadmap.md
+```
+
+- Parse `state.json.artifacts[]` filtered by milestone
+- Parse `roadmap.md` for phase list in this milestone
+- Group artifacts by type and phase
+
+### Step 3: Phase Coverage Check
+
+For each phase in roadmap:
+- Check for completed analyze artifact (optional but noted)
+- Check for completed plan artifact (required)
+- Check for completed execute artifact (required)
+
+Report coverage matrix.
+
+### Step 4: Ad-hoc & Execution Completeness
+
+- Check all adhoc-scoped artifacts are completed
+- For each execute artifact, verify tasks in plan dir are all completed
+
+### Step 5: Integration Check
+
+Spawn Agent for cross-phase integration validation:
+- Shared interfaces compatibility
+- Dependency chain satisfaction
+- Data contract consistency
+- API endpoint consistency
+
+Write report to `.workflow/milestones/{milestone}/audit-report.md`
+
+### Step 6: Verdict
+
+```
+PASS if:
+  - All phases have EXC artifacts (completed)
+  - No critical integration gaps
+  - All adhoc artifacts completed
+
+FAIL if:
+  - Missing EXC artifacts for any phase
+  - Critical integration gaps found
+```
+
+Display structured audit report with next-step routing.
+
+</execution>
+
+<error_codes>
+
+| Code | Severity | Description | Recovery |
+|------|----------|-------------|----------|
+| E001 | error | Milestone identifier required | Specify milestone or ensure current_milestone is set |
+| E002 | error | Milestone not found in state.json | Check milestone ID |
+| E003 | error | No execute artifacts found | Run maestro-execute first |
+| W001 | warning | Some phases lack analyze artifacts | Note: analysis optional but recommended |
+
+</error_codes>
+
+<success_criteria>
+- [ ] Artifact registry loaded and filtered by milestone
+- [ ] Phase coverage matrix generated
+- [ ] Ad-hoc and execution completeness verified
+- [ ] Integration check performed via agent
+- [ ] Audit report written to milestones/ directory
+- [ ] Clear PASS/FAIL verdict with specific reasons
+</success_criteria>

package/.codex/skills/maestro-milestone-complete/SKILL.md

@@ -1,149 +1,155 @@
----
-name: maestro-milestone-complete
-description: Archive completed milestone scratch artifacts to milestones/ dir, move artifact entries to milestone_history, extract learnings, advance state.
-argument-hint: "[milestone] [--force]"
-allowed-tools: Read, Write, Edit, Bash, Glob, Grep
----
-
-# Milestone Complete
-
-## Usage
-
-```bash
-$maestro-milestone-complete "M1"
-$maestro-milestone-complete              # uses current_milestone from state.json
-$maestro-milestone-complete --force "M1"  # skip audit check
-```
-
-**Output**: `.workflow/milestones/{milestone}/` archive directory
-
----
-
-## Overview
-
-Sequential milestone archival: validate audit → archive scratch dirs → extract learnings → move artifact entries to milestone_history → advance state → clean scratch.
-
----
-
-## Implementation
-
-### Step 1: Parse & Validate
-
-1. Read `.workflow/state.json` to get `current_milestone`, `artifacts[]`, `milestones[]`
-2. Determine target milestone (from args or current_milestone)
-3. Check `--force` flag
-4. If no milestone: **E001**
-5. Check audit report exists at `.workflow/milestones/{milestone}/audit-report.md`
-   - Missing + not --force: **E002**
-   - Verdict FAIL + not --force: **E002**
-6. Check all milestone artifacts completed:
-   - `state.json.artifacts.filter(a => a.milestone == target && a.status != "completed")`
-   - If any incomplete + not --force: **E003**
-
-### Step 2: Archive Scratch Dirs
-
-```bash
-mkdir -p .workflow/milestones/{milestone}/artifacts/
-
-# For each artifact path, copy to archive
-for artifact in milestone_artifacts:
-  if dir exists .workflow/{artifact.path}:
-    cp -r .workflow/{artifact.path} .workflow/milestones/{milestone}/artifacts/$(basename {artifact.path})/
-```
-
-Snapshot roadmap:
-```bash
-cp .workflow/roadmap.md .workflow/milestones/{milestone}/roadmap-snapshot.md
-```
-
-### Step 3: Extract Learnings
-
-- Read `.summaries/` from each execute artifact's plan dir
-- Read `reflection-log.md` if exists
-- Extract patterns, pitfalls, strategy adjustments
-- Append to `.workflow/specs/learnings.md`
-- Avoid duplicates (check existing entries)
-
-### Step 4: Archive Artifact Entries
-
-Move artifact entries from `state.json.artifacts[]` to `milestone_history`:
-
-```json
-{
-  "milestone_history": [
-    ...existing,
-    {
-      "id": "{milestone}",
-      "name": "{milestone_name}",
-      "status": "completed",
-      "completed_at": "{now}",
-      "archive_path": "milestones/{milestone}/",
-      "archived_artifacts": [ ...all milestone artifact entries... ]
-    }
-  ]
-}
-```
-
-Remove from `artifacts[]`:
-```
-state.json.artifacts = state.json.artifacts.filter(a => a.milestone != target)
-```
-
-### Step 5: Advance State
-
-```
-next = state.json.milestones.find(m => m.status == "pending")
-if next:
-  state.json.current_milestone = next.id
-  next.status = "active"
-else:
-  state.json.current_milestone = null
-  state.json.status = "completed"
-
-state.json.last_updated = now()
-Write state.json (atomic)
-```
-
-### Step 6: Clean Scratch
-
-```bash
-for artifact in archived_artifacts:
-  rm -rf .workflow/{artifact.path}
-```
-
-### Step 7: Generate Summary & Report
-
-Write `.workflow/milestones/{milestone}/summary.md` with outcomes and learnings.
-Update `.workflow/project.md` Context section.
-
-```
-=== MILESTONE COMPLETE ===
-Milestone: {milestone} ({name})
-Artifacts: {count} archived
-Next:      {next_milestone or "Project complete"}
-
-Next steps:
-  $maestro-milestone-release  -- Cut release
-  $maestro-analyze            -- Start next milestone
-  $manage-status              -- View state
-```
-
----
-
-## Error Handling
-
-| Code | Severity | Description | Recovery |
-|------|----------|-------------|----------|
-| E001 | error | Milestone identifier required | Specify milestone |
-| E002 | error | Audit not passed | Run milestone-audit first |
-| E003 | error | Incomplete artifacts remain | Complete work first |
-
----
-
-## Core Rules
-
-1. **Audit before archive** — refuse without passing audit (unless --force)
-2. **Atomic state update** — write state.json via tmp+rename
-3. **Learnings are mandatory** — always extract before archiving
-4. **Clean after archive** — remove scratch dirs only after successful copy
-5. **Advance state** — always set next milestone or mark project complete
+---
+name: maestro-milestone-complete
+description: Archive completed milestone scratch artifacts to milestones/ dir, move artifact entries to milestone_history, extract learnings, advance state.
+argument-hint: "[milestone] [--force]"
+allowed-tools: Read, Write, Edit, Bash, Glob, Grep
+---
+
+<purpose>
+Sequential milestone archival: validate audit → archive scratch dirs → extract learnings → move artifact entries to milestone_history → advance state → clean scratch.
+</purpose>
+
+<context>
+
+```bash
+$maestro-milestone-complete "M1"
+$maestro-milestone-complete              # uses current_milestone from state.json
+$maestro-milestone-complete --force "M1"  # skip audit check
+```
+
+**Output**: `.workflow/milestones/{milestone}/` archive directory
+
+</context>
+
+<invariants>
+1. **Audit before archive** — refuse without passing audit (unless --force)
+2. **Atomic state update** — write state.json via tmp+rename
+3. **Learnings are mandatory** — always extract before archiving
+4. **Clean after archive** — remove scratch dirs only after successful copy
+5. **Advance state** — always set next milestone or mark project complete
+</invariants>
+
+<execution>
+
+### Step 1: Parse & Validate
+
+1. Read `.workflow/state.json` to get `current_milestone`, `artifacts[]`, `milestones[]`
+2. Determine target milestone (from args or current_milestone)
+3. Check `--force` flag
+4. If no milestone: **E001**
+5. Check audit report exists at `.workflow/milestones/{milestone}/audit-report.md`
+   - Missing + not --force: **E002**
+   - Verdict FAIL + not --force: **E002**
+6. Check all milestone artifacts completed:
+   - `state.json.artifacts.filter(a => a.milestone == target && a.status != "completed")`
+   - If any incomplete + not --force: **E003**
+
+### Step 2: Archive Scratch Dirs
+
+```bash
+mkdir -p .workflow/milestones/{milestone}/artifacts/
+
+# For each artifact path, copy to archive
+for artifact in milestone_artifacts:
+  if dir exists .workflow/{artifact.path}:
+    cp -r .workflow/{artifact.path} .workflow/milestones/{milestone}/artifacts/$(basename {artifact.path})/
+```
+
+Snapshot roadmap:
+```bash
+cp .workflow/roadmap.md .workflow/milestones/{milestone}/roadmap-snapshot.md
+```
+
+### Step 3: Extract Learnings
+
+- Read `.summaries/` from each execute artifact's plan dir
+- Read `reflection-log.md` if exists
+- Extract patterns, pitfalls, strategy adjustments
+- Append to `.workflow/specs/learnings.md`
+- Avoid duplicates (check existing entries)
+
+### Step 4: Archive Artifact Entries
+
+Move artifact entries from `state.json.artifacts[]` to `milestone_history`:
+
+```json
+{
+  "milestone_history": [
+    ...existing,
+    {
+      "id": "{milestone}",
+      "name": "{milestone_name}",
+      "status": "completed",
+      "completed_at": "{now}",
+      "archive_path": "milestones/{milestone}/",
+      "archived_artifacts": [ ...all milestone artifact entries... ]
+    }
+  ]
+}
+```
+
+Remove from `artifacts[]`:
+```
+state.json.artifacts = state.json.artifacts.filter(a => a.milestone != target)
+```
+
+### Step 5: Advance State
+
+```
+next = state.json.milestones.find(m => m.status == "pending")
+if next:
+  state.json.current_milestone = next.id
+  next.status = "active"
+else:
+  state.json.current_milestone = null
+  state.json.status = "completed"
+
+state.json.last_updated = now()
+Write state.json (atomic)
+```
+
+### Step 6: Clean Scratch
+
+```bash
+for artifact in archived_artifacts:
+  rm -rf .workflow/{artifact.path}
+```
+
+### Step 7: Generate Summary & Report
+
+Write `.workflow/milestones/{milestone}/summary.md` with outcomes and learnings.
+Update `.workflow/project.md` Context section.
+
+```
+=== MILESTONE COMPLETE ===
+Milestone: {milestone} ({name})
+Artifacts: {count} archived
+Next:      {next_milestone or "Project complete"}
+
+Next steps:
+  $maestro-milestone-release  -- Cut release
+  $maestro-analyze            -- Start next milestone
+  $manage-status              -- View state
+```
+
+</execution>
+
+<error_codes>
+
+| Code | Severity | Description | Recovery |
+|------|----------|-------------|----------|
+| E001 | error | Milestone identifier required | Specify milestone |
+| E002 | error | Audit not passed | Run milestone-audit first |
+| E003 | error | Incomplete artifacts remain | Complete work first |
+
+</error_codes>
+
+<success_criteria>
+- [ ] Audit report validated (or --force used)
+- [ ] Scratch directories archived to milestones/
+- [ ] Learnings extracted and appended to specs/learnings.md
+- [ ] Artifact entries moved to milestone_history in state.json
+- [ ] State advanced to next milestone (or project marked complete)
+- [ ] Scratch directories cleaned
+- [ ] Summary and completion report generated
+</success_criteria>

package/.codex/skills/maestro-milestone-release/SKILL.md

@@ -0,0 +1,70 @@
+---
+name: maestro-milestone-release
+description: Version bump, changelog generation, and git tag for a completed milestone. Auto-detects version manifest (package.json, pyproject.toml, Cargo.toml), generates changelog from milestone summaries + git log, creates annotated tag.
+argument-hint: "[<version>] [--bump patch|minor|major] [--dry-run] [--no-tag] [--no-push]"
+allowed-tools: Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion
+---
+
+<purpose>
+Package a completed milestone into a releasable version. Bumps project version in manifest,
+generates CHANGELOG.md entry from phase/milestone summaries and git log, creates annotated
+git tag, optionally pushes to remote. Runs after `/maestro-milestone-complete`.
+</purpose>
+
+<required_reading>
+@~/.maestro/workflows/milestone-release.md
+</required_reading>
+
+<context>
+$ARGUMENTS — optional explicit version and flags.
+
+**Flags:**
+- `<version>` — Explicit version (e.g. `1.2.0`). If omitted, derived from `--bump`.
+- `--bump patch|minor|major` — Semver bump (default: `minor`)
+- `--dry-run` — Compute version + changelog without writing
+- `--no-tag` — Skip git tag creation
+- `--no-push` — Skip `git push --follow-tags`
+
+**Preconditions:**
+- Current milestone completed (audit PASS + milestone-complete run)
+- Working tree clean (no uncommitted changes) unless `--dry-run`
+</context>
+
+<execution>
+Follow '~/.maestro/workflows/milestone-release.md' completely.
+
+**Flow:** Validate preconditions → Resolve version → Collect changes → Generate CHANGELOG →
+Bump manifest → Commit → Tag → Push
+
+**Report:**
+```
+=== RELEASE COMPLETE ===
+Version:   v{previous} → v{new}
+Milestone: {name}
+Tag:       v{new} {pushed|local-only}
+Changelog: {N} entries
+```
+</execution>
+
+<error_codes>
+| Code | Severity | Condition | Recovery |
+|------|----------|-----------|----------|
+| E001 | error | Milestone not completed | Run `$maestro-milestone-complete` first |
+| E002 | error | Audit verdict not PASS | Re-run `$maestro-milestone-audit` |
+| E003 | error | Working tree not clean | Commit or stash changes |
+| E004 | error | Version manifest not found | Add manifest or pass explicit version |
+| E005 | error | Version not greater than current | Choose higher version |
+| W001 | warning | No changes since last tag | Confirm release is desired |
+| W002 | warning | Remote push failed | Retry `git push --follow-tags` |
+</error_codes>
+
+<success_criteria>
+- [ ] Preconditions validated
+- [ ] Target version computed and greater than previous
+- [ ] Version manifest(s) updated
+- [ ] CHANGELOG.md entry with milestone summary + grouped changes
+- [ ] Release commit created
+- [ ] Annotated git tag created (unless --no-tag)
+- [ ] Pushed to remote (unless --no-push)
+- [ ] state.json updated with last_release_version
+</success_criteria>