maestro-flow 0.1.3 → 0.2.0

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

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

@@ -1,173 +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)
+---
+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)