Maestro Next

Pi mirrors canonical Session/Run state automatically:

• Advance only with todo({ action: "next" }); do not create or update mirror tasks manually.
• Goal completion is derived from terminal chain state and clean gates.
• After compaction, reattach through the current Run's brief.command.

Pi lifecycle routing:

• Execute every Session/Run lifecycle read or mutation with the run-control tool by passing the displayed Maestro arguments as argv without the leading maestro executable. Never execute lifecycle mutation through Bash.
• Fenced Maestro CLI examples below are human syntax references, not an alternate Pi execution path. Shorthand command-family mentions are not executable examples. Any executable human CLI example must show the complete v3 authority envelope: exact --session, identical --participant and --actor, a distinct --request-id, --reason, and the applicable entity revision fences.
• For session open, the coordinator injects participant == actor, request ID, reason, and JSON output; a new Session has no --session or expected revision yet.
• For operations on an active Session, the coordinator injects the exact --session, participant == actor, request ID, reason, and current --expected-orchestration-revision; Run mutations also receive --expected-run-revision. session migrate uses legacy identity/activity revision fences instead.
• The coordinator must be available for every run-control call. Session opening does not require an already active Session; all other mutations target an exact active or explicitly named Session.

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

• Consume the injected Topic Session resolution and ReuseAssessment as read-only routing evidence.
• Accept upstream only from same-Session sealed outputs.
• Resolve each argument_requirements entry through required, missing, type, source, optional default, and question.
• Treat the birth packet as compact routing; load the execution protocol from brief.command.
• A completion hint with suggest_only=true is displayed and never executed implicitly.

Flags:

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.

S_PARSE: → S_STATE WHEN: intent present / "continue"/"next"/"go" → S_PARSE WHEN: no arguments at all (1 clarify round via [@ask] user prompt) → 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 /maestro-ralph "<intent>" (orchestrated) → END WHEN: user cancels

S_EXECUTE: → END DO: A_EXECUTE_STEP

S_FALLBACK: → END DO: raise E001

A_INFER_LIFECYCLE

Read canonical Session/Run state to infer lifecycle_position; never inspect .workflow/state.json or choose by mtime:

maestro session list --json
maestro session status --session {session_id} --json
maestro session resume-view --session {session_id} --json

Canonical state → lifecycle_position → natural next step:

Lifecycle main line:

init → {brainstorm | blueprint | analyze-macro} → roadmap
  → [per session] analyze → plan → execute
  → [quality gate] review → auto-test → test
  → session-manage --complete → next dep-ready session

Multi-Session resolution: historical similarity is read-only evidence. Resolve an exact compatible Session from session list plus session status; multiple compatible Sessions require user selection. Use resume-view and same-Session sealed Artifacts for lifecycle inference. Never select a Session from a local projection, directory order, or modification time.

A_SCORE_CANDIDATES

Scoring signals (high → low):

Complexity assessment (determines channel):

Routing preference: prefer the lightest channel that satisfies the task. Default to Companion for anything that looks like a quick fix/lookup/exploration. Only upgrade to Standard when there is concrete evidence the task produces artifacts a downstream step will consume, or needs a gate/verdict for lifecycle tracking. Only route to /maestro when the intent genuinely spans ≥2 distinct lifecycle steps. When in doubt between Companion and Standard, ask the user via the confirmation menu rather than auto-upgrading.

Lightweight signals (all must hold):

• Intent specifies a concrete, bounded action — the user names what to change and where (file, function, error message). "Fix the login bug" is NOT lightweight (unbounded diagnosis); "change the timeout from 30s to 60s in auth.ts" IS lightweight. File count is irrelevant; a 20-file rename with a known pattern is still lightweight
• No typed artifact needs to be consumed by a downstream step
• No gate/verdict needs to be recorded for lifecycle tracking
• Task does not require pre-task thinking (prepare) or structured brief to execute correctly
• Single concern — intent does not span multiple lifecycle phases (e.g., analyze+plan, execute+review)

Multi-step detection: intent matches keywords of ≥2 distinct steps in the routing table → classify the relationship before setting multi_step:

Dominant step = the step whose keyword appears first or carries the primary verb. When in doubt, present both as alternatives rather than auto-selecting.

Orchestrator selection (for multi-step routing):

• /maestro (manual): user explicitly asks for stepwise/per-step control ("one step at a time", "confirm each step"), or intent is a simple sequential pipeline of ≤3 steps without quality gates
• /maestro-ralph (orchestrated, default): intent implies iterative quality convergence — broad refactoring (>5 files), migration, "end-to-end", "full lifecycle", or needs decision gates/drift analysis/auto-retry. When in doubt, default to /maestro-ralph

Override flags:

• Channel is auto-detected from the signals above; the verdict is shown to the user before routing, and the user may override the channel at the confirmation menu (S_CONFIRM).

Intent routing table: first-tier rows enter the executable candidate pool. Retained-command rows are advisory routes: show the exact slash command and stop.

Cross-category priority: first-tier step keywords take precedence over retained-command keywords when both match. Example: "security test" → test (first-tier) wins over security/OWASP (odyssey campaign), unless the intent explicitly says "security audit" or "OWASP". Auxiliary cluster triggers are the lowest priority — they group retained commands for display but never override individual keyword matches.

Scope guard: keyword match identifies the candidate step, but the complexity verdict still applies independently. A keyword hit does NOT override lightweight signals. Example: "rename this variable" matches execute/implement keywords → candidate = execute step, but complexity = lightweight (1 file, no handoff) → channel = /maestro-companion. The routing table answers "which step?", the complexity assessment answers "which channel?".

Auxiliary workflow clusters:

A_EXECUTE_STEP

Single-run path only. Multi-step execution is handled by /maestro (manual) and /maestro-ralph (orchestrated).

For first-tier steps (those with prepare/ + workflows/ files):

# 1. Open an empty Session; participant and actor are the same identity.
maestro session open "<objective>" --id YYYYMMDD-<step>-<topic> --participant {actor_id} --actor {actor_id} --request-id {open_request_id} --reason "open single-step Session" --json
#    Or attach an existing compatible Session read-only first: maestro session status --session {session_id} --json

# 2. Persist the selected step and each required positional command input.
maestro session chain insert --session {session_id} --step-id {step_id} --command <step> --arg "<domain input>" --participant {actor_id} --actor {actor_id} --request-id {insert_request_id} --reason "add selected step" --expected-orchestration-revision {open_orchestration_revision} --json

# 2a. LLM performs pre-task thinking using the prepare guidance embedded in the birth packet.

# 3. Dispatch with the exact revision returned by chain insert.
maestro run next --session {session_id} --participant {actor_id} --actor {actor_id} --request-id {next_request_id} --reason "dispatch selected step" --expected-orchestration-revision {insert_orchestration_revision} --json
#    Direct machine-protocol alternative (only for an existing exact step):
#    maestro run create <step> "<domain input>" --session {session_id} --run {run_id} --step {step_id} --goal "<goal>" --input <ART-id> --participant {actor_id} --actor {actor_id} --request-id {create_request_id} --reason "create selected Run" --expected-orchestration-revision {step_orchestration_revision} --json
#    Returns: run_id, run_dir, upstream, resolved task, entry blockers, and structured executable continuation

# 3a. Entry blocker degradation (execute-specific)
#    IF step == execute AND entry_blockers is non-empty (missing current-plan):
#      Inspect upstream for alternative artifacts (latest-review, latest-debug, latest-fix-directions).
#      Route per the degradation table in prepare/execute.md:
#        - Small scope (≤3 findings, ≤2 files each) → transition/cancel the attempt, surface /maestro-companion
#        - Larger scope → transition/cancel the attempt, surface /odyssey-planex
#        - No alternative upstream → `maestro run transition {run_id} blocked`, surface E001 + suggest /plan
#      The chain step returns to pending; a later fenced `maestro run next` may retry it.
#      Do NOT proceed to step 4 with a blocked execute run.

# 3b. Entry blocker handling (general, non-execute steps)
#    IF step != execute AND entry_blockers is non-empty:
#      Display each blocker with recovery suggestion:
#        - Missing upstream artifact → suggest the producing step (e.g., "run analyze first")
#        - Gate failure → suggest the gate step (review/verify/auto-test)
#      `maestro run transition {run_id} blocked` (or `maestro run cancel {run_id}`) — do NOT proceed to step 4.

# 4. Load the execution manual (follow the birth packet `guidance`/`brief.command` from step 3)
#    Execute the birth packet guidance verbatim — append no flag.
#    Returns: workflow content, run-mode summary, goal, gate status

# 5. LLM executes the workflow (core process)

# 6. Check and complete the run
maestro run check {run_id} --session {session_id} --json
maestro run complete {run_id} --session {session_id} --participant {actor_id} --actor {actor_id} --request-id {complete_request_id} --reason "complete selected step" --expected-orchestration-revision {orchestration_revision} --expected-run-revision {run_revision} --verdict done --advance --json

After run complete --advance: re-infer lifecycle and surface the natural next step as a continuation hint — stepwise multi-step work proceeds by re-invoking /maestro-next or /maestro -c.

For retained commands, output the exact slash command as a suggest-only result. Do not execute it, including under -y; the user invokes it explicitly in a subsequent message.

Normal mode

[⚠ Multi-step intent detected]   ← only when multi_step

Target: /<step-name>
Kind: first-tier step | retained command | companion | multi-step
  <description>
  Reason: <match rule + lifecycle position>
  Channel: /maestro-companion | single run | /maestro (manual) | /maestro-ralph (orchestrated)
  Invocation:
    companion       → /maestro-companion "<intent>"
    single run      → Confirm to execute through Maestro Run lifecycle
    multi-step      → /maestro "<intent>" (manual) or /maestro-ralph "<intent>" (orchestrated)
    retained        → Run manually: /<command> <subcommand> <args> (suggest only)

Alternatives:
  2. /<alt-1> — <description> — <invocation method>
  3. /<alt-2> — <description> — <invocation method>

Args: <args>

Confirmation menu varies by channel verdict:

When channel == companion:

• Run as companion (Recommended) → /maestro-companion "<intent>"
• Upgrade to standard run → S_EXECUTE
• Cancel

When channel == standard:

• Execute recommendation (Recommended)
• Choose alternative
• Modify arguments
• Cancel

When multi_step:

• Hand off to orchestrator (Recommended) → /maestro "<intent>" (manual) or /maestro-ralph "<intent>" (orchestrated)
• Just this step (execute only the top pick as single run)
• Cancel

-y: execute/route immediately per channel.