Maestra v0.3

Maestra keeps thinking and design in Main Sol while isolating execution noise in fresh subagents.

Installing Maestra does not change normal Codex behavior. Maestra is activated only by explicitly invoking $maestra:using-maestra.

Main Sol/high       — user dialogue, Spec, full Detailed Plan, semantic gates
Terra/xhigh         — one-Run execution coordination only
Luna/max            — bounded implementation
Sol/xhigh           — independent review

v0.3 planning boundary

$maestra:plan produces the complete implementation Plan in Main: architecture, Run/Task decomposition, target files/modules, implementation steps, design decisions, verification strategy, review focus, and Run gate questions. After user approval, /compact is recommended.

Execution then re-reads approved Spec/Plan artifacts. Terra may resolve mechanical details such as exact package-script commands, but must return PLAN_GAP rather than infer missing substantive design.

Opt-in activation

All seven Skills have allow_implicit_invocation: false:

$maestra:using-maestra — the only workflow entry
$maestra:doctor
$maestra:spec
$maestra:plan
$maestra:run
$maestra:gate (normally reached automatically from run)
$maestra:finish

Ordinary prompts never start Maestra or create its state/artifacts/subagents. Doctor is workflow-neutral: a standalone Doctor run reports diagnostics and returns to normal Codex behavior. No hooks or persistent activation marker are used.

After explicit activation, Main brainstorms normally, then loads each independent sibling phase protocol by exact SKILL.md path. Codex has no nested Skill-invocation API, so this deterministic progressive-disclosure route keeps every phase independent and explicit-only without requiring the user to type every phase name.

The managed lifecycle is Brainstorm → Spec → explicit approval → Plan → explicit approval → Run → Gate → next Run → Finish. Direct phase invocation remains available for recovery/debugging but does not activate the full lifecycle.

Typical use requires only these commands:

$maestra:doctor                  # optional, first-time/version check
$maestra:using-maestra

Add OAuth login support. I want to discuss the design first.

Main then manages Brainstorm → Spec approval → Plan approval → Runs/Gates → Finish.

Context/routing

Main  -> Terra : gpt-5.6-terra / xhigh / fork_turns:none
Terra -> Luna  : gpt-5.6-luna  / max   / fork_turns:none
Terra -> Sol   : gpt-5.6-sol   / xhigh / fork_turns:none

Main→Terra and Terra→Luna/Reviewer waits are event-driven with wait_agent(timeout_ms: 3600000). Mailbox updates and completion return early. Healthy Runs do not use short polling or routine list_agents; a real timeout first checks lightweight Run/Task evidence and permits at most one path-scoped agent-tree inspection when liveness remains unclear.

Doctor is fail-closed. It verifies the recorded spawn arguments, parent/child rollout chain, and observed child model/effort before binding the proof to current Codex + Maestra versions. Model self-claims alone never pass.

Runtime state

Maestra does not create product .maestra/. Runtime artifacts live under:

git rev-parse --git-path maestra

This also gives linked worktrees checkout-specific state.

Execution safety

Main Detailed Plan must pass schema-v2 completeness checks before Terra is spawned.
PLAN_GAP stops execution and only Main may resolve it through replanning/user decision.
Reviewer findings are mediated by Terra; accepted fixes stay inside approved design.
Maximum two Task review rounds with Finding Freeze.
Verification/Review/commit are bound to the same candidate tree.
Run completion requires passing Run-level verification + fresh Sol Integration Review.
Whole-branch Final Sol review is risk-based; Main final semantic check is always required.

See bundled docs for design, troubleshooting, migration, and acceptance criteria.