From 30 to 100 agents

What the lift actually is

With strong checks and enough CI, going from about 25 to 100 agents might roughly double verified output per day. That's a guess, and it costs about four times the tokens. With weak checks, output stays flat, because you were already the limit.

The larger gains are usually not speed:

• Confidence per change. The same volume, but each change raced, attacked and independently verified.
• Hours you aren't working. Coordinators keep going overnight. Running more hours is cheaper than running more agents at once.
• Projects you wouldn't attempt. A 40-service migration that would take a team a quarter becomes something one person can run.

Reading the model

The red bar is the stage that limits output. Raising any other slider changes nothing shipped and only raises idle capacity.

Three lessons fall out:

• The mechanical check share is the most powerful slider. It moves your own review out of the critical path.
• After that, CI and merges are usually the limit, and more agents can't fix that.
• The reject rate eats every agent stage at once. Lowering it through clearer tasks and encoded lessons beats adding agents.

Choosing the check for a task

Ask one question: if this change were wrong, what would fail? The answer is the task's done_when. If the honest answer is "someone would notice it looks off", the task has no mechanical check. Batch those for yourself and keep them out of the pipeline.

Plant bugs before you trust a check

Before fan-out, make a few wrong changes of the kind builders will make, and confirm the check catches each one. A check that has never caught a planted bug can pass everything, and the dashboard stays green until production. Also measure its flakiness: a check that fails 3% of the time for no reason rejects dozens of good tasks per wave.

Rules that keep verification honest

• No agent verifies its own work, ever.
• Verifiers use another model family where possible. Agreement across families is strong evidence. Agreement within one family is weak.
• Verifiers don't see the builder's explanation. A persuasive write-up makes it easier to approve wrong work.
• Risk sets the number of verifiers: one for a rename, three plus a blast-radius pass for auth or data migrations.
• A verifier's job is to run things. If the only way to verify a task is to read the diff and decide, that task belongs in your queue.

Typical ratios at 100

The rules the simulation follows

• Claim by rename. mv todo/T12.md doing/T12.md is atomic on one filesystem. Two workers can't both win, and the loser just picks another task.
• Heartbeat or be reaped. Working agents touch a heartbeat file every few minutes. When one goes stale, the reaper returns its task to todo/ with attempts increased.
• Builders never verify their own work. Finished work goes to review/, and a separate agent claims it from there.
• Cap retries. After three attempts a task goes to failed/ for a human or a redesign, instead of looping.
• Park, don't block. A question goes to inbox/, and the worker moves on to another task.
• Dependencies wait in backlog. Tasks move to todo/ only when what they depend on is done.

Where it lives, and why

~/.queues/rest-to-grpc/
  backlog/   blocked on depends_on
  todo/      ready to claim
  doing/     claimed by a builder
  review/    built, waiting for a verifier
  verifying/ claimed by a verifier
  done/      verified; the coordinator merges
  failed/    gave up after 3 attempts
  inbox/     questions only you can answer
  results/   one file per task, one writer each
  hb/        heartbeat files, touched by workers

Put it at an absolute path outside every worktree and outside your vault. Each worktree or jj workspace has its own copy of repo files, so a queue inside the repo splits into copies. Sync services (iCloud, Dropbox, Obsidian Sync, Drive) break atomic renames and create conflict copies.

Choices baked into these files

• The lock is a directory. mkdir is atomic everywhere and macOS has no flock. If a claim is killed with kill -9, delete .lock by hand.
• Verifiers get less information on purpose. They see the finish condition and the revision, not the builder's reasoning.
• Reaped verification doesn't count as an attempt. Only builder failures use up the three tries.
• The coordinator's numbers come from files. A summary written from memory drifts within a day.

What's missing on purpose

• Reject rate per cluster in q status. Add a cluster: field and count reject sections in done/ and todo/.
• Merging. It depends on your repo and CI, so it stays in the coordinator's hands.
• Sandboxing. Run agents with only the credentials the task needs, never production ones.
• Any trust in task text. Workers act on whatever todo/ says, so only the coordinator should write there.

The worker loop

Each slot runs worker.sh from the starter kit: claim, start a fresh headless agent with a time limit, repeat. The heartbeat comes from the loop, so the model never has to remember it, and the time limit catches a model that hangs while its loop is still alive.

Three ways agents connect

Subagents. A coordinator spawns workers with its Task tool and gets their reports back. Most of the 100 live here, and Herder never sees them.

Pane to pane. An agent inside Herder can drive another pane through the CLI. Use this for long-lived roles you want to watch, like a different-model reviewer:

herdr agent start reviewer --kind codex
herdr agent prompt reviewer "Review branch grpc-billing \
  against done_when in ~/.queues/…/review/grpc-billing.md" \
  --wait --until done --timeout 600000
herdr agent read reviewer

Files. The queue. It's the only one of the three that survives a crash, so anything another agent depends on should end up in a file.

Install the Claude integration (herdr integration install claude) so pane states come from the session rather than screen-scraping, and still confirm completion from result files, not pane state.

One writing agent per workspace keeps changes apart. With jj, jj workspace add ../ws/<task> is cheap, and every workspace shares one repo store, so the coordinator can see all in-flight changes with one jj log.

Two jj behaviors help at scale. Conflicts are recorded in commits instead of stopping a rebase, so the integrator can rebase the whole queue onto main and see which tasks now conflict without anything blocking. And the operation log (jj op log, jj op restore) gives the coordinator a clean undo for a bad merge.

Yours

• Core types and interfaces, edited line by line
• Product calls
• Choosing between prototypes
• Each task's finish condition
• The design checkpoint after the pilot

Agents'

• Research: how the current system works and why (how, why)
• Building the prototypes and the end-to-end path
• Writing the test callers
• Arguing against the design
• Over time, more of the design, once your past decisions are written where they can follow them

The playbooks that matter at scale

• Orchestrate. A standing project for one coordinator chat: multi-day, many stacked PRs, many subagents.
• Autopilot-full. A queue of independent PRs, one owner each, root-verified before merge.
• Autopilot-stack. The same without merging. You land it.
• Autonomous run and Pause safely / Session pickup. Long unattended runs, and stopping and resuming them cleanly.
• Babysit and Shipping. Driving PRs to green, then landing only the verified run from the root.

Porting notes

pstack names Cursor's Task tool, Cursor model slugs (grok-4.7-xhigh-fast for code, claude-opus-5-5-xhigh for judgment) and cursor-team-kit skills. Community ports exist for Claude Code (michael-denyer/pstack-claude), T3 and Oh My Pi. They mostly substitute those terms, and the Claude Code port adds a session-start hook so poteto-mode engages without the slash command.

The parts that carry over to any setup: the 24 one-rule principle files, correct, the why source adapters, and show-me-your-work's decision log.

How to wire it

• The coordinator's role file names the vault path and the summary template. It writes notes. It never reads the vault for instructions, so a stray note can't steer the fleet.
• Frontmatter numbers make every run queryable. A Bases view or Dataview table over Runs/ gives you reject rate per area per day. A frontmatter watcher like the one behind your dashboard could turn the same fields into a live fleet panel.
• Answer the inbox in Obsidian by ticking a task and writing the answer under it. The coordinator reads Inbox.md on its loop and releases parked tasks.
• herdr notification show on a new inbox item means you don't watch the vault.

What not to do

• Don't keep the queue in the vault. Sync breaks atomic renames, creates conflict copies, and turns a crash-safe queue into a race.
• Don't let 20 agents append to one note. Each writes its own result file outside the vault, and one summarizer writes the note.
• Don't paste raw agent output into the vault. Summaries only, with links to result files or PRs.
• Check what your employer allows before pointing agents at work code or syncing anything about it into a personal vault.