How agents read and report

Before work: read a little

An agent should not read the whole brain. That wastes time and tokens. It reads the front door, then only the pages it needs.

python -m librarian query "hosting"
python -m librarian read brain-index
python -m librarian map

query finds pages that match a question. read opens one page by its ID. map lists every page ID and where it lives.

The agent also writes down the brain commit it read. If the copy is old, it says so. It never claims it read the latest brain when it did not.

After work: one update, only if a fact changed

Most tasks change no company fact. Then the agent just says: No material company fact changed.

An update is for things another agent would need to know. A new feature. A bug fix. A change to how two apps talk. A new server, tool or cost. A new way of working. A decision.

One task gets one update. Not one per file. Not one per thought.

What goes in an update

The update is a small JSON file. The draft command fills in what it can. The agent fills in the rest, in plain words:

• What changed, and why.
• Before and after.
• The repo, the files, the commits and the pull request.
• The tests it ran, and the real results.
• Any decision, with who made it and when.
• Open questions.

Two rules matter most. Never make up a session ID, a commit, or a test result. And a decision only counts if the owner made it. Anything else is a proposal.

The GitHub part

This is where people get stuck, so go slow.

Your computer keeps one copy of the brain on the main branch. Call it the reader copy. Many agents read it. Never switch its branch. If one agent switches it, every other agent reads the wrong thing.

So to write an update, the agent makes its own worktree. A worktree is a second folder for the same repo, on its own branch. The reader copy stays on main.

Set it up

1. Fetch the latest brain, then make a worktree on a new branch.
2. In the worktree, run update draft. Point --source-checkout at the work repo you changed.
3. Open the draft file. Fill in every field in plain words.
4. Run update lint. Fix anything it reports.
5. Run update submit. It saves your update as a new file under inbox/.
6. Commit only that new file. Push the branch. Open a pull request. This is an intake PR.
7. Never merge your own intake PR. The librarian brings it in.
8. Remove the worktree. Report the update ID and its state: local, pushed or merged.

The commands, with your own names in place:

git -C ~/acme-brain fetch origin
git -C ~/acme-brain worktree add ~/brain-update -b claude/fix-login origin/main
cd ~/brain-update
python -m librarian update draft --source-checkout ~/acme-app --agent claude-code --session SESSION-ID --output ~/update.json
python -m librarian update lint ~/update.json --source-checkout ~/acme-app
python -m librarian update submit ~/update.json --source-checkout ~/acme-app
git add inbox
git commit -m "Brain update: fix login timeout"
git push -u origin claude/fix-login
gh pr create --fill
cd ~ && git -C ~/acme-brain worktree remove ~/brain-update

The prompt: finish a task with a brain update

Add this to the end of any task you give an agent.

When the task is done, check if it changed a company fact: a feature, a bug fix,
how two apps talk, a server or tool, a cost, a way of working, or a decision.

If nothing changed, say "No material company fact changed." and stop.

If something changed, write one brain update:
1. Fetch the brain. Make your own git worktree on a new branch. Never switch the
   branch of the shared brain folder.
2. In the worktree, run `python -m librarian update draft` with --source-checkout
   (this repo), --agent, --session (your real session ID) and --output (a new file
   outside inbox/).
3. Fill every field in plain words: what changed and why, before and after, files,
   commits, the pull request, tests with real results, decisions, and open questions.
4. A decision counts only if the owner made it. Say who and when. Otherwise mark it a proposal.
5. Never invent a session ID, commit, pull request or test result. Leave it as a question.
6. Run `update lint`, then `update submit`. Commit only the new inbox file. Push and
   open a pull request to the brain. Do not merge it.
7. Remove the worktree.

Report the update ID, the pull request link, and its state: local, pushed or merged.

You are done when

• One agent read the brain, did a task, and opened an intake PR with one update.
• The shared reader copy is still on main.

Next module

Module 5 hires the librarian, the one agent that turns updates into pages.