maestro-flow 0.1.0

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

@@ -0,0 +1,209 @@
+---
+name: maestro-milestone-audit
+description: Audit current milestone for cross-phase integration gaps and produce verdict report
+argument-hint: "[milestone, e.g., 'v1.0']"
+allowed-tools: Read, Write, Bash, Glob, Grep, Agent
+---
+
+# Maestro Milestone Audit (Single Agent)
+
+## Usage
+
+```bash
+$maestro-milestone-audit ""
+$maestro-milestone-audit "v1.0"
+$maestro-milestone-audit "MVP"
+```
+
+**Flags**:
+- `[milestone]`: Milestone identifier (defaults to current_milestone from state.json)
+
+**Output**: Audit report with cross-phase integration analysis, gap list, and PASS/FAIL verdict
+
+---
+
+## Overview
+
+Sequential audit of a milestone's cross-phase integration health. Identifies all phases belonging to the milestone, reads their index.json and verification results, checks for integration gaps across phase boundaries, and produces a structured audit report with a clear verdict.
+
+---
+
+## 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 Milestone Context
+
+```bash
+cat .workflow/state.json
+cat .workflow/roadmap.md
+```
+
+Parse roadmap.md to find all phases belonging to this milestone.
+If milestone not found in roadmap: error E002.
+
+### Step 3: Collect Phase Data
+
+For each phase in the milestone:
+
+```bash
+cat .workflow/phases/{NN}-{slug}/index.json
+cat .workflow/phases/{NN}-{slug}/verification.json 2>/dev/null
+cat .workflow/phases/{NN}-{slug}/review.json 2>/dev/null
+```
+
+Collect:
+- Phase status (complete/active/pending)
+- Task completion counts
+- Verification verdicts
+- Review verdicts
+- Unresolved gaps
+
+Flag phases without `completed_at` as W001.
+If any phase is not complete/verifying: warning E003.
+
+### Step 4: Cross-Phase Integration Analysis
+
+Analyze integration points across phase boundaries:
+
+1. **Shared interfaces**: Grep for types/interfaces defined in one phase and used in another
+   ```bash
+   grep -r "export.*interface\|export.*type" .workflow/phases/*/
+   ```
+
+2. **Data contracts**: Check that data schemas are consistent across phases
+   ```bash
+   grep -r "schema\|contract\|interface" .workflow/phases/*/
+   ```
+
+3. **Dependency chains**: Verify that phase N's outputs satisfy phase N+1's inputs
+   - Read each phase's index.json for declared dependencies
+   - Check convergence criteria cross-references
+
+4. **API surface consistency**: Look for breaking changes between phases
+   ```bash
+   grep -r "breaking\|deprecated\|removed" .workflow/phases/*/verification.json
+   ```
+
+5. **Test coverage gaps**: Identify integration test blind spots
+   - Check if cross-phase interactions have test coverage
+   - Flag untested boundaries
+
+### Step 5: Spawn Integration Checker (if complex)
+
+For milestones with 3+ phases, spawn a workflow-integration-checker agent:
+
+```
+Agent({
+  subagent_type: "workflow-integration-checker",
+  prompt: "Check cross-phase integration for milestone {milestone}. Phases: {phase_list}. Focus on: shared interfaces, data contracts, dependency chains.",
+  run_in_background: false
+})
+```
+
+Merge agent findings with Step 4 analysis.
+
+### Step 6: Categorize Findings
+
+Classify each finding:
+- **Critical**: Breaking integration gap (blocks milestone completion)
+- **High**: Missing integration test coverage
+- **Medium**: Inconsistent naming/conventions across phases
+- **Low**: Documentation gaps, minor style inconsistencies
+
+### Step 7: Determine Verdict
+
+- **PASS**: No critical or high findings
+- **CONDITIONAL**: High findings exist but have clear fix paths
+- **FAIL**: Critical findings that block milestone completion
+
+### Step 8: Write Audit Report
+
+Write to `.workflow/milestone-audit-{milestone}.md`:
+
+```markdown
+# Milestone Audit: {milestone}
+**Date**: {ISO date}
+**Verdict**: {PASS|CONDITIONAL|FAIL}
+
+## Phases Audited
+
+| Phase | Status | Verification | Review | Tasks |
+|-------|--------|-------------|--------|-------|
+| {NN}-{slug} | {status} | {verdict} | {verdict} | {done}/{total} |
+
+## Integration Analysis
+
+### Critical Issues
+{list or "None"}
+
+### High Issues
+{list or "None"}
+
+### Medium Issues
+{list or "None"}
+
+### Low Issues
+{list or "None"}
+
+## Cross-Phase Dependencies
+
+{dependency matrix or diagram}
+
+## Recommendations
+
+{prioritized fix suggestions}
+
+## Next Steps
+
+{if PASS}
+  Ready for: $maestro-milestone-complete "{milestone}"
+{elif CONDITIONAL}
+  Fix high issues, then re-audit: $maestro-milestone-audit "{milestone}"
+{else}
+  Fix critical issues first. See recommendations above.
+{endif}
+```
+
+### Step 9: Completion Report
+
+```
+=== MILESTONE AUDIT: {milestone} ===
+Verdict: {PASS|CONDITIONAL|FAIL}
+
+Phases: {count} audited
+Findings: {critical} critical, {high} high, {medium} medium, {low} low
+
+Report: .workflow/milestone-audit-{milestone}.md
+
+{if PASS}
+Ready for milestone completion: $maestro-milestone-complete "{milestone}"
+{else}
+Fix {critical+high} blocking issues before completing milestone.
+{endif}
+```
+
+---
+
+## Error Handling
+
+| Code | Severity | Description | Recovery |
+|------|----------|-------------|----------|
+| E001 | error | Milestone identifier required | Specify milestone or set current_milestone in state.json |
+| E002 | error | Milestone not found in roadmap | Check roadmap.md for valid milestones |
+| E003 | error | Phases incomplete for this milestone | Complete phases first, or audit partial |
+| W001 | warning | Phase lacks completed_at | May not have been formally transitioned |
+
+---
+
+## Core Rules
+
+1. **Read everything before judging** — collect all phase data before analyzing gaps
+2. **Cross-phase focus** — single-phase issues are not this skill's concern; focus on boundaries
+3. **Actionable findings** — every finding must include a specific fix suggestion
+4. **Clear verdict** — PASS/CONDITIONAL/FAIL with unambiguous criteria
+5. **Agent only when needed** — spawn integration-checker only for 3+ phase milestones

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

@@ -0,0 +1,158 @@
+---
+name: maestro-milestone-complete
+description: Archive completed milestone and prepare for next. Validates all phases complete, creates archive, extracts learnings, updates state.json.
+argument-hint: "[milestone] [--force]"
+allowed-tools: Read, Write, Edit, Bash, Glob, Grep
+---
+
+# Milestone Complete
+
+## Usage
+
+```bash
+$maestro-milestone-complete "v1.0"
+$maestro-milestone-complete              # uses current_milestone from state.json
+$maestro-milestone-complete --force "v1.0"  # skip audit check
+```
+
+**Flags**:
+- `[milestone]`: Target milestone identifier (default: current_milestone from state.json)
+- `--force`: Skip audit verification, complete without passing audit
+
+**Output**: `.workflow/milestones/{milestone}/` archive directory
+
+---
+
+## Overview
+
+Sequential milestone archival: validate audit + phases -> create archive -> extract learnings -> update state -> report.
+
+---
+
+## Implementation
+
+### Step 1: Parse Input
+
+1. Read `.workflow/state.json` to get `current_milestone`
+2. If `$ARGUMENTS` contains a milestone identifier, use it; otherwise use `current_milestone`
+3. Detect `--force` flag
+4. If no milestone resolvable: **E001** -- exit
+
+### Step 2: Validate Completion
+
+**2a. Check audit report:**
+```
+Read .workflow/milestone-audit-{milestone}.md
+```
+- If missing and not `--force`: **E002** -- warn "No audit report found. Run milestone-audit first." Ask user to proceed or abort.
+- If verdict is FAIL and not `--force`: **E002** -- exit with suggestion to fix failing items
+
+**2b. Verify all phases completed:**
+```
+For each phase in milestone (from roadmap.md):
+  Read .workflow/phases/{NN}-{slug}/index.json
+  If status != "completed": E003 -- list incomplete phases, exit
+```
+
+### Step 3: Create Archive
+
+1. Create archive directory:
+   ```bash
+   mkdir -p .workflow/milestones/{milestone}/phases/
+   ```
+
+2. Snapshot roadmap:
+   ```bash
+   cp .workflow/roadmap.md .workflow/milestones/{milestone}/roadmap-snapshot.md
+   ```
+
+3. Archive each phase directory:
+   ```bash
+   cp -r .workflow/phases/{NN}-{slug}/ .workflow/milestones/{milestone}/phases/{NN}-{slug}/
+   ```
+
+4. Copy audit report (if exists):
+   ```bash
+   cp .workflow/milestone-audit-{milestone}.md .workflow/milestones/{milestone}/audit-report.md
+   ```
+
+### Step 4: Extract Learnings
+
+1. Load existing learnings from `.workflow/specs/learnings.md` to avoid duplicates
+2. For each phase, read `reflection-log.md` if exists:
+   - Extract strategy adjustments, patterns discovered, pitfalls encountered
+3. Append aggregated learnings to `.workflow/specs/learnings.md`:
+   ```markdown
+   ## Milestone {milestone} Learnings ({date})
+
+   ### Strategy Adjustments
+   - {from reflection-log entries}
+
+   ### Patterns Discovered
+   - {from reflection-log entries}
+
+   ### Pitfalls Encountered
+   - {from reflection-log entries}
+   ```
+
+### Step 5: Update State
+
+1. Update `.workflow/state.json`:
+   - `current_milestone` -> next version (increment minor)
+   - `current_phase` -> 1 (reset)
+   - `status` -> "idle"
+   - Reset `phases_summary` counters
+   - Preserve `accumulated_context` (decisions + deferred items carry forward)
+   - Set `last_updated` timestamp
+
+2. Clean up completed phase directories:
+   ```bash
+   rm -rf .workflow/phases/{NN}-{slug}/  # for each archived phase
+   ```
+   Keep `.workflow/phases/` directory (empty, ready for new milestone).
+
+### Step 6: Report and Route
+
+Display completion summary:
+```
+====================================================
+  MILESTONE COMPLETED: {milestone}
+====================================================
+
+Archived:
+  - {N} phases archived to .workflow/milestones/{milestone}/
+  - Roadmap snapshot saved
+  - Audit report archived
+  - {M} learnings extracted to specs/learnings.md
+
+State reset:
+  - Current milestone: {next_milestone}
+  - Current phase: 1
+  - Status: idle
+
+====================================================
+```
+
+Suggest next steps:
+- "Start planning next milestone?" -> Skill({ skill: "maestro-plan" })
+- "Project is idle." -> Skill({ skill: "manage-status" })
+
+---
+
+## Error Handling
+
+| Code | Severity | Condition | Recovery |
+|------|----------|-----------|----------|
+| E001 | error | Milestone identifier required and not resolvable | Prompt user for milestone |
+| E002 | error | Audit not passed (missing or FAIL verdict) | Run milestone-audit first, or use --force |
+| E003 | error | Incomplete phases remain | Complete or verify remaining phases |
+
+---
+
+## Core Rules
+
+- **Never delete** phase directories before archiving -- always copy first
+- **Preserve** `accumulated_context` across milestone boundaries
+- **Learnings dedup** -- check existing entries before appending
+- **Git commit** if in a git repo: `chore: complete milestone {milestone}`
+- **--force** bypasses audit check only, not phase completion check

package/.codex/skills/maestro-phase-add/SKILL.md

@@ -0,0 +1,154 @@
+---
+name: maestro-phase-add
+description: Add or insert a new phase into the project roadmap with automatic renumbering
+argument-hint: "\"phase name\" [--after N] [--before N]"
+allowed-tools: Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion
+---
+
+# Maestro Phase Add (Single Agent)
+
+## Usage
+
+```bash
+$maestro-phase-add "authentication"
+$maestro-phase-add "caching-layer" --after 2
+$maestro-phase-add "security-hardening" --before 5
+```
+
+**Flags**:
+- `"phase name"`: Required. Used as both slug and title (slug = lowercase, hyphens)
+- `--after N`: Insert after phase N (renumbers subsequent phases)
+- `--before N`: Insert before phase N (renumbers from N onward)
+- If neither: append at end
+
+**Output**: New phase directory, updated roadmap.md, updated state.json
+
+---
+
+## Overview
+
+Single mutation operation on the project roadmap. Creates a new phase directory with initialized index.json, inserts the phase entry into roadmap.md at the correct position, and handles automatic renumbering of all affected phase directories and references.
+
+---
+
+## Implementation
+
+### Step 1: Parse Arguments
+
+Extract:
+- Phase name/slug (required — E001 if missing)
+- `--after N` or `--before N` flag (mutually exclusive)
+- Generate slug: lowercase, replace spaces with hyphens, strip special chars
+
+### Step 2: Load Roadmap State
+
+```bash
+cat .workflow/roadmap.md
+cat .workflow/state.json
+ls -d .workflow/phases/*/
+```
+
+- Parse existing phases from roadmap.md
+- List existing phase directories
+- Check for duplicate slug (E003 if exists)
+- Verify roadmap.md exists (E002 if not)
+
+### Step 3: Calculate Position
+
+- If `--after N`: new phase number = N + 1
+- If `--before N`: new phase number = N
+- If neither: new phase number = max_existing + 1
+
+### Step 4: Renumber Existing Phases (if inserting)
+
+**Only when `--after N` or `--before N` is used.**
+
+For each phase with number >= new phase number (process in reverse order to avoid collisions):
+
+1. Rename directory: `.workflow/phases/{NN}-{slug}` → `.workflow/phases/{NN+1}-{slug}`
+2. Update index.json inside renamed directory: `"phase": N+1`
+
+```bash
+# Rename in reverse order to prevent collisions
+for dir in $(ls -rd .workflow/phases/*/); do
+  # Extract number, if >= insertion point, rename to number+1
+done
+```
+
+### Step 5: Create Phase Directory
+
+```bash
+mkdir -p .workflow/phases/{NN}-{slug}
+```
+
+Format NN as zero-padded 2-digit number (e.g., 03).
+
+### Step 6: Initialize Phase index.json
+
+Read template from `~/.maestro/templates/index.json` if available, otherwise create:
+
+```json
+{
+  "phase": <N>,
+  "slug": "<slug>",
+  "title": "<phase name>",
+  "status": "pending",
+  "created_at": "<ISO timestamp>",
+  "tasks": []
+}
+```
+
+Write to `.workflow/phases/{NN}-{slug}/index.json`.
+
+### Step 7: Update roadmap.md
+
+Insert new phase entry at the correct position in roadmap.md:
+- Match the existing phase entry format
+- If inserting, update all subsequent phase numbers in the document
+
+### Step 8: Update state.json
+
+If renumbering affected `current_phase` or `phases_completed`:
+- Adjust `current_phase` number if it was shifted
+- Adjust all entries in `phases_completed` that were shifted
+
+### Step 9: Completion Report
+
+```
+=== PHASE ADDED ===
+Phase: {NN} - {phase name}
+Location: .workflow/phases/{NN}-{slug}/
+
+{if renumbered}
+Renumbered: Phases {start}-{end} shifted by +1
+{endif}
+
+Updated:
+  .workflow/roadmap.md
+  .workflow/phases/{NN}-{slug}/index.json
+  {if renumbered}.workflow/state.json{endif}
+
+Next steps:
+  $maestro-plan ""         -- Plan tasks for the new phase
+  $maestro-status          -- View updated roadmap
+```
+
+---
+
+## Error Handling
+
+| Code | Severity | Description | Recovery |
+|------|----------|-------------|----------|
+| E001 | error | Phase name/slug required | Provide phase name as argument |
+| E002 | error | roadmap.md not found | Run maestro-init first |
+| E003 | error | Duplicate phase name/slug exists | Choose a different name |
+
+---
+
+## Core Rules
+
+1. **Reverse-order renumbering** — always rename directories from highest to lowest to prevent collisions
+2. **State consistency** — state.json phase references must be adjusted after renumbering
+3. **Match existing format** — new roadmap.md entries must match the style of existing entries
+4. **Zero-padded numbers** — always use 2-digit format (01, 02, ... 99)
+5. **Slug normalization** — lowercase, hyphens only, no special characters

package/.codex/skills/maestro-phase-transition/SKILL.md

@@ -0,0 +1,173 @@
+---
+name: maestro-phase-transition
+description: Mark current or specified phase as complete, extract learnings, advance to next phase
+argument-hint: "[phase-number] [--force]"
+allowed-tools: Read, Write, Edit, Bash, Glob, Grep
+---
+
+# Maestro Phase Transition (Single Agent)
+
+## Usage
+
+```bash
+$maestro-phase-transition ""
+$maestro-phase-transition "2"
+$maestro-phase-transition "3 --force"
+```
+
+**Flags**:
+- `[phase-number]`: Phase to transition from (defaults to current_phase from state.json)
+- `--force`: Skip gap checks and force transition even with warnings
+
+**Output**: Updated state.json, completed phase index.json, initialized next phase, learnings extracted
+
+---
+
+## Overview
+
+State-machine transition skill. Validates that the current phase meets completion criteria (tasks done, verification passed, no unresolved gaps), marks it complete, extracts learnings, and advances to the next phase. Creates next phase directory if needed.
+
+---
+
+## Implementation
+
+### Step 1: Parse Arguments
+
+Extract:
+- Phase number (optional, integer)
+- `--force` flag
+
+### Step 2: Load State
+
+```bash
+cat .workflow/state.json
+```
+
+Determine phase number:
+- If provided: use specified phase
+- If omitted: use `current_phase` from state.json
+- If neither: error E001
+
+### Step 3: Resolve Phase Directory
+
+```bash
+ls -d .workflow/phases/*/ | grep "^.workflow/phases/0*{N}-"
+```
+
+Read phase files:
+- `.workflow/phases/{NN}-{slug}/index.json` — phase metadata, task statuses
+- `.workflow/phases/{NN}-{slug}/verification.json` — verification results (if exists)
+- `.workflow/phases/{NN}-{slug}/review.json` — code review results (if exists)
+
+### Step 4: Validate Completion
+
+Check the following (skip all if `--force`):
+
+1. **Task completion**: All tasks in index.json have status "completed" or "skipped"
+2. **Verification passed**: verification.json exists and verdict is not "FAIL" (E002 if failed)
+3. **No critical gaps**: No unresolved critical gaps in verification results (E003)
+4. **Review status**: Check review.json if exists
+   - BLOCK verdict → W003 (warning, suggest quality-review fix)
+   - No review.json → W004 (warning, suggest running quality-review)
+5. **UAT status**: Check for test failures → W002
+
+If warnings only (no errors) and not `--force`: display warnings and ask user to confirm.
+
+### Step 5: Mark Phase Complete
+
+Update `.workflow/phases/{NN}-{slug}/index.json`:
+```json
+{
+  "status": "complete",
+  "completed_at": "<ISO timestamp>"
+}
+```
+
+### Step 6: Extract Learnings
+
+Analyze phase artifacts for learnings:
+1. Read verification.json gaps and resolutions
+2. Read review.json feedback patterns
+3. Read task summaries for recurring themes
+4. Identify patterns: what worked, what didn't, what to carry forward
+
+Append to `.workflow/specs/learnings.md`:
+```markdown
+## Phase {N}: {slug}
+**Completed**: {date}
+
+### What Worked
+- {items}
+
+### Challenges
+- {items}
+
+### Carry Forward
+- {items}
+```
+
+### Step 7: Initialize Next Phase
+
+Determine next phase number = N + 1.
+
+Check if next phase directory exists:
+- If exists: verify index.json has status "pending", update to "active"
+- If not exists: create directory and initialize
+
+```bash
+mkdir -p .workflow/phases/{NN+1}-{next_slug}
+```
+
+Write `index.json` for next phase (read template from `~/.maestro/templates/index.json` if available):
+```json
+{
+  "phase": <N+1>,
+  "status": "active",
+  "created_at": "<ISO timestamp>"
+}
+```
+
+### Step 8: Update Project State
+
+Update `.workflow/state.json`:
+- `current_phase`: N + 1
+- `phases_completed`: append phase N
+
+### Step 9: Completion Report
+
+```
+=== PHASE TRANSITION ===
+From: Phase {N} ({slug}) → COMPLETE
+To:   Phase {N+1} ({next_slug}) → ACTIVE
+
+Learnings extracted: .workflow/specs/learnings.md
+State updated:       .workflow/state.json
+
+Next steps:
+  $maestro-plan ""    -- Plan tasks for Phase {N+1}
+  $maestro-status     -- View project dashboard
+```
+
+---
+
+## Error Handling
+
+| Code | Severity | Description | Recovery |
+|------|----------|-------------|----------|
+| E001 | error | Phase number required and could not determine | Specify phase number explicitly |
+| E002 | error | Phase has not passed verification | Run maestro-verify first |
+| E003 | error | Phase has unresolved critical gaps | Fix gaps, re-verify |
+| W001 | warning | Phase has warnings but no blockers | Proceed with confirmation |
+| W002 | warning | UAT test failures exist | Review recommended |
+| W003 | warning | Code review verdict is BLOCK | Fix review findings first |
+| W004 | warning | Code review not yet run | Run quality-review first |
+
+---
+
+## Core Rules
+
+1. **Verify before transition** — refuse to transition without verification (unless --force)
+2. **Learnings are mandatory** — always extract and persist learnings, even if minimal
+3. **Next phase must be ready** — create directory and index.json before reporting success
+4. **State consistency** — state.json and index.json must agree at all times
+5. **Warnings need acknowledgment** — display warnings and require user confirmation (unless --force)