Maestro

• background: false is the default. Use foreground dispatch whenever the result determines the current answer or next action.
• Use background: true only for independent work. If this turn must consume a background result, call observe exactly once with action: "wait" and a bounded timeout before continuing; never continue independently while the result is pending.
• Otherwise end the turn and wait for the automatic teammate-complete notification. Do not rely on SendMessage, team_msg, or hook callbacks as completion signals.
• Never silently ignore an unfinished dispatch.

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.

If any required file above was not expanded into context by the host, or its content is no longer in context, Read it explicitly before executing the state machine.

• 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.

• -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 — classify and display the proposed chain without creating a Session or executing any step.

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.

S_CONTINUE: → S_RUN_LOOP WHEN: exactly one live compatible Session → S_FALLBACK WHEN: Session has an open decision gate or a stuck Run (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

A_CLASSIFY

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

Minimum chain rules:

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 scope, constraints and observable done criteria; broad ambiguity is not skipped by -y. (broad = affects ≥3 modules OR requires cross-package interface changes OR ≥2 of 3 decomposition questions remain unanswered.) Produce:

{
  "boundary_contract": { "in_scope": [], "out_of_scope": [], "constraints": [], "definition_of_done": "" },
  "decomposition": {
    "execution_criteria": [],
    "goals": [{ "id": "G1", "goal": "", "boundary": "", "done_when": "", "evidence": "", "lifecycle": [], "status": "pending" }],
    "changelog": []
  }
}

Goals describe outcomes, not lifecycle stages.

A_CREATE

Assemble and create per prepare/maestro.md §1–§4 (specs precheck, Skill-name prevalidation, chain assembly, creation). Maestro-specific policy:

• The chain assembly protocol (§3 template) lives in prepare/maestro.md (required_reading); if it is not in context, Read that file directly. In v3 the same prepare guidance is injected into the run next / run create birth packet (guidance-snapshot/1.0) — prepare is embedded in the Run, not a standalone run prepare step.
• Maestro does not emit formal decision nodes; new chains express quality/goal/scope checks as Skill steps that own a Run and may return a proposal. (The closed-loop policy that mandates decision nodes before seal belongs to /maestro-ralph; route there when the work needs it.)
• For narrow/single-step chains, generate a minimal implicit boundary_contract: in_scope = [intent], out_of_scope = [], constraints = [], definition_of_done = 'step completed with passing gates'.
• Do not inline unescaped JSON.

A_CONTINUE

Use read-only maestro run recall plus maestro session status --session {session_id} --json. A Session with an open decision gate or a stuck Run is out of scope here — report it and route to /maestro-ralph -c for audited recovery (S_FALLBACK); completed/archived Sessions are terminal. Multiple live candidates require explicit selection.

A_AMEND

Read ralph-amend-goal.md, use maestro session status --session {session_id} --json for the snapshot, perform read-only impact analysis, confirm, then apply the amendment through a chain-aware typed proposal: goal/decomposition metadata is committed with fenced maestro session chain insert|replace (per-step --goal-ref / --stage / --decision-ref). session meta update is session/1.x/2.0 compatibility-only and must not be used in the canonical branch. Any pending-tail change must come from a planning Skill proposal.

A_DRY_RUN

Perform A_CLASSIFY and A_DECOMPOSE in memory, display the proposed chain, boundary contract, goals, risk and unresolved arguments, then END. Do not call any Session/Run mutation command, dispatch an executor, or write workflow authority.

Legacy session/1.x/2.x Compatibility Branch

The v2 command surface is deprecated / compatibility-only for explicitly selected old CLI/schema (see run-mode.md Legacy session/1.x/2.x Compatibility Branch): maestro session create --chain-file, maestro session done --verdict, maestro session decide, maestro session meta update, and the standalone run prepare dispatcher are never used by the canonical flow above. Normal orchestration calls only the v3 surface: session open/status/list/chain insert|replace|skip/complete, run next/create/brief/check/complete --advance/decide/transition/cancel, and knowledge stage/review/promote.