A new agent that already knows the project.
The first thing a fresh agent does is read the workspace — what the system is, what's already been settled, and how work is done here — before it proposes anything. The briefing lives with the data, so it never has to be given twice.
Every new agent starts at zero. You are the onboarding.
Think about what actually happens when you open a new agent on a project that's been running for months. It reads the code, which is real knowledge but the wrong kind — it tells you what the system does and nothing about what it's for, which parts are load-bearing, or which obvious improvement is obvious because three people already tried it.
So you fill the gap by hand. You explain the architecture, mention the two constraints that matter, remember the third one halfway through, and say "don't touch the migration path" in slightly different words than last time. Then the session ends and the next agent gets a slightly different version of the same briefing.
This is the same problem teams solved for humans decades ago, and the solution was never "explain it better each time." It was to write it down somewhere the newcomer is expected to look.
What a newcomer actually needs
Not everything. A small, stable set of documents at the root of the workspace does most of the work:
- What the system is. An architecture note describing the current shape — the services, the data stores, what's rebuildable and what isn't.
- What it's for. The product intent: who uses it, what shipped, what's deliberately out of scope.
- What's settled. The decision log — the constraints an agent should design around rather than rediscover.
- How to work here. The conventions: where new records go, what's append-only, what an agent should never write unprompted.
That last one is the piece most setups are missing, and it's the one that turns a folder of documents into an onboarding pack.
The conventions belong with the data
Drop an _markbase.md at any folder root and you've written
the contract for that subtree: what it's for, what the frontmatter
contract is, what's append-only, who writes here. Agents read the chain
root-to-leaf before acting on a path and apply what they find.
The difference from a CLAUDE.md in a repo is reach. That
file briefs one harness, on one machine, for one repository — and the
moment you add a second agent, a second machine, or a second project,
you're maintaining the same rules in several places and watching them
drift. A workspace briefs whatever connects to it, and there's exactly
one copy to keep current.
It reads as onboarding for people, too
None of this is machine-only. It's Markdown, and the dashboard renders it — so the same architecture note and the same decision log are what you hand a human joining the project on Monday.
Which is a useful test of whether the workspace is any good. If a new engineer can read it and be useful by lunchtime, an agent can too. If it reads as cryptic notes-to-self, both will struggle, and you've learned that before it cost you a sprint.
The second project shouldn't start empty
Each project gets its own workspace, but the layout you worked out doesn't have to be re-invented for each one. Agents can create a new workspace from a template, so a new project opens with the folder structure, the schemas and the conventions already in place.
And the knowledge itself crosses projects. Ask an agent to design a feature in the new project informed by the architecture decisions from the old one, and it can read both in the same conversation — so what you figured out once becomes the starting point rather than something to work out again.
In practice
First contact with a project it's never seen.
A fresh session, a workspace it has no history with. It orients from the conventions and the root documents before it has an opinion about anything.
What makes it work
Three primitives, doing the work.
Conventions inside the store
An _markbase.md at any folder root says what that subtree is for and how to write in it. Agents read the chain root-to-leaf before they act, so the briefing arrives with the data instead of from your config.
Written once, read by everyone
A CLAUDE.md briefs one harness on one machine. A workspace briefs whatever connects — a second coding agent, a research agent, another vendor's client, you next quarter.
New projects start furnished
Agents can create a workspace from a template, so project number four opens with the folder layout, schemas and conventions that projects one through three earned.
More use cases
Other jobs a shared workspace does.
- Decisions & precedent An agent that can't see why you chose Postgres over Redis will cheerfully propose Redis again. A decision log it can query turns settled questions into constraints.
- Session handoff Context windows end; the work doesn't. Write a handoff into the workspace and resume it in a fresh session — on another machine, or with another agent.
- Agents from different vendors Different models are genuinely better at different jobs. The one thing they have in common is MCP — so make the memory the thing they share.
- Parallel agent fleets Fan a job out across a fleet and they all reach for the same file. Every write says which version it's changing, so the loser of a race is told, not silently overwritten.
- Background & scheduled agents A nightly run has nowhere to put what it found. Give it a folder and the report is waiting in the morning — for you, and for the next run.
- Research & deliverables Agents produce spreadsheets, PDFs and rendered charts. Keeping them at the same paths as the notes that cite them is what makes the analysis reproducible later.
Free plan, no card
If you brief every new agent from memory.
If you can feel yourself giving the same project briefing for the fifth time this week, that's the signal. Write the briefing down once, somewhere every agent reads before it acts — free to try, no card.