Skip to main content

Orchestrated delivery for Codex and Claude Code

A collection of software delivery skills and focused subagents for Codex and Claude Code. It installs a reusable orchestration workflow, an explicit code-review workflow, and custom subagents so the coding agent follows a structured process for discovery, planning, independent plan review, implementation, testing, and final review. Two small companion skills stress-test a plan before work starts and hand a session over to a fresh one.

The delivery skill instructs the main conversation to orchestrate only: classify the request, delegate bounded work when specialization, independent review, or parallelism materially improves the result, and verify the result. The orchestrator hands each subagent a scoped digest of the plan and a discovery impact map, so work proceeds without re-reading whole artifacts, keeping runs fast and cheap under the same phased contract.

The same workflow ships as one package per harness, built from this repository and released together with the same version:

Harness Package and command Invoke a skill with
Codex orchestrated-codex $orchestrated-delivery
Claude Code orchestrated-claude /orchestrated-delivery

Both packages offer the same components, command-line options, and installer guarantees; only the file formats and install locations differ.

Installation

Install with uv, using the package for your harness:

uvx orchestrated-codex --install
uvx orchestrated-claude --install

The installer opens a guided checklist. Use the arrow keys to move, Space to select one or more components, and Enter to install the selected set. Previously installed components are preselected; deselecting one removes its unchanged files while preserving locally modified files.

To run from source instead, use a checkout and pick the harness with --codex or --claude:

git clone https://github.com/knuthelge/orchestrated-codex.git
cd orchestrated-codex
uv run main.py --codex --install
uv run main.py --claude --install

For CI or other unattended installs, install the bundled set or name a comma-separated component set. The options are the same for both packages:

uvx orchestrated-claude --install --all
uvx orchestrated-codex --install --components code-review
uvx orchestrated-claude --install --components grill-me,handoff

Named component installs automatically include dependencies declared by the component registry. --install --all installs or updates every component. Installation needs no network access. A plain --install requires an interactive terminal.

Where files are installed

Codex Claude Code
Skills $HOME/.agents/skills <config>/skills
Subagents <codex home>/agents/*.toml <config>/agents/*.md
Installation manifest <codex home>/codex-orchestrator-install.json <config>/claude-orchestrator-install.json
Home directory CODEX_HOME if set, else ~/.codex CLAUDE_CONFIG_DIR if set, else ~/.claude
Override flag --codex-home PATH (skills stay under $HOME/.agents/skills) --claude-config-dir PATH (skills and subagents move together)

Usage

Start a new conversation after installation (for Codex, restart it). Both workflows run only when you invoke them; neither harness selects them automatically:

$orchestrated-delivery implement this feature          # Codex
$orchestrated-code-review review the current changes   # Codex
$orchestrated-grill-me <your plan>                     # Codex
$orchestrated-handoff                                  # Codex

/orchestrated-delivery implement this feature          # Claude Code
/orchestrated-code-review review the current changes   # Claude Code
/orchestrated-grill-me <your plan>                     # Claude Code
/orchestrated-handoff                                  # Claude Code

The code-review skill writes its independently verified, prioritized findings to code-review.md. It reviews local changes by default and uses pull-request context when available. Every review also tracks the mandatory ten-stage workflow and its per-finding validation in .agent-work/code-review-checklist.md. The review does not publish comments or modify code unless you separately ask for that action. In Claude Code, the bundled /code-review skill is unaffected.

The grill-me skill interviews you about a plan in rounds of numbered questions, each with a recommended answer, until every open decision is settled; it looks facts up itself and does not act until you confirm the summary. The handoff skill prints a copyable summary of the session (goal, state, decisions, open questions, next steps, references) for a fresh session to continue from; it writes no file.

Uninstall

Remove the installed files with the package you installed:

uvx orchestrated-codex --uninstall
uvx orchestrated-claude --uninstall

The installer refuses to overwrite files it does not own. Uninstall removes only installed files that still match the recorded hashes and then deletes the manifest; locally modified installed files are preserved and reported.

Installed components

The bundled components are the same for both harnesses:

  • orchestrated-delivery (skill): task classification and an adaptive discovery, planning, independent plan review, implementation, testing, and final-review workflow.
  • orchestrated-code-review (skill, component code-review): explicit-only review of a local diff or pull request, producing a comprehensive, prioritized, independently verified code-review.md report without a minimum or maximum finding count.
  • orchestrated-grill-me (skill, component grill-me): explicit-only interview that stress-tests a plan until every decision is settled.
  • orchestrated-handoff (skill, component handoff): explicit-only, copyable handoff summary for continuing the work in a fresh session.
  • Seven subagents, installed with orchestrated-delivery:
Subagent Role Codex model Claude Code model
discovery Read-only codebase reconnaissance gpt-6-luna haiku
spec-designer Requirements and technical design gpt-6.1-sol opus
rubber-duck Independent PRD peer review (PASS/CONCERNS) gpt-6.1-sol opus
ui-designer Visual design specification for substantial UI work gpt-6.1-sol opus
developer Implements planned changes and fixes test or review failures gpt-5.6-terra sonnet
tester Authors and runs tests and verifies requirements (PASS/FAIL) gpt-5.6-terra sonnet
final-reviewer Read-only holistic final review gpt-6.1-sol opus

Codex names these agents with underscores (rubber_duck, final_reviewer); Claude Code uses the hyphenated names shown.

Implementation is delegated to the developer subagent. The main conversation orchestrates the workflow and does not implement work itself. Independent delegations use fresh context and the orchestrator does not poll while waiting for subagent results. Read-only subagents are restricted by each harness: Codex runs them in a read-only sandbox, and Claude Code removes its file-editing tools from them (they keep shell access for inspection commands such as git diff). In Claude Code, no installed subagent can start subagents of its own.

Upgrading from earlier Codex versions

The review skill was previously named code-review and invoked as $code-review. Updating an existing installation removes the old code-review skill directory and installs orchestrated-code-review; if you edited the old skill, your copy is preserved and reported, and remains available until you delete it. The component is still selected with --components code-review. Implementation, previously delegated to the built-in worker, now goes to the installed developer agent.

Development

This repository is one codebase. The two packages published to PyPI are exported from it at build time; neither exists as hand-edited source.

src/orchestrated/     installer engine (cli, registry, runtime) and targets.py,
                      which defines the Codex and Claude Code targets side by side
content/              skills, agents, and the component registry, written once
scripts/export.py     renders each target's resources and exports its package
main.py               runs the codebase directly: --codex or --claude
tests/                test the codebase; target-dependent tests run once per target

Run the tests from a checkout:

uv run python -m unittest discover -s tests

Everything that differs between harnesses is in src/orchestrated/targets.py (install roots, home variable and flag, manifest name, installer ID, product name) and content/targets.yaml (resource vocabulary and package metadata). The engine reads the active target at run time: each exported package's entry point, and main.py, activates one target and its rendered resources before running it.

Skills, agents, and the component registry live under content/ and are rendered into each harness's native format: Codex agent TOML files with openai.yaml skill metadata, and Claude Code agent and skill Markdown with frontmatter. content/targets.yaml holds each harness's vocabulary (model tiers, agent naming, invocation prefix, ask-the-user wording); sources reference it through Jinja placeholders such as {{ agents.tester }}, {{ product }}, and {{ invoke }}{{ skills.code_review }}. Use a {% if target == "codex" %} block only where the harnesses behave differently, not merely where they name things differently. Agent sources are Markdown with description, tier (deep, standard, or fast), effort, and read_only frontmatter and the instructions as the body; an optional model: mapping overrides the tier model per target.

Installable choices are defined in content/install-components.yaml.j2, rendered into each package's resources. Its component entries supply the checklist text, active state, optional dependencies, destination roots (config_home or skills), relative destinations, and resource sources, each a path relative to the packaged resources. Registry loading rejects unknown fields, unsafe paths, and duplicate source or destination mappings.

Inactive components that were never installed are hidden and excluded from unattended installs. If an installed component becomes inactive, the guided installer presents it as retired so the user can retain it or deselect it for safe removal. All destinations must remain under a supported installation root, and no file may be installed inside a directory that another resource installs as a whole.

Export and build the packages:

uv run scripts/export.py                      # writes build/orchestrated-codex and build/orchestrated-claude
uv build build/orchestrated-codex --out-dir dist/codex
uv build build/orchestrated-claude --out-dir dist/claude

Each exported package contains a pyproject.toml, this README, the engine, an entry point that activates its target, and its rendered resources. The Codex package installs module codex_orchestrator and command orchestrated-codex; the Claude Code package installs module claude_orchestrator and command orchestrated-claude. The root project, named orchestrated, is never published.

Both packages take their version, dependencies, and classifiers from the root pyproject.toml, so a release updates one version. A vX.Y.Z tag tests the codebase, exports and builds both packages, smoke-tests all four distributions, and publishes both to PyPI. Running the publish workflow manually performs the same checks, builds, and smoke tests without publishing.

Metadata

Release files for orchestrated-codex 0.2.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for orchestrated-codex 0.2.0
File Size Uploaded Provenance Actions
orchestrated_codex-0.2.0.tar.gz 34.3 kB With provenance Details for orchestrated_codex-0.2.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for orchestrated-codex 0.2.0
File Interpreter ABI Platform Actions
orchestrated_codex-0.2.0-py3-none-any.whl Python 3 none any Details for orchestrated_codex-0.2.0-py3-none-any.whl

Total release size: 83.0 kB

Release files / orchestrated_codex-0.2.0.tar.gz

Download URL orchestrated_codex-0.2.0.tar.gz
Size 34.3 kB
Tags Source
SHA-256 checksum
How to use checksums
d2c611b0651ae9010272988b71cbb78f49aba8c2f315f9734323f0e5c45a4bfd
BLAKE2b-256 checksum
How to use checksums
91203d67ed61cdc9aec9b191112b3ac02d43e28f74677b3673cfe63e6d772bad
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 13, 2026.

Transparency log

Release files / orchestrated_codex-0.2.0-py3-none-any.whl

Download URL orchestrated_codex-0.2.0-py3-none-any.whl
Size 48.7 kB
Tags Python 3
SHA-256 checksum
How to use checksums
8cd8851016428acef5e5cfad50b34d3852ebbb060ea1e1824ed3192cc6c89636
BLAKE2b-256 checksum
How to use checksums
b3b8175aa578e305cc080f1288ec12e34589690194d8e355d416790257052224
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 13, 2026.

Transparency log

Security for orchestrated-codex 0.2.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for orchestrated_codex-0.2.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 13, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page