maestro-overlay

<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 + request_user_input).
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 request_user_input 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 request_user_input; 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 request_user_input: (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>
  <context>
  <execution>
     ├─ [existing] cli-verify #1  "CLI Verification step"
     >>> NEW: append here (your overlay)
  <success_criteria>
```

Use request_user_input to confirm:
- **"Confirm"** — proceed with this injection point
- **"Pick different section"** — re-select section/mode
- **"Cancel"** — abort

### 2.5. Skill chain configuration

After confi