Teams

Two agents worked the last chapter - a builder, and a verifier that didn’t trust it - and it closed on a question nobody answered: who verifies the verifier? Not a third agent. The answer that chapter landed was structural: a verifier with no chat input can only be corrected through the claims file you edit by hand, so the regress stops at you. Remove the option to be wrong instead of adding something to police it - this chapter runs that same structural move again, at a bigger scale.

The migration it runs on has been sitting in plain sight since your first day in this repo. pyproject.toml declares readability-lxml>=0.8.1, and not one line of stash (the course’s running example, a small FastAPI feed reader) imports it. The README calls stash/extract.py a readability extractor; the function it means, extract_meta, is a naive <title> string slice that pulls out a title and nothing else - and nothing in the sync path even calls it. Every row in stash.db, the last chapter’s import included, was saved from feed metadata alone.

You’ve decided to make the README true: wire the declared library in, extract real content for every stored entry, and handle whatever the richer extraction returns. That’s not one fix. It’s at least three, wearing one migration’s name - the extraction itself (stash/extract.py, plus the sync-path step that fetches an entry’s page and calls it), the storage underneath (stash/db.py and stash/models.py, where a richer extracted article has to live on disk), and the interface on top (stash/main.py, where GET /articles has to answer with the new shape).

Fan that out flat, the way the last chapter taught you, and three domains’ worth of workers all report to the same thread - yours. You become the bottleneck the whole point of subagents was supposed to remove: reading every domain’s back-and-forth yourself, because nothing stands between you and the workers.

More agents on the job doesn’t mean less work for you. Past a certain point it means more windows to watch and more coordination to do by hand, and that coordination cost is the real villain of this chapter - not the migration itself.

Here’s the claim this chapter is going to earn, not just assert: a lead per domain turns however many workers are underneath it into one report you actually read, and that ratio gets better the bigger the team gets. But the tokens spent don’t shrink, they move, and every layer you add back (a lead, an expertise file, a peer channel between leads) has to pay for itself against what it costs to build and run.

Some of what you’re about to build will clear that bar easily. At least one piece of it, run at the wrong size, won’t - and this chapter says so when the trace shows it, instead of only celebrating the wins.

• Orchestration - add the missing layer between you and the workers: leads, one per domain, structurally forbidden from touching a file themselves. Count what that actually buys, then the real reason to decompose the migration at all - it was never about context size.
• Expertise - give each lead a place to keep what it’s learned about its own lane, so the extraction lead gets better at extraction over the migration instead of rediscovering the same dead end every spawn.
• Coms - let two leads talk to each other directly when the hierarchy gets in the way, and run the honest test for whether that channel - or any of this - was worth building at all.

By the end you’ll have run a real three-tier team on a real migration, priced every layer’s cost honestly against its payoff, and be able to say, without hand-waving, whether it was the right tool for the job. Start with orchestration.