06 — A context engineering workbench
What you will have at the end: two agents in one workspace that know different things on purpose — and the ability to say why the arrangement is the way it is.
What you need: tutorial 02 finished. One agent connected, an AGENTS.md,
and a folder of its own.
The problem with one agent that does everything
You have an agent. It works. And then it does one of these:
- It forgets a convention you explained last week, because you explained it in a prompt and prompts do not persist.
- It reviews its own work and approves it, because it can see its own reasoning and finds it convincing.
- It reads its own old notes as though they were decisions, because nothing in the workspace says which is which.
None of these is a model problem. They are all the same problem: the agent's context is whatever happened to be in the conversation. You cannot arrange something you cannot see, and a prompt disappears the moment it scrolls away.
The fix is to stop putting context in conversations and start putting it in files. Once it is in files, it has a location, and a location is something you can design.
1. The three places context lives
There are exactly three, and each answers a different question:
| Where | Answers | Who reads it |
|---|---|---|
AGENTS.md at the workspace root | How is work done here? | Every agent, every session |
WHOAMI.md in an agent's folder | What is this agent for? | That one agent — and you |
| The rest of that agent's folder | What does this agent know? | That one agent — and you |
The right-hand column is about agents. Every person with access to the workspace reads all three, whatever is in them; the wall is between agents, and only between agents.
Write the playbook for the workspace, not for an agent. If a sentence in
AGENTS.md names one agent, it probably belongs in that agent's brief. The
playbook is the part that stays true when you add a second agent:
## House rules
- Never resolve a comment thread. Resolving is my signal.
- Reply on the thread when you are done — your reply is the report.
- Ask on the thread when something is genuinely ambiguous rather than guessing.
That is house process. It is true of every agent you will ever add.
Write the brief for the job, not for the task. A brief that describes today's work is a prompt in a file. A brief that describes a standing role is context:
# author-bot
You draft. When I ask for a document, you write the first version and you write it
to be argued with — say what you considered and rejected, not only what you chose.
You keep your working notes in this folder. They are yours; nothing outside this
folder should depend on them.
Notice what that last line does. It tells the agent its notes are private working material, not shared output. That distinction is about to become the whole point.
2. Why a reviewer needs to be kept in the dark
Give a reviewer the argument and you get a review of the argument. Give it only the document and you get a review of the document.
Two things are known here, and they pull in different directions.
A model asked to judge its own work grades it generously. That is measured, not folklore, and the fix is to use a different judge rather than to ask nicely. Verdicts also move with how a thing is framed — so a critic that has read your justification is reviewing a case already made to it.
But hiding things does not automatically improve a review. Human peer review has tested this for decades and the results are mixed: blinding removes bias about who wrote something, which is not the same as making the review better.
So the rule is narrower than "withhold context":
Hide the case you made. Keep everything you knew.
A critic that cannot see your reasoning is independent. A critic that cannot see the specs, the decisions or the threads is just uninformed — it will flag things settled last week for reasons it never saw.
Private folders are how you write that line down. Everything outside them is shared — the documents, the specs, the comment threads. Only each agent's own working notes are its own, and no other agent can reach them at all.
3. Build the asymmetry
You already have one agent from tutorial 02 — helper-bot. It is the author in
everything that follows. Rename it to author-bot in organization
configuration's Agents section if you
want your workspace to match the examples here: renaming an agent renames its
private folder with it, so nothing else has to move.
Then add a second, and make the two deliberately unequal in what they can see.
Create a second agent — call it critic-bot — grant it a role in the same
workspace, and give it a root folder named after it. Two agents, two folders:
AGENTS.md
author-bot/
WHOAMI.md
notes/
critic-bot/
WHOAMI.md
documents/
proposal.md
Now write the critic's brief so that its independence is explicit:
# critic-bot
You review documents on their own terms. You read the document and the comment
threads on it, and nothing else — you do not have access to the author's working
notes, and that is deliberate: your value is that you were not persuaded on the way
in.
Report on the thread. Say what is unclear, what is unsupported, and what a reader
would misread. You do not rewrite.
Both agents read the same AGENTS.md. Both follow the same house rules. Neither can
see into the other's folder — to critic-bot, the author-bot folder does not
appear in the tree at all. Not greyed out. Absent.
4. Watch it work
Ask author-bot for a short proposal, and tell it to keep its reasoning in its own
notes. It writes documents/proposal.md and, separately, its working notes in its
own folder.
Now open the proposal, select a claim in it, and start a comment:
@critic-bot Is this claim supported by what the document actually says?
Tell the critic's harness to check in. It reads the document, reads the thread, and replies — and it replies without the author's justification in front of it, because it cannot reach it.
That reply is worth more than a self-review, and the reason is structural rather than a matter of the model trying harder. It could not have been influenced by reasoning it never saw.
5. When it goes wrong
Four failures, all of them common, all of them fixable in the files:
The brief that grew into a manual. A brief is read at the start of every session. If yours has reached three pages, it is a manual somebody re-reads all day. Move the detail into the folder as an ordinary document and let the brief point at it. Keep the brief to a page.
The playbook that contradicts a brief. They arrive in a fixed order — the playbook first, the brief second — and the playbook wins. So if a brief seems to be ignored, check whether the playbook already said the opposite. This is deliberate: house rules everyone agreed to should not be quietly redefined by one agent's brief.
The folder that is not actually private. Which section of the explorer it sits in is the only signal that the convention fired. Still up in Workspace Files means the name does not match — a trailing space is the usual culprit — and it is an ordinary folder every agent can read. Look at the section, not at the folder.
The agent that rewrote its own brief. Agents can edit their own briefs, and that
is genuinely useful — "read your brief, work, and improve it" is a reasonable thing
to ask for. The cost is that an agent talked into rewriting it keeps the new
instructions for every session afterwards. What bounds this is that the file is not
hidden machinery: it sits in the tree with the same icon AGENTS.md carries, in a
folder you can see, where a change is as visible as any other document's. Look at
it occasionally.
What you have now
Not two bots. An arrangement: one shared playbook, two briefs, and one deliberate decision about what each agent cannot see — all of it readable off the file tree, with no permission dialog anywhere.
That is the workbench. The parts are files, so the design is a thing you can read, diff, and argue about.