/maestro-overlay

name: maestro-overlay
disable-model-invocation: true
description: Create or edit command overlays from natural language, or auto-generate them from workflow deficiency signals
argument-hint: "<intent> | --amend [--scan] [--dry-run] [-y]"
allowed-tools:
  - Read
  - Write
  - Bash
  - Glob
  - Grep
  - AskUserQuestion
session-mode: none

<purpose> Turn instructions into command overlays — JSON patch files that augment `.claude/commands/*.md` non-invasively, auto-applied by `maestro install`. Two modes:

• **Default (intent)** — turn a natural-language instruction into one overlay interactively.
• **`--amend`** — signal-driven auto-generation: collect workflow deficiency signals from

multiple sources, diagnose which commands need amendment, batch-generate targeted overlays.

Both modes use the same overlay system (`~/.maestro/overlays/*.json`) — non-invasive, idempotent, survives reinstall. </purpose>

<context> **Mode selection**: `--amend` (or any `--from-*` / `--scan` signal flag) → **Amend mode** (signal-driven auto-generation, jump to `<amend_mode>` in execution). Otherwise → **Default mode** (natural-language intent, steps 1–5 below).

**Overlay model**:

• JSON file: `name`, `targets[]` (command names), `patches[]`
• Patch: `section` (XML tag), `mode` (append/prepend/replace/new-section), `content`
• Apply: hashed HTML-comment markers (idempotent, surgical removal)

**Where overlays live**

• User overlays: `~/.maestro/overlays/*.json` — created by this skill
• Shared docs: `~/.maestro/overlays/docs/*.md` — referenced via `@~/.maestro/overlays/docs/*.md` inside patch content
• Shipped examples: `~/.maestro/overlays/_shipped/` — read-only, do not edit

**Management** — listing and removing overlays is handled by `maestro overlay list` (ink TUI with interactive delete). This skill focuses solely on creation.

**Available sections** (for `section:` in patches): `purpose`, `required_reading`, `deferred_reading`, `context`, `execution`, `completion`, `invariants`, `error_codes`, `success_criteria`.

**Amend mode signal sources** (when `--amend`):

| Flag | Source | Collects | |------|--------|----------| | `--from-verify <dir>` | verification.json | Workflow gaps from verify failures | | `--from-review <dir>` | review.json | Process deficiencies from code review | | `--from-session <id>` | Session artifacts | Problems during workflow execution | | `--from-issues ISS-xxx,...` | issues.jsonl | Issues tracing to command deficiency | | `--scan` | Auto-scan .workflow/ | Discover all workflow-related signals | | _(positional text)_ | User description | Direct observation |

Multiple combinable. `--amend` with no flags/description → interactive (scan + [@ask] AskUserQuestion). Amend control: `--dry-run` (preview, don't install), `-y` (skip confirmations). Amend output: `~/.maestro/overlays/amend-{slug}.json` + optional `~/.maestro/overlays/docs/amend-{slug}.md`.

**Output boundary**: ALL file writes MUST target `~/.maestro/overlays/` (overlay JSON + docs) only. Command file patching is handled by `maestro overlay add` — this skill NEVER modifies `.claude/commands/*.md` directly. </context>

<invariants> 1. **Non-invasive** — overlays MUST use hashed HTML-comment markers for injection; NEVER edit command file content directly outside the overlay system 2. **Idempotent** — re-running `maestro overlay apply` with the same overlay JSON MUST produce no file changes 3. **Creation only** — this skill MUST only create overlays; listing and removal are handled by `maestro overlay list` (ink TUI) 4. **Pristine source preferred** — injection point analysis MUST read from `$PKG_ROOT/.claude/commands/` (untouched originals) first, fall back to `~/.claude/commands/` only if pristine unavailable 5. **User approval before write** — overlay JSON MUST be shown and approved via [@ask] AskUserQuestion before writing to disk, unless `-y` is explicitly provided (amend mode only) 6. **Chain skip option mandatory** — if a skill chain is configured, the injected content MUST include a "Skip" option in [@ask] AskUserQuestion; NEVER force the user into a chain

**Amend mode only** (when `--amend`):

7. **Pristine source reads** — signal diagnosis MUST read from `$PKG_ROOT/.claude/commands/` (untouched originals), not installed copies 8. **Code bugs excluded** — signals classified as code bugs MUST be routed to `/maestro-companion` or step `plan` (`--gaps`), NEVER patched via overlay 9. **Section existence verified** — target section MUST be confirmed to exist in the pristine source before drafting a patch; missing sections trigger `new-section` mode </invariants>

<execution>

> **Amend mode** (`--amend` or any `--from-*` / `--scan` flag): skip steps 1–5 below and follow `<amend_mode>` at the end of this section instead. **Default mode**: continue with steps 1–5.

1. Parse user intent

Treat the argument as natural-language intent. If unclear, ask up to 2 questions with [@ask] AskUserQuestion: (a) which command(s) to target, (b) where in the command flow the injection should happen.

2. Identify targets, injection points, and visualize

For each likely target command, read the pristine source from `$PKG_ROOT/.claude/commands/<name>.md` (preferred — untouched by overlays) or fall back to `~/.claude/commands/<name>.md`. Inspect the XML sections and pick the right one:

• **New step after execution** → `section: execution`, `mode: append`
• **Required reading** → `section: required_reading`, `mode: append`
• **Preconditions / gating** → `section: context`, `mode: append`
• **Output quality gate** → `section: success_criteria`, `mode: append`

If the user wants a whole new section, use `mode: new-section` with `afterSection: execution` (or whichever anchor makes sense).

**Injection point preview** — after selecting section + mode, render the target command's section map showing existing overlays and the new injection point:

=== maestro-next.md (1 overlay exists) ===

  <purpose>
  <required_reading>
  <c