Agent workspace starter

A project instructions template that keeps status, facts and history apart so agents stop working blind.

When to use it: When you set up a folder or project that an AI agent will work in for weeks.

Save it as CLAUDE.md

# [Project name]: workspace instructions

Read this file first, then `STATUS.md`. Together they are the whole orientation. Open everything else on demand.

> If your tool does not reliably load this file on its own (cloud sessions, restarted sessions), put this line in the project instructions field: "Before anything else, read `CLAUDE.md` and `STATUS.md` at the root of the [project] folder, then the `CLAUDE.md` of the subfolder the task touches. When I report an event, update `STATUS.md` in the same turn."

## Who I am
[Your name, role and how you want the assistant to behave. For example: "Be a sharp, practical collaborator, not a yes-machine. Direct and concise, no preamble. Produce the thing when asked instead of opening with clarifying questions, unless something is genuinely ambiguous. Honest critique over empty validation."]

## What this is
[Two to five lines on the project and its parts.]

## The four document types
Every file here is one of four things. Mixing them is what causes drift.

| Type | Holds | Changes | Where |
|---|---|---|---|
| `CLAUDE.md` | How to work here: rules, conventions, confirmed facts | Rarely | Root and each major subfolder |
| `STATUS.md` | Where everything stands now and what is next | Whenever something happens. Edited in place | Root only. One file |
| Reference docs | Plans, specs, research, templates, design rules | When the work changes | Beside their subject |
| `log.md` and `delivered.md` | Dated history: decisions, what actually shipped | Append only. `delivered.md` is written the same day | In the folder of the thing they record |

## Three rules

**Status appears in `STATUS.md` and nowhere else.** If another file needs to say where something stands, it links. "Next step: send the draft" belongs in `STATUS.md` even when it feels natural to write it elsewhere.

**An event updates `STATUS.md` in the same turn.** When I report something that happened (a delivery, a message sent or answered, a decision, a number changed), edit `STATUS.md` before other work. Replace the line that changed and the date at the top. Never add a paragraph beneath an old one. Then update the subject's own record (`delivered.md` or `log.md`). An event not written down in the turn it is reported is lost.

**`CLAUDE.md` files carry facts, not state.** "Workshops are onsite because the exercises need someone circulating the room" is a fact and lives here. "Session 3 delivered on [date]" is state and lives in `STATUS.md`. Keep each instruction file under about 200 lines, and watch density as well as length.

## Map
```
[project]/
├── CLAUDE.md      instructions and this map
├── STATUS.md      the only status ledger
├── [folder]/      [what lives here]
└── shared/        anything used by more than one part. one source of truth
```

## Where things go
- [Type of work] goes in [folder].
- Anything used by more than one part of the project goes in `shared/`. Reference it, do not copy it.
- When in doubt, ask which layer something belongs to instead of guessing.

## Confidential material
- [Client or private data] never goes into `shared/`, demos or anything public. Generalize a learning only after stripping every specific from it.
- Never modify original source files. Any transformation writes a new file elsewhere.
- Never let two versions of the same number (a price, a date) exist in one folder. Update it and delete the old one.

## After something ships
- Write `delivered.md` beside it the same day: what actually went out, what changed at the last minute and what to change next time. It is the most valuable habit in a workspace and the easiest to skip, so prompt me for it.