~/jessejaffe/work/codex-orchestration
all work

developer tooling / 2026

Codex Orchestration

I evolved an open-source routing plugin into an event-driven delivery system that matches work to the right model, separates implementation from review, and keeps releases supervised.

view repository
role
system design, Python, prompt architecture
system
router + implementers + read-only supervisors
release
v0.10.5

the problem

One model should not plan, build, review, and approve its own work.

Coding tasks vary from a quick factual check to a full product build, but a single undifferentiated workflow treats them as if they carry the same cost and risk.

Codex Orchestration classifies the intended outcome first, gives each role a narrow responsibility, and makes evidence—not momentum—the gate to release.

visual walkthrough

A task moves through distinct roles, not one long improvisation.

The workflow stays proportional for small work and adds checkpoints as risk grows.

  1. 01

    Classify the outcome

    A taxonomy-only orchestrator reads the current request and bounded continuity, chooses one of six work classes, returns the fixed route, and stops.

    $ route current_request

    CLASS BUILD
    IMPLEMENTER Sol / High
    SUPERVISOR Sol / Extra High
  2. 02

    Separate making from judging

    The implementer owns every edit and test. A different, read-only supervisor defines acceptance, reviews evidence at quiescent checkpoints, and can require precise corrections.

    IMPLEMENTER owns change
    • edit
    • test
    • release
    SUPERVISOR owns review
    • acceptance
    • evidence
    • corrections
  3. 03

    Advance on evidence

    Builds pause at architecture, vertical-slice, and release-candidate checkpoints. Only supervisor readiness unlocks the already-prepared release plan.

    01architectureboundaries + proof
    02vertical sliceend-to-end evidence
    03release candidateready, not released
    04releaseapproved + verified
  4. 04

    Keep the exact task intact

    Versioned context bundles preserve the root-visible request and completion continuity. Amendments update the same roles and acceptance instead of silently losing earlier constraints.

    revision 01initial request
    revision 02request + amendment
    accepted resultcompletion continuity

technical brief

README.md

A local Codex plugin built around strict role boundaries, exact continuity, and event-driven supervision.

01 / architecture

Root coordinates; narrow roles do one job each

A stable chat-scoped hook gives root a binary gate and the current task context. For routed work, a Terra / Extra High orchestrator returns only the relationship, work class, route, and reason. Root then starts the selected implementer and read-only supervisor against the same exact bundle.

01 current request bounded continuity + control state
02 fixed route class + roles + checkpoints
03 supervised result evidence + released revision

The orchestrator never inspects the repository, performs task work, or judges acceptance. The supervisor never edits. Those constraints prevent responsibility from bleeding across roles.

02 / outcome taxonomy

Six classes keep cost proportional to the job

READ_ONLY

Fresh verification, audit, or substantial research.

STANDARD_ARTIFACT

Content-first documents, sheets, PDFs, and presentations.

DESIGN_ARTIFACT

Non-code deliverables where visual expression defines the outcome.

SMALL_TWEAK

One existing behavior in one production component.

BIG_TWEAK

Existing behavior spanning components or material operational risk.

BUILD

Any net-new code capability, with three supervised checkpoints.

Complexity remains telemetry rather than a hidden routing lever. The outcome class alone determines the fixed implementation lane, review lane, and checkpoint sequence.

03 / context continuity

Exact bundles replace lossy prompt retelling

Each task role independently loads a private, versioned JSON bundle containing the ordered root-visible conversation since the last accepted or cancelled objective. Later checkpoint relays carry only the new decision plus immutable acceptance. 

current request
  → immutable context bundle
  → fixed route + acceptance
  → implementation checkpoint
  → continue | correct | ready to release
  → completion receipt

If the user amends active work, the hook writes a new bundle revision. The implementer pauses mutation while the same supervisor revises acceptance, preserving both the earlier request and the new constraint.

04 / release safety

The release plan exists before release authority

quiescent checkpoints

Editing, tests, builds, deploys, and migrations stop before each review.

executable plan

Repository, deployment, decisive probe, and tunnel lifecycle are resolved at release candidate.

single release owner

The same implementer performs the approved commit, push, deployment, and final probe.

root-only experience proof

Rendered or interactive outcomes use a bounded live check without turning the supervisor into an editor.

05 / stack

Small runtime, explicit protocol

plugin surface
Codex plugin manifest, hooks, custom agent profiles
runtime
Python 3, shell, JSON
model lanes
GPT-5.6 Sol, Terra, and Luna
verification
offline fixtures, protocol tests, install-state checks
distribution
Codex plugin marketplace, MIT license

Codex Orchestration is maintained at jessejaffe/codex-orchestration and builds on Danny McAteer's original sol-advisor project.