maestro-flow 0.3.8 → 0.3.10

package/.claude/commands/manage-issue-analyze.md

@@ -1,62 +0,0 @@
----
-name: manage-issue-analyze
-description: Root cause analysis for a specific issue using CLI exploration
-argument-hint: "<ISS-ID> [--tool gemini|qwen] [--depth standard|deep]"
-allowed-tools:
-  - Read
-  - Write
-  - Bash
-  - Glob
-  - Grep
-  - Agent
-  - AskUserQuestion
----
-<purpose>
-Root cause analysis for a specific issue. Uses CLI exploration to analyze codebase context, identify root cause, assess impact, and produce a structured analysis record attached to the issue in `.workflow/issues/issues.jsonl`.
-
-- **--tool**: CLI tool for analysis (default: gemini)
-- **--depth**: `standard` (keyword grep) or `deep` (semantic search via Agent)
-
-For issue CRUD, use `/manage-issue`. For solution planning, use `/manage-issue-plan`.
-</purpose>
-
-<required_reading>
-@~/.maestro/workflows/issue-analyze.md
-</required_reading>
-
-<deferred_reading>
-- [issue.json template](~/.maestro/templates/issue.json) -- read when building the analysis record structure
-</deferred_reading>
-
-<context>
-$ARGUMENTS -- ISS-ID (required) + optional flags.
-
-**Options:**
-- `<ISS-ID>` -- issue ID in ISS-XXXXXXXX-NNN format (required)
-- `--tool gemini|qwen` -- CLI tool for analysis (default: gemini)
-- `--depth standard|deep` -- analysis depth (default: standard)
-
-**State files:**
-- `.workflow/issues/issues.jsonl` -- issue records (read + write)
-</context>
-
-<execution>
-Follow '~/.maestro/workflows/issue-analyze.md' completely.
-</execution>
-
-<error_codes>
-| Code | Severity | Condition | Recovery |
-|------|----------|-----------|----------|
-| E_NO_ISSUE_ID | error | No ISS-ID provided in $ARGUMENTS | Display usage hint with example |
-| E_ISSUE_NOT_FOUND | error | ISS-ID not found in issues.jsonl | Suggest `/manage-issue list` to find valid IDs |
-| E_INVALID_STATUS | warning | Issue status is not 'open' or 'registered' | Warn but allow analysis to proceed |
-| E_ANALYSIS_FAILED | error | CLI analysis returned no usable results | Retry with different --tool or report partial context |
-</error_codes>
-
-<success_criteria>
-- [ ] Issue loaded and validated from issues.jsonl
-- [ ] Codebase context gathered (grep or semantic search)
-- [ ] CLI analysis executed and JSON result parsed
-- [ ] Analysis record attached to issue in issues.jsonl
-- [ ] Summary displayed with next-step routing to manage-issue-plan
-</success_criteria>

package/.claude/commands/manage-issue-execute.md

@@ -1,73 +0,0 @@
----
-name: manage-issue-execute
-description: Execute planned solution for an issue via dual-mode agent dispatch
-argument-hint: "<ISS-ID> [--executor claude-code|codex|gemini] [--dry-run]"
-allowed-tools:
-  - Read
-  - Write
-  - Bash
-  - Glob
-  - Grep
-  - Agent
-  - AskUserQuestion
----
-<purpose>
-Execute a planned solution for a specific issue. Supports dual-mode dispatch:
-
-- **Server UP**: POST to `/api/execution/dispatch` for orchestrated execution
-- **Server DOWN**: Direct execution via `maestro delegate` with the solution prompt
-
-Options:
-- **--executor**: Agent to execute the solution (default: claude-code)
-- **--dry-run**: Display the constructed prompt and steps without executing
-
-For issue CRUD, use `/manage-issue`. For analysis, use `/manage-issue-analyze`. For planning, use `/manage-issue-plan`.
-</purpose>
-
-<required_reading>
-@~/.maestro/workflows/issue-execute.md
-</required_reading>
-
-<deferred_reading>
-- [issue.json template](~/.maestro/templates/issue.json) -- read when updating issue status after execution
-</deferred_reading>
-
-<context>
-$ARGUMENTS -- ISS-ID (required) + optional flags.
-
-**Options:**
-- `<ISS-ID>` -- issue ID in ISS-XXXXXXXX-NNN format (required)
-- `--executor claude-code|codex|gemini` -- execution agent (default: claude-code)
-- `--dry-run` -- preview prompt and steps without executing
-
-**State files:**
-- `.workflow/issues/issues.jsonl` -- issue records (read + write)
-</context>
-
-<execution>
-Follow '~/.maestro/workflows/issue-execute.md' completely.
-
-**Next-step routing on completion:**
-- Execution succeeded → Skill({ skill: "manage-issue", args: "close <ISS-ID> --resolution fixed" })
-- Execution failed → Skill({ skill: "quality-debug", args: "<failure description>" }) then retry
-- Want verification → Skill({ skill: "maestro-verify", args: "{phase}" })
-</execution>
-
-<error_codes>
-| Code | Severity | Condition | Recovery |
-|------|----------|-----------|----------|
-| E_NO_ISSUE_ID | error | No ISS-ID provided in $ARGUMENTS | Display usage hint with example |
-| E_NO_SOLUTION | error | Issue has no solution record (issue.solution is null) | Suggest `/manage-issue-plan` first |
-| E_DISPATCH_FAILED | error | Server dispatch or CLI execution failed | Log error, revert status to open, display failure details |
-</error_codes>
-
-<success_criteria>
-- [ ] Issue loaded with valid solution record
-- [ ] Execution mode detected (server UP or DOWN)
-- [ ] Solution executed (or dry-run displayed)
-- [ ] Issue status updated in issues.jsonl (in_progress -> resolved or open on failure)
-- [ ] Result summary displayed with next-step routing:
-  - Execution succeeded → Skill({ skill: "manage-issue", args: "close <ISS-ID> --resolution fixed" })
-  - Execution failed → Skill({ skill: "quality-debug", args: "<failure description>" }) then retry
-  - Want verification → Skill({ skill: "maestro-verify", args: "{phase}" })
-</success_criteria>

package/.claude/commands/manage-issue-plan.md

@@ -1,62 +0,0 @@
----
-name: manage-issue-plan
-description: Solution planning for a specific issue with codebase-aware step generation
-argument-hint: "<ISS-ID> [--tool gemini|qwen] [--from-analysis]"
-allowed-tools:
-  - Read
-  - Write
-  - Bash
-  - Glob
-  - Grep
-  - Agent
-  - AskUserQuestion
----
-<purpose>
-Solution planning for a specific issue. Generates a structured, codebase-aware solution with ordered steps, context, and a prompt template for execution. Attaches the solution record to the issue in `.workflow/issues/issues.jsonl`.
-
-- **--tool**: CLI tool for planning (default: gemini)
-- **--from-analysis**: Auto-detected; includes analysis context (root_cause, related_files) in the planning prompt if issue.analysis exists
-
-For issue CRUD, use `/manage-issue`. For execution, use `/manage-issue-execute`.
-</purpose>
-
-<required_reading>
-@~/.maestro/workflows/issue-plan.md
-</required_reading>
-
-<deferred_reading>
-- [issue.json template](~/.maestro/templates/issue.json) -- read when building the solution record structure
-</deferred_reading>
-
-<context>
-$ARGUMENTS -- ISS-ID (required) + optional flags.
-
-**Options:**
-- `<ISS-ID>` -- issue ID in ISS-XXXXXXXX-NNN format (required)
-- `--tool gemini|qwen` -- CLI tool for planning (default: gemini)
-- `--from-analysis` -- explicitly include analysis context (auto-detected if issue.analysis exists)
-
-**State files:**
-- `.workflow/issues/issues.jsonl` -- issue records (read + write)
-</context>
-
-<execution>
-Follow '~/.maestro/workflows/issue-plan.md' completely.
-</execution>
-
-<error_codes>
-| Code | Severity | Condition | Recovery |
-|------|----------|-----------|----------|
-| E_NO_ISSUE_ID | error | No ISS-ID provided in $ARGUMENTS | Display usage hint with example |
-| E_ISSUE_NOT_FOUND | error | ISS-ID not found in issues.jsonl | Suggest `/manage-issue list` to find valid IDs |
-| E_NO_ANALYSIS | warning | No analysis record on issue and --from-analysis specified | Proceed without analysis context, suggest `/manage-issue-analyze` first |
-| E_PLANNING_FAILED | error | CLI planning returned no usable results | Retry with different --tool or report partial output |
-</error_codes>
-
-<success_criteria>
-- [ ] Issue loaded and validated from issues.jsonl
-- [ ] Analysis context included in prompt (if available)
-- [ ] CLI planning executed and solution JSON parsed
-- [ ] Solution record attached to issue in issues.jsonl
-- [ ] Solution steps displayed with next-step routing to manage-issue-execute
-</success_criteria>

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

@@ -1,154 +0,0 @@
----
-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
-  $manage-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 +0,0 @@
----
-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}
-  $manage-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)