Feature Library
Playbook

Several people, each with their own agents

When a team shares a codebase and everyone brings their own AI helpers: the agreements that have to live in the repository, who claims what, who may approve what, and how work survives the end of a session.

Updated 16 November 2026 · checked with GitHub and Claude Code, Nov 2026

The first two playbooks are about one person coordinating many agents. Add more people and something changes: each person's agents hear only their own person. Two people can agree something over coffee, and neither person's agents will ever know. So everything the team relies on has to be written in the repository, where every agent reads it.

This library has so far been built by one person with many agents, so this playbook is part experience and part reasoning from it. Each section says which: tried here means it happened on this project, not yet tried here means it follows from what did.

Before you start

  • (default) The contract (types, APIs, folder layout, what "done" means) is written down and agreed before anyone's agents start.
  • (default) One board in the repository says who is doing what, on which branch.
  • (default) People claim work on the board before it starts. Agents don't claim.
  • (default) The house rules live in files every agent reads (the brief, the tests), not in anyone's head.
  • (default) Shared files have named owners, and changes to them go in a pull request of their own.
  • (default) Nobody approves their own work, and an agent's work counts as the work of the person who ran it.
  • (always) What agents must not see is written down: customer code, secrets, other teams' private repositories, because what an agent has read can turn up in anything it writes.
  • (default) Every session ends with a handover note in the repository, not only in someone's chat.

Decisions go in the repository

People settle things in meetings, messages and corridors. Agents read files. A decision that only lives in a conversation might as well not exist for everyone else's agents, so each one gets a short file:

# One folder per entry, found by the site

Decided 2026-11-03 by Hannes.

Every entry lives in entries/<id>/ and the site discovers it; no list
to edit. So parallel work never meets in one file.

Instead of: a registry file everyone adds to, which every parallel
piece would have to edit.

Keep them short and numbered, and never edit an old one: write a new one that replaces it. Then "why is it like this?" has an answer that any person, and any agent, can find.

Not yet tried here. This library's decisions live in its README, its backlog and its commit messages, which is enough for one person. A team needs the place to be obvious.

One board, claimed by people

Without one shared list of who is doing what, two people's agents will build the same thing. Keep the board in the repository, where every person and every agent reads it:

| Piece               | Claimed by | Branch                | State    |
|---------------------|------------|-----------------------|----------|
| Keyframe timeline   | Hannes     | entry/timeline        | review   |
| Quiet charts        | Sam        | entry/quiet-charts    | building |
| Comic text          |            |                       | free     |

The rule that makes it work: a person claims a piece before any agent starts on it, and the claim is committed, so everyone sees it on their next pull. Agents work on claimed pieces; they never claim one themselves.

Tried here, by one person. This library's backlog took three surveys, a list of picks, an approval and a "built" list, in that order. Nothing was built that wasn't on it.

The house rules live in files

Each person's agents learn the house style from what they read, so put the house style where all of them read it:

  • The brief, kept in the repository (docs/briefs/entry.md), with the conventions, the rules and what a report must say.
  • The tests, for everything that can be checked: here they fail if an entry imports a package it shouldn't, ships a private path or a key, or links to an entry that doesn't exist.
  • Instructions for the agents themselves, in the file your agent tool reads at the start of every session in the repository.

Change any of these by pull request, like code. A rule changed quietly in one person's copy only changes that person's agents.

Tried here. One brief, read by 17 agents, kept the entries consistent, and the tests caught what the brief couldn't enforce. Here the brief was a scratch file. A team should commit it.

Owners for shared files

Some files belong to everyone, so they belong to someone: the schema, the site's styles, the package list, the tests, the brief itself. Name an owner for each, and make changes to them in a pull request of their own, never mixed into a feature:

# Shared files need their owner's review.
harness/schema.ts     @your-handle
src/styles.css        @your-handle
package.json          @your-handle
tests/                @your-handle
docs/briefs/          @your-handle

Tried here, in one session. The coordinating session owned the shared files, and the agents reported what they needed there instead of changing it. Three separate site bugs were each fixed once, by the owner.

Review across people

Two rules keep review honest when half the code is written by agents:

  1. (default) Nobody approves their own work. An agent's output counts as the work of the person who ran it, so that person can't approve it either.
  2. (default) The reviewer checks the result, not only the diff. They run the checks themselves and look at what was built, because a diff can't show that a preview came out empty.

Say in every pull request what agents did and what was checked. That tells the reviewer where to look hardest:

## What and why

## How it was built
- Agents used, and for what:
- Brief they followed:

## Checked
- [ ] Typecheck, all tests and the production build
- [ ] Seen working: desktop, phone, light and dark
- [ ] Not checked, and why:

This repository's own version, with its measuring and drift checks added, is in .github/pull_request_template.md.

Tried here, with one reviewer. Seventeen honest agent reports still missed two real bugs, and the owner's own work missed a third. Looking at every result side by side found all three.

Handovers that survive the session

Sessions end without warning: a laptop sleeps, a subscription lapses, someone goes home. Whatever wasn't written down goes with them. End every session with a short note in the repository:

## Done
Playbooks section, and the first two playbooks.

## Where it stands
Committed on main. Nothing open.

## Not checked
The figure's animation was only seen in stills.

## Next
Playbook 3 (several people); the user reviews each before the next.

The Not checked line matters most. Leave it out, and whoever comes next assumes everything was checked.

Tried here, the hard way. This project's previous session ended mid-question when its account's access stopped. The next session found its place from the transcript left on disk and a one-line memory note saying licensing guidance was still owed. It worked, but only by luck: a handover note would have made it certain.

What agents must not see

Every person's agents need the same limits. Write down what is off-limits, and put it in the brief:

  • (always) Customer and company content: code, data, specifications, names. For this library one source app's customer areas were listed by path, and every agent's brief said never to copy from them, because it belongs to the customer and a copy can't be taken back.
  • (always) Secrets: keys, tokens, passwords. Keep them out of the repository entirely; here a test fails if one turns up in an entry or a playbook, because a key in the history stays readable after it is deleted.
  • (always) Other people's work: a colleague's private repository is theirs, not your agent's.

Tried here. The keep-out list was in every brief, and no customer code reached the library.

As of November 2026: GitHub enforces CODEOWNERS review once branch protection requires it. Claude Code reads a CLAUDE.md in the repository at the start of each session there, which makes it the natural home for house rules that every person's Claude sessions should follow.