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

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.

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

• "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 request_user_input so the user controls whether to proceed:

---

**Skill Handoff** (overlay)

After the above step completes, use request_user_input:
- "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. request_user_input:

• "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 request_user_input) | 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.

<amend_mode>

Amend Mode — signal-driven auto-generation

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:

Signal pattern	Section	Mode
Missing pre-check/gate	execution	prepend
Missing post-step/verification	execution	append
Missing reading/context	required_reading / deferred_reading	append
Incomplete success criteria	success_criteria	append
Missing error handling	error_codes	append
Scope/context gap	context	append
Wrong/missing next-step routing	completion	replace / append
Missing/wrong invariant	invariants	append
Entirely new concern	(new section)	new-section

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 request_user_input 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. request_user_input: 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>

<error_codes> Amend mode only:

Code	Condition	Recovery
E001	No signals from any source	Verify artifact paths or provide description
E002	Signal source path invalid or unreadable	Check --from-* path; ensure artifact exists
E003	All signals are code bugs, not command gaps	Use /maestro-companion or step plan via /maestro-next
E004	Overlay validation failed after 2 retries	Review JSON manually
W001	Some signals skipped (code bugs)	Route to appropriate fix command
W002	Target command has >= 3 existing overlays	Consider consolidating
</error_codes>

<success_criteria> Default mode:

• Overlay JSON written to ~/.maestro/overlays/<slug>.json and validates
• maestro overlay add exited successfully and applied to at least one scope
• Target command file(s) contain <!-- maestro-overlay:<slug>#N hash=... --> markers
• Re-running maestro overlay apply produces no file changes (idempotent)
• User shown the report with target list and removal instructions
• Injection point preview shown (with existing overlays + >>> marker) and confirmed before drafting
• If chain configured, content includes a retained-command recommendation with request_user_input + Skip option

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 </success_criteria>