The workspace

1 Why it exists

Without your team’s context, an agent guesses. Its guesses read as confidently as its facts.

The model brings general skill. The repository says what the software is today. Neither one knows which repository a change belongs in, which branch your team abandoned, or what you mean by an everyday word.

That knowledge usually lives in a few people’s heads. Those people get good results from an agent, and everyone else gets guesses. The workspace writes the knowledge down, so working well with an agent becomes a team practice instead of a private skill.

2 What it holds, and what it refuses

A workspace grows until nobody reads it. A written boundary stops the growth.

Cheap insurance stays, even when a model usually gets the answer right. A one-line warning that prevents a costly mistake earns its place.

When adding and deleting are otherwise equal, delete. Correct an existing page before you write a new one.

Finished work moves to an archive. It stays in the repository, but a search-ignore file hides it from agent search, so old plans stop showing up as current advice.

Two places hide team knowledge without anyone noticing. One is the agent’s private memory on one person’s machine. The other is the always-loaded rules file, which grows until every session pays for rules it never uses. Move team facts out of private memory, and keep the always-loaded layer to routing and the traps.

3 It sits beside your code

The workspace is its own repository. It points at your code repositories; it does not contain them.

Submodule. A git feature that includes one repository inside another, fixed at an exact commit.

Your code keeps its own repositories, history and reviews. The workspace includes each one as a pinned reference, such as a git submodule. When a change merges upstream, the workspace moves its pin forward.

The split pays off three ways. Code reviewers never see workspace churn. One workspace can describe several repositories, including ones your team does not own. And every claim in it describes a known version of the code.

Design it so nobody needs access to everything. A newcomer who can reach only two of the repositories should still get working docs and passing checks.

4 Write it once, every tool reads it

Each rule and procedure lives in one file. Every tool, and every published copy, points back at it.

Most agent tools have their own format for commands and rules. Write a procedure into each format and the copies drift apart. Instead, write it once as plain markdown, and give each tool a wrapper of a few lines that points at it.

Rules work the same way. One contract file holds the rules every tool reads, and each tool’s own settings file imports it instead of repeating it.

Path-scoped rule. A rules file that applies only to matching paths, such as front-end components or deploy configuration.

Some rules apply only to certain files. Keep those in path-scoped rule files. Some tools load them on their own. For the rest, a hook shows the matching file when the agent edits a covered path.

People who never clone the repository still need some of it, such as the decision records and the team’s agreements. Publish those to your wiki one way, with a banner that names the source. Edits go to the source, and the next publish carries them.

5 Two front doors, one set of docs

People and agents need different entrances. They do not need different documents.

A person wants the reasons and a route to the task. An agent wants the rules and the fastest path to a fact. So each gets its own entrance: a guide and a task router for people, the contract and a topic index for agents.

Behind both entrances is one set of documents. Nothing is written twice for two audiences, so a fact that changes, changes once.

Start with those five rows; they cover most work. Add a row when someone asks where to go and the answer is not there.

Short requests should expand to full procedures. The workspace defines what each one means, so the same words do the same thing for everyone.

6 Three kinds of guidance

A reader should know from the folder name what kind of help they are about to get.

Diátaxis. A public framework that sorts documentation by what the reader needs: to learn, to do a task, to look something up, or to understand why.

The split follows Diátaxis. Playbooks are the how-tos an agent can run, which is why they get their own folder. Keep one term per concept: when two words name the same kind of document, retire one.

Every page opens with one sentence saying what it is for and who reads it. A page that reports a finding or a decision also opens with an “In short” line a reader can stop after. A gate checks that the line is there.

7 Finding things

Choose the lookup that fits what you already know. Don’t stack them.

The alias table is often the most useful thing a workspace gives an agent. People and code use different words for the same thing, and a search for the everyday word finds nothing.

Code maps help people as much as agents. A newcomer can scan a repository’s shape without opening a source file.

Outside systems get the same treatment. A register lists every system you call, and a text model records each call and the class of data it carries. The maps and diagrams are generated from the model. Figure 1 on my home page shows that loop.

8 Size the work first

Process should scale with the work. A size gate decides how much each change gets.

A change skips the ceremony when it is all four of these:

• Small
• Easy to reverse
• In one repository
• Under a day of work

Then write a failing test, make it pass, and ship it. Everything else climbs a ladder, and stops climbing as soon as the work allows.

1. Bound it. Write the goal and the non-goals before touching anything. Agents tend to do more than you asked, and non-goals stop that.
2. Grill. The agent interviews you about the design until the open questions are settled.
3. Spec. Write down what will be true when the work is done.
4. Plan. Break the work into slices an agent can run, each with its own checks.
5. Red-team. A fresh session with no stake in the plan attacks it. Done means every finding is triaged, not that none were found.
6. Execute. Run the slices, verify each one, and record what happened.

Decision record. Often called an ADR, for architecture decision record: a short page naming a choice, its options and what it gave up.

A call that is hard to reverse becomes a decision record. The next person, or the next agent, reads why before reopening it.

Work that runs for weeks gets one folder for its hub, its open questions, its specs and its plans. Very large work, with its own conditions for stopping, gets a short requirements document above the ladder.

9 Done means verified

An agent’s “done” is a claim. The workspace says what evidence the claim needs.

A change is done when all of these hold:

• Tests come first, and they fail before the fix.
• The build is clean against where it started. Only new warnings count, so old ones can’t hide new ones.
• The change is checked in the running app, on a disposable local environment.
• An impact check lists what else the changed paths touch.
• Every claim in the report is marked verified or inferred.

Verified means the agent ran something and saw the result. Inferred means it reasoned its way there. Both are useful. Mixing them up is how a confident wrong answer gets merged.

A bug that shows on screen gets a screenshot or a short video, captured on the local environment. A person approves each bug report before it is filed.

10 A local environment per working copy

Each working copy of the code gets its own disposable environment, so parallel sessions never share test data.

Working copy. A separate checkout of a repository on its own branch. Git calls an extra one a worktree.

Agents work in parallel, each on its own branch in its own working copy. If they share one local database, one session’s test data breaks another session’s test.

So each working copy gets a slot: a local environment with the real schema, its own database and a seeded test user. One command starts the slot or reuses it, and another takes it down.

The slots look after themselves. Idle slots are reclaimed, and a session’s slot comes down when the session ends. A slot also refuses to run code from a branch that has fallen behind.

A slot never points at shared data. Where a service would call out, a local stand-in answers, and the browser asks before it leaves the local environment.

Fixtures reset the test data before each run, so a regression suite gives the same answer twice. An agent can run that suite on a slot and draft bug reports, with captioned video, for a person to approve.

11 Review before people see it

An agent reviews the branch before any person does, and the pull request opens as a draft.

Several reviewers run over the finished branch, one per concern: correctness, architecture, security, reuse and drift in the docs. Each reviewer is a separate session that sees only the ticket and the change. None sees the conversation that wrote the code, so none inherits the author’s reasoning.

Before the reviewers run, a build-and-lint pass compares the branch with its base, so only new problems count.

The review leaves a record of which reviewers finished and what each one found. A hook refuses to open a pull request for a commit with no record. The agent opens it only as a draft, and a person reads it and publishes it.

On a teammate’s pull request, each finding is checked against the code before anything is posted, and a person approves every comment.

A finding that won’t be fixed now is deferred to a ticket. A gate flags a deferred finding whose ticket closed without a fix.

When a defect gets past a review anyway, an escape review asks what kind of miss it was. The fix goes into the review itself, so the next defect of that kind gets caught.

12 Unattended runs and model tiers

An agent can run a plan alone when the plan says how it will know it’s done, and what to do when it isn’t.

Name the tier for every task you hand off. A helper that quietly inherits the strongest model costs the most and gains nothing. A hook refuses a handoff that names no tier.

Delegating saves context, not tokens. A helper reads widely so the main session doesn’t have to. The bill drops only when the helper runs on a cheaper tier or at lower effort.

Where judgment is needed, nudge instead of forcing. A hook can suggest a cheaper tier when a request looks mechanical, and the session decides.

13 Work survives a handoff

A second person can pick up a task midstream, because each kind of state has exactly one home.

The workspace is not a status tracker. Ticket status changes daily, and a workspace that copied it would be wrong by morning.

A fresh session, or a teammate, reads all three and carries on. After the merge, one request closes the loop: “do the bookkeeping” handles the subtasks, the pin, the generated maps and the leftover branches.

14 Drift gates

Generated maps and docs go stale quietly. Gates make the staleness fail loudly.

CI. Continuous integration: the checks a server runs after every push.

Run the gates before each commit and again in CI. A teammate who never installed the hooks is still caught after the push.

A commit gate checks a snapshot of exactly what is being committed, not the folder around it. Another session’s unsaved edits can’t make it pass or fail.

15 Hooks in the agent’s runtime

Hooks act at the moment of the action. They remind where judgment is needed, and refuse where a mistake is costly.

Hook. A small script the agent tool runs on its own at a set moment, such as before an edit or when a session starts.

A rule written only in prose gets broken. When the same mistake shows up twice, turn the rule into a hook.

Each hook has its own test cases, which run like any other test. Without them, a hook can stop firing and nobody notices.

Keep secrets out of the agent’s shell. Load each one only for the command that needs it, and scan every commit for credentials.

16 Testing the guidance

A small change to a playbook can change what an agent does. Eval cases catch that before it ships.

Eval. Short for evaluation: a repeatable test of how an agent behaves on a set task.

A wording change can change which procedure an agent picks. Without cases, nobody notices until the agent starts doing the wrong thing.

Each case runs twice: with the playbook and without it. A playbook stays only while it beats the bare model. If it doesn’t, the model has caught up, and the playbook is noise.

A gate refuses a push that changes a playbook unless its cases have a passing run on record. A routing suite checks that everyday requests reach the right playbook. A before-and-after run shows what each change made better or worse.

Run the cases on the smaller models you hand work to. A playbook that routes correctly only on the biggest model fails as soon as a cheaper one picks it up.

When an agent goes wrong in real work, the failure becomes a new case before the fix merges. New playbooks follow the same rule: write one only after a baseline test shows the bare model failing at the task.

17 Changing the machinery

Docs change freely. The scripts, hooks and CI that check them take a stricter path.

A doc change goes straight to the main branch, and the gates check it after the push. Low friction is the point: fixing a doc should cost almost nothing.

A change to the machinery is different, because a broken gate stops everyone. It goes to its own branch first and merges only after CI passes on Windows, macOS and Linux. A hook refuses a direct push of machinery to the main branch.

A nightly job clones the workspace from nothing and follows the README, the way a new teammate would. A step that works only on the author’s machine fails there first.

18 How you know it works

The measure is a person, not the workspace: a teammate ships a real fix through it without asking the author anything.

Every question a teammate has to ask is evidence. It marks context the workspace failed to carry, so log it as a gap and fix it where the next person will look.

Size and polish measure nothing. A large, well-made workspace that people route around has failed.

The first real test is a teammate cloning it from zero with only the README. Every stumble becomes a doc fix. After that, the nightly clone keeps the test running.

Ownership has to spread too. Whoever finds a gap fixes it, with their own agent. A workspace that only its author edits is still a notebook.

19 What changed in 2.0

Version 1.0 worked for its author. Version 2.0 is built for the next person.

Models got better at reading code, and that changed what is worth writing down. Version 1.0 spent many pages on things a model now works out for itself. Version 2.0 cut those and kept what a model cannot derive. As models improve, a good workspace gets smaller and sharper.

One thing is deliberately not built: an installer that sets up a workspace for a new project. It waits until a second team actually needs one. A generator nobody runs is exactly the unused tooling this pattern exists to prevent.

20 Start your own

Start with the facts only you know. Add machinery when you hit the problem it solves.

Don’t build the whole thing up front. Each piece earns its place by fixing a problem you have actually hit.

21 Glossary

Agent

An AI coding tool that reads, edits and runs code in a session.

Contract

The one rules file every tool reads, often named AGENTS.md.

Task router

A table that turns “I want to…” into the right procedure.

Playbook

A procedure, in plain markdown, that an agent can run on request.

Wrapper

A few lines in one tool’s format that point at a playbook.

Hub

The index page at the top of a docs area, giving its reading order.

Search alias

An everyday word mapped to the name the code uses.

Code map

A generated list of a repository’s components and routes, each with a file and line.

Pin

The exact commit of a code repository that the workspace points at.

Drift gate

An automated check that fails when a doc stops matching the code.

Hook

A script the agent tool runs at a set moment, such as before an edit.

Eval case

A test for a playbook: a request, a scaffold and graders.

Decision record

A short page on a hard-to-reverse choice, its options and what it gave up. Often called an ADR.

Size gate

The test that sends small work straight to a failing test.

Hand-off plan

A plan an agent can run alone, with success criteria, checks, non-goals and a recovery rule.

Slot

A disposable local environment for one working copy.

Review record

The note an agent review leaves: which reviewers ran and what each found.

Bookkeeping

The cleanup after a merge: subtasks, pins, maps and leftover branches.

Question log

The record of every question someone had to ask a person. Each one is a gap.