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

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

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 --codex-home /path/to/test-home
uv run python -m unittest discover -s tests

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.