Expertise, domain, and skills per agent

Leads fixed the coordination cost of reading - three reports instead of seven. They didn’t fix the coordination cost of forgetting. Spawn the extraction lead fresh for a new session and it knows nothing about the migration it already ran yesterday, which means part of the same villain - more agents, more windows, more re-explaining - survives even with the hierarchy in place. By the end of this chapter: one written line turns a rediscovery a lead pays for every session into a cost it pays exactly once.

What “starts from nothing” actually costs

Three of the sites in the extraction lead’s backlog are paywalled - no amount of extractor logic recovers content that never reached the fetch worker. Spawn the extraction lead with no memory of its own lane, and it doesn’t know that. It reads the backlog, sees three unresolved items, and does the only sane thing an agent with that assignment can do: spawns a worker to go investigate them. That worker reads the fetch logs, checks the raw response, and eventually reaches the exact conclusion last session’s lead already reached - paywalled, not fixable, don’t reassign. One whole worker spawn, burned re-deriving a fact you already paid for once.

Guess how often that repeats. Take a toy pace for this migration - one extraction-lead session a day, for two weeks - and with no expertise file, that’s fourteen wasted worker-spawns on the exact same three-site dead end, once per fresh spawn, until someone happens to catch it by hand and mention it in the prompt. Write the fact down once, in a file the lead actually reads before it plans, and the number for every session after the first is zero.

Personas are just markdown with frontmatter

There’s no separate “agent config” system to learn here - a persona is a .md file, frontmatter on top, prose underneath, the same shape you’ve been writing prompts in all course. What makes it a team persona is a handful of extra frontmatter fields your team extension knows to read and act on: model, tools, domain, expertise, skills. None of these are special to Pi’s core - they’re plain YAML keys your own dispatch code parses before it spawns the child process, the identical idiom every extension in this course has used for its own config.

---
model: sonnet
tools: read,edit,bash,grep
domain: src/stash/extract/, app/worker.py
expertise: .pi/agents/expertise/extraction-lead.md
skills: onboard-content-source
---

You are the extraction lead for the stash migration. You own everything under
`src/stash/extract/` and the extractor call site in `app/worker.py`. Read
your expertise file below before planning any work.

domain - a boundary, not a suggestion

domain restricts where an agent is allowed to look and work - the extraction lead’s domain is the extractor module and the worker call site, full stop. It’s the same domain-scoping idea the damage-control gate used back in the harness-building chapter, just pointed at focus instead of safety: there, a domain boundary stopped an agent from touching the database or .env; here, it stops the extraction lead’s reads from wandering into the index rebuild or the UI, which is exactly the discipline the last lesson’s “focused agent is a performant agent” argument depends on. A domain field that’s advisory only is worth nothing - enforce it the same way you’d enforce a damage-control rule, in code the agent can’t talk itself past.

expertise - not memory, a curated file

“Memory” is vague - a raw transcript, everything the agent ever said, useful for nothing in particular. Expertise is narrower and more useful: a file the agent deliberately curates, holding only the judgment calls worth keeping about its own recurring lane. Nobody auto-logs it; the agent (or you) decides what earns a line. Here’s what the extraction lead’s expertise file might look like a few sessions into the migration, with the paywalled-site fact from above already paid off as its third line:

# Extraction lead - expertise

- Sites using client-rendered article bodies (no server HTML) still fail
  under the new extractor too - same failure mode as the old readability
  pass, not something this migration fixes. Flag, don't "fix."
- The new extractor returns `lang` on every row; the old one didn't. Index
  lead needs to know before it reindexes, or it'll reindex against a shape
  that's about to change again.
- Three of the sites in the "broke the old extractor" backlog turned out to
  be paywalled - no amount of extractor logic recovers content that never
  reached the fetch worker. Don't keep re-assigning these to a worker.

A curated file like this stays short by design - a comparably narrow role in a demonstrated multi-agent build ran to around 75 lines, not a transcript’s worth. Short enough to read in one sitting is the point: this is judgment worth keeping, not a log of everything that happened.

Why this belongs on leads, not workers

Workers are cheap and disposable on purpose - spun up for one job, torn down when it’s done, no state worth keeping because they’ll never see this exact task again. Leads are the opposite: they’re the ones who come back to the same domain, spawn after spawn, for as long as the migration runs. That’s the entire criterion for where an expertise file earns its keep - not “is this agent important,” but “will this agent see this domain again.” Give expertise files to your leads and your domain-owning long-runners; skip them for one-shot workers, or you’re just maintaining files nobody ever reads.

This is the same “write it down once” instinct from the SYSTEM.md lesson, and the same instinct behind packaging a skill instead of re-explaining a procedure - just scoped one level narrower, to a single agent’s own lane instead of the whole project. The skills field is where those two ideas meet directly: if your onboarding skill from the skills chapter already teaches “how to bring in a new content source,” attach it to a lead’s frontmatter and every worker that lead spawns can invoke it too, without you re-teaching it per persona.

What the roster looks like now

Three leads, each with a domain that doesn’t overlap the others’, each with an expertise file that only it writes to, each pointed at whatever skills its lane actually needs. Not every lead needs a skill yet - the extraction lead does, because onboarding a new content source is a real recurring job; the other two don’t have one assigned, and an empty field beats a skill invented to fill it:

Lead	Domain	Expertise file	Skills
Extraction lead	src/stash/extract/, app/worker.py	.pi/agents/expertise/extraction-lead.md	onboard-content-source
Index lead	full-text search rebuild	.pi/agents/expertise/index-lead.md	-
Interface lead	web UI + CLI rendering	.pi/agents/expertise/interface-lead.md	-

The workers underneath stay exactly as disposable as they were in the last lesson - nothing about specialization changes their job, only their leads’.

This chapter’s line in the running ledger: an expertise file costs a small curated file a lead re-reads on every spawn, and buys back every rediscovery it would otherwise pay for again.

Layer	What it costs	What it buys	Who decided
Expertise file, one per lead	a small markdown file the lead re-reads every spawn; nothing if nobody curates it	zero repeated worker-spawns rediscovering a fact the lead already paid to learn once	the lead, curated by hand - never auto-logged

So far, though, every message in this team has flowed one way: orchestrator down to lead, lead down to worker, and a summary back up the same path it came down. That’s about to become a problem, because the migration has a fact one lead discovers that another lead needs immediately, and routing it through you adds two hops that have nothing useful to contribute. Next: let two leads talk to each other directly - and the honest test for whether that’s worth building.