maestro-flow 0.3.4 → 0.3.6

package/.codex/skills/maestro-init/SKILL.md

@@ -1,167 +1,167 @@
----
-name: maestro-init
-description: Initialize project with auto state detection — creates .workflow/ directory, project.md, state.json, config.json, and specs/
-argument-hint: "[--auto] [--from-brainstorm SESSION-ID]"
-allowed-tools: Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion
----
-
-## Auto Mode
-
-When `--auto`: After config questions, run research without further interaction. Expects idea document via @ reference.
-
-# Maestro Init (Single Agent)
-
-## Usage
-
-```bash
-$maestro-init ""
-$maestro-init "--auto"
-$maestro-init "--from-brainstorm brainstorm-auth-20260318"
-```
-
-**Flags**:
-- `--auto`: Skip interactive questioning; extract from provided document
-- `--from-brainstorm SESSION-ID`: Import vision/goals/constraints from brainstorm guidance-specification.md
-
-**Output**: `.workflow/` directory with project.md, state.json, config.json, specs/
-
----
-
-## Overview
-
-Sequential project setup skill. Detects project state (empty/code/existing), gathers project information through deep questioning or document extraction, then creates the `.workflow/` directory structure. No parallel agents — single sequential flow.
-
----
-
-## Implementation
-
-### Step 1: Parse Arguments
-
-Extract flags from arguments:
-- `--auto` flag presence
-- `--from-brainstorm SESSION-ID` value
-- Remaining text as project description
-
-### Step 2: Detect Project State
-
-```bash
-# Check existing state
-ls .workflow/state.json 2>/dev/null
-ls package.json pyproject.toml Cargo.toml go.mod 2>/dev/null
-```
-
-Classify as:
-- **existing**: `.workflow/state.json` found — warn and exit (E002)
-- **code**: Source files present but no `.workflow/` — onboarding existing codebase
-- **empty**: Greenfield project
-
-### Step 3: Gather Project Information
-
-**If `--from-brainstorm`**:
-- Read `.workflow/.brainstorm/{SESSION-ID}/guidance-specification.md`
-- Extract: vision, goals, constraints, terminology, tech decisions
-- Skip interactive questioning
-
-**If `--auto`**:
-- Extract project info from provided document/@ reference
-- Minimal interactive questions (confirm core value only)
-
-**Otherwise (interactive)**:
-- Deep questioning flow:
-  1. What is the core value proposition?
-  2. Who are the target users?
-  3. What are the key requirements? (follow threads, don't rush)
-  4. What are known constraints/limitations?
-  5. What tech stack preferences exist?
-- Follow each thread with clarifying questions until satisfied
-
-### Step 4: Read Templates
-
-Read the following templates:
-- `~/.maestro/templates/project.md`
-- `~/.maestro/templates/state.json`
-- `~/.maestro/templates/config.json`
-
-### Step 5: Create .workflow/ Structure
-
-```bash
-mkdir -p .workflow/specs .workflow/phases .workflow/scratch .workflow/codebase
-```
-
-### Step 6: Write project.md
-
-Populate template with gathered information:
-- Project name, core value proposition
-- Requirements: Validated / Active / Out of Scope
-- Key decisions and constraints
-- Tech stack (detected or specified)
-
-Write to `.workflow/project.md`.
-
-### Step 7: Write state.json
-
-Initialize state from template:
-- `current_phase`: null
-- `current_milestone`: null
-- `status`: "initialized"
-
-Write to `.workflow/state.json`.
-
-### Step 8: Write config.json
-
-Configuration questions (or defaults for --auto):
-- Granularity: fine / medium / coarse
-- Workflow agents: enable/disable optional agents
-- Gate preferences: verification strictness
-
-Write to `.workflow/config.json`.
-
-### Step 9: Initialize specs/
-
-Create convention files in `.workflow/specs/`:
-- `conventions.md` — detected or specified coding conventions
-- `learnings.md` — empty, populated during phase transitions
-
-### Step 10: Completion Report
-
-```
-=== WORKFLOW INITIALIZED ===
-Project: {project_name}
-State:   .workflow/state.json (active)
-
-Created:
-  .workflow/project.md
-  .workflow/state.json
-  .workflow/config.json
-  .workflow/specs/
-
-Next steps (choose one path to create roadmap):
-  $maestro-spec-generate "<idea>"   -- Full spec package + roadmap (heavy)
-  $maestro-roadmap "<requirement>"  -- Direct interactive roadmap (light)
-
-Other commands:
-  $maestro-status                   -- View project dashboard
-  $maestro-brainstorm "<topic>"     -- Explore ideas first
-  $maestro-quick "<task>"           -- Quick ad-hoc task
-```
-
----
-
-## Error Handling
-
-| Code | Severity | Description | Recovery |
-|------|----------|-------------|----------|
-| E001 | error | No arguments when --auto requires document | Ask user for document reference |
-| E002 | error | .workflow/ already exists | Show status, suggest manage-status |
-| E003 | error | Brainstorm session not found | List available sessions |
-| W001 | warning | Could not detect tech stack | Continue with manual input |
-
----
-
-## Core Rules
-
-1. **Never create roadmap** — init only creates .workflow/ structure; roadmap is a separate step
-2. **Deep questioning over speed** — follow threads, ask clarifying questions (unless --auto)
-3. **Detect, don't assume** — scan for existing files, package managers, frameworks before asking
-4. **Templates are source of truth** — always read templates before writing files
-5. **Idempotent check** — if .workflow/ exists, refuse to overwrite (E002)
+---
+name: maestro-init
+description: Initialize project with auto state detection — creates .workflow/ directory, project.md, state.json, config.json, and specs/
+argument-hint: "[--auto] [--from-brainstorm SESSION-ID]"
+allowed-tools: Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion
+---
+
+## Auto Mode
+
+When `--auto`: After config questions, run research without further interaction. Expects idea document via @ reference.
+
+# Maestro Init (Single Agent)
+
+## Usage
+
+```bash
+$maestro-init ""
+$maestro-init "--auto"
+$maestro-init "--from-brainstorm brainstorm-auth-20260318"
+```
+
+**Flags**:
+- `--auto`: Skip interactive questioning; extract from provided document
+- `--from-brainstorm SESSION-ID`: Import vision/goals/constraints from brainstorm guidance-specification.md
+
+**Output**: `.workflow/` directory with project.md, state.json, config.json, specs/
+
+---
+
+## Overview
+
+Sequential project setup skill. Detects project state (empty/code/existing), gathers project information through deep questioning or document extraction, then creates the `.workflow/` directory structure. No parallel agents — single sequential flow.
+
+---
+
+## Implementation
+
+### Step 1: Parse Arguments
+
+Extract flags from arguments:
+- `--auto` flag presence
+- `--from-brainstorm SESSION-ID` value
+- Remaining text as project description
+
+### Step 2: Detect Project State
+
+```bash
+# Check existing state
+ls .workflow/state.json 2>/dev/null
+ls package.json pyproject.toml Cargo.toml go.mod 2>/dev/null
+```
+
+Classify as:
+- **existing**: `.workflow/state.json` found — warn and exit (E002)
+- **code**: Source files present but no `.workflow/` — onboarding existing codebase
+- **empty**: Greenfield project
+
+### Step 3: Gather Project Information
+
+**If `--from-brainstorm`**:
+- Read `.workflow/.brainstorm/{SESSION-ID}/guidance-specification.md`
+- Extract: vision, goals, constraints, terminology, tech decisions
+- Skip interactive questioning
+
+**If `--auto`**:
+- Extract project info from provided document/@ reference
+- Minimal interactive questions (confirm core value only)
+
+**Otherwise (interactive)**:
+- Deep questioning flow:
+  1. What is the core value proposition?
+  2. Who are the target users?
+  3. What are the key requirements? (follow threads, don't rush)
+  4. What are known constraints/limitations?
+  5. What tech stack preferences exist?
+- Follow each thread with clarifying questions until satisfied
+
+### Step 4: Read Templates
+
+Read the following templates:
+- `~/.maestro/templates/project.md`
+- `~/.maestro/templates/state.json`
+- `~/.maestro/templates/config.json`
+
+### Step 5: Create .workflow/ Structure
+
+```bash
+mkdir -p .workflow/specs .workflow/phases .workflow/scratch .workflow/codebase
+```
+
+### Step 6: Write project.md
+
+Populate template with gathered information:
+- Project name, core value proposition
+- Requirements: Validated / Active / Out of Scope
+- Key decisions and constraints
+- Tech stack (detected or specified)
+
+Write to `.workflow/project.md`.
+
+### Step 7: Write state.json
+
+Initialize state from template:
+- `current_phase`: null
+- `current_milestone`: null
+- `status`: "initialized"
+
+Write to `.workflow/state.json`.
+
+### Step 8: Write config.json
+
+Configuration questions (or defaults for --auto):
+- Granularity: fine / medium / coarse
+- Workflow agents: enable/disable optional agents
+- Gate preferences: verification strictness
+
+Write to `.workflow/config.json`.
+
+### Step 9: Initialize specs/
+
+Create convention files in `.workflow/specs/`:
+- `conventions.md` — detected or specified coding conventions
+- `learnings.md` — empty, populated during phase transitions
+
+### Step 10: Completion Report
+
+```
+=== WORKFLOW INITIALIZED ===
+Project: {project_name}
+State:   .workflow/state.json (active)
+
+Created:
+  .workflow/project.md
+  .workflow/state.json
+  .workflow/config.json
+  .workflow/specs/
+
+Next steps (choose one path to create roadmap):
+  $maestro-spec-generate "<idea>"   -- Full spec package + roadmap (heavy)
+  $maestro-roadmap "<requirement>"  -- Direct interactive roadmap (light)
+
+Other commands:
+  $manage-status                   -- View project dashboard
+  $maestro-brainstorm "<topic>"     -- Explore ideas first
+  $maestro-quick "<task>"           -- Quick ad-hoc task
+```
+
+---
+
+## Error Handling
+
+| Code | Severity | Description | Recovery |
+|------|----------|-------------|----------|
+| E001 | error | No arguments when --auto requires document | Ask user for document reference |
+| E002 | error | .workflow/ already exists | Show status, suggest manage-status |
+| E003 | error | Brainstorm session not found | List available sessions |
+| W001 | warning | Could not detect tech stack | Continue with manual input |
+
+---
+
+## Core Rules
+
+1. **Never create roadmap** — init only creates .workflow/ structure; roadmap is a separate step
+2. **Deep questioning over speed** — follow threads, ask clarifying questions (unless --auto)
+3. **Detect, don't assume** — scan for existing files, package managers, frameworks before asking
+4. **Templates are source of truth** — always read templates before writing files
+5. **Idempotent check** — if .workflow/ exists, refuse to overwrite (E002)

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
+  $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