maestro-flow 0.3.15 → 0.3.17

package/.codex/skills/maestro-link-coordinate/SKILL.md

@@ -70,264 +70,96 @@ $ARGUMENTS — user intent text, or flags.
 
 ### Phase 1: Load Chain Graph
 
-```javascript
-const args = $ARGUMENTS.trim();
-const listMode = /\b--list\b/.test(args);
-const autoYes = /\b(-y|--yes)\b/.test(args);
-const resumeMode = /\b(-c|--continue)\b/.test(args);
-const resumeId = args.match(/(?:-c|--continue)\s+(\S+)/)?.[1] || null;
-const forcedChain = args.match(/--chain\s+(\S+)/)?.[1] || null;
-const intent = args
-  .replace(/\b(-y|--yes|--list|-c|--continue)\b/g, '')
-  .replace(/(?:-c|--continue)\s+\S+/g, '')
-  .replace(/--chain\s+\S+/g, '')
-  .trim();
-```
+Parse `$ARGUMENTS` to extract: `listMode` (`--list`), `autoYes` (`-y`/`--yes`), `resumeMode` (`-c`/`--continue`), `resumeId`, `forcedChain` (`--chain <name>`), `intent` (remaining text).
 
 **`--list`**: Scan `chains/*.json` and `chains/singles/*.json`, display names + descriptions, stop.
 
-**`-c` (resume)**:
-1. Glob `.workflow/.maestro-coordinate/MLC-*/state.json`, pick most recent (or by `resumeId`)
-2. Load state → find first node with `status !== "completed"` → set as `current_node`
-3. Jump to **Phase 2**
+**`-c` (resume)**: Glob `.workflow/.maestro-coordinate/MLC-*/state.json`, pick most recent (or by `resumeId`). Load state → find first incomplete node → jump to Phase 2.
 
 **Fresh session**:
 1. Resolve chain: `--chain` direct or classify from intent using `chains/_intent-map.json`
 2. Load chain JSON: try `chains/{name}.json` then `chains/singles/{name}.json`
 3. Read `.workflow/state.json` for project context (phase, milestone)
-4. Initialize session:
-
-```javascript
-const sessionId = `MLC-${dateStr}-${timeStr}`;
-const sessionDir = `.workflow/.maestro-coordinate/${sessionId}`;
-
-const state = {
-  id: sessionId, intent, chain: graph.id, auto_mode: autoYes,
-  status: "in_progress", started_at: new Date().toISOString(),
-  current_node: graph.entry,
-  context: {
-    phase: resolvedPhase ?? null, description: intent,
-    result: null   // last command result, used by decision eval
-  },
-  visit_counts: {},   // nodeId → number
-  history: [],        // { node_id, type, outcome, summary, timestamp }
-};
-Write(`${sessionDir}/state.json`, JSON.stringify(state, null, 2));
+4. Initialize session state:
+
+```json
+{
+  "id": "MLC-{YYYYMMDD}-{HHmmss}",
+  "intent": "<intent>", "chain": "<graph.id>", "auto_mode": false,
+  "status": "in_progress", "started_at": "<ISO>",
+  "current_node": "<graph.entry>",
+  "context": { "phase": null, "description": "<intent>", "result": null },
+  "visit_counts": {},
+  "history": []
+}
 ```
 
-**`--dry-run`**: Display node walk order with types, stop.
+Session dir: `.workflow/.maestro-coordinate/{sessionId}/`
 
+**`--dry-run`**: Display node walk order with types, stop.
 **Confirm** (skip if `autoYes`): Display chain summary, prompt `Proceed?`.
 
 ### Phase 2: Walk Loop
 
-```javascript
-while (state.status === 'in_progress') {
-  const nodeId = state.current_node;
-  const node = graph.nodes[nodeId];
-
-  if (!node) {
-    state.status = 'failed';
-    state.history.push({ node_id: nodeId, type: 'error', outcome: 'failed',
-      summary: `Node "${nodeId}" not found in graph`, timestamp: now() });
-    break;
-  }
-
-  // max_visits guard
-  state.visit_counts[nodeId] = (state.visit_counts[nodeId] ?? 0) + 1;
-  if (node.max_visits && state.visit_counts[nodeId] > node.max_visits) {
-    state.status = 'failed';
-    state.history.push({ node_id: nodeId, type: node.type, outcome: 'max_visits_exceeded',
-      summary: `Exceeded max_visits (${node.max_visits})`, timestamp: now() });
-    break;
-  }
-
-  switch (node.type) {
-    case 'command':  handleCommand(state, graph, nodeId, node); break;
-    case 'decision': handleDecision(state, nodeId, node);       break;
-    case 'gate':     handleGate(state, nodeId, node);            break;
-    case 'terminal': handleTerminal(state, nodeId, node);        break;
-  }
-
-  // Persist after every node
-  Write(`${sessionDir}/state.json`, JSON.stringify(state, null, 2));
-}
-```
+Loop while `state.status === 'in_progress'`:
+1. Resolve `current_node` from graph — fail if not found
+2. Increment `visit_counts[nodeId]` — fail if exceeds `node.max_visits`
+3. Dispatch by `node.type`: command → handleCommand, decision → handleDecision, gate → handleGate, terminal → handleTerminal
+4. Persist `state.json` after every node
 
 #### handleCommand — spawn via CSV
 
+1. Build `skill_call` from node config + context + auto_mode
+2. Write single-row CSV: `wave-{nodeId}.csv` with columns `id,skill_call,topic`
+3. Spawn:
+
 ```javascript
-function handleCommand(state, graph, nodeId, node) {
-  // 1. Build skill_call
-  const skillCall = buildSkillCall(node, state.context, state.auto_mode);
-
-  // 2. Write single-row CSV
-  const csvPath = `${sessionDir}/wave-${nodeId}.csv`;
-  const csv = `id,skill_call,topic\n"${nodeId}","${skillCall.replace(/"/g, '""')}","Chain \\"${state.chain}\\" node ${nodeId}"`;
-  Write(csvPath, csv);
-
-  // 3. Spawn
-  spawn_agents_on_csv({
-    csv_path: csvPath,
-    id_column: "id",
-    instruction: AGENT_INSTRUCTION,
-    max_workers: 1,
-    max_runtime_seconds: 1800,
-    output_csv_path: `${sessionDir}/wave-${nodeId}-results.csv`,
-    output_schema: RESULT_SCHEMA
-  });
-
-  // 4. Read result
-  const results = readCSV(`${sessionDir}/wave-${nodeId}-results.csv`);
-  const result = results[0];
-  const outcome = result?.status === 'completed' ? 'success' : 'failed';
-
-  // 5. Update context with result (for downstream decision eval)
-  state.context.result = parseResultContext(result);
-
-  // 6. Record history
-  state.history.push({
-    node_id: nodeId, type: 'command', outcome,
-    summary: result?.summary ?? '', timestamp: now()
-  });
-
-  // 7. Advance or fail
-  if (outcome === 'failed') {
-    if (node.on_failure) {
-      state.current_node = node.on_failure;
-    } else {
-      state.status = 'failed';
-    }
-  } else {
-    state.current_node = node.next;
-  }
-}
+spawn_agents_on_csv({
+  csv_path: csvPath,
+  id_column: "id",
+  instruction: AGENT_INSTRUCTION,
+  max_workers: 1,
+  max_runtime_seconds: 1800,
+  output_csv_path: `${sessionDir}/wave-${nodeId}-results.csv`,
+  output_schema: RESULT_SCHEMA
+})
 ```
 
+4. Read result → parse findings into `state.context.result` (for downstream decision eval)
+5. Record history entry with outcome
+6. Advance: success → `node.next`, failure → `node.on_failure` or fail state
+
 #### handleDecision — in-process expr evaluation
 
-```javascript
-function handleDecision(state, nodeId, node) {
-  // Resolve eval expression from context
-  const evalKey = node.eval;   // e.g. "ctx.result.verification_status"
-  const value = resolveExpr(evalKey, state.context);
-
-  // Match edge
-  let target = null;
-  let matchedLabel = null;
-  for (const edge of node.edges) {
-    if (edge.value !== undefined && String(edge.value) === String(value)) {
-      target = edge.target;
-      matchedLabel = edge.label ?? edge.description ?? String(edge.value);
-      break;
-    }
-    if (edge.match && new RegExp(edge.match).test(String(value))) {
-      target = edge.target;
-      matchedLabel = edge.label ?? edge.description ?? edge.match;
-      break;
-    }
-  }
-  // Default fallback
-  if (!target) {
-    const defaultEdge = node.edges.find(e => e.default);
-    if (defaultEdge) {
-      target = defaultEdge.target;
-      matchedLabel = defaultEdge.label ?? defaultEdge.description ?? 'default';
-    }
-  }
-
-  state.history.push({
-    node_id: nodeId, type: 'decision',
-    outcome: target ? 'resolved' : 'no_match',
-    summary: `${evalKey} = "${value}" → ${matchedLabel ?? 'none'}`,
-    timestamp: now()
-  });
-
-  if (target) {
-    state.current_node = target;
-  } else {
-    state.status = 'failed';
-  }
-}
-```
+1. Evaluate `node.eval` expression (e.g. `ctx.result.verification_status`) against `state.context` via dot-path resolution
+2. Match against `node.edges[]`: first by exact `edge.value`, then by regex `edge.match`, finally `edge.default`
+3. Record history: `evalKey = "value" → matchedLabel`
+4. Advance to matched `edge.target` — fail if no match found
 
 #### handleGate — condition check
 
-```javascript
-function handleGate(state, nodeId, node) {
-  const passed = resolveExpr(node.condition, state.context);
-  state.history.push({
-    node_id: nodeId, type: 'gate',
-    outcome: passed ? 'passed' : 'blocked',
-    summary: `${node.condition} → ${passed}`,
-    timestamp: now()
-  });
-  state.current_node = passed ? node.on_pass : node.on_fail;
-}
-```
+Evaluate `node.condition` against context. Route to `node.on_pass` or `node.on_fail`. Record history with passed/blocked outcome.
 
 #### handleTerminal
 
-```javascript
-function handleTerminal(state, nodeId, node) {
-  state.status = node.status === 'success' ? 'completed' : 'failed';
-  state.history.push({
-    node_id: nodeId, type: 'terminal',
-    outcome: node.status ?? 'completed',
-    summary: node.summary ?? 'Chain walk complete',
-    timestamp: now()
-  });
-}
-```
+Set `state.status` to completed/failed based on `node.status`. Record final history entry.
 
 ### Shared Utilities
 
-```javascript
-const AUTO_FLAG_MAP = {
-  'maestro-analyze': '-y', 'maestro-brainstorm': '-y',
-  'maestro-ui-design': '-y', 'maestro-plan': '--auto',
-  'maestro-spec-generate': '-y', 'quality-test': '--auto-fix',
-  'quality-retrospective': '--auto-yes', 'maestro-roadmap': '-y',
-};
+**AUTO_FLAG_MAP** (skill → auto-confirm flag):
 
-function buildSkillCall(node, ctx, autoMode) {
-  let args = (node.args ?? '')
-    .replace(/{phase}/g, ctx.phase ?? '')
-    .replace(/{description}/g, ctx.description ?? '')
-    .replace(/{issue_id}/g, ctx.issue_id ?? '')
-    .replace(/{milestone_num}/g, ctx.milestone_num ?? '');
-  if (autoMode) {
-    const flag = node.auto_flag ?? AUTO_FLAG_MAP[node.cmd];
-    if (flag && !args.includes(flag)) args = args ? `${args} ${flag}` : flag;
-  }
-  return `$${node.cmd} ${args}`.trim();
-}
+| Skill | Flag |
+|-------|------|
+| `maestro-analyze`, `maestro-brainstorm`, `maestro-ui-design`, `maestro-spec-generate`, `maestro-roadmap` | `-y` |
+| `maestro-plan` | `--auto` |
+| `quality-test` | `--auto-fix` |
+| `quality-retrospective` | `--auto-yes` |
 
-function resolveExpr(expr, ctx) {
-  // expr is "ctx.result.verification_status" or "all_phases_completed"
-  // Navigate dot-path from context root
-  if (!expr) return undefined;
-  const path = expr.replace(/^ctx\./, '').split('.');
-  let val = ctx;
-  for (const key of path) {
-    if (val == null) return undefined;
-    val = val[key];
-  }
-  return val;
-}
+**buildSkillCall(node, ctx, autoMode)**: Substitute `{phase}`, `{description}`, `{issue_id}`, `{milestone_num}` from context into `node.args`. If autoMode, append auto flag from `node.auto_flag` or AUTO_FLAG_MAP. Return `$${node.cmd} ${resolvedArgs}`.
 
-function parseResultContext(result) {
-  // Extract structured fields from agent result for decision eval
-  if (!result) return {};
-  try {
-    const parsed = typeof result.findings === 'string'
-      ? JSON.parse(result.findings) : result.findings;
-    return { ...parsed, _raw_summary: result.summary, _status: result.status };
-  } catch {
-    return { _raw_summary: result.summary ?? '', _status: result.status ?? 'unknown' };
-  }
-}
-```
+**resolveExpr(expr, ctx)**: Navigate dot-path (e.g. `ctx.result.verification_status`) from context root. Strip `ctx.` prefix, walk path segments, return leaf value or undefined.
+
+**parseResultContext(result)**: Parse `result.findings` as JSON if string, merge with `_raw_summary` and `_status`. Fallback to raw summary on parse failure.
 
 ### Sub-Agent Instruction Template
 
@@ -375,12 +207,7 @@ const RESULT_SCHEMA = {
 
 ### Phase 3: Completion Report
 
-```javascript
-state.completed_at = new Date().toISOString();
-Write(`${sessionDir}/state.json`, JSON.stringify(state, null, 2));
-```
-
-Display:
+Set `state.completed_at`, persist final `state.json`. Display:
 ```
 === LINK-COORDINATE COMPLETE ===
 Session:  {sessionId}

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

@@ -31,57 +31,28 @@ $maestro-milestone-audit "M1"
 
 ### Step 1: Parse Arguments
 
-Extract milestone identifier from arguments.
-If empty: read `current_milestone` from `.workflow/state.json`.
-If still empty: error E001.
+Extract milestone identifier from arguments. Fallback: read `current_milestone` from `.workflow/state.json`. If still empty: E001.
 
 ### Step 2: Load Artifact Registry
 
-```bash
-cat .workflow/state.json
-cat .workflow/roadmap.md
-```
-
-- Parse `state.json.artifacts[]` filtered by milestone
-- Parse `roadmap.md` for phase list in this milestone
-- Group artifacts by type and phase
+Read `.workflow/state.json` and `.workflow/roadmap.md`. Filter `artifacts[]` by milestone, parse phase list, group by type and phase.
 
 ### Step 3: Phase Coverage Check
 
-For each phase in roadmap:
-- Check for completed analyze artifact (optional but noted)
-- Check for completed plan artifact (required)
-- Check for completed execute artifact (required)
-
-Report coverage matrix.
+For each phase: check for completed analyze (optional), plan (required), execute (required) artifacts. Report coverage matrix.
 
 ### Step 4: Ad-hoc & Execution Completeness
 
-- Check all adhoc-scoped artifacts are completed
-- For each execute artifact, verify tasks in plan dir are all completed
+Verify all adhoc-scoped artifacts completed. For each execute artifact, verify all tasks in plan dir completed.
 
 ### Step 5: Integration Check
 
-Spawn Agent for cross-phase integration validation:
-- Shared interfaces compatibility
-- Dependency chain satisfaction
-- Data contract consistency
-- API endpoint consistency
-
-Write report to `.workflow/milestones/{milestone}/audit-report.md`
+Spawn Agent for cross-phase validation: shared interfaces, dependency chains, data contracts, API consistency. Write report to `.workflow/milestones/{milestone}/audit-report.md`.
 
 ### Step 6: Verdict
 
-```
-PASS if:
-  - All phases have EXC artifacts (completed)
-  - No critical integration gaps
-  - All adhoc artifacts completed
-
-FAIL if:
-  - Missing EXC artifacts for any phase
-  - Critical integration gaps found
-```
+**PASS**: All phases have completed EXC artifacts, no critical integration gaps, all adhoc completed.
+**FAIL**: Missing EXC artifacts or critical integration gaps found.
 
 Display structured audit report with next-step routing.
 

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

@@ -33,121 +33,39 @@ $maestro-milestone-complete --force "M1"  # skip audit check
 
 ### Step 1: Parse & Validate
 
-1. Read `.workflow/state.json` to get `current_milestone`, `artifacts[]`, `milestones[]`
-2. Determine target milestone (from args or current_milestone)
-3. Check `--force` flag
-4. If no milestone: **E001**
-5. Check audit report exists at `.workflow/milestones/{milestone}/audit-report.md`
-   - Missing + not --force: **E002**
-   - Verdict FAIL + not --force: **E002**
-6. Check all milestone artifacts completed:
-   - `state.json.artifacts.filter(a => a.milestone == target && a.status != "completed")`
-   - If any incomplete + not --force: **E003**
+Read `.workflow/state.json` for `current_milestone`, `artifacts[]`, `milestones[]`. Determine target from args or current_milestone (E001 if none). Validate audit report at `.workflow/milestones/{milestone}/audit-report.md` with PASS verdict (E002 unless `--force`). Verify all milestone artifacts completed (E003 unless `--force`).
 
 ### Step 2: Archive Scratch Dirs
 
-```bash
-mkdir -p .workflow/milestones/{milestone}/artifacts/
-
-# For each artifact path, copy to archive
-for artifact in milestone_artifacts:
-  if dir exists .workflow/{artifact.path}:
-    cp -r .workflow/{artifact.path} .workflow/milestones/{milestone}/artifacts/$(basename {artifact.path})/
-```
-
-Snapshot roadmap:
-```bash
-cp .workflow/roadmap.md .workflow/milestones/{milestone}/roadmap-snapshot.md
-```
+Copy each milestone artifact's directory to `.workflow/milestones/{milestone}/artifacts/`. Snapshot `roadmap.md` as `roadmap-snapshot.md` in the milestone archive.
 
 ### Step 3: Extract Learnings
 
-- Read `.summaries/` from each execute artifact's plan dir
-- Read `reflection-log.md` if exists
-- Extract patterns, pitfalls, strategy adjustments
-- Check existing entries via `maestro spec load --category learning` (dedup)
-- Append to `.workflow/specs/learnings.md` using `<spec-entry>` closed-tag format (category=`learning`, auto-extract keywords, date=today, source=`milestone-complete`)
-- Avoid duplicates (check existing entries)
+Read `.summaries/` and `reflection-log.md` from execute artifacts. Extract patterns, pitfalls, strategy adjustments. Dedup against existing entries via `maestro spec load --category learning`. Append to `.workflow/specs/learnings.md` using `<spec-entry>` closed-tag format (category=`learning`, auto-extract keywords, date=today, source=`milestone-complete`).
 
 ### Step 3b: Knowledge Promotion Inquiry
 
-After learning extraction, scan `learnings.md` for promotion candidates:
-
-1. **High-frequency pattern detection**: Scan all `<spec-entry category="learning">` entries for keyword overlap (≥2 entries sharing keywords):
-   → Ask: "Keyword '{keyword}' appears in {N} learning entries. Should this be promoted to a formal coding convention? (`/spec-add coding`)"
-
-2. **Convention drift detection**: Compare executed task summaries against `coding-conventions.md` and `architecture-constraints.md`:
-   → Ask: "Were any established conventions bypassed during this milestone? Should conventions be updated?"
+1. **High-frequency patterns**: Scan learning entries for keyword overlap (>=2 entries) -- offer promotion to coding convention via `/spec-add coding`
+2. **Convention drift**: Compare summaries against `coding-conventions.md` and `architecture-constraints.md` -- ask if conventions need updating
+3. **Wiki island check**: Auto-trigger `wiki-connect --fix` to link new knowledge
 
-3. **Wiki island check**: Auto-trigger `wiki-connect --fix` to link newly extracted knowledge.
-
-If user confirms, append promoted `<spec-entry>` to target category file, preserving original date and source traceability.
+If user confirms promotion, append `<spec-entry>` to target category file preserving original date and source.
 
 ### Step 4: Archive Artifact Entries
 
-Move artifact entries from `state.json.artifacts[]` to `milestone_history`:
-
-```json
-{
-  "milestone_history": [
-    ...existing,
-    {
-      "id": "{milestone}",
-      "name": "{milestone_name}",
-      "status": "completed",
-      "completed_at": "{now}",
-      "archive_path": "milestones/{milestone}/",
-      "archived_artifacts": [ ...all milestone artifact entries... ]
-    }
-  ]
-}
-```
-
-Remove from `artifacts[]`:
-```
-state.json.artifacts = state.json.artifacts.filter(a => a.milestone != target)
-```
+Move milestone artifacts from `state.json.artifacts[]` to `milestone_history[]` with completion metadata (id, name, status, completed_at, archive_path, archived_artifacts). Remove from active `artifacts[]`.
 
 ### Step 5: Advance State
 
-```
-next = state.json.milestones.find(m => m.status == "pending")
-if next:
-  state.json.current_milestone = next.id
-  next.status = "active"
-else:
-  state.json.current_milestone = null
-  state.json.status = "completed"
-
-state.json.last_updated = now()
-Write state.json (atomic)
-```
+Set `current_milestone` to next pending milestone (mark it active), or set project `status: "completed"` if none remain. Atomic write to `state.json`.
 
 ### Step 6: Clean Scratch
 
-```bash
-for artifact in archived_artifacts:
-  rm -rf .workflow/{artifact.path}
-```
+Remove archived artifact directories from `.workflow/`.
 
 ### Step 7: Generate Summary & Report
 
-Write `.workflow/milestones/{milestone}/summary.md` with outcomes and learnings.
-Update `.workflow/project.md` Context section.
-
-```
-=== MILESTONE COMPLETE ===
-Milestone: {milestone} ({name})
-Artifacts: {count} archived
-Next:      {next_milestone or "Project complete"}
-
-Next steps:
-  $maestro-milestone-release  -- Cut release
-  $maestro-analyze            -- Start next milestone
-  $manage-status              -- View state
-  $manage-wiki health         -- Check wiki graph health
-  $wiki-digest                -- Generate knowledge digest
-```
+Write `.workflow/milestones/{milestone}/summary.md` with outcomes and learnings. Update `.workflow/project.md` Context section. Display completion report with next steps: `$maestro-milestone-release`, `$maestro-analyze`, `$manage-status`, `$manage-wiki health`, `$wiki-digest`.
 
 </execution>
 

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

@@ -53,33 +53,15 @@ $maestro-overlay "--remove cli-verify-after-execute"
 
 ### 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)"
-})
-```
+- `--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
 
-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:
+Read pristine command source from `$PKG_ROOT/.claude/commands/<name>.md` (fallback: `~/.claude/commands/<name>.md`). Select injection point:
 
 | Intent type | Section | Mode |
 |-------------|---------|------|
@@ -91,81 +73,30 @@ For each likely target command, read the pristine source from `$PKG_ROOT/.claude
 
 ### 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
+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 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" }
-  ]
-})
-```
+**Content guidelines**: Lead with `## Title (overlay)` heading. Use `@~/.maestro/...` references. Keep concise.
 
 ### 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" }
-  ]
-})
-```
+Run `maestro overlay add ~/.maestro/overlays/<slug>.json`. On validation failure, fix JSON and retry (max 2).
 
-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
-```
+Display report with name, path, targets (applied/skipped), and commands for re-apply/remove/inspect.
 
 </execution>