Maestro Overlay

• 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.

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):

Multiple combinable. --amend with no flags/description → interactive (scan + [@ask] user prompt). 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.

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

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] user prompt: (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 [@ask] user prompt to confirm:

• "Confirm" — proceed with this injection point
• "Pick different section" — re-select section/mode
• "Cancel" — abort

2.5. Skill chain configuration

After confirming the injection point, ask whether this overlay should recommend another retained command upon completion. Emit its exact slash command after confirmation. team-* and maestro-odyssey are not valid handoff targets.

Use [@ask] user prompt:

• "No chain" — standard overlay, no skill handoff
• "Chain to skill" → ask for the target step (review, execute, test); route it through /maestro-next or the canonical receipt-chained self-start flow, with domain text persisted by session chain insert --arg
• "Chain with alternatives" → ask for primary skill + 1-2 alternative skills

If chain is selected, record the skill name(s) for use in Step 3.

3. Draft the overlay JSON

Build a slug from the user's intent (kebab-case, lowercase). Write to ~/.maestro/overlays/<slug>.json:

{
  "name": "<slug>",
  "description": "<short summary of what and why>",
  "targets": ["maestro-next"],
  "priority": 50,
  "enabled": true,
  "patches": [
    {
      "section": "execution",
      "mode": "append",
      "content": "## CLI Verification (overlay)\n\nAfter execution, run:\n```\nccw cli -p \"PURPOSE: ...\" --mode analysis --rule analysis-review-code-quality\n```"
    }
  ]
}

Content guidelines

• Lead the injected block with a heading that includes (overlay) so readers see it's machine-injected
• Keep content concise — overlays should add a step, not rewrite the command
• ~/.maestro/... references are encouraged for pointing at docs
• Escape \n in JSON strings; use a HEREDOC via Bash if content is long

Skill chain content — if a chain was configured in Step 2.5, append a Skill Handoff block at the end of the patch content. The handoff uses [@ask] user prompt so the user controls whether to proceed:

---

**Skill Handoff** (overlay)

After the above step completes, use [@ask] user prompt:
- "Proceed to review" — Hand off to step `review` through `/maestro-next` or the canonical receipt-chained self-start flow
- "Skip" — Continue with current command flow
- "Alternative: execute" — Run step `execute` with built-in verification instead

On user selection:
- Proceed → route step `review` through `/maestro-next`
- Alternative → route step `execute` through `/maestro-next`
- Skip → continue normally

Handoff rules:

• Always include a "Skip" option — the user can always decline the chain
• Use an exact slash command for confirmed retained-command handoffs
• Mark handoff heading with (overlay) tag
• Support runtime variable placeholders: {phase}, {description}, {session_id}
• Keep handoff block under 10 lines of markdown

3.5. Content approval

Display the full overlay JSON to the user. [@ask] user prompt:

• "Approve & install" — proceed to installation
• "Edit" — user provides corrections, re-draft
• "Cancel" — discard overlay, do not write

Only write the overlay JSON file to ~/.maestro/overlays/<slug>.json after user approval.

4. Install via maestro overlay add

Run:

maestro overlay add ~/.maestro/overlays/<slug>.json

5. Report

Show the user:

• Path of the saved overlay JSON
• Which targets were patched and which were skipped (missing/disabled)
• Skill chain info (if configured)
• A reminder that maestro install will auto-reapply on every run
• How to remove: maestro overlay remove <slug>

Report format

=== OVERLAY INSTALLED ===
Name:    <slug>
Path:    ~/.maestro/overlays/<slug>.json
Targets: maestro-next (applied), maestro-init (skipped: missing)
Chain:   review (via [@ask] user prompt) | none
Scopes:  [global]

Re-apply: maestro overlay apply
Remove:   maestro overlay remove <slug>
Inspect:  maestro overlay list

After the report, remind the user they can run maestro overlay list for the interactive TUI showing section maps and overlay management.

Runs when --amend (or any --from-* / --scan signal flag) is present. Collects deficiency signals, diagnoses which commands need patching, batch-generates targeted overlays. State machine:

S_COLLECT   — 收集信号（从 flags / scan / description）    PERSIST: —
S_DIAGNOSE  — 映射信号到命令补丁                           PERSIST: —
S_GROUP     — 分组、规划 overlay 粒度                      PERSIST: —
S_PREVIEW   — 展示注入点地图、用户确认                     PERSIST: —
S_DRAFT     — 生成 overlay JSON                            PERSIST: overlay files
S_INSTALL   — 安装 overlay                                 PERSIST: command files
S_REPORT    — 报告摘要 + post-patch routing                PERSIST: —

Transitions: S_COLLECT → S_DIAGNOSE (signals found; else ERROR E001) → S_GROUP (command deficiencies found; else ERROR E003 when all signals are code bugs) → S_PREVIEW → S_DRAFT (user confirms "Apply all" / selects patches; "Edit" loops back to S_PREVIEW; cancel → END) → S_INSTALL (skipped when --dry-run, which displays JSON + section map and ENDs) → S_REPORT → END.

A. Collect signals

If source flags: extract signals from each specified source. If --scan or interactive: scan .workflow/ for:

• verification.json → must_have_failures, anti_patterns (filter for command gap direction)
• review.json → findings tagged "process" or "workflow"
• debug understanding.md → root causes with workflow/command cause_type
• issues.jsonl → status=open AND tags include "workflow"/"command"
• execution summaries → plan deviations suggesting missing command step

If only description: parse for affected command(s), what's missing, expected behavior.

B. Diagnose signals

Per signal, determine: signal_id, source, description, target_command, target_section, patch_mode, fix_direction, severity.

Section mapping:

Read pristine source from $PKG_ROOT/.claude/commands/<name>.md to confirm section. Classify: command deficiency → proceed; code bug → skip (suggest /maestro-companion).

Classification decision tree:

• Signal points to 'command file missing a section/gate/step/routing rule' → command deficiency → proceed with overlay
• Signal points to 'code implementation does not match existing command requirements' → code bug → skip, route to /maestro-companion or step plan via /maestro-next
• Signal involves both → split: deficiency part → overlay; bug part → route to companion
• Uncertain → default to [@ask] user prompt for user classification

C. Group overlays

Group by target command + section (merge same command+section). Granularity: 1-2 signals → patch-{command}-{slug}.json; 3+ cross-command → amend-{slug}.json. Read target commands to verify sections exist, check existing overlays. Display section map with injection points per target command.

D. Preview & confirm

Display the section map with injection points. [@ask] user prompt: Apply all / Select patches / Edit (modify signal target/section, loop back) / Cancel. Skip confirmation if -y.

E. Draft overlays

Build overlay JSON per schema: name, description, targets[], cli, priority (60), enabled, patches[{section, mode, content}]. Content rules: heading includes (patch: SIG-NNN), concise, supplementary doc to ~/.maestro/overlays/docs/ if >10 lines. If --dry-run: display JSON + section map preview and END.

CLI targeting: "cli": "claude" (default, patches .claude/commands/), "codex" (patches .codex/skills/), "both" (both paths).

F. Install

maestro overlay add ~/.maestro/overlays/amend-{slug}.json

On validation failure: fix JSON, retry (max 2).

G. Report

Display summary: signals collected/applied/skipped, overlay details, skipped code-bug routing (to /maestro-companion or step plan via /maestro-next).

Amend mode:

• Signals classified: command deficiency vs code bug
• Pristine command sources read to verify injection points
• Section map with injection points confirmed by user (unless -y)
• Overlay JSON installed successfully; command files contain overlay markers
• Skipped code-bug signals routed to alternatives