/maestro-next

name: maestro-next
disable-model-invocation: false
description: "Unified entry for all development intents — classify intent, assess complexity, route to the correct execution channel: /maestro-companion (lightweight), standard single run, or /maestro and /maestro-ralph (multi-step manual/orchestrated). Pure router, never runs execution loops itself"
argument-hint: "<intent> [-y]"
allowed-tools:
  - Read
  - Write
  - Edit
  - Bash
  - Glob
  - Grep
  - AskUserQuestion
session-mode: run
contract:
  discovery: self-described
  consumes: []
  produces: []

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

<purpose> Unified interactive entry for all development intents. Pure router: parse intent + project state → classify → assess complexity → route to the appropriate channel:

• **Companion** (lightweight): route to `/maestro-companion "<intent>"` — minimal run lifecycle, continuous evidence recording
• **Standard** (single run): recommend a step → confirm → execute via `maestro run prepare` + `maestro run start`
• **Multi-step**: route to `/maestro "<intent>"` (manual stepwise control) or `/maestro-ralph "<intent>"` (orchestrated closed-loop)

This command is the single entry point. It classifies and routes. Multi-step execution loops live in `/maestro` (manual) and `/maestro-ralph` (orchestrated). </purpose>

<context> $ARGUMENTS — intent text + optional flags.

**Flags:**

| Flag | Effect | |------|--------| | `-y` / `--yes` | Skip confirmation. Auto-executes only the **standard** channel; for companion/multi-step it emits the target invocation (router semantics — the target command owns execution) |

**Mode detection (priority order):** 1. Intent text present → S_STATE → S_RANK → route by complexity verdict 2. "continue"/"next"/"go" → lifecycle inference for natural next step 3. No arguments at all → 1 clarify round

**Candidate pool:** All 14 first-tier steps registered in `prepare/` + `workflows/`. Companion is a routing channel, not a first-tier step. Pipeline orchestrators (`maestro`, `maestro-ralph*`) are NEVER in the candidate pool. </context>

<invariants> 1. **Pure router for multi-step** — this command never runs execution loops (manual chain or orchestrated). Multi-step execution is delegated to `/maestro` (manual) or `/maestro-ralph` (orchestrated) 2. **Pipeline orchestrators excluded** — only recommend registered steps as single-run targets 3. **Lifecycle continuation** — "continue"/"next"/"go" are explicit continuation signals → lifecycle_position inference (S_STATE). Truly empty arguments (no text at all) → 1 clarify round via [@ask] AskUserQuestion; still empty → S_FALLBACK (E001) 4. **Literal match priority** — keyword match takes precedence; lifecycle is tie-breaker 5. **Argument pass-through** — the intent phrase is Session metadata only (the positional phrase to `run start`); the selected step's domain payload becomes command input through repeatable `--arg <value>`. The user can modify command inputs at confirmation; `-y` only passes through when the user provided it 6. **Manual campaigns excluded** — `team-*` and `maestro-odyssey` never enter the executable candidate pool and are never executed in this turn; they may only be emitted as suggest-only invocations (see the odyssey campaign rows in the intent routing table) 7. **Retained commands are suggest-only** — route retained commands to an exact slash command. Never execute them in this turn; `-y` applies only to first-tier steps 8. **Companion routing is suggest-or-execute** — when complexity == lightweight, output `/maestro-companion "<intent>"` invocation. With `-y`, emit the invocation directly (`/maestro-companion "<intent>" -y`); the companion command owns its own execution. Without `-y`, present it as the recommended channel for user confirmation 9. **Multi-step routes to the orchestrators** — when intent spans ≥2 steps or needs orchestration, output `/maestro "<intent>"` (manual stepwise) or `/maestro-ralph "<intent>"` (orchestrated closed-loop). This command never creates sessions or manages chains itself 10. **Cross-category keyword priority** — when an intent keyword matches both a first-tier step and a retained command, the first-tier step wins for candidate selection; complexity assessment still applies independently. Auxiliary clusters are advisory grouping for display, never routing overrides 11. **`-y` means skip-confirmation, not auto-execute** — for standard channel, skipping confirmation proceeds to S_EXECUTE (this command runs the step). For companion/multi-step channels, this command is a router: skipping confirmation means outputting the target invocation text directly. The target command owns its own execution semantics </invariants>

<state_machine>

<states> S_PARSE — Parse arguments, extract flags, detect mode S_STATE — Read project state, infer lifecycle_position S_RANK — Score candidates, assess complexity, determine channel S_PRESENT — Show top pick + alternatives + reasoning + channel verdict S_CONFIRM — [@ask] AskUserQuestion for confirmation (skipped by -y) S_EXECUTE — Run prepare + start for selected single step S_FALLBACK — Intent empty after clarification </states>

<transitions>

S_PARSE: → S_STATE WHEN: intent present / "continue"/"next"/"go" → S_PARSE WHEN: no arguments at all (1 clarify round via [@ask] AskUserQuestion) → S_FALLBACK WHEN: clarification still empty

S_STATE: → S_RANK DO: A_INFER_LIFECYCLE

S_RANK: → S_PRESENT DO: A_SCORE_CANDIDATES (channel verdict embedded in presentation)

S_PRESENT: → END WHEN: target_kind == retained-command DO: display exact slash command; suggest only → S_EXECUTE WHEN: -y AND channel == standard → END WHEN: -y AND channel == companion DO: output `/maestro-companion "<intent>" -y` → END WHEN: -y AND channel == multi-step DO: output the selected orchestrator: `/maestro "<intent>" -y` (manual) or `/maestro-ralph "<intent>" -y` (or