claude-code-orchestration-template

# Claude Code Orchestration Template

> A drop-in orchestration layer for Claude Code: specialized subagents, a reusable delegation skill, and a short policy file that routes each task to the cheapest capable model, gates premium spend, and runs an independent diff review before merging code. Optionally pairs with the OpenAI Codex CLI for cross-family AI code review.

This repository is a template, not a runtime library: its "code" is a set of Markdown instruction files that configure how Claude Code delegates work, spends on models, and reviews diffs. There are no scripts, dependencies, hooks, or telemetry. Project-specific configuration (risk paths, build/test/lint commands, data boundaries) lives only in `CLAUDE.md`. English is the canonical language for all instruction files.

## Start here

- [README.md](README.md): what the template is, who it's for, install steps, and the design rationale.
- [docs/example-workflow.md](docs/example-workflow.md): a worked example of one task moving through spec, delegation, independent review, and merge.
- [CLAUDE.md](CLAUDE.md): the orchestration policy loaded every session - model routing, risk paths, review rules. The single source of truth for project-specific settings.
- [AGENTS.md](AGENTS.md): orientation for AI coding agents working on this repository.

## Agents

- [.claude/agents/fast-worker.md](.claude/agents/fast-worker.md): Sonnet. Executes mechanical, fully-specified tasks with the smallest safe diff. Read/write, scoped to allowed files.
- [.claude/agents/deep-reasoner.md](.claude/agents/deep-reasoner.md): Opus. One hard scoped question in, one decision-grade analysis out. Read-only.
- [.claude/agents/premium-reasoner.md](.claude/agents/premium-reasoner.md): top tier (Fable). The spend-gated escalation rung; refuses to run without a human-supplied `PREMIUM-APPROVED` token. Read-only.
- [.claude/agents/diff-reviewer.md](.claude/agents/diff-reviewer.md): Sonnet. Adversarial branch review before merge; diagnosis only, never edits. Read-only. The designated reviewer for Codex-authored diffs, and the final, local fallback when Codex is unavailable.

## Skills

- [.claude/skills/delegation-protocol/SKILL.md](.claude/skills/delegation-protocol/SKILL.md): the delegation mechanics - task-spec template, routing table, author-reviewer independence rules, and quota fallbacks. Loaded when delegating or reviewing.
- [.claude/skills/delegation-protocol/codex-review-transport.md](.claude/skills/delegation-protocol/codex-review-transport.md): skill §6, read on demand - how a Codex review is shipped (direct or inline-task), its deadline, the rollout check of model, effort and read-only profile, and the validation of each finding.
- [.claude/skills/delegation-protocol/grok-fallback-review.md](.claude/skills/delegation-protocol/grok-fallback-review.md): skill §7, read on demand - the optional Grok Build fallback review: readiness and consent, the disposable worktree, tool control, verification.
- [.claude/skills/x-search/SKILL.md](.claude/skills/x-search/SKILL.md): X (Twitter) search through the Grok Build CLI, because Claude's web tools cannot reach x.com - an empty working directory, web search and page fetch only, the user's request as consent, checks of every call and every quote against Grok's session record.

## Concepts

- [Model routing](CLAUDE.md): cheap models for volume, expensive models for leverage (planning and diff review), a different model family where independence matters.
- [Spend gates](.claude/agents/premium-reasoner.md): premium reasoning is refused unless a human adds the `PREMIUM-APPROVED` token; costs are disclosed at runtime rather than hardcoded, so the template never goes stale on prices. Every delegated report opens with a provenance line (agent, harness-resolved model when reported, effort) and carries harness-reported token usage when the runtime exposes it.
- [Review gates](.claude/skills/delegation-protocol/SKILL.md): an independent diff review (the author is never the reviewer) before merging behavioral changes; the exact self-merge threshold is defined here in the delegation-protocol skill.
- [Codex integration (optional)](README.md): routes review of Claude-authored diffs to the OpenAI Codex CLI (GPT-6.1 Sol; GPT-6 Astra for the risk-path adversarial pass) for cross-family validation; Codex-authored diffs go to the local `diff-reviewer` or a human instead; degrades cleanly when the plugin is absent - to Grok Build if that optional fallback is installed and the run is eligible (next item), else to `diff-reviewer`. Delivery goes through a configurable review transport: on native Windows, reviews ship as inline diffs over the read-only task path (`inline-task`), because the direct review commands hang there (July 2026; a verified per-machine fix exists as of August 2026). Reviews run at the highest allowed effort each path exposes - `max` pinnable per invocation only on the direct path, `xhigh` on inline-task (higher reachable by config inheritance); the `ultra` effort above `max` is automatic sub-agent delegation (Codex Ultra) and is excluded. The model, effort and read-only profile that actually ran are verified from the session rollout before a verdict is acted on.
- [Grok Build integration (optional)](README.md): a cross-family fallback for the standard review of Claude-authored diffs when the Codex route is unavailable - Grok reviews before the local `diff-reviewer`, from a disposable git worktree, only when the whole committed tree may go to xAI and - on native Windows, where its sandbox is not enforced - with the human's OK per run. The tools it was offered and called are checked against a read-only allowlist, and its session record (read-only profile, effort) plus a clean worktree `git status` and a working-tree `git status` matching its pre-dispatch snapshot are checked before the verdict is used - tripwires, not a sandbox. It never takes the risk-path adversarial pass, Codex-authored diffs or writing (verified October 2026 against plugin 0.2.1 / Grok Build CLI 1.0.52).
- [Gemini 4 Argon (evaluated, not adopted)](docs/specs/gemini-4-argon-reviewer.md): weighed as a third external reviewer in October 2026 and deferred - consumer-account data terms allow use for product improvement, Gemini CLI does not serve the model and no scriptable route through Antigravity's CLI is verified, and no calibration probe has run; the file lists the verified facts and the conditions to revisit.

## Optional

- [README.es.md](README.es.md): Spanish translation of the README (non-canonical; English wins on any discrepancy).
- [CONTRIBUTING.md](CONTRIBUTING.md): how to propose changes and translations.
- [SECURITY.md](SECURITY.md): data boundary and how to report issues.
- [CHANGELOG.md](CHANGELOG.md): version history.
- [LICENSE](LICENSE): MIT.