← back to the chaos

the .claude/ agent system

The Agent Fleet

a swarm of tiny specialists builds this repo, and a second swarm tears their work apart.

25 agents · paired author + critic per domain · nobody approves their own work.

Every task and code change routes through the .claude/ system. You name no agent. It reads the files you touched, picks the author that owns that area, runs an independent critic over the diff, pulls in a security or performance secondary when there’s risk, writes tests, sweeps dead code, and lets a steward close the docs. Poke around below to watch it move.

one issue in →

Intake → Delegation

the fleet decides who touches it, and why.

pick an issue to see who handles it.

one change, down the line

The Assembly Line

a single diff rides through nine stations, each a different specialist. scroll to run it.

station 1 / 9 · intake & triage

↓ keep scrolling — the diff moves with you

one change, down the line

The Assembly Line

a single diff passes through nine stations, each a different specialist.

  1. station 1 / 9 · main session
    intake & triage
    paths matched to review-routes.json; first glob wins.
  2. station 2 / 9 · write access
    author implements
    the domain author makes the smallest diff that fits.
    rust-backend-author
  3. station 3 / 9 · read-only
    critic audits
    an independent critic reviews the diff. it never wrote it.
    rust-backend-architect
  4. station 4 / 9 · if testable
    test-author
    adds unit / golden / e2e coverage for the change.
    test-author
  5. station 5 / 9 · read-only
    testing-reviewer
    challenges weak assertions + untested error paths.
    testing-reviewer
  6. station 6 / 9 · report-first
    cleanup
    sweeps dead code the change orphaned; safe deletes only.
    cleanup
  7. station 7 / 9 · sole doc writer
    project-steward
    syncs docs/knowledge, persists lessons, updates the graphs.
    project-steward
  8. station 8 / 9 · before the PR
    pr-reviewer gate
    real tools + blast-radius. 🔴+🟠 block the PR.
    pr-reviewer
  9. station 9 / 9 · PR opens
    ship
    CodeRabbit finds less, because the fleet already did.

every specialist, one tap away

The Fleet

authors write (left, green). critics audit (right, pink). tap any node for its brief: pair, paths, and how you’d delegate to it.

authors ✎
⌕ critics
cross-cutting & risk — they ride along, no author pair

tap a node above — every one of the 25 is here.

author (writes) critic (audits) cross-cutting / risk author ↔ critic pairing risk secondary

all at once →

Make Them Work Together

one cross-layer ask, the whole fleet in parallel.

Implement a "save job to a folder" feature end-to-end: new IPC command + Rust store, a renderer panel to pick the folder, and ATS-aware tagging. Route it through the agent fleet.

Disjoint files, in parallel

  • rust-backend-author — IPC command + SQLite store (commands/, data_store.rs)
  • frontend-author — the folder-picker panel (renderer/**)
  • job-match-author — the ATS tag logic

Critics challenge each other

  • rust-backend-architect + tauri-security-reviewer on the new IPC surface
  • frontend-reviewer + ui-ux-expert on the panel
  • job-match-expert on the scoring

Then the close-out

  • test-author → testing-reviewer across all three
  • cleanup sweep
  • project-steward docs + lessons

is it worth it?

With vs Without the Fleet

same job. honestly: agents cost a token premium for higher reliability + parallel speed.

One agent, no fleet

Wall-clockSerial. One context does intake, code, review, tests, docs — back to back.
TokensCold re-exploration every spawn: ≈70–122k tokens/spawn, ≈120 tool-uses to rebuild context it never kept.
Bugs caught before releaseThe writer reviews its own work — the missed error is the one it didn’t see the first time. No release gate.

The agent fleet ↑ this one

Wall-clockAuthors run in parallel on disjoint files; critics audit alongside. Faster on cross-layer work.
TokensPre-harvested handoff instead of cold start: ≈44 tool-uses vs ≈120. Multi-agent adds ≈+58% token overhead — kept small by the handoff.
Bugs caught before releaseAn independent writer/critic split catches ≈60–80% of otherwise-missed errors, plus the Stop review-gate before merge.

ILLUSTRATIVE FIGURES. The numbers above (cold-start ≈70–122k tokens/spawn; ≈44 vs ≈120 tool-uses pre-harvested vs cold; writer/critic catching ≈60–80% of missed errors; multi-agent ≈+58% token overhead) are illustrative, not measured benchmarks of this repo. The honest trade: agents cost a token premium for higher reliability and parallel speed; the pre-harvested handoff is what keeps that premium small.