agent-org

A CEO and a team of specialist agents for any repo, with autonomy earned on evidence.

agent-org is a Claude Code plugin. /org-init reads your codebase and generates an org fitted to it: agents that own real parts of your code, agents that only check, a CEO skill that runs them, and the guards, memory and evals that let the org earn more autonomy over time.

It is distilled from four production agent orgs: a 19k-entry web directory, an AI travel app, a photo-sharing app, and a chart library. The core idea, in one line: autonomy comes from verification, constraints, evals and orchestration, not from better prompts.

Install

As a Claude Code plugin:

/plugin marketplace add BbekShr/agent-org
/plugin install agent-org@agent-org

Without the plugin system, clone the repository and run ./install.sh. It copies the four skills (org-init, org-doctor, org-eval, org-feedback) into ~/.claude/skills.

Your first run

In the project you want an org for:

/org-init

/org-init works in phases. It reads the repo with four parallel scouts (stack and commands, architecture and code areas, risk surface, conventions and history), runs your existing checks once to set a baseline, and audits which of your rules are enforced by code and which only by prose. It asks you up to four questions (north star, org size, the autonomy you are aiming for, optional modes), shows the design, and generates everything on a branch. It never pushes without asking.

Then start read-only:

/<project>-ceo audit

The audit writes a board report and changes nothing. When you are ready for fixes, run /<project>-ceo (a light run: the top 1 to 3 items, behind a PR).

Adopt an existing org

If the repo already has a hand-built CEO skill and agents, use /org-init adopt. It keeps your content (agents, backlog, learnings, reports) and adds only what is missing: org.json, the trust curve with a level backfilled from your real PR history, the scorecard, the guard, a verify skill, playbooks and eval cases. For each existing file it proposes the gaps as small, separate edits.

Adopt also checks that it will not break how you already work. On photobari it found that the maintainer's own sessions regularly merge PRs and push to main, so the guard's merge and push blocks were scoped to org runs only.

The team

The team is staffed from your repo's real structure. Every finding gets exactly one owner, and only builders can change code.

Size scales the team: a small repo gets about 4 agents, a standard one 8 to 10, a large or high-stakes one more. Choosing a mode adds its role: discover adds a bug hunter, e2e an app explorer. Read-only agents carry no edit tools, and /org-doctor fails if one does.

The security engineer

Every org has one. It audits secrets, authentication and authorization, injection, data exposure, abuse limits and dependencies, tailored to the project's kind: a web app's checklist (roles, cross-user access, rate limits) is replaced with subprocess, prompt-injection and update-channel checks for a local CLI. It runs in every assess pass and on any diff that touches the security surface.

The run cycle

1. Preflight. Kill switch, clean tree, autonomy level, open PRs (no duplicate work), scorecard update, org self-check.
2. Assess. Report-only specialists in parallel.
3. Decide. Re-verify each finding at its file:line, rank by the objective function, cap a light run at 1 to 3 fixes.
4. Build. The owning editor, with the playbook for that kind of change and a proving test, on a branch. Hard items get a read-only plan from the top model first.
5. Review and gate. Adversarial reviewers (one per lens) and the release manager run together while the tree is frozen. The CEO's own design decisions are named as claims to attack. A diff that changes after verification is verified again.
6. Records, then PR. Facts, lessons, the scorecard and a one-line retro, then the PR.

The trust curve

An org starts at L0 if its checks cannot prove a change correct, otherwise at L1, never higher. The CEO proposes a promotion when the scorecard meets the criteria (for L1 to L2: at least 5 runs, 80% of PRs landed without human edits, no reverts, no escaped defects). Only you raise the level, in org.json. A revert or an escaped defect drops it one level automatically.

The guard

.claude/hooks/org_guard.py is a small, dependency-free hook that runs before Bash commands and file edits.

• Always blocked: gh pr merge --admin, force pushes without a lease, --no-verify, and edits to gate config files.
• Blocked only during an org run: merging below L3, pushing to the base branch, and git stash (the stash is shared by every worktree, and a stash mid-run once removed an agent's work from under it).

A run is active while the CEO's marker file exists (it expires after 12 hours) or when AGENT_ORG_RUN=1 is set for headless runs. Your own sessions are never bound by the org's level. A change that genuinely needs to strengthen a gate goes through you: you allow it for one run with touch .claude/ceo/ALLOW_GATE_EDITS.

Memory

Every backlog item is a claim about code, and claims decay, so items are re-verified before a run acts on them. Only the short ## Active list of lessons enters agent briefs; older lessons move to an archive instead of being deleted.

Skills and playbooks

The org takes its taste and judgment from skills you already have installed, not from prose in its own files. /org-init wires each relevant skill to the roles that need it, by exact installed name, with a fallback for environments where it is missing: for example ponytail for every editor, a taste skill for the frontend editor and design critic, your framework's best-practices skills for the matching editor.

Seven playbooks (bug fix, perf, feature, refactor, security, upgrade, test gap) say how each kind of change is done well in this repo. The CEO names one in every brief. If Pstack is installed, the playbooks become thin project adapters on top of it.

A generated /<project>-verify skill is the org's runtime eyes and hands: how to set up, start, drive and inspect the real software (traces, heap snapshots, screenshots at each required width), so agents prove their own changes instead of a person relaying what happened.

Evals

/org-eval treats agents like code under test. Each case pins a commit, a neutral task and a rubric. The agent runs in a throwaway worktree with the current org laid over it, and a different model scores the result.

/org-eval                    # every case
/org-eval <agent>            # one agent
/org-eval <agent> --blind    # without the org's lessons
/org-eval mine               # draft cases from past fix commits

The best cases come free from history: check out the commit before a real fix and see whether the agent finds the bug. When a case comes from a bug the org has since learned from, the normal run is a regression test and --blind measures the agent itself. Report both.

Feedback

At each run's retro the CEO sorts friction into local (fixed in the project) and template (would happen in any org). Template findings go to .claude/ceo/upstream.md, a local file that never leaves your machine on its own.

Feedback is opt-in: set "feedback": {"enabled": true} in org.json, or say yes when /org-init asks. Then /org-feedback re-checks each finding against the current templates, merges duplicates, strips project names, paths, code and data, and drafts an issue (or a tested PR if you maintain agent-org). Nothing is posted until you approve the drafts.

Commands

Generated files

CLAUDE.md                         + a 4-line pointer (skipped if it ships to end users)
.claude/
  agents/<slug>-*.md              the team
  skills/<slug>-ceo/SKILL.md      the orchestrator
  skills/<slug>-verify/SKILL.md   runtime eyes and hands
  hooks/org_guard.py              the guard
  settings.json                   hooks merged in, existing settings kept
  ceo/
    org.json  RULES.md  backlog.md
    memory/  learnings/  playbooks/  evals/
    upstream.md                   template findings (local unless you opt in)
    PRINCIPLES.md  AUTONOMY.md
    bin/org_doctor.py

org.json

The machine-readable org: what the doctor checks and the guard reads.

{
  "project": "Photobari",
  "slug": "photobari",
  "autonomy_level": "L1",
  "autonomy_target": "L2",
  "gates": [{ "name": "typecheck", "cmd": "npm run typecheck", "cheap": true }],
  "protected_paths": ["CLAUDE.md", ".github/workflows/**", "drizzle/**"],
  "agents": [{ "name": "photobari-frontend-engineer", "access": "editor",
               "perimeter": ["src/app/**", "src/components/**"], "except": ["src/app/api/**"] }],
  "skills": { "ponytail": { "agents": ["photobari-frontend-engineer"],
                            "when": "before writing code", "fallback": "apply RULES.md" } },
  "feedback": { "enabled": false, "upstream": "BbekShr/agent-org" }
}

FAQ

Does it merge or deploy on its own?

Not until you raise the org to L3, and never to a protected path. It never deploys to production or runs production migrations at any level.

Will it change my CLAUDE.md?

It appends a 4-line pointer, and skips even that if your CLAUDE.md ships to end users. The org's own rules live in .claude/ceo/RULES.md.

What does it need to run?

Claude Code, git, and Python 3 for the guard and the doctor (standard library only). gh is used for PRs when it is available.

Why start so restricted?

Because trust is earned on this codebase with these agents. The early runs build tests, bans and evals; throughput compounds once the org has earned L2 and L3.