<required_reading> @/.maestro/workflows/overlays.md @/.maestro/cli-tools.json </required_reading>
Signal sources:
| 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. No flags + no description → interactive (scan + request_user_input).
Control: --dry-run (preview, don't install), -y (skip confirmations)
CLI targeting: "cli": "claude" (default, patches .claude/commands/), "codex" (patches .codex/skills/), "both" (both paths)
Source path mapping by CLI:
| CLI | Pristine source path |
|---|---|
claude |
$PKG_ROOT/.claude/commands/<name>.md |
codex |
.codex/skills/<name>/SKILL.md |
both |
Both paths checked; overlay targets whichever exists |
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. NEVER modify .claude/commands/*.md directly — overlay installation is handled by maestro overlay add.
<state_machine>
S_COLLECT: → S_DIAGNOSE WHEN: signals found DO: A_COLLECT_SIGNALS → ERROR(E001) WHEN: no signals from any source
S_DIAGNOSE: → S_GROUP WHEN: command deficiencies identified DO: A_DIAGNOSE_SIGNALS → ERROR(E003) WHEN: all signals are code bugs (not command gaps)
S_GROUP: → S_PREVIEW DO: A_GROUP_OVERLAYS
S_PREVIEW:
→ S_DRAFT WHEN: -y flag set (skip confirmation, apply all)
→ S_DRAFT WHEN: user confirms "Apply all" or selects patches
→ S_PREVIEW WHEN: user selects "Edit" DO: modify signal target/section
→ END WHEN: user cancels
S_DRAFT: → S_INSTALL WHEN: not --dry-run DO: A_DRAFT_OVERLAYS → END WHEN: --dry-run DO: display JSON + section map preview
S_INSTALL:
→ S_REPORT DO: A_INSTALL_OVERLAYS (maestro overlay add, retry max 2 on validation failure)
S_REPORT: → END DO: display summary (signals collected/applied/skipped, overlay details, skipped code-bug routing)
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.
A_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 |
| Entirely new concern | (new section) | new-section |
Read pristine source using CLI path mapping: claude → $PKG_ROOT/.claude/commands/<name>.md, codex → .codex/skills/<name>/SKILL.md. Confirm section exists in target.
Classify: command deficiency → proceed; code bug → skip (suggest $maestro-quick).
A_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.
A_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.
A_INSTALL_OVERLAYS
maestro overlay add ~/.maestro/overlays/amend-{slug}.json
On validation failure: fix JSON, retry (max 2).
</state_machine>
<error_codes>
| Code | Condition | Recovery |
|---|---|---|
| E001 | No signals from any source | Verify artifact paths or provide description |
| E003 | All signals are code bugs, not command gaps | Use $maestro-quick or $maestro-plan --gaps |
| 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>
- Signals classified: command deficiency vs code bug
- Pristine command sources read to verify injection points
- Section map with injection points confirmed by user
- Overlay JSON installed successfully; command files contain overlay markers
- Skipped code-bug signals routed to alternatives </success_criteria>