maestro-flow 0.3.9 → 0.3.11

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

@@ -1,185 +1,188 @@
----
-name: maestro-overlay
-description: Create or edit a non-invasive command overlay from natural-language intent. Writes a JSON patch file to ~/.maestro/overlays/, applies it via maestro overlay add, and confirms installation with idempotent re-apply support.
-argument-hint: "<intent> | --list | --remove <name>"
-allowed-tools: Read, Write, Bash, Glob, Grep
----
-
-# Maestro Overlay
-
-## Usage
-
-```bash
-$maestro-overlay "always run CLI verification after maestro-execute"
-$maestro-overlay "require reading doc X before maestro-plan"
-$maestro-overlay "--list"
-$maestro-overlay "--remove cli-verify-after-execute"
-```
-
-**Flags**:
-- `<intent>` — Natural-language description of what to inject and where
-- `--list` — Show installed overlays and their applied state
-- `--remove <name>` — Strip overlay from targets and delete its file
-
-**Overlay storage**:
-- User overlays: `~/.maestro/overlays/*.json`
-- Shared docs: `~/.maestro/overlays/docs/*.md`
-- Shipped examples: `~/.maestro/overlays/_shipped/` (read-only)
-
----
-
-## Overview
-
-4-step pipeline: parse intent → identify targets + injection points → draft overlay JSON → install via CLI and report. Overlays are JSON patch files that augment `.claude/commands/*.md` non-invasively. They survive reinstalls because `maestro install` auto-reapplies them. Each overlay is idempotent: the patcher wraps content in hashed HTML-comment markers, so re-running `maestro overlay apply` produces no file changes.
-
-```
-Parse Intent  →  Identify Targets  →  Draft JSON  →  Install + Report
-(or --list /      (read command        (apply_patch    (exec_command +
-  --remove)         XML sections)       to overlays/)    banner)
-```
-
-**Available injection sections**: `purpose`, `required_reading`, `deferred_reading`, `context`, `execution`, `error_codes`, `success_criteria`
-
-**Patch modes**: `append`, `prepend`, `replace`, `new-section`
-
----
-
-## Implementation
-
-### Step 1: Parse User Intent
-
-```javascript
-functions.update_plan({
-  explanation: "Parsing overlay intent",
-  plan: [
-    { step: "Parse intent", status: "in_progress" },
-    { step: "Identify targets and injection points", status: "pending" },
-    { step: "Draft overlay JSON", status: "pending" },
-    { step: "Install and report", status: "pending" }
-  ]
-})
-```
-
-**Quick-exit paths**:
-- `--list` → `functions.exec_command({ cmd: "maestro overlay list" })` then stop
-- `--remove <name>` → `functions.exec_command({ cmd: "maestro overlay remove <name>" })` then stop
-
-**Ambiguous intent**: If intent does not clearly specify (a) which command to target or (b) where in the flow to inject, ask up to 2 focused questions:
-```javascript
-functions.request_user_input({
-  id: "overlay-clarify",
-  message: "Which command(s) should this overlay target? (e.g. maestro-execute, maestro-plan)"
-})
-```
-
-### Step 2: Identify Targets and Injection Points
-
-For each likely target command, read the pristine source from `$PKG_ROOT/.claude/commands/<name>.md` (preferred) or fall back to `~/.claude/commands/<name>.md`. Inspect XML sections and select injection point:
-
-| Intent type | Section | Mode |
-|-------------|---------|------|
-| New step after execution | `execution` | `append` |
-| Required reading / prerequisite | `required_reading` | `append` |
-| Preconditions / gating | `context` | `append` |
-| Output quality gate | `success_criteria` | `append` |
-| Brand-new section | `execution` | `new-section` (with `afterSection`) |
-
-### Step 3: Draft Overlay JSON
-
-Build a slug from intent (kebab-case, lowercase, max 40 chars).
-
-```javascript
-functions.apply_patch:
-*** Begin Patch
-*** Add File: ~/.maestro/overlays/<slug>.json
-+{
-+  "name": "<slug>",
-+  "description": "<short summary of what and why>",
-+  "targets": ["<command-name>"],
-+  "priority": 50,
-+  "enabled": true,
-+  "patches": [
-+    {
-+      "section": "<section>",
-+      "mode": "<append|prepend|replace|new-section>",
-+      "content": "<injected markdown content with (overlay) heading>"
-+    }
-+  ]
-+}
-*** End Patch
-```
-
-**Content guidelines**:
-- Lead injected block with heading including `(overlay)` e.g. `## CLI Verification (overlay)`
-- `@~/.maestro/...` references are encouraged for docs
-- Keep content concise — overlay adds a step, not rewrites the command
-
-```javascript
-functions.update_plan({
-  explanation: "Overlay JSON drafted",
-  plan: [
-    { step: "Parse intent", status: "completed" },
-    { step: "Identify targets and injection points", status: "completed" },
-    { step: "Draft overlay JSON", status: "completed" },
-    { step: "Install and report", status: "in_progress" }
-  ]
-})
-```
-
-### Step 4: Install via CLI and Report
-
-```javascript
-functions.exec_command({
-  cmd: "maestro overlay add ~/.maestro/overlays/<slug>.json",
-  workdir: "."
-})
-```
-
-On validation failure, fix the JSON and re-run (max 2 retries).
-
-```javascript
-functions.update_plan({
-  explanation: "Overlay installed",
-  plan: [
-    { step: "Parse intent", status: "completed" },
-    { step: "Identify targets and injection points", status: "completed" },
-    { step: "Draft overlay JSON", status: "completed" },
-    { step: "Install and report", status: "completed" }
-  ]
-})
-```
-
-Display report:
-```
-=== OVERLAY INSTALLED ===
-Name:    <slug>
-Path:    ~/.maestro/overlays/<slug>.json
-Targets: <command> (applied), <command> (skipped: missing)
-Scopes:  [global]
-
-Re-apply: maestro overlay apply
-Remove:   maestro overlay remove <slug>
-Inspect:  maestro overlay list
-```
-
----
-
-## Error Handling
-
-| Code | Severity | Description | Recovery |
-|------|----------|-------------|----------|
-| E001 | error | `maestro overlay add` validation failed | Fix JSON syntax or section name, retry |
-| E002 | error | No targets found (all commands missing) | Check command name spelling |
-| E003 | error | `--remove` target not found in overlay store | Run `--list` to see installed overlays |
-| W001 | warning | One or more targets skipped (command missing from install) | Overlay still installed; applies when command is added |
-
----
-
-## Core Rules
-
-1. **Quick-exit first**: `--list` and `--remove` skip all intent parsing
-2. **Pristine source preferred**: Always read `.claude/commands/<name>.md` for the untouched command spec before deciding injection point
-3. **Idempotent content**: Injected blocks use hashed comment markers — re-runs produce no changes
-4. **Heading required**: Every injected block must start with a `## <Title> (overlay)` heading
-5. **Validate before report**: Run `maestro overlay add` successfully before displaying the report banner
-6. **Max 2 clarification questions**: If intent is ambiguous, ask at most 2 focused questions then proceed with best guess
+---
+name: maestro-overlay
+description: Create or edit a non-invasive command overlay from natural-language intent. Writes a JSON patch file to ~/.maestro/overlays/, applies it via maestro overlay add, and confirms installation with idempotent re-apply support.
+argument-hint: "<intent> | --list | --remove <name>"
+allowed-tools: Read, Write, Bash, Glob, Grep
+---
+
+<purpose>
+4-step pipeline: parse intent → identify targets + injection points → draft overlay JSON → install via CLI and report. Overlays are JSON patch files that augment `.claude/commands/*.md` non-invasively. They survive reinstalls because `maestro install` auto-reapplies them. Each overlay is idempotent: the patcher wraps content in hashed HTML-comment markers, so re-running `maestro overlay apply` produces no file changes.
+
+```
+Parse Intent  →  Identify Targets  →  Draft JSON  →  Install + Report
+(or --list /      (read command        (apply_patch    (exec_command +
+  --remove)         XML sections)       to overlays/)    banner)
+```
+
+**Available injection sections**: `purpose`, `required_reading`, `deferred_reading`, `context`, `execution`, `error_codes`, `success_criteria`
+
+**Patch modes**: `append`, `prepend`, `replace`, `new-section`
+</purpose>
+
+<context>
+
+```bash
+$maestro-overlay "always run CLI verification after maestro-execute"
+$maestro-overlay "require reading doc X before maestro-plan"
+$maestro-overlay "--list"
+$maestro-overlay "--remove cli-verify-after-execute"
+```
+
+**Flags**:
+- `<intent>` — Natural-language description of what to inject and where
+- `--list` — Show installed overlays and their applied state
+- `--remove <name>` — Strip overlay from targets and delete its file
+
+**Overlay storage**:
+- User overlays: `~/.maestro/overlays/*.json`
+- Shared docs: `~/.maestro/overlays/docs/*.md`
+- Shipped examples: `~/.maestro/overlays/_shipped/` (read-only)
+
+</context>
+
+<invariants>
+1. **Quick-exit first**: `--list` and `--remove` skip all intent parsing
+2. **Pristine source preferred**: Always read `.claude/commands/<name>.md` for the untouched command spec before deciding injection point
+3. **Idempotent content**: Injected blocks use hashed comment markers — re-runs produce no changes
+4. **Heading required**: Every injected block must start with a `## <Title> (overlay)` heading
+5. **Validate before report**: Run `maestro overlay add` successfully before displaying the report banner
+6. **Max 2 clarification questions**: If intent is ambiguous, ask at most 2 focused questions then proceed with best guess
+</invariants>
+
+<execution>
+
+### Step 1: Parse User Intent
+
+```javascript
+functions.update_plan({
+  explanation: "Parsing overlay intent",
+  plan: [
+    { step: "Parse intent", status: "in_progress" },
+    { step: "Identify targets and injection points", status: "pending" },
+    { step: "Draft overlay JSON", status: "pending" },
+    { step: "Install and report", status: "pending" }
+  ]
+})
+```
+
+**Quick-exit paths**:
+- `--list` → `functions.exec_command({ cmd: "maestro overlay list" })` then stop
+- `--remove <name>` → `functions.exec_command({ cmd: "maestro overlay remove <name>" })` then stop
+
+**Ambiguous intent**: If intent does not clearly specify (a) which command to target or (b) where in the flow to inject, ask up to 2 focused questions:
+```javascript
+functions.request_user_input({
+  id: "overlay-clarify",
+  message: "Which command(s) should this overlay target? (e.g. maestro-execute, maestro-plan)"
+})
+```
+
+### Step 2: Identify Targets and Injection Points
+
+For each likely target command, read the pristine source from `$PKG_ROOT/.claude/commands/<name>.md` (preferred) or fall back to `~/.claude/commands/<name>.md`. Inspect XML sections and select injection point:
+
+| Intent type | Section | Mode |
+|-------------|---------|------|
+| New step after execution | `execution` | `append` |
+| Required reading / prerequisite | `required_reading` | `append` |
+| Preconditions / gating | `context` | `append` |
+| Output quality gate | `success_criteria` | `append` |
+| Brand-new section | `execution` | `new-section` (with `afterSection`) |
+
+### Step 3: Draft Overlay JSON
+
+Build a slug from intent (kebab-case, lowercase, max 40 chars).
+
+```javascript
+functions.apply_patch:
+*** Begin Patch
+*** Add File: ~/.maestro/overlays/<slug>.json
++{
++  "name": "<slug>",
++  "description": "<short summary of what and why>",
++  "targets": ["<command-name>"],
++  "priority": 50,
++  "enabled": true,
++  "patches": [
++    {
++      "section": "<section>",
++      "mode": "<append|prepend|replace|new-section>",
++      "content": "<injected markdown content with (overlay) heading>"
++    }
++  ]
++}
+*** End Patch
+```
+
+**Content guidelines**:
+- Lead injected block with heading including `(overlay)` e.g. `## CLI Verification (overlay)`
+- `@~/.maestro/...` references are encouraged for docs
+- Keep content concise — overlay adds a step, not rewrites the command
+
+```javascript
+functions.update_plan({
+  explanation: "Overlay JSON drafted",
+  plan: [
+    { step: "Parse intent", status: "completed" },
+    { step: "Identify targets and injection points", status: "completed" },
+    { step: "Draft overlay JSON", status: "completed" },
+    { step: "Install and report", status: "in_progress" }
+  ]
+})
+```
+
+### Step 4: Install via CLI and Report
+
+```javascript
+functions.exec_command({
+  cmd: "maestro overlay add ~/.maestro/overlays/<slug>.json",
+  workdir: "."
+})
+```
+
+On validation failure, fix the JSON and re-run (max 2 retries).
+
+```javascript
+functions.update_plan({
+  explanation: "Overlay installed",
+  plan: [
+    { step: "Parse intent", status: "completed" },
+    { step: "Identify targets and injection points", status: "completed" },
+    { step: "Draft overlay JSON", status: "completed" },
+    { step: "Install and report", status: "completed" }
+  ]
+})
+```
+
+Display report:
+```
+=== OVERLAY INSTALLED ===
+Name:    <slug>
+Path:    ~/.maestro/overlays/<slug>.json
+Targets: <command> (applied), <command> (skipped: missing)
+Scopes:  [global]
+
+Re-apply: maestro overlay apply
+Remove:   maestro overlay remove <slug>
+Inspect:  maestro overlay list
+```
+
+</execution>
+
+<error_codes>
+
+| Code | Severity | Description | Recovery |
+|------|----------|-------------|----------|
+| E001 | error | `maestro overlay add` validation failed | Fix JSON syntax or section name, retry |
+| E002 | error | No targets found (all commands missing) | Check command name spelling |
+| E003 | error | `--remove` target not found in overlay store | Run `--list` to see installed overlays |
+| W001 | warning | One or more targets skipped (command missing from install) | Overlay still installed; applies when command is added |
+
+</error_codes>
+
+<success_criteria>
+- [ ] Intent parsed and targets identified
+- [ ] Overlay JSON drafted with correct section and mode
+- [ ] `maestro overlay add` executed successfully
+- [ ] Report displayed with apply/remove/inspect commands
+</success_criteria>

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

@@ -5,35 +5,7 @@ argument-hint: "[-y|--yes] [-c|--concurrency N] [--continue] \"<phase> [--auto]
 allowed-tools: spawn_agents_on_csv, Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion
 ---
 
-## Auto Mode
-
-When `--yes` or `-y`: Auto-confirm exploration angles, skip interactive clarification (P2), use defaults for complexity detection.
-
-# Maestro Plan (CSV Wave)
-
-## Usage
-
-```bash
-$maestro-plan "3"
-$maestro-plan -y "3 --auto"
-$maestro-plan -c 4 "3 --spec SPEC-001"
-$maestro-plan "3 --gaps"
-$maestro-plan "3 --dir .workflow/scratch/quick-nav-fix"
-$maestro-plan --continue "plan-phase3-20260318"
-```
-
-**Flags**:
-- `-y, --yes`: Skip all confirmations (auto mode)
-- `-c, --concurrency N`: Max concurrent agents within each wave (default: 4)
-- `--continue`: Resume existing session
-
-**Output Directory**: `.workflow/.csv-wave/{session-id}/`
-**Core Output**: `tasks.csv` (master state) + `results.csv` (final) + `discoveries.ndjson` (shared exploration) + `context.md` (human-readable report) + `plan.json` + `.task/TASK-*.json`
-
----
-
-## Overview
-
+<purpose>
 Wave-based planning using `spawn_agents_on_csv`. Wave 1 explores codebase context in parallel across multiple angles, Wave 2 consumes all exploration findings to generate a verified execution plan.
 
 **Core workflow**: Resolve Phase -> Determine Explorations -> Parallel Exploration -> Sequential Planning -> Check + Confirm
@@ -74,10 +46,30 @@ Wave-based planning using `spawn_agents_on_csv`. Wave 1 explores codebase contex
 |                                                                           |
 +---------------------------------------------------------------------------+
 ```
+</purpose>
 
----
+<context>
+```bash
+$maestro-plan "3"
+$maestro-plan -y "3 --auto"
+$maestro-plan -c 4 "3 --spec SPEC-001"
+$maestro-plan "3 --gaps"
+$maestro-plan "3 --dir .workflow/scratch/quick-nav-fix"
+$maestro-plan --continue "plan-phase3-20260318"
+```
+
+**Flags**:
+- `-y, --yes`: Skip all confirmations (auto mode)
+- `-c, --concurrency N`: Max concurrent agents within each wave (default: 4)
+- `--continue`: Resume existing session
 
-## CSV Schema
+When `--yes` or `-y`: Auto-confirm exploration angles, skip interactive clarification (P2), use defaults for complexity detection.
+
+**Output Directory**: `.workflow/.csv-wave/{session-id}/`
+**Core Output**: `tasks.csv` (master state) + `results.csv` (final) + `discoveries.ndjson` (shared exploration) + `context.md` (human-readable report) + `plan.json` + `.task/TASK-*.json`
+</context>
+
+<csv_schema>
 
 ### tasks.csv (Master State)
 
@@ -109,9 +101,7 @@ id,title,description,exploration_focus,deps,context_from,wave,status,findings,er
 
 Each wave generates `wave-{N}.csv` with extra `prev_context` column.
 
----
-
-## Output Artifacts
+### Output Artifacts
 
 | File | Purpose | Lifecycle |
 |------|---------|-----------|
@@ -123,9 +113,7 @@ Each wave generates `wave-{N}.csv` with extra `prev_context` column.
 | `plan.json` | Execution plan (in phase directory) | Created by wave 2 agent |
 | `.task/TASK-*.json` | Individual task definitions (in phase directory) | Created by wave 2 agent |
 
----
-
-## Session Structure
+### Session Structure
 
 ```
 .workflow/.csv-wave/plan-{phase}-{date}/
@@ -135,10 +123,20 @@ Each wave generates `wave-{N}.csv` with extra `prev_context` column.
 +-- context.md
 +-- wave-{N}.csv (temporary)
 ```
+</csv_schema>
 
----
+<invariants>
+1. **Start Immediately**: First action is session initialization, then Phase 1
+2. **Wave Order is Sacred**: Never execute wave 2 before wave 1 completes and results are merged
+3. **CSV is Source of Truth**: Master tasks.csv holds all state
+4. **Context Propagation**: prev_context built from master CSV, not from memory
+5. **Discovery Board is Append-Only**: Never clear, modify, or recreate discoveries.ndjson
+6. **Skip on Failure**: If all exploration agents failed, planning agent proceeds with available context
+7. **Cleanup Temp Files**: Remove wave-{N}.csv after results are merged
+8. **DO NOT STOP**: Continuous execution until all waves complete
+</invariants>
 
-## Implementation
+<execution>
 
 ### Session Initialization
 
@@ -207,8 +205,6 @@ Bash(`mkdir -p ${sessionFolder}`)
 Bash(`mkdir -p ${scratchDir}/.task/`)
 ```
 
----
-
 ### Phase 1: Phase Resolution -> CSV
 
 **Objective**: Resolve phase, load context, determine exploration angles, generate tasks.csv.
@@ -224,7 +220,7 @@ Bash(`mkdir -p ${scratchDir}/.task/`)
    - Read spec-ref if `--spec` flag
    - Read `.workflow/codebase/doc-index.json` if exists
    - Find design artifacts from `state.json.artifacts[]` (type=brainstorm with ui-designer) for MASTER.md
-   - Load project specs via `maestro spec load --category planning`
+   - Load project specs via `maestro spec load --category arch`
 
 3. **Upstream analysis check**:
    - If `{contextDir}/conclusions.json` exists and has content: reuse as exploration context, skip wave 1
@@ -250,8 +246,6 @@ Bash(`mkdir -p ${scratchDir}/.task/`)
 
 **User validation**: Display exploration breakdown (skip if AUTO_YES or `--auto`).
 
----
-
 ### Phase 2: Wave Execution Engine
 
 **Objective**: Explore codebase then generate plan via spawn_agents_on_csv.
@@ -341,8 +335,6 @@ spawn_agents_on_csv({
 - If `--gaps`: create fix tasks from gap context, link to issues
 - If `--collab`: pre-allocate ID ranges for parallel planners
 
----
-
 ### Phase 3: Plan Checking + Confirmation
 
 **Objective**: Validate plan quality, revise if needed, present to user.
@@ -404,7 +396,15 @@ spawn_agents_on_csv({
    }
    ```
 
-5. **Issue linking** (if --gaps): Update issues in `issues.jsonl` with status `planned`, link to TASK IDs.
+5. **Issue linking** (if --gaps):
+   For each created TASK-{NNN}.json that has `issue_id`:
+   - Update corresponding issue in `.workflow/issues/issues.jsonl`:
+     - `task_refs`: append TASK-{NNN} to array
+     - `task_plan_dir`: relative path to `.task/` directory
+     - `status`: "planned"
+     - `updated_at`: now()
+   - Append history entry: `{ action: "planned", at: <ISO>, by: "maestro-plan", summary: "Linked to TASK-{NNN}" }`
+   This ensures bidirectional issue <-> TASK traceability for dashboard display.
 
 6. **Display summary + options** (skip options if AUTO_YES):
    ```
@@ -421,11 +421,9 @@ spawn_agents_on_csv({
      Skill({ skill: "maestro-plan", args: "{phase}" })     -- Re-plan with modifications
    ```
 
----
-
-## Shared Discovery Board Protocol
+### Shared Discovery Board Protocol
 
-### Standard Discovery Types
+#### Standard Discovery Types
 
 | Type | Dedup Key | Data Schema | Description |
 |------|-----------|-------------|-------------|
@@ -435,7 +433,7 @@ spawn_agents_on_csv({
 | `blocker` | `data.issue` | `{issue, severity, impact}` | Blocking issue found |
 | `tech_stack` | singleton | `{framework, language, tools[]}` | Technology stack info |
 
-### Domain Discovery Types
+#### Domain Discovery Types
 
 | Type | Dedup Key | Data Schema | Description |
 |------|-----------|-------------|-------------|
@@ -444,7 +442,7 @@ spawn_agents_on_csv({
 | `risk_factor` | `data.risk` | `{risk, severity, mitigation, affected_files[]}` | Identified risk |
 | `test_command` | `data.command` | `{command, scope, framework}` | Test execution command |
 
-### Protocol
+#### Protocol
 
 1. **Read** `{session_folder}/discoveries.ndjson` before own exploration
 2. **Skip covered**: If discovery of same type + dedup key exists, skip
@@ -455,10 +453,9 @@ spawn_agents_on_csv({
 ```bash
 echo '{"ts":"<ISO>","worker":"{id}","type":"existing_pattern","data":{"name":"Result error handling","file":"src/utils/result.ts","description":"All functions return Result<T,E> instead of throwing","usage":"Used in auth, payments, validation modules"}}' >> {session_folder}/discoveries.ndjson
 ```
+</execution>
 
----
-
-## Error Handling
+<error_codes>
 
 | Error | Resolution |
 |-------|------------|
@@ -473,16 +470,16 @@ echo '{"ts":"<ISO>","worker":"{id}","type":"existing_pattern","data":{"name":"Re
 | CSV parse error | Validate format, show line number |
 | discoveries.ndjson corrupt | Ignore malformed lines |
 | Continue mode: no session found | List available sessions |
-
----
-
-## Core Rules
-
-1. **Start Immediately**: First action is session initialization, then Phase 1
-2. **Wave Order is Sacred**: Never execute wave 2 before wave 1 completes and results are merged
-3. **CSV is Source of Truth**: Master tasks.csv holds all state
-4. **Context Propagation**: prev_context built from master CSV, not from memory
-5. **Discovery Board is Append-Only**: Never clear, modify, or recreate discoveries.ndjson
-6. **Skip on Failure**: If all exploration agents failed, planning agent proceeds with available context
-7. **Cleanup Temp Files**: Remove wave-{N}.csv after results are merged
-8. **DO NOT STOP**: Continuous execution until all waves complete
+</error_codes>
+
+<success_criteria>
+- [ ] Session folder created with valid tasks.csv
+- [ ] All waves executed in order
+- [ ] plan.json produced in phase directory
+- [ ] .task/TASK-*.json files produced for all tasks
+- [ ] Plan passes quality checks (coverage, deps, criteria)
+- [ ] context.md produced with exploration findings + plan overview
+- [ ] index.json updated with plan metadata
+- [ ] Issues linked (if --gaps mode)
+- [ ] discoveries.ndjson append-only throughout
+</success_criteria>