Metadata-Version: 2.3
Name: orchestrated-claude
Version: 0.2.0
Summary: Install Claude Code delivery and code-review skills with focused custom agents.
Keywords: claude,claude-code,orchestration,developer-tools
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Requires-Dist: prompt-toolkit>=3.0.52,<4
Requires-Dist: pyyaml>=6.0.3,<7
Requires-Dist: questionary>=2.1.1,<3
Requires-Python: >=3.11
Description-Content-Type: text/markdown

# 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`](https://pypi.org/project/orchestrated-codex/) | `$orchestrated-delivery` |
| Claude Code | [`orchestrated-claude`](https://pypi.org/project/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](https://docs.astral.sh/uv/), using the package for your harness:

```sh
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`:

```sh
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:

```sh
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:

```text
$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:

```sh
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:

```sh
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:

```sh
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.
