/maestro

name: maestro
disable-model-invocation: false
description: "Intent-to-chain planner over the canonical Session/Run lifecycle"
argument-hint: "<intent> [-y] [-c] [--amend] [--dry-run]"
allowed-tools:
  - Read
  - Write
  - Edit
  - Bash
  - Glob
  - Grep
  - Agent
  - SendMessage
  - AskUserQuestion
  - TodoWrite
  - TaskCreate
  - TaskUpdate
session-mode: run
contract:
  discovery: self-described
  consumes: []
  produces: []

<required_reading> @~/.maestro/workflows/run-mode.md @~/.maestro/workflows/orchestrator-run-loop.md @~/.maestro/prepare/maestro.md </required_reading>

<deferred_reading>

• [maestro.md](~/.maestro/workflows/maestro.md) — read before initial intent classification
• [ralph-amend-goal.md](~/.maestro/workflows/ralph-amend-goal.md) — read only for `--amend`

</deferred_reading>

<purpose> Turn a user intent into the initial Skill chain, create one canonical topic Session through `maestro session create --chain-file`, then execute the shared Run loop. Static versus dynamic is not a Session or command mode: each Skill contract decides whether it emits a typed chain proposal. For new intents, use this command. For policy-driven execution over existing Sessions, use `/maestro-ralph`. </purpose>

<interface> Only these user flags are accepted:

• `-y` — skip all confirmation/clarification interactions, use default choices. Does NOT change data semantics (no auto-deferred decisions). Never bypasses: high-risk classification, confidence <60, ambiguity requiring user input, failed gates, or drift escalation.
• `-c` — continue the unique live compatible Session.
• `--amend` — amend that Session's goal; remaining text is the change request.
• `--dry-run` — show chain without executing.

Execution always dispatches run-executor (the default behavior); this never changes Session type or chain semantics.

All other text is intent. Unknown flags are not silently reinterpreted. Platform, roadmap, quality, template reuse, parallelism and adversarial depth are inferred. </interface>

<invariants> 1. **One chain** — every task uses the same Session/Run protocol; no static/dynamic, Maestro/Ralph, or executor-specific Session type. 2. **Session before execution** — create via `session create --chain-file` before allocating a step Run. 3. **Creator owns decomposition** — Maestro creates `boundary_contract` and outcome-oriented goals; later orchestrators consume rather than overwrite them. 4. **Runtime owns mutation** — prompt never writes session.json/run.json and never auto-uses admin chain commands. 5. **Skill owns domain adaptation** — optional chain changes come only from the current Skill's validated `chain-proposal/1.0`. 6. **Verdict advances** — execution steps advance only through `session done --verdict`; decision steps only through `session decide`. 7. **Historical similarity remains read-only evidence** — it never selects a Session or binds outputs. 8. **Compatibility commands are out of band** — normal orchestration calls only `maestro run ...`. 9. **Auto is bounded** — `-y` never bypasses high risk, low confidence, ambiguity, failed gates or drift escalation. 10. **Router is not a step** — `/maestro-next` may route here but never appears inside the chain. 11. **Running means continue** — while canonical continuation authority is `automatic`, execute it and re-read the receipt in the same turn; `suggest_only` is Runtime passivity, not a reason to end the turn. </invariants>

<state_machine>

<states> S_PARSE — parse intent and flags S_CONTINUE — locate the unique live Session S_AMEND — audited goal amendment S_CLASSIFY — select the smallest sufficient initial chain S_DECOMPOSE — derive boundary, criteria and observable goals S_CREATE — create via `session create --chain-file` S_CONFIRM — confirm classification unless `-y` S_RUN_LOOP — execute `orchestrator-run-loop.md` S_FALLBACK — request missing intent or disambiguation </states>

<transitions> S_PARSE: → S_AMEND WHEN: `--amend` → S_CONTINUE WHEN: `-c` → S_CLASSIFY WHEN: intent present → S_FALLBACK OTHERWISE

S_CONTINUE: → S_RUN_LOOP WHEN: exactly one live compatible Session → S_FALLBACK WHEN: Session is paused (suggest /maestro-ralph -c for audited recovery) → S_FALLBACK WHEN: none or multiple

S_AMEND: → S_RUN_LOOP WHEN: shared amend protocol committed → END WHEN: cancelled or blocked

S_CLASSIFY: → S_RUN_LOOP WHEN: existing compatible Session found (do not rebuild) → S_DECOMPOSE WHEN: multi-step chain → S_CREATE WHEN: narrow/single-step chain → S_FALLBACK WHEN: confidence < 60

S_DECOMPOSE → S_CREATE S_CREATE → S_RUN_LOOP WHEN: `-y` AND risk ≠ high AND confidence ≥ 60 S_CREATE → S_CONFIRM WHEN: `-y` AND (risk == high OR confidence < 60) S_CREATE → S_CONFIRM OTHERWISE S_CREATE → S_FALLBACK WHEN: creation fails (delete temp file, report error) S_CONFIRM → S_RUN_LOOP WHEN: confirmed S_CONFIRM → S_CLASSIFY WHEN: revised (maestro re-classifies the revised intent from scratch because a changed intent may reshape the chain; ralph returns to S_BUILD instead since its chain shape is already fixed) S_CONFIRM → END WHEN: cancelled </transitions>

<actions>

A_CLASSIFY

Read deferred `maestro.md`. Record matched evidence, excluded alternatives and confidence before creation.

Minimum chain rules:

| Intent evidence | Initial chain | |---|---| | narrow fix/change | analyze → plan → execute → review/test as required | | broad rewrite/migration | analyze-macro → scope decision → plan/roadmap path | | brainstorm/explore | brainstorm, then only Skill-proposed continuation | | stress/grill | grill, then only Skill-proposed continuation | | formal specification | blueprint → plan path | | existing compatible Session | do not rebuild; enter shared loop |

Roadmap is inferred only for multi-release evidence. Quality depth follows project specs, UI evidence needs frontend verification, and every executable command is resolved by Run Runtime.

A_DECOMPOSE

For broad intent, ask at most 3 questions covering