<div align="center">

ORRERY

Astra, Sol, Terra and Luna — in exact motion.

Architect-first orchestration for coding agents. Exact model pinning. Consented writes. Fail-closed, always.

</div>

---

Contents

Start here — What this is · The four bodies · The problem

How it runs — How it works · The flow · Orchestration semantics · Routing reference

What it guarantees — The one rule · Security model · Tool-surface consent · Supported clients · What it will not do · Interrogate it yourself · When not to use this

Using it — Quick start · MCP tools · Preview and consent · Development

---

What this is

Orrery keeps you the architect.

Your main chat owns the requirements, the architecture, the decomposition, the diff review and the acceptance. It delegates implementation to three roles you pin yourself — a routine implementer, a high-complexity implementer, and a read-only advisor that returns exactly ship, fix-first, or rethink. Worker reports are treated as claims until you verify them.

The two implementation roles are genuinely different workers, not one worker with two names. That distinction is the entire point of routing, so they are pinned to different models at different reasoning budgets — and the pin is checked against observed runtime routing before the parent accepts a result.

The same rule applies to client adapters: rendered files express requested model, effort, and read-only behavior, but only a live host observation can prove that a client honored them. See the compatibility evidence matrix.

An orrery is a clockwork model of the solar system: every body driven in exact, inspectable relation, nothing drifting on its own. That is the contract.

---

The four bodies

Each body has one job and one pin. Nothing is selected by price, and nothing falls back to something else when it is unavailable — an unavailable body stops its lane.

| Body | Pin | Orbit | |---|---|---| | Astra | gpt-6-astra · xhigh | Security and authorization logic, concurrency and ordering, non-trivial algorithms, hard debugging, migrations, wide blast radius. | | Terra | gpt-5.6-terra · high | Bounded, mechanical, fully specified work, where the specification already resolves the hard parts. | | Sol | gpt-5.6-sol · high · read-only | The fresh final review. Returns exactly ship, fix-first, or rethink, and never implements its own fixes. | | Luna | gpt-5.6-luna · max | The explicit opt-in, user-visible Codex app-task lane. Never a fallback, never activated implicitly. |

The parent is the centre they orbit. It inherits your model and reasoning effort, and it keeps architecture, decomposition, diff review, rerun verification and acceptance for itself.

Astra and Terra are the two implementation lanes, and choosing between them is a decision with consequences. Ties break toward Astra. Over-spending reasoning on a bounded edit costs latency; under-spending it on a migration costs correctness, and only the first is recoverable after the fact.

Routing is enforced at acceptance, not merely requested. If the parent selects Astra and observes Terra, that is a substituted worker and the lane stops — even when the work looks correct — because the selection was made on stated evidence, and quietly serving it from the other lane discards the decision instead of executing it.

---

The problem

Handing a whole feature to one agent and hoping is not engineering. But the fix — a lead agent that decomposes work and delegates to specialists — runs straight into two walls:

1. Every client defines subagents differently. One wants .codex/agents/*.toml, another .cursor/agents/*.md, another .claude/agents/*.md. They bind different things: some pin a model and reasoning effort and a sandbox, some pin only a model.
2. A plugin that writes into your agent config is privileged. If a prompt-injected model can talk it into writing an arbitrary file to an arbitrary path, you have handed an attacker your editor.

Orrery solves the first without ever conceding the second.

---

How it works

        YOU
         │
         ▼
  ┌─────────────────────────────────────────────┐
  │  PARENT CHAT  =  ARCHITECT                  │
  │  inherits YOUR model and reasoning effort   │
  │                                             │
  │  owns: requirements · architecture ·        │
  │        decomposition · the actual diff ·    │
  │        re-running checks · acceptance       │
  └──────────────────┬──────────────────────────┘
                     │  delegates, then verifies
     ┌───────────────┼───────────────┐
     ▼               ▼               ▼
 ┌──────────────┐ ┌──────────────┐ ┌──────────────┐
 │   ROUTINE    │ │     HIGH     │ │   ADVISOR    │
 │  terra·high  │ │ astra·xhigh  │ │   sol·high   │
 ├──────────────┤ ├──────────────┤ ├──────────────┤
 │ bounded      │ │ security     │ │ read-only    │
 │ wiring       │ │ concurrency  │ │   ship /     │
 │ full specs   │ │ algorithms   │ │   fix-first /│
 │              │ │ migrations   │ │   rethink    │
 └──────────────┘ └──────────────┘ └──────────────┘

The parent never types implementation code when a delegated lane can do it. Workers receive a complete five-part specification — objective, file ownership, interfaces, constraints, verification — and return structured evidence. The parent then inspects the working tree, confirms only in-scope files changed, and re-runs the verification commands itself before a fresh advisor is asked for a verdict.

A ship verdict is not the end of a conversation. It is the end of an audit.

---

The flow

There is a trap in the question "how do all four models work together", and it is worth naming before the diagram: they never all run at once. The four bodies are a roster, not a pipeline.

• Astra ⊕ Terra — mutually exclusive. Exactly one implementer per delegation.
• Native lane ⊕ Luna lane — mutually exclusive. Luna is opt-in only and is never a fallback.

The most that is ever live in a single run is three bodies, and only when the parent is Sol.

The native lane

              YOU
               │  goal + constraints
               ▼
   ┌───────────────────────────┐
   │  PARENT CHAT = ARCHITECT  │   inherits YOUR model
   │  (Sol / High recommended, │   ← a recommendation only,
   │   never required)         │     never a gate
   └─────────────┬─────────────┘
                 │
      ┌──────────▼──────────┐
      │  0. SETUP GATE      │  get_setup_status → get_preferences
      │     tools-changed?  │  ── STOP. A security event, not a nuisance.
      └──────────┬──────────┘
                 │
      ┌──────────▼──────────┐
      │  1. PREFLIGHT       │  install-agents.sh --check → must exit 0
      │                     │  all three agent_type names exposed?
      └──────────┬──────────┘
                 │
      ┌──────────▼──────────┐
      │  2. ROUTE           │  the parent decides, on stated evidence
      └─────┬─────────┬─────┘
            │         │
   bounded, │         │  security · concurrency · algorithms
   specified│         │  hard debugging · migrations · wide radius
            ▼         ▼
      ┌─────────┐ ┌──────────┐
      │  TERRA  │ │  ASTRA   │   ← exactly one of these
      │  high   │ │  xhigh   │
      └────┬────┘ └────┬─────┘
           └─────┬─────┘
                 │  five-part specification in, evidence out
      ┌──────────▼──────────┐
      │  3. ROUTING PROOF   │  observed model/effort == the lane selected?
      │                     │  ── mismatch is a substituted worker. STOP.
      └──────────┬──────────┘
                 │
      ┌──────────▼──────────┐
      │  4. PARENT VERIFIES │  inspect the diff · in-scope files only ·
      │     (not the worker)│  RERUN the verification commands itself
      └──────────┬──────────┘
                 │
      ┌──────────▼──────────┐
      │  5. SOL — read-only │  fresh context, never implements its own fixes
      └──────────┬──────────┘
                 │
        ship ────┴──── fix-first ──▶ re-delegate, verify, obtain a NEW review
          │              rethink  ──▶ revise architecture, do not report done
          ▼
       ACCEPT

Sol appears three times

| Where | What it is | |---|---| | The parent | gpt-5.6-sol / High is the recommended orchestrator, and purely advisory. The skill must never block because the parent is not Sol, never change it, and never claim it changed it. | | Commitment-boundary consult | Before a consequential architecture decision, migration, public API, or wide refactor — and always before accepting Astra-lane work, since that lane is selected precisely when the blast radius is wide. | | Final review | Always. Returns exactly ship, fix-first, or rethink. |

Sol reviewing Sol-authored work is context-clean, not model-family-independent. That distinction is stated rather than glossed, because it is the limit of what this lane can honestly claim.

The Luna lane

Entered only when the current request explicitly authorizes it — "Use the Luna task lane for this feature."

PARENT ──list_projects──▶ pick projectId, check isGitRepository
   │
   ├──create_thread──▶  LUNA   gpt-5.6-luna · thinking: max
   │                    a user-visible Codex app task, own worktree
   │                    ⚠ clientThreadId is a SETUP HANDLE, not a task id
   │                       → correlate a real threadId + hostId first
   │
   ├──wait_threads──▶ monitor
   ├──read_thread───▶ handoff
   │
   ├── PARENT inspects the actual branch, diff and checks itself
   │
   ├──send_message_to_thread──▶ corrections go to the SAME task
   │                             then wait, read, and re-review again
   │
   └── PARENT authorizes the PR ──▶ only now may the child push

Two things differ sharply from the native lane. No Sol is spawned — the parent performs the final revie