Expertise, domain, and skills per agent

Right now every lead and worker in your migration team is a one-shot persona: a system-prompt string, spawned fresh, gone the moment it returns a summary. That’s fine for a worker - it did one narrow job and disposable is exactly what you want. It’s a waste for a lead. The extraction lead is going to run for the whole migration, spawning worker after worker against the same domain, and every time you spawn it fresh it starts from nothing - even though last session it worked out exactly which of stash’s saved sites break the new extractor.

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:

# 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.

That third line is the kind of thing a fresh, memory-less worker would rediscover every single time it got assigned that backlog item. A lead that keeps its own expertise file stops paying that cost twice.

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. The workers underneath stay exactly as disposable as they were in the last lesson - nothing about specialization changes their job, only their leads’.

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 a hop that has nothing useful to contribute. Next: let two leads talk to each other directly - and the honest test for whether that’s worth building.