maestro-flow 0.5.36 → 0.5.37

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

@@ -1,119 +1,119 @@
----
-name: maestro-overlay
-description: Create or edit command overlays from natural language
-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
-
-**Quick-exit paths**:
-- `--list` → run `maestro overlay list`, then stop
-- `--remove <name>` → run `maestro overlay remove <name>`, then stop
-
-**Ambiguous intent**: If target command or injection point unclear, ask up to 2 focused questions.
-
-### Step 2: Identify Targets and Injection Points
-
-Read pristine command source from `$PKG_ROOT/.claude/commands/<name>.md` (fallback: `~/.claude/commands/<name>.md`). 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 slug from intent (kebab-case, lowercase, max 40 chars). Write overlay to `~/.maestro/overlays/<slug>.json`:
-
-```json
-{
-  "name": "<slug>",
-  "description": "<short summary>",
-  "targets": ["<command-name>"],
-  "priority": 50,
-  "enabled": true,
-  "patches": [{
-    "section": "<section>",
-    "mode": "<append|prepend|replace|new-section>",
-    "content": "<injected markdown with (overlay) heading>"
-  }]
-}
-```
-
-**Content guidelines**: Lead with `## Title (overlay)` heading. Use `@~/.maestro/...` references. Keep concise.
-
-### Step 4: Install via CLI and Report
-
-Run `maestro overlay add ~/.maestro/overlays/<slug>.json`. On validation failure, fix JSON and retry (max 2).
-
-Display report with name, path, targets (applied/skipped), and commands for re-apply/remove/inspect.
-
-</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>
+---
+name: maestro-overlay
+description: Create or edit command overlays from natural language
+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
+
+**Quick-exit paths**:
+- `--list` → run `maestro overlay list`, then stop
+- `--remove <name>` → run `maestro overlay remove <name>`, then stop
+
+**Ambiguous intent**: If target command or injection point unclear, ask up to 2 focused questions.
+
+### Step 2: Identify Targets and Injection Points
+
+Read pristine command source from `$PKG_ROOT/.claude/commands/<name>.md` (fallback: `~/.claude/commands/<name>.md`). 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 slug from intent (kebab-case, lowercase, max 40 chars). Write overlay to `~/.maestro/overlays/<slug>.json`:
+
+```json
+{
+  "name": "<slug>",
+  "description": "<short summary>",
+  "targets": ["<command-name>"],
+  "priority": 50,
+  "enabled": true,
+  "patches": [{
+    "section": "<section>",
+    "mode": "<append|prepend|replace|new-section>",
+    "content": "<injected markdown with (overlay) heading>"
+  }]
+}
+```
+
+**Content guidelines**: Lead with `## Title (overlay)` heading. Use `@~/.maestro/...` references. Keep concise.
+
+### Step 4: Install via CLI and Report
+
+Run `maestro overlay add ~/.maestro/overlays/<slug>.json`. On validation failure, fix JSON and retry (max 2).
+
+Display report with name, path, targets (applied/skipped), and commands for re-apply/remove/inspect.
+
+</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

@@ -88,7 +88,7 @@ Write resolved milestone into PLN artifact registration and `plan.json.milestone
 **Session**: `.workflow/.csv-wave/{YYYYMMDD}-plan-P{N}-{slug}/`
 **Scratch**: `.workflow/scratch/{YYYYMMDD}-plan-P{N}-{slug}/` (.task/ subdir)
 
-**Pre-load** (optional): context-package.json (via `--from`, takes precedence), context.md (prior analyze), conclusions.json, codebase ARCHITECTURE.md, `maestro search`, `maestro spec load --category arch`, team preflight `maestro collab preflight`.
+**Pre-load** (optional): context-package.json (via `--from`, takes precedence), context.md (prior analyze), conclusions.json, codebase ARCHITECTURE.md, `maestro search`, `maestro load --type spec --category arch`, team preflight `maestro collab preflight`.
 
 **D-008 Ad-hoc Milestone Auto-Creation**: When scope resolves to `standalone` via standard resolution (routes 6 or 7, NOT via `--from`), and `state.json.current_milestone == null`, auto-create an adhoc milestone:
 ```

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

@@ -51,7 +51,7 @@ Extract from arguments:
 
 Read `.workflow/state.json` and `.workflow/project.md` if they exist. If `.workflow/` does not exist, create minimal scratch structure anyway (quick works without full init).
 
-Load coding specs + tools if available: `maestro spec load --category coding`. If the task involves frontend/UI work (description contains component, page, style, layout, CSS, HTML, frontend), also run `maestro spec load --category ui`. Browse wiki: `maestro search --category coding`, load relevant entries via `maestro wiki load <id>`. All optional — proceed without if unavailable.
+Load coding specs + tools if available: `maestro load --type spec --category coding`. If the task involves frontend/UI work (description contains component, page, style, layout, CSS, HTML, frontend), also run `maestro load --type spec --category ui`. Browse wiki: `maestro search --category coding`, load relevant entries via `maestro load --type knowhow --id <id>`. All optional — proceed without if unavailable.
 
 ### Step 3: Create Scratch Directory
 
@@ -70,7 +70,7 @@ Analyze the task for gray areas and ambiguities:
 ### Step 5: Quick Analysis
 
 Rapid codebase exploration focused on the task:
-1. Search for related files using Grep/Glob
+1. Search for related files using `maestro explore` (preferred, fallback Grep/Glob)
 2. Identify existing patterns to follow
 3. Map dependencies and integration points
 4. Write analysis findings to `context.md` (append if --discuss created it)

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

@@ -29,7 +29,7 @@ $ARGUMENTS -- requirement/idea text or @file reference, plus optional flags.
 **Output**: tasks.csv, results.csv, discoveries.ndjson, context.md, `.workflow/roadmap.md`
 
 ### Pre-load (runs unconditionally, including -y auto mode)
-1. **Architecture specs**: `maestro spec load --category arch` — load architecture constraints for phase decomposition
+1. **Architecture specs**: `maestro load --type spec --category arch` — load architecture constraints for phase decomposition
 2. **Wiki search**: `maestro search "{requirement keywords}" --json` → prior knowledge for dependency and scope analysis
 3. All optional — proceed without if unavailable (log warning)
 </context>
@@ -38,7 +38,7 @@ $ARGUMENTS -- requirement/idea text or @file reference, plus optional flags.
 Interview the user relentlessly until shared understanding is reached. Active only in interactive mode; skip when `-y/--yes`, `--revise`, `--review`, `-c`, or input is already specific (clear requirement + mode).
 
 - One decision per turn via request_user_input with 2–4 options + a (Recommended) default. The user controls termination — keep interviewing until convergence; they can interrupt naturally at any time.
-- Search-first when uncertain: before asking, resolve via `state.json`, existing `roadmap.md`, `project.md`, `maestro spec load`, `maestro search`, Glob/Grep/Read, or — for open-ended multi-file scans — `maestro delegate ... --role explore`. Never ask what code or memory can verify; never bounce your own ambiguity back to the user — search first, then ask only what truly needs human judgment.
+- Search-first when uncertain: before asking, resolve via `state.json`, existing `roadmap.md`, `project.md`, `maestro load --type spec`, `maestro search`, `maestro explore` (preferred, fallback Glob/Grep/Read). Never ask what code or memory can verify; never bounce your own ambiguity back to the user — search first, then ask only what truly needs human judgment.
 - Writeback cadence: each settled decision is immediately appended/updated in the `Roadmap Decisions` section at the top of `.workflow/roadmap.md` (create the section if absent). Do NOT batch writeback to the end — partial decisions must already be on disk before the next question.
 - Walk the decision dependency tree strictly: mode → requirement scope → decomposition strategy → phase dependencies/order. Do not open the next branch until the current one is settled.
 - Scope guard: only decide the shape of the roadmap. Do not pre-resolve intra-phase task breakdown — that belongs to `plan`.

package/.codex/skills/maestro-tools-execute/SKILL.md

@@ -33,13 +33,13 @@ Empty arguments enters interactive mode: list all tools for user selection.
 
 **By name**:
 ```bash
-maestro spec load --category coding --keyword <name>
+maestro load --type spec --category coding --keyword <name>
 ```
 Match tool entries whose title or keywords contain the name.
 
 **By category**:
 ```bash
-maestro spec load --category <category>
+maestro load --type spec --category <category>
 ```
 Extract tool entries from output, list available tools.
 
@@ -54,7 +54,7 @@ Show tool information:
 
 Expand ref entries:
 ```bash
-maestro wiki load <knowhow-id>
+maestro load --type knowhow --id <knowhow-id>
 ```
 
 ### Step 3: Confirm Execution

package/.codex/skills/maestro-tools-register/SKILL.md

@@ -68,7 +68,7 @@ Parse $ARGUMENTS to determine mode:
 - If unclear, ask user with request_user_input
 
 **Optimize mode**:
-- Load existing tool: `maestro spec load --category coding --keyword <name>`
+- Load existing tool: `maestro load --type spec --category coding --keyword <name>`
 - Analyze improvement points (step splitting, prerequisites, error handling)
 
 **Promote mode** (existing knowhow → tool):
@@ -149,7 +149,7 @@ tool: true
 
 ### Step 6: Verify
 
-- `maestro spec load --category <category> --keyword <keyword>` to confirm loadable
+- `maestro load --type spec --category <category> --keyword <keyword>` to confirm loadable
 - Display result: title, category, keywords, storage location
 
 </execution>

package/.codex/skills/maestro-ui-codify/SKILL.md

@@ -106,7 +106,7 @@ id,wave,title,description,agent_type,deps
 </csv_schema>
 
 <invariants>
-0. **Load UI Specs**: Before extraction, load project UI conventions via `maestro spec load --category ui` (if available). Ensures extracted tokens align with existing conventions.
+0. **Load UI Specs**: Before extraction, load project UI conventions via `maestro load --type spec --category ui` (if available). Ensures extracted tokens align with existing conventions.
 1. **Start Immediately**: First action is argument parsing, then validation
 2. **Wave Order is Sacred**: Never execute wave N+1 before wave N completes and results are merged
 3. **CSV is Source of Truth**: Master tasks.csv holds all state
@@ -396,7 +396,7 @@ Open preview:
 
 Next steps:
   maestro search --category coding    # Browse by role
-  maestro spec load --keyword {package_name}    # Load related specs
+  maestro load --type spec --keyword {package_name}    # Load related specs
 ```
 
 </execution>

package/.codex/skills/manage-codebase-refresh/SKILL.md

@@ -1,72 +1,72 @@
----
-name: manage-codebase-refresh
-description: Refresh codebase docs from recent changes
-argument-hint: "[--since <date>] [--deep]"
-allowed-tools: Read, Write, Edit, Bash, Glob, Grep
----
-
-<purpose>
-Incremental refresh of codebase documentation based on recent git changes. Detects changed files, maps them to existing doc entries, and updates only affected sections. Use `--deep` for broader context re-scanning.
-</purpose>
-
-<context>
-$ARGUMENTS — optional flags.
-
-```bash
-$manage-codebase-refresh
-$manage-codebase-refresh "--since 2026-03-15"
-$manage-codebase-refresh "--deep"
-$manage-codebase-refresh "--since 3d --deep"
-```
-
-**Flags**:
-- `--since <date>` -- Override change detection window (ISO date or relative like `3d`)
-- `--deep` -- Force deeper re-scan even for minor changes
-</context>
-
-<execution>
-
-### Step 1: Validate Preconditions
-
-Verify `.workflow/` exists (E001) and `.workflow/codebase/` exists (E002 -- use codebase-rebuild instead).
-
-### Step 2: Detect Changes
-
-Resolve baseline: `--since` flag > `state.json.codebase_last_refreshed` > `codebase_last_rebuilt` > 7-day fallback. Run `git diff --name-only --since="{baseline}" HEAD`. If no changes: W001, exit.
-
-### Step 3: Map Changes to Docs
-
-Read `.workflow/codebase/doc-index.json` to find doc entries covering changed files. Build affected entry list.
-
-### Step 3.5: KG Impact Analysis (if KG exists)
-
-If `.workflow/codebase/knowledge-graph.json` exists: run `maestro kg diff-wiki --json`. Parse output for `affectedWiki` entries. If any, log WARNING for each: "KG impact: code changes affect [entry.id] — [entry.title]". Log summary: "{directNodes} direct, {impactedNodes} impacted KG nodes, {affectedWiki.length} wiki entries flagged". If KG does not exist: skip silently.
-
-### Step 4: Refresh Affected Docs
-
-For each affected entry: re-read changed source files, update corresponding doc in `.workflow/codebase/`, update timestamp in `doc-index.json`. With `--deep`: also re-scan adjacent files.
-
-### Step 5: Update State
-
-Update `doc-index.json` timestamps and `state.json.codebase_last_refreshed`. Display summary with change/refresh/skip counts.
-</execution>
-
-<error_codes>
-| Code | Severity | Description |
-|------|----------|-------------|
-| E001 | fatal | `.workflow/` not initialized |
-| E002 | fatal | No codebase docs exist -- use `$manage-codebase-rebuild` instead |
-| W001 | warning | No changes detected since last refresh |
-</error_codes>
-
-<success_criteria>
-- [ ] Preconditions validated (.workflow/ and .workflow/codebase/ exist)
-- [ ] Change detection baseline resolved (--since flag, state.json, or 7-day fallback)
-- [ ] Git changes detected and mapped to doc entries via doc-index.json
-- [ ] KG impact analysis run (if knowledge-graph.json exists)
-- [ ] Affected wiki entries flagged with warnings (if any)
-- [ ] Affected docs refreshed with updated source content
-- [ ] --deep flag triggers adjacent file re-scan
-- [ ] doc-index.json timestamps and state.json codebase_last_refreshed updated
-- [ ] Summary displayed with change/refresh/skip counts
-</success_criteria>
+---
+name: manage-codebase-refresh
+description: Refresh codebase docs from recent changes
+argument-hint: "[--since <date>] [--deep]"
+allowed-tools: Read, Write, Edit, Bash, Glob, Grep
+---
+
+<purpose>
+Incremental refresh of codebase documentation based on recent git changes. Detects changed files, maps them to existing doc entries, and updates only affected sections. Use `--deep` for broader context re-scanning.
+</purpose>
+
+<context>
+$ARGUMENTS — optional flags.
+
+```bash
+$manage-codebase-refresh
+$manage-codebase-refresh "--since 2026-03-15"
+$manage-codebase-refresh "--deep"
+$manage-codebase-refresh "--since 3d --deep"
+```
+
+**Flags**:
+- `--since <date>` -- Override change detection window (ISO date or relative like `3d`)
+- `--deep` -- Force deeper re-scan even for minor changes
+</context>
+
+<execution>
+
+### Step 1: Validate Preconditions
+
+Verify `.workflow/` exists (E001) and `.workflow/codebase/` exists (E002 -- use codebase-rebuild instead).
+
+### Step 2: Detect Changes
+
+Resolve baseline: `--since` flag > `state.json.codebase_last_refreshed` > `codebase_last_rebuilt` > 7-day fallback. Run `git diff --name-only --since="{baseline}" HEAD`. If no changes: W001, exit.
+
+### Step 3: Map Changes to Docs
+
+Read `.workflow/codebase/doc-index.json` to find doc entries covering changed files. Build affected entry list.
+
+### Step 3.5: KG Impact Analysis (if KG exists)
+
+If `.workflow/codebase/knowledge-graph.json` exists: run `maestro kg diff-wiki --json`. Parse output for `affectedWiki` entries. If any, log WARNING for each: "KG impact: code changes affect [entry.id] — [entry.title]". Log summary: "{directNodes} direct, {impactedNodes} impacted KG nodes, {affectedWiki.length} wiki entries flagged". If KG does not exist: skip silently.
+
+### Step 4: Refresh Affected Docs
+
+For each affected entry: re-read changed source files, update corresponding doc in `.workflow/codebase/`, update timestamp in `doc-index.json`. With `--deep`: also re-scan adjacent files.
+
+### Step 5: Update State
+
+Update `doc-index.json` timestamps and `state.json.codebase_last_refreshed`. Display summary with change/refresh/skip counts.
+</execution>
+
+<error_codes>
+| Code | Severity | Description |
+|------|----------|-------------|
+| E001 | fatal | `.workflow/` not initialized |
+| E002 | fatal | No codebase docs exist -- use `$manage-codebase-rebuild` instead |
+| W001 | warning | No changes detected since last refresh |
+</error_codes>
+
+<success_criteria>
+- [ ] Preconditions validated (.workflow/ and .workflow/codebase/ exist)
+- [ ] Change detection baseline resolved (--since flag, state.json, or 7-day fallback)
+- [ ] Git changes detected and mapped to doc entries via doc-index.json
+- [ ] KG impact analysis run (if knowledge-graph.json exists)
+- [ ] Affected wiki entries flagged with warnings (if any)
+- [ ] Affected docs refreshed with updated source content
+- [ ] --deep flag triggers adjacent file re-scan
+- [ ] doc-index.json timestamps and state.json codebase_last_refreshed updated
+- [ ] Summary displayed with change/refresh/skip counts
+</success_criteria>