Cross-Session Project State

Keep long-horizon work coherent across many sessions: externalized project state that any session can load, advance, and hand off.

4 steps12 verify checks90-120 minutesWorks with: emergent · chatgpt · claude · cursor

Start Guided Walkthrough

#project-state #long-horizon #handoff #continuity #external-memory

The Route

0/4 verified

Design the project-state document

The document a stranger could continue from is the standard.

3 checks 02

Implement the session-start protocol

Orientation before action, every single time.

3 checks 03

Implement the session-end advance

A session that does not advance the state never happened.

3 checks 04

Run the multi-session and handoff tests

Continuity is the claim - test it like one.

3 checks

Every step ends at a Verify Gate. Do not continue until every check passes.

Context Pack

Paste this first. It briefs the AI on requirements, constraints, and the Definition of Done before your first build prompt.

Context Pack

PROJECT CONTEXT:
My project spans dozens of agent sessions and each one starts half-blind: re-discovering the plan, redoing analysis, contradicting past decisions. Long-horizon research (external memory architectures, handoff patterns) treats project state as a first-class external artifact.

GOAL:
Build an externalized project-state system: a canonical state document maintained across sessions, with load, advance, and handoff protocols.

REQUIREMENTS:
- A canonical PROJECT_STATE document: goal, milestones, current position, decisions, blockers
- A session-start protocol loading state and orienting the agent
- A session-end protocol advancing state with what changed
- Handoff quality: a brand-new session (or agent) can continue without human re-explanation
- State-vs-reality validation to catch drift (state says X, code says Y)

CONSTRAINTS:
- The state document is the single source of truth - sessions serve it, not vice versa
- State updates record deltas with dates, never silent rewrites of history

DEFINITION OF DONE:
- Session N+1 continues exactly where session N stopped, verified across a 5-session task
- A cold-start handoff test passes: fresh context, state doc only, correct continuation
- Decisions made in early sessions are honored in late ones
- Drift between state and repository reality is detected and flagged at session start

COMMON FAILURES TO AVOID:
- 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

Paste this into your AI builder first. It teaches the AI what you want before you give it the build prompt.

Definition of Done

You are not done until every one of these is true.

Session N+1 continues exactly where session N stopped, verified across a 5-session task
A cold-start handoff test passes: fresh context, state doc only, correct continuation
Decisions made in early sessions are honored in late ones
Drift between state and repository reality is detected and flagged at session start

Do not call it shipped if…

What AI builders commonly fake or get wrong on this goal.

!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