ceo-orchestration

Português: README.pt-BR.md

A governance and auditability layer for running Claude Code as a structured team of specialist agents — installed into an existing repository, not run as a service.

Status: maintained personal-use framework — bus-factor 1, no roadmap commitments; the public repo is a stable snapshot, not an actively-staffed product. There is no public community, contributor base, or external adopter to speak of — just the framework and its tests.

The premise is narrow and deliberate: an LLM coding agent is most dangerous not when it writes bad code, but when it makes an unreviewed, unrecorded, irreversible change to a repository you care about. ceo-orchestration puts a gate and a ledger in front of that moment.

Who it's for: a solo maintainer or small team running Claude Code on a repository they care about, who want governance and an audit trail over their agent's changes — not speed. If that isn't you, this will mostly feel like friction.

No speed claim

Six internal experiments found no general speedup from this orchestration over an optimized solo Claude Code session. The value here is governance and auditability — properties that are orthogonal to velocity. We say so at the top rather than dress it up. If you are shopping for "make my agent faster," this is the wrong tool.

What it does give you:

• A Plan → Debate → Execute gate for risky changes, so an agent cannot silently rewrite protected files.
• A tamper-evident audit log (HMAC-chained) of every agent spawn (the CEO launching a subagent), edit, and ceremony — so you can detect after the fact whether the recorded history was altered.
• A cross-model review rail: a second LLM (Codex) reviews Claude's edits to protected paths before they land.
• A catalog of ready-made skill checklists an agent loads on demand instead of improvising.

How it works

When installed, the framework registers a set of Claude Code hooks that intercept tool calls (spawning agents, editing files, running shell commands) and apply policy before the action happens.

1. The CEO protocol. Work is framed as a "CEO" delegating to specialist agents — that framing is where the name ceo-orchestration comes from. The session acts as a CEO that decides what needs doing and delegates each piece to a purpose-built agent (a security reviewer, an onboarding guide, a debate persona), rather than doing everything in one undifferentiated thread. Routine edits proceed directly. Cross-cutting or risky changes are gated: they require a recorded plan, and for the riskiest class, a structured multi-round debate among agent personas before execution. The protocol is a written contract (PROTOCOL.md), enforced mechanically by hooks rather than by convention.

2. Tamper-evident audit log. Every governed event appends one JSONL line to a local audit log, each entry HMAC-chained to the previous one. A verify_chain() routine walks the log and reports the first break. This detects tampering — a removed or edited entry breaks the chain — but it does not prove the absence of tampering, and it is a local control, not a notarization service. Treat it as an integrity tripwire, not a court exhibit.

3. Cross-model pair-rail. When an agent tries to edit a canonical (protected) path, a hook routes the proposed change to a second model for read-only review. If that reviewer returns anything write-shaped, the edit is blocked. The honest caveat: the default reviewer is another large language model, and same-class reviewers share blind spots (see Risks).

4. Skill checklists. The framework ships 151 skill files — reusable, domain-specific checklists (security review, audit fan-out, onboarding to an unfamiliar codebase, and so on) that an agent loads when relevant instead of reinventing the steps each time.

What's in the box

All counts below are verifiable from a clean checkout (see Verifying the numbers).

| Component | Count | Notes | |---|---|---| | Skill checklists | 151 | 42 core + 8 frontend + 101 domain | | Hook scripts (on disk) | 53 | Python entrypoints under .claude/hooks/ | | Hooks wired in settings.json | 44 | distinct scripts, 46 event registrations | | Shared library modules | 67 | stdlib-only, under .claude/hooks/_lib/ (excluding the package __init__.py) | | Slash commands | 22 | under .claude/commands/ | | Architecture decision records | 171 | under .claude/adr/ | | Tests | ~12,000 cases | reported by pytest --collect-only across the hook, script, and conformance suites |

The gap between 53 on disk and 44 wired is benign: several non-event modules are activated through in-process dispatch (invoked by other hooks) rather than by a direct settings.json event registration.

Runtime dependencies: none. Hooks and scripts are Python ≥ 3.9, standard library only — zero third-party runtime packages. See SBOM.md. (Development and CI use third-party test tooling such as pytest; the installed runtime does not.)

There is also a published compliance contract under SPEC/v1/ (32 files — 28 *.schema.md plus contract docs, version-pinned), a TLA+ specification of the core circuit-breaker state machine, a conformance harness, and a local read-only audit dashboard.

Quick start

Prerequisites: Python ≥ 3.9, Git, and Bash. On macOS the system Bash is 3.2; install a modern one with brew install bash before installing.

# 1. Clone the framework somewhere outside your project
git clone https://github.com/Canhada-Labs/ceo-orchestration.git
cd ceo-orchestration

# 2. Install it INTO your target repository
./scripts/install.sh /path/to/your-app

# 3. From inside your project, confirm the governance layer is live
cd /path/to/your-app
bash .claude/scripts/validate-governance.sh   # prints an error count; 0 = healthy

Install paths. The clone-and-install.sh flow above is the supported path today. A one-step npm shim is also available — npx ceo-orchestration /path/to/your-app (published to npm with SLSA 3 provenance).

By default the installer copies the core and frontend skill profiles and the governance hooks. Select profiles and stack hooks explicitly:

./scripts/install.sh /path/to/your-app --profile core,frontend,fintech --stack node

Two install modes:

• --ceremony maintainer (default): full governance, including signed-edit ceremonies on protected paths.
• --ceremony user: advisory hooks only, no signing — writes only under .claude/. Good for a low-friction trial.

To verify the safety guards actually block what they claim, run the in-process self-test (hermetic, no network, no cost):

# from inside your installed project, in Claude Code
/self-test

To remove the framework cleanly:

/path/to/ceo-orchestration/scripts/uninstall.sh /path/to/your-app

Verifying the numbers

Don't take the table on faith. From a clean checkout:

find .claude/skills -name SKILL.md | wc -l        # 151 skills
ls .claude/commands/*.md | wc -l                  # 22 slash commands
ls .claude/adr | grep -c '^ADR-'                  # 171 ADRs
python3 -m pytest --collect-only -q | tail -1     # ~12,000 collected cases

Risks and what this is not

Intellectual honesty is the point, so the caveats are first-class:

• Bus factor of one. This is built and maintained by a single maintainer. There is no team behind it, no SLA, and no guarantee of continuity. Evaluate it accordingly.
• Same-vendor reviewer caveat. The cross-model pair-rail reduces single-model blind spots, but the reviewer is still a large language model and can share failure modes with the model under review. It is defense-in-depth, not an independent oracle.
• Codex is not bundled — the pair-rail is inert until you install it. The cross-model review rail invokes the Codex CLI, which is not shipped with this framework. On a fresh install with no Codex present, the pair-rail fails open and contributes zero review — protected-path edits still pass the GPG ceremony, but no second model looks at them. You only get the cross-model rung after installing Codex separately. See docs/HONEST-LIMITATIONS.md and ADR-145.
• Per-edit overhead. Each governed tool call runs the hook chain before the action lands, adding roughly ~0.3–1.0s of latency per edit on typical hardware. That is the cost of the gate; if you want zero overhead on routine work, the governance layer is not free.
• A gate can be wrong — there is an escape hatch. Hooks fail open on their own infrastructure bugs, but a correct gate can still issue a DENY you disagree with (a false block on a protected path). The intended path is /architect (which routes the change through review) or, for a structural framework change, a PLAN-NNN with an Owner-signed sentinel (a GPG-signed approval record that authorizes a specific protected-path edit). For a deliberate, audited override of the canonical-edit gate, the Owner can set CEO_SENTINEL_UNLOCK=<plan-id> + CEO_SENTINEL_UNLOCK_ACK=I-ACCEPT for that action — the override itself is logged. Kernel-path hard-denies (an unconditional block on the most safety-critical files, which no sentinel can lift) need the stronger CEO_KERNEL_OVERRIDE ceremony. See docs/TROUBLESHOOTING.md. To trial the framework without any of this friction, install with --ceremony user (advisory hooks, no signing).
• Detection, not prevention, on the audit chain. The HMAC chain tells you that the recorded log was altered; it cannot prevent an attacker with local write access from doing damage, and it is not a substitute for proper access controls or backups.
• Formal verification is scoped, not universal. A TLA+ specification exists for the core state machine, but model-checking is not part of the enforcing CI gate — do not read "has a TLA+ spec" as "formally verified." The overwhelming majority of behavior is covered by conventional tests, not mechanized proof.
• It is a framework, not a product. No UI, no managed runtime, no "operating system." It installs into your repo and gets out of the way.
• No speed benefit. Restated because it matters: this will not make your agent faster.

Alternatives worth comparing if multi-agent orchestration (rather than governance) is your goal: AutoGen, MetaGPT, and LangGraph. Those optimize for agent collaboration and workflow expressiveness; this project optimizes for gating and auditing a single capable agent's changes to a real repository.

Learn more

New here? Start with these:

• docs/FAQ.md — the first-user FAQ: what this is (and is not), "a hook just blocked my edit, now what?", does it slow me down, do I need Codex, what gets sent anywhere, how to uninstall.
• docs/QUICKSTART.md — install into a repo and confirm the governance layer is live.
• docs/DAY-1-CHECKLIST.md — a guided first session.

Then the reference material:

• PROTOCOL.md — the governance contract (Plan → Debate → Execute, vetoes, the three-strike rule).
• docs/ARCHITECTURE.md — component map and data flow.
• docs/HONEST-LIMITATIONS.md — the long-form version of the Risks section.
• SBOM.md — dependency inventory.
• docs/GLOSSARY.md — term dictionary: definitions for sentinel, kernel hard-deny, spawn, and the rest of the vocabulary used here.
• SPEC/v1/ — the published compliance contract.

License

See LICENSE.