maestro-next

<required_reading>
@~/.maestro/workflows/run-mode.md
@~/.maestro/workflows/codex-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 a v3 Session (`maestro session open` + `maestro run next`)
- **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 request_user_input; 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 objective to `session open`); when a chain step needs domain inputs, store them with repeatable `--arg <value>` on `maestro session chain insert|replace`. A fully specified machine-protocol `run create` passes domain text positionally; `--input <ART-id>` is only for sealed same-Session Artifact IDs. 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  — request_user_input for confirmation (skipped by -y)
S_EXECUTE  — Open Session + dispatch the selected single step Run
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 request_user_input)
  → 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` (orchestrated)
  → S_CONFIRM  WHEN: interactive

S_CONFIRM:
  → S_EXECUTE  WHEN: user confirms standard step / selects alternative / modifies args
  → END        WHEN: user picks companion → output `/maestro-companion "<intent>"`
  → END        WHEN: user picks multi-step → output the selected orchestrator: `/maestro "<intent>"` (manual) or `/ma