Handler

Handler is an autonomous multi-agent orchestration harness for Claude Code. It turns a generic agent into a verification-first "top-1% operator": you hand it a blueprint (or a plain-language wish), and it plans the work, dispatches a fleet of fresh-context worker subagents, supervises them, verifies the result with reviewers that never wrote the code, and ships — deciding and logging along the way instead of stopping to ask you.

It is a set of doctrine documents, a machine-readable policy, a few playbooks, and a small self-learning engine. There is no framework to install and no service to run — Handler is prompt-and-policy IP that a Claude Code session loads and follows.

What it is

The core idea is that an agent's results are bounded less by the model and more by how it is driven: plan quality, context hygiene, and — above all — verification. Handler encodes that as an explicit operating loop with hard rules:

• Plan before building. Every job opens with a four-field Intent block (goal, non_goals, constraints, success_criteria) and binary acceptance criteria, each with the exact check that proves it. No check, no criterion.
• Writer is never the reviewer. The agent that writes a slice never verifies it. Review is routed to a fresh-context agent, and a deterministic gate (tests / build / lint / typecheck) always runs before any LLM judgment.
• Decide and log, don't interrupt. The orchestrator makes the ship / wait / redo call itself and records it. It only pauses for a short, hard list of irreversible actions (force-push over history, hard reset of uncommitted work, writes to a protected branch, deleting real data, spending money).
• Difficulty-aware routing. Work is tiered easy / mid / hard, and both the model and the reviewer fleet scale to the tier — cheaper models and a single neutral reviewer for routine work, the strongest model and a full adversarial fleet for hard, cross-cutting, or security-sensitive changes.

How it works

The run is a six-phase loop: PLAN → DISPATCH → SUPERVISE → VERIFY → DECIDE → SHIP. Each phase has a dedicated document:

• DOCTRINE.md — the principles the whole harness is built on, distilled and ranked by how many independent practitioners converge on them.
• DESIGN.md — the architecture: the cast of roles, the flow, the autonomy policy, and how the loop survives usage limits and long runs.
• SUPERVISOR.md — the orchestrator's brain: the actual run-loop it executes phase by phase.
• VERIFICATION.md — verification-first design plus the gated, difficulty-calibrated verifier fleet that decides whether a build ships.
• ROUTER.md and INTAKE.md — the non-technical front door: classify a plain-language wish (website / web-app / automation / document) and interview for a spec without making the user say a technical word.
• AMPLIFY.md — a test-time-compute ladder (best-of-N sampling with verifier selection, bounded refinement, council-for-design) gated to the hardest steps, where a strong verifier exists.
• MODEL-TUNING.md — model/effort tuning for Claude Opus 4.8. Tuning only; the rest of the doctrine is model-agnostic.
• policy.json — the machine-readable rules (autonomy, model-by-role routing, verify gate, amplify, merge policy) that the supervisor loads at run time. This is the file you edit to retune behavior.

AMPLIFY is deliberately honest about its ceiling: best-of-N only works because the deterministic gate and verifier fleet pick the real winner. Without a strong verifier on a step, amplification is wasted spend, and the harness falls back to the normal flow.

The ACE engine

ace/ is a small, deterministic self-learning loop — the Agentic Compounding Engine. It stores a voteable set of tactical if-then rules that the harness has learned. At PLAN time it injects the most relevant rules into context; after VERIFY it votes each applied rule helpful or harmful; during maintenance it evicts net-harmful or stale rules.

ACE does no LLM calls and has zero npm dependencies — it is pure, deterministic bookkeeping over an append-only log, built on Node's standard library. The vote signal comes from the caller (did following the rule lead to a verified, passing result, or a false lead?), so the engine only stores, ranks, and evicts.

node ace/ace.mjs add --id deterministic-gate-first \
  --if "a slice is finished" \
  --then "run tests/build/typecheck and require green exit BEFORE any LLM review" \
  --tags verify,gate
node ace/ace.mjs inject --context "verify a website build before shipping" --limit 5
node ace/ace.mjs vote --id deterministic-gate-first --helpful --note "caught a broken import"
node ace/ace.mjs evict
node ace/ace.mjs stats
node ace/test-ace.mjs   # smoke test against an isolated temp store

See ace/README.md for the data model and the three integration points (inject at PLAN, vote at VERIFY, evict at maintenance).

Playbooks

playbooks/ holds end-to-end recipes that thread the engine for a specific kind of job:

• brand-website.md — a non-technical "make me a website" wish → intake → build → browser-verify → plain-English handback.
• web-app.md — a logged-in, data-persisting web app, verified end to end in a real browser.
• remove-feature.md — feature removal done right: trace the full blast radius, delete the orphaned chain, prove nothing dangles.

Install

Handler is a drop-in for Claude Code. Place the repo where Claude Code can read it, for example:

~/.claude/handler/

Wire a /handler slash command (in ~/.claude/commands/handler.md) that loads SUPERVISOR.md and policy.json as the run-loop, or load it as a skill via SKILL.md. The documents reference each other by relative path, so keep the directory layout intact. Then edit policy.json to match your model choices, autonomy preferences, and escalation list.

The harness assumes the bd (beads) issue tracker as its durable work queue and a Node runtime for the ACE engine; everything else is model-and-prompt.

License

MIT. See LICENSE.