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, componentcode-review): explicit-only review of a local diff or pull request, producing a comprehensive, prioritized, independently verifiedcode-review.mdreport without a minimum or maximum finding count.orchestrated-grill-me(skill, componentgrill-me): explicit-only interview that stress-tests a plan until every decision is settled.orchestrated-handoff(skill, componenthandoff): 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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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 logRelease 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 logSecurity 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.
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 logA 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.