Step 1 of 4
Design the project-state document
The document a stranger could continue from is the standard.
Design PROJECT_STATE.md. Sections: GOAL (the outcome, verbatim from the owner), MILESTONES (ordered, with status: done/active/pending and completion evidence for done ones), CURRENT POSITION (exactly where work stands: active milestone, last completed step, the very next action), DECISIONS (dated: decision, reason, alternatives rejected), BLOCKERS & RISKS (open issues with owner), WORKSPACE MAP (key files/dirs this project touches, one line each), CHANGELOG (dated deltas per session). Write the initial document for my actual project now, populating every section honestly - especially the next action, which must be executable as written.
Expected after this step
A populated PROJECT_STATE.md whose next action is executable as written.
Should not happen
- ✕Plans living in chat history, evaporating at session end
- ✕State documents that describe the past but not the current position and next action
- ✕Sessions editing state destructively so history and rationale vanish
- ✕State drifting from code reality until it misleads instead of orients
Verify before continuing
Do not move on until every check is true. The complete button stays locked until then.
Do not continue if…
- !Plans living in chat history, evaporating at session end
- !State documents that describe the past but not the current position and next action
- !Sessions editing state destructively so history and rationale vanish
- !State drifting from code reality until it misleads instead of orients
If the AI messes this up
Use this when the AI fakes progress or breaks the feature. It forces a real fix.
CURRENT POSITION is vague ('working on backend'). Rewrite to the resolution of a single next command or edit: a stranger with this doc should know exactly what to do in the first five minutes.