orchestrated-codex

A standalone collection of Codex-native software delivery skills. It installs a reusable orchestration workflow, an explicit code-review workflow, and focused custom agents so Codex can follow a structured process for discovery, planning, independent plan review, implementation, testing, and final review. The delivery skill instructs the primary Codex thread 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.

Installation

Install with uv:

uvx orchestrated-codex --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:

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

For CI or other unattended installs, explicitly install everything or name a comma-separated component set:

uvx orchestrated-codex --install --all
uvx orchestrated-codex --install --components code-review

Named component installs automatically include dependencies declared by the component registry. A plain --install requires an interactive terminal.

Restart Codex or start a new conversation after installation. Invoke either workflow explicitly; Codex will not select them automatically based on the request:

$orchestrated-delivery implement this feature
$code-review review the current changes

$code-review 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.

The installer writes to two independent roots:

• The skills install under $HOME/.agents/skills, a documented Codex skills root, so Codex discovers them.
• The agents install under the Codex home — CODEX_HOME when it is set and ~/.codex otherwise — as agents/*.toml.

Use --codex-home PATH to target another Codex home for the agents; the skill always resolves under $HOME/.agents/skills.

Uninstall

Remove the installed files with:

uvx orchestrated-codex --uninstall

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

Installed components

• orchestrated-delivery (skill): task classification and an adaptive discovery, planning, independent plan review, implementation, testing, and final-review workflow. Installs under $HOME/.agents/skills.
• code-review (skill): 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.
• agents/discovery.toml: read-only codebase reconnaissance.
• agents/spec-designer.toml: requirements and technical design.
• agents/rubber-duck.toml: independent PRD peer review (PASS/CONCERNS).
• agents/ui-designer.toml: visual design specification for substantial UI work.
• agents/tester.toml: authors and runs tests and verifies requirements (PASS/FAIL).
• agents/final-reviewer.toml: read-only holistic final review.

Implementation is delegated to Codex's built-in worker. The primary Codex thread orchestrates the workflow and does not implement work itself. Independent delegations use fresh context by default and the orchestrator avoids short polling loops while waiting for subagent results.

Development

Run from a checkout and execute the tests:

uv run main.py --install --all --codex-home /path/to/test-home
uv run python -m unittest discover -s tests

Installable choices are defined in src/codex_orchestrator/resources/install-components.yaml. Each entry supplies the text shown by the installer, its active state, component dependencies, packaged sources, destination roots, and relative destination paths. Add new choices there rather than hard-coding them in the CLI. 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. Registry paths must remain relative to the packaged resources and one of the supported installation roots.

Build the wheel and source distribution and inspect them:

uv build

The PyPI distribution and command are both named orchestrated-codex. The importable Python module remains codex_orchestrator for compatibility.