AI Corporate

Corporate governance for Claude Code and Codex.

Run your AI agents like a company. Named employees, specialist routing, HR approval, disciplinary hooks, and capability-aligned roles.

---

Most agent frameworks advise. This one enforces.

A rule an agent can talk its way out of is not a rule. Discipline here lives in hooks the harness runs, not in prose the model can rationalise past:

• route-guard hard-denies an inline source edit and names the specialist to spawn
• the brief-quality gate denies an agent spawn whose prompt is incomplete
• anti-decay reinjection re-states the load-bearing rules every turn, because session-start rules decay by hour 2-3 on any model tier
• escape hatches can only be created by the user, from outside the session

Twenty sharp agent roles and four hooks for Claude Code, seven agents and four hooks for Codex. No dependencies in either.

Install

/plugin marketplace add karthiknl0/ai-corporate

Status: both plugin manifests pass claude plugin validate, but a clean-machine install has not yet been confirmed. Until it is, the manual path below is the supported one. See .claude-plugin/PLUGIN_SCHEMA_NOTES.md and docs/packaging-roadmap.md.

Manual install: Getting Started.

---

Why?

Multi-agent AI coding systems have a scaling problem. Once you move beyond a single assistant, you run into questions that software teams solved decades ago:

• Who handles what? Without routing rules, every agent tries to do everything — badly.
• Who's allowed to touch what? Without domain boundaries, two agents edit the same file and create merge conflicts or silent regressions.
• How do you assign work well? Sending every task to the same model ignores the distinct strengths of specialized roles.
• How do you enforce standards? Without pre-commit gates, agents skip documentation, ignore type errors, and bypass specialist knowledge.

AI Corporate treats these as organizational problems, not technical ones. It gives your agents job titles, reporting lines, domain ownership, and disciplinary enforcement — the same structures that make human engineering teams function.

This framework was battle-tested on a production ERP system with 47 AI agents across 3 model tiers before being extracted as a reusable package.

---

Key Features

Named Employee System

Every agent has a name, a role, and a model tier. No more agent-1 or helper-bot. Each employee has a definition file specifying their capabilities, tools, and constraints.

Claude Code employee definitions use Markdown:

agents/
  postgres-pro.md         # Priya (sonnet) — read-only DB specialist
  senior-engineer.md      # Vikram (opus) — cross-cutting architecture
  verifier.md             # Deepa (haiku) — build/test runner
  ...

Codex employee profiles use .codex/agents/*.toml. The shipped defaults use Codex-native model roles:

Codex model	Role	When to use
gpt-5.6-sol	Senior review	Architecture, data/security judgment, approval advice
gpt-5.6-terra	Implementation specialist	Bounded, complex implementation
gpt-5.6-luna	Worker	Mapping, verification, and documentation

Claude Code's Opus/Sonnet/Haiku tiers remain documented in the Claude package. Change a Codex profile's model only if your workspace does not offer the shipped model ID; do not rely on inheriting an arbitrary parent model.

Mandatory Specialist Routing

A routing table in CLAUDE.md (Claude Code) or AGENTS.md (Codex) maps triggers to the right specialist. The orchestrating agent must delegate — it cannot do the work inline.

| Trigger                  | Agent              |
|--------------------------|--------------------|
| DB query / schema change | postgres-pro       |
| Complex TS errors        | typescript-pro     |
| Security audit           | security-auditor   |
| React re-renders         | react-specialist   |

This prevents the generalist agent from attempting work it lacks context for. Claude Code's route-guard can hard-deny out-of-route writes; Codex hooks provide lifecycle context and routing reminders because its hook payload does not expose a reliable parent-versus-subagent identity.

Clarification Discipline

The user request is work to complete, not a framing to debate. Proceed with a stated, reasonable, reversible assumption whenever it does not materially change the result. Ask only when the answer changes scope, data, operational impact, safety, an irreversible action, or a required approval. Do not replace ordinary work with refusal speeches, lectures, or repeated non-blocking questions.

8 Pre-Commit Gates

A .githooks/pre-commit script runs 8 checks before any commit lands:

1. Docs pairing — code changes require matching documentation updates
2. Typecheck — staged TypeScript must pass the project's tsc config
3. Skill freshness — agent knowledge files must not have stale verification dates
4. Date-only bump block — prevents agents from faking skill verification by just updating a date
5. Code-map pairing — large files (1,500+ lines) must have a paired structural map
6. Code-map anchor check — structural anchors in maps must match actual source
7. Edge function check — Deno files must pass deno check
8. Test gate — enforced test coverage for changed modules

Claude Code Route-Guard Hook (v5 — hard deny, docs route too)

A PreToolUse hook intercepts file writes in real time — both Edit/Write tool calls AND shell writes (sed -i, redirects, tee, cp/mv, Set-Content, git apply/checkout/restore). If the orchestrator tries to write a specialist-domain source file, the hook denies the write and names the specialist to spawn.

Deny, not ask: an "ask" dialog gets habitually approved and the orchestrator learns nothing; a deny bounces the correction back to the model, which then spawns the specialist. This matters most for orchestrator roles, where rule compliance can decay under long-running work.

Genuine inline exceptions go through a user-only override file (.claude/ROUTE_OVERRIDE, one path per line, consumed one-shot) — the hook denies any in-session attempt to create or modify it, so only the human can grant the exception.

v5 — docs route too. The blanket "orchestrator may edit any .md" allowance is closed: docs/** routes to the docs worker, .agents/skills/** to the skill updater. Field observation: the "one-line doc edit is faster inline" carve-out got generalized into full multi-table doc rewrites by two different orchestrator models on the same day. Memory files and root CLAUDE.md remain orchestrator-editable.

Claude Code Brief-Guard Hook

A second PreToolUse hook validates every agent spawn prompt before it dispatches. The prompt must contain: the identity opener (You are **Name** (role, model)), the first-output identity instruction, a REPORT schema, a Done = stop condition, and — for write-capable agents — the destructive-git prohibition. Missing pieces are denied back to the orchestrator with the exact fix, and it re-spawns correctly — no user interruption.

Anti-Decay Reinjection

Claude Code's UserPromptSubmit hook re-injects the three load-bearing invariants (~50 tokens) on every user turn: route source edits to specialists, complete spawn briefs, prod changes need approval. The Codex package supplies equivalent SessionStart, SubagentStart, UserPromptSubmit, and source-edit reminder hooks where its lifecycle API supports them. Session-start rules decay from context by hour 2–3 on any model — just-in-time reinforcement beats a bigger rulebook at the top.

Auto-Escalation

When a Claude Code agent fails twice at a task, it automatically escalates to the next tier up:

haiku (fails) --> sonnet (fails) --> opus

Two strikes at a tier triggers mandatory escalation. This prevents repeated attempts on problems above the agent's capability.

Claude Code Domain Exclusion

File-level locking prevents two agents from editing the same domain simultaneously. When an agent claims a file, other agents are blocked until the lock is released. A utility script handles manual lock clearing when needed.

HR Recruitment

Every new employee proposal goes through an HR evaluation that checks:

• Does an existing agent already cover this domain?
• Is the proposed model tier appropriate for the work?
• Does the agent definition include clear boundaries and constraints?
• Is there a routing trigger that would actually invoke this agent?

This prevents agent sprawl — the tendency to create a new specialist for every minor sub-problem.

Role-Based Assignment

The Claude Code three-tier system assigns work by role and responsibility:

• Haiku handles grep sweeps, build verification, log monitoring, docs updates — anything mechanical and well-specified.
• Sonnet handles domain-specific implementation where the agent needs real expertise.
• Opus handles judgment calls, architecture decisions, and cross-cutting refactors where mistakes are difficult to reverse.

RTK (Rust Token Killer) is a CLI proxy that can compress tool outputs before they reach the model. AI Corporate's agent output discipline (R1–R19, see docs/agent-efficiency.md) complements this by keeping agent reports concise and structured.

Performance Tracking

A JSON-based performance log (agent-performance-log.json) records every subagent task — successes, failures, and violations. This enables:

• Accountability: Agents that ignore instructions or produce subpar output are logged with evidence.
• HR routing: Historical performance data informs which agent gets future tasks.
• Capability audits: Periodic reviews reveal agents that need retraining, tier changes, or retirement.

See Performance Tracking for the full system.

Mid-Task Communication (Claude Code)

Background agents can receive updated instructions via SendMessage while running. This is essential for correcting an agent's approach mid-task without killing and re-spawning. However, agents under token pressure may ignore mid-task corrections — the performance log catches this pattern.

Delegation Brief Discipline

The orchestrator follows a strict protocol for writing delegation prompts. Brief anatomy: one-sentence task + acceptance condition, file paths and line ranges (never file contents), hard constraints only, fixed report schema. Agents receive the minimum context they need to do the work — not a knowledge dump of everything the orchestrator knows.

A standard report schema is embedded in every implementation brief, forcing agents to produce checkable file:line evidence instead of prose:

VERDICT: <fixed | blocked | needs-decision>
ROOT CAUSE: file:line + ≤2 sentences
CHANGES: bullet list, file per line
EVIDENCE: ≤10 lines of output diff

See Writing Delegation Briefs for the full brief anatomy, tier selection table, escalation handoff template, and trust signals for verifying subagent output.

Agent Learning Methodology

Agents accumulate beliefs about the codebase across long sessions. Without discipline, these beliefs grow stale, get written into memory indiscriminately, or get silently swallowed mid-task when a discovery contradicts the brief.

AI Corporate defines a protocol for how agents should update their beliefs:

• Surprise filter: update only when the new information contradicts a prediction you would have made
• Effect-level verification: verify at the outcome, not at the claim — never trust a tool's self-report about its own gate
• Retention threshold: only write down what a competent engineer cannot rediscover in under a minute
• Worker 3-tier protocol: Tier 1 (act + state update in report) · Tier 2 (put LEARNED: in report, let orchestrator retain) · Tier 3 (stop and escalate — never reconcile contradictions silently)

See Learning Methodology for the full protocol.

Reasoning Discipline (Fable transfer)

Captured from Fable 5 (Anthropic's Mythos-class model) before its access window closed: nine problem-solving mechanics written as executable procedure — bet-before-look, most informative discriminating test, invariant-first debugging, one-level-deeper causality, altitude control, reversible/irreversible split, negative-space check, pre-mortem, declared stop conditions — plus per-tier application and an honest map of where the discipline itself fails (compliance decay, non-transferable taste, doc drift).

Every Claude Code agent definition carries its tier's slice: Opus seniors get the judgment mechanics, Sonnet specialists the debugging loop, Haiku workers surprise-reporting and schema-as-stop-condition. The Codex profiles use the equivalent Sol, Terra, and Luna role split.

See Reasoning Discipline.

The Orchestrator Turn Loop

The moment-to-moment algorithm that strings the components together: classify every message before acting (material question vs inline diff vs specialist route vs approval gate); for non-material ambiguity, state a reversible assumption and proceed. Then run the dispatch beat (commit → brief with an in-head bet → fan-out in one block → "I'm free"), the integration beat (compare report to bet; a surprise means the brief was wrong), and the closeout beat (verify at the effect, docs in the same commit, negative-space pass).

Concise reporting falls out of the loop: orchestrator context grows by ≤250-word reports instead of files, and the most severe failure — acting past an unprocessed surprise — is structurally blocked.

See The Orchestrator Turn Loop — includes verbatim mini-briefs at calibrated lengths.

Claude Code Installable Skills (.claude/skills/)

The docs/ set is reading material; the skills are the load-on-demand form a live Claude Code session actually triggers on. Two ship with the framework:

• fable-orchestration — the whole orchestration discipline (turn loop, brief anatomy, tier selection, report schemas, escalation, reasoning mechanics, learning protocol) as one session-loadable skill. Copy it to ~/.claude/skills/ to get it in every project, or keep it per-repo.
• skill-library-bootstrap — how to build a project's skill library so worker models can carry it: gap-analysis before authoring (the taxonomy is a menu, not a mandate), a ≤5-question discovery phase, ground-truth authoring rules, a 3-reviewer pipeline, and model-transfer evals. Sized honestly: greenfield repos get 3–5 skills, not 16.

Skills and docs share one-home-per-fact: docs hold depth, skills hold the operational form.

Codex uses AGENTS.md for durable repository guidance and .codex/agents/*.toml for employee profiles. Its reusable skills live in the user's .agents/skills directory or the installing project's .agents/skills; do not copy Claude's .claude/skills directory into Codex as though it were a Codex configuration layer.

Corporate Org Chart

An interactive HTML visualization (org-chart.html) renders the full workforce hierarchy — tiers, roles, domain ownership, and reporting lines. Useful for onboarding and for auditing agent coverage gaps.

---

Tool Output Discipline with RTK

AI Corporate controls agent output tokens (what agents write back). RTK can compress tool output input (what CLI tools pipe into the model) as a separate layer.

Install RTK alongside this framework when its hook-level tool-output compression fits your Claude Code workflow:

cargo install rtk
# Then run Claude Code — RTK rewrites git/grep/bash output transparently via hook
rtk gain   # view tool-output statistics

See docs/agent-efficiency.md for the full R1–R19 output discipline rules and how both tools complement each other.

RTK's transparent hook-level integration is documented here for Claude Code. Codex users should enable RTK only where their local Codex setup supports it; AI Corporate's Codex package does not claim to install or configure RTK automatically.

---

Response Verbosity Control with Caveman

RTK (above) compresses tool output input — what CLI commands pipe back into the model. Caveman is a complementary, separate layer: it compresses agent output itself, rewriting responses in terse, fragment-heavy phrasing (~65% fewer output tokens in the maintainer's own benchmarks) while keeping code, commands, and error text byte-exact.

It is not a proxy and does not route any traffic — it's a skill/instruction set the agent reads, so it fits AI Corporate's "enforce, don't advise" model as an optional add-on, not infrastructure sitting between you and the model.

Vendored in this repo: .claude/skills/caveman/SKILL.md ships with AI Corporate — copying .claude/skills/ into your project (see Getting Started) brings Caveman along with fable-orchestration and skill-library-bootstrap. No separate install needed for Claude Code to pick it up. The vendored copy is the upstream skill definition as of 2026-07-13; it's not auto-updated, so check the upstream repo for newer versions.

For the full upstream toolkit (extra slash-commands like /caveman-commit, /caveman-review, /caveman-stats, and the Codex integration), install directly from upstream:

Claude Code (global, user-scoped plugin — full toolkit, not just the skill):

claude plugin marketplace add JuliusBrussee/caveman
claude plugin install caveman@caveman

Codex:

npx skills add JuliusBrussee/caveman -a codex

Run from your home directory for a global/user-level install, or from inside a specific repo to scope it there — the installer detects the working directory it's run from.

Activation: whether vendored or installed from upstream, this is a manual per-session toggle — /caveman (defaults to full) or /caveman lite for a lighter touch. There is no persistent default-intensity setting; say "normal mode" to turn it off.

See docs/agent-efficiency.md for how this fits alongside RTK's tool-output compression and AI Corporate's own R1–R19 output discipline rules — the three layers cover different token classes (tool-output input, agent-response output, and behavioral discipline) rather than overlapping.

---

Getting Started

1. Clone the repo

git clone https://github.com/your-org/ai-corporate.git

2. Copy the framework into your project

# Claude Code
cp -r ai-corporate/.claude/ your-project/.claude/
cp ai-corporate/CLAUDE.md your-project/CLAUDE.md

# Codex
cp -r ai-corporate/.codex/ your-project/.codex/
cp ai-corporate/AGENTS.md your-project/AGENTS.md

# Shared Git quality gates
cp -r ai-corporate/.githooks/ your-project/.githooks/

If the target already has CLAUDE.md, AGENTS.md, .claude/, or .codex/, merge the template deliberately rather than overwriting project-specific rules.

3. Configure git hooks

cd your-project
git config core.hooksPath .githooks
chmod +x .githooks/pre-commit

4. Customize agent definitions

For Claude Code, edit .claude/agents/. For Codex, edit .codex/agents/. Both packages provide named, scoped employee profiles; keep their responsibilities aligned with your project's domains.

• Name, role, and model tier
• Tools the agent is allowed to use
• Domain boundaries (what files/systems it owns)
• Constraints and safety gates

5. Update the routing table

Edit CLAUDE.md for Claude Code and AGENTS.md for Codex to map your project's file structure and domains to the appropriate specialists. The routing table is the core of the system — it determines which agent handles which trigger.

For Codex, open /hooks after copying .codex/, review the project-local hook definitions, trust them, then start a new task. Project hooks are skipped until trusted.

6. Configure pre-commit gates

Edit .githooks/pre-commit to enable or disable gates based on your project's needs. Not every project needs all 8 gates — start with docs pairing and typecheck, then add more as your agent workforce matures.

---

How the System Works

AI Corporate routes every task to the configured role that best fits it. The bundled runtime mappings are intentionally separate:

Runtime	Senior / review	Specialist / implementation	Worker
Claude Code	Opus	Sonnet	Haiku
Codex	gpt-5.6-sol	gpt-5.6-terra	gpt-5.6-luna

Use the same role split for Codex and configure the model IDs available in your workspace.

For the Claude Code operational methodology, see How It Works -- covering parallel execution, the orchestrator pattern, agent lifecycle, and the pre-commit gate pipeline. Codex setup and hook behavior are documented in Migration Guide.

Claude Code Session Example: Parallel Execution Flow

When a user requests a new feature, the system executes in parallel rather than sequentially:

User: "Add an inventory report with API endpoint"

1. Orchestrator reads routing table, spawns Planner (opus)
2. Planner returns sub-tasks:
   - DB query (postgres specialist)
   - Report component (frontend specialist)
   - Edge function (edge-fn specialist)
   - Tests (QA engineer)
   - Docs (docs scribe)

3. Orchestrator spawns in parallel (all background):
   +-- Postgres specialist (sonnet) --> writes query
   +-- QA engineer (sonnet)         --> writes tests
   +-- Docs scribe (haiku)          --> prepares doc updates
   |
   (orchestrator stays free for other work)
   |
4. Sequential follow-ups (depend on DB output):
   +-- Frontend specialist (sonnet) --> builds component
   +-- Edge-fn specialist (sonnet)  --> implements endpoint

5. Orchestrator verifies: build + typecheck + tests + deno check
6. Commits code + docs together (pre-commit gates enforce pairing)
7. Deploys after user approval (safety gate)
8. Skill-updater audits agent knowledge (same commit)

The orchestrator never does specialist work inline. It coordinates, verifies, and holds all approval gates. Specialists report back; the orchestrator decides.

---

Directory Structure

.claude/
  agents/                          # Employee definitions (one .md per agent)
    postgres-pro.md
    typescript-pro.md
    senior-engineer.md
    verifier.md
    ...
  hooks/
    route-guard.mjs                # Specialist routing enforcement
    clear-domain-locks.mjs         # Manual lock clearing utility
  memory/                          # Persistent memory across sessions
  org-chart.html                   # Interactive workforce visualization
  settings.json                    # Hook registration + permissions

.codex/
  agents/                          # Named Codex subagent profiles (.toml)
    corporate_architect.toml
    implementation_specialist.toml
    verifier.toml
    ...
  hooks/                           # Codex lifecycle context and routing reminders
  hooks.json                       # Codex hook registration
  config.toml                      # Project-level Codex agent settings

.githooks/
  pre-commit                       # 8-gate enforcement hook

CLAUDE.md                          # Master rules file
                                   #   - Routing table (trigger -> agent)
                                   #   - Pre-commit gate definitions
                                   #   - Safety policies
                                   #   - Model-role guidelines
AGENTS.md                          # Codex-native routing and safety guidance

---

Battle-Tested Stats

This framework was extracted from a production deployment where it managed:

• 49 employees across 3 model tiers
• 8 pre-commit gates enforced on every commit
• 3 governance hooks (route-guard, db-write-guard, read-skill-reminder)
• 247 enforced tests gated by pre-commit
• Performance log tracking every agent task with violation accountability
• 13 deliverables completed in the first full governance session

---

Design Principles

Agents are employees, not tools. They have names, roles, boundaries, and accountability. This is not metaphorical — the naming and role structure changes how the orchestrator reasons about delegation.

Enforce, don't advise. Every rule that matters is hook-enforced. Advisory guidelines get ignored under token pressure. If a rule is worth having, it is worth blocking commits over.

Capability-aligned roles. Every task should run with the role that matches its scope: Claude Code uses Opus/Sonnet/Haiku; the bundled Codex profiles use Sol/Terra/Luna.

Documentation is not optional. Code changes without matching docs updates are rejected at pre-commit. Agents cannot skip this step.

Specialists own domains. A generalist agent that "knows a little about everything" produces worse results than a specialist that knows its domain deeply. The routing table makes this structural, not aspirational.

---

Adapting to Your Project

AI Corporate is domain-agnostic. The framework provides the governance structure; you provide the domain knowledge. To adapt it:

1. Define your domains. What are the major areas of your codebase? Database, frontend, API, infrastructure, testing?

2. Staff accordingly. Create one specialist agent per domain. Start small — 5-10 agents is plenty for most projects. You can always recruit more through the HR process.

3. Set your routing table. Map file patterns and task triggers to specialists. Be specific: *.sql files go to the database specialist, *.test.* files go to the QA agent.

4. Choose your gates. Enable the pre-commit gates that match your workflow. Docs pairing and typecheck are good defaults.

5. Assign model roles. Assign the worker model to mechanical work (verification, formatting, grep), the specialist model to bounded implementation, and the senior/review model to decisions with broad or hard-to-reverse impact. For the shipped Codex profiles this is Luna, Terra, and Sol respectively.

---

Contributing

Contributions are welcome. If you have governance patterns that worked well in your multi-agent setup, open a PR.

Areas of particular interest:

• Additional pre-commit gates
• Alternative escalation strategies
• Cross-agent communication patterns
• Metrics and observability for agent performance

---

License

MIT

---

Credits

Built by Karthik Nataraj for your project ERP, extracted as a reusable framework for governing AI coding agent workforces.

Complementary tools referenced in this README (not part of AI Corporate, credited to their own maintainers):

• RTK — tool-output compression, by reachingforthejack.
• Caveman — agent response verbosity control, by Julius Brussee.