Skip to main content

Project State Files (STATE.md)

In one line: A short, generated project-root file that answers "what is happening right now?" — the one question CLAUDE.md, ROADMAP.md, and memory files don't.

CLAUDE.md tells a fresh agent how this project works. ROADMAP.md tells it where the project is going. Memory files tell it what was learned. None answer the first operational question a fresh session has: what is happening right now?

STATE.md fills that gap. It is a short, project-root file (~30-50 lines) that captures the current state of work in a form a fresh agent can read in 30 seconds and immediately know:

  • Which milestone is in flight, and how far through it.
  • What the last shipped artifact was (commit SHA, task number, ADR).
  • What is currently blocked, and on what.
  • What the next dispatch will work on.
  • Pointers to the canonical documents (CLAUDE.md, ROADMAP.md, current plan, memory MEMORY.md).

Why STATE.md is a peer artifact, not a memory file.

Memory files live outside the repository, untracked by git, invisible to a fresh ls — they hold durable observations that travel across machines. STATE.md belongs in the project root because it answers "what's the current frame of work?" — an answer that changes weekly, must travel with the code, and must be visible in the tree without spelunking.

Updating STATE.md is part of finishing a development branch: when a feature lands, the "Last shipped," "Current focus," and "Blockers" lines are revised. A STATE.md that says "Task 4 in flight" when the latest commit shipped Task 8 is broken state — like a doc page that contradicts the code.

What STATE.md is not.

  • Not a daily journal. The cadence is per-shipped-artifact, not per-day. A project where seven tasks land in one day generates one STATE.md update, not seven.
  • Not a substitute for ROADMAP.md. ROADMAP.md describes the shape of the work (milestones, phases, decision history). STATE.md describes the position within that shape.
  • Not a substitute for the plan document. A plan describes the tasks and their dependencies. STATE.md says which task in that plan is in flight.
  • Not a substitute for memory files. Memory captures durable lessons; STATE captures ephemeral position.

The orientation budget.

A fresh agent's first 30 seconds set the conversation's trajectory. CLAUDE.md gives architectural context; STATE.md gives operational context. Together they answer "what does this project do, and what is happening right now?" without the agent running git log, scanning the tree, or guessing from PR descriptions — and every minute spent inferring context is a minute not spent working.

The canonical STATE.md template, with worked examples, is in Appendix J.