maestro-flow 0.1.4 → 0.2.1

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

@@ -1,158 +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
+---
+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-overlay/SKILL.md

@@ -0,0 +1,187 @@
+---
+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",
+  items: [
+    { type: "text", text: "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