| name | three-file-memory |
| description | Project state tracked in exactly three markdown files — roadmap.md (queue), currentactions.md (ONE task in flight), alreadybuilt.md (append-only ledger). Use at the start of any project work session, when picking up or finishing a build task, when the user asks "what's next / where were we / what's shipped", or whenever project plans change. Enforces one-task-at-a-time and the conservation rule: nothing leaves the roadmap except into currentactions. |
three-file-memory
Project memory lives in exactly three files at the project root. Each has one
job, one direction of flow, and rules that are cheap to follow and expensive
to break:
roadmap.md ──pull──▶ currentactions.md ──ship──▶ alreadybuilt.md
(queue, (ONE task, (ledger,
reorderable) always current) append-only)
If a project already has a cased variant (ROADMAP.md), use it as
roadmap.md — match the existing case, never create a duplicate.
The three files
roadmap.md — the queue
Everything planned but not started. Ordered by priority (top = next pull).
Freely edited: add, reorder, split, re-scope, delete-with-reason. Each entry
needs enough detail that future-you can pull it cold: what, why, and how
you'll know it's done.
currentactions.md — the spotlight
Holds exactly one task/build at a time. Never two. Never zero-with-work-
in-flight. This file is the first thing read at session start and the last
thing updated at session end. It carries:
- The task (copied verbatim from roadmap, then enriched)
- Status:
QUEUED → IN PROGRESS → VERIFYING
- A live checklist of sub-steps, updated as work happens
- Blockers and open decisions, so a cold session can resume in one read
alreadybuilt.md — the ledger
Append-only. New entries go at the top, with date and a one-line
verification status (tested / previewed / typechecked / UNVERIFIED because X). Never edit or delete past entries — if something shipped broken,
that's a new roadmap item, not a revision of history. The ledger is how the
project proves to itself it's moving.
The two laws
Law 1 — Conservation (the big one)
Never remove anything from roadmap.md without, in the same working step
(immediately before or immediately after), writing it into
currentactions.md. A task exists in exactly one file at all times. The
failure this prevents is silent loss: a plan deleted "for now" that nobody
remembers to restore. Deleting a roadmap item permanently is allowed, but
only deliberately — move it to a ## Retired section at the bottom of
roadmap.md with one line of reasoning. Retired ≠ vanished.
Law 2 — One in flight
currentactions.md holds one task. Before pulling the next item from the
roadmap, the current one must leave — by shipping to alreadybuilt.md, or by
being demoted back to roadmap.md with a note explaining why it went back
(blocked, deprioritized, wrongly scoped). Demotion is legal; limbo is not.
If a task turns out to contain two tasks, split it: keep the half you're
doing, move the other half to roadmap before continuing.
The rituals
Session start: read currentactions.md first. If a task is IN PROGRESS,
resume it — do not pull new work, do not start side quests. If the file says
IDLE, pull the top roadmap item: paste it into currentactions.md, then
delete it from roadmap.md (that order, so a crash mid-edit duplicates rather
than loses).
During work: keep the currentactions checklist honest in near-real-time.
New ideas discovered mid-task go to roadmap.md immediately — never into the
current task's scope, and never into your head.
Ship: when the task is done and verified, write the alreadybuilt.md
entry (date, what shipped, verification status, one line of where), then
clear currentactions.md to IDLE (or pull the next item in the same breath).
"Done" without a verification word is not done.
Session end: currentactions.md must describe reality — exact stopping
point, next concrete step, any command that must be re-run. Write it for a
stranger; the stranger is you next week.
Edge cases, decided in advance
| Situation | Rule |
|---|
| Urgent interrupt (prod fire, user request) | Demote current task to the TOP of roadmap with a "paused at:" note; pull the interrupt in. One in flight, always. |
| Task fails / approach abandoned | Ship nothing. Demote to roadmap with the post-mortem note, or Retire it with reasoning. alreadybuilt.md never records attempts, only builds. |
| Tiny fix (< a few minutes) mid-task | Do it, and note it in the current task's checklist as a rider. Don't ceremony it — but if the "tiny fix" grows, stop and split honestly. |
| User asks "what's next?" | Answer from roadmap.md top three, verbatim. If the answer isn't in the file, the file is wrong — fix the file. |
| Conflict between files (task in two places) | currentactions.md wins; delete the duplicate elsewhere and note the correction. |
Templates
Starter templates for all three files: references/templates.md.
