How work stays coherent across sessions
An AI coding agent forgets everything between sessions. Brilliant for an hour, a stranger the next morning. Nothing holds unless it's written where the agent reads it. This is the system that holds it: six layers keep the state, three processes move work between them, and one constraint keeps the whole thing from getting heavier than the work it protects. Adopt one layer today; add the rest as you feel the drift.
This is the state half. The code half — how a codebase stays organized as it grows — lives on /architecture.
The engine — three processes, all converging on the ledger
Open a layer above, or walk the system stage by stage
The walkthrough, as text
Every stage of the interactive walkthrough above, as plain readable text. Each stage has its own link.
Stage 0The rules that load firstCLAUDE.md + Memory, loaded every session
The instruction layer
CLAUDE.md and the memory/ files load before any work starts and stay loaded every session. Every later decision happens inside those rules, not against them. This is the one layer you never open on purpose — it's already there, governing everything below it. A lesson only becomes a permanent rule after it survives three audits, generalizes, and reduces to one line.
The always-on layer. Two stores load on every session and govern the five layers below. It also decides what's even allowed to become a rule.
What happens
Two stores load before the first line of work and stay loaded the whole session. CLAUDE.md is the constitution: how the agent works, what scope a change may take, the build-and-test gate, the security posture. Memory is accumulated knowledge — who you are, settled preferences, and the lessons that graduated from experience. Together they're the top of the stack: the most stable layer, rarely rewritten, governing every layer under it. You don't visit this layer. It's the field the rest of the work happens in.
The instruction layer governs its own growth, so the always-on prompt stays small and true. A lesson doesn't become a rule because it sounded right once. It earns in through the promotion gate: it survives three audits without being walked back, it generalizes beyond this one project, and it reduces to a single line. Then /end-session promotes it into memory/, where it loads forever after. Memory is where the lesson ratchet deposits — the one way the volatile bottom of the stack feeds the stable top.
Who acts
- CLAUDE.md, rule: The constitution. How the agent works, what scope a change may take, the build/test gate, the security posture. Loaded every session, before anything.
- memory/, constant: Accumulated knowledge: who you are, settled preferences, and lessons that graduated from experience. Governs every layer below, and receives what the lesson ratchet promotes.
- the promotion gate, gate: The bar a lesson clears to become permanent: survives three audits, generalizes past this project, reduces to one line. Run by /end-session's lessons audit.
The rules
- Loads first, governs everything. CLAUDE.md and Memory load before any work and stay loaded. Every later decision happens inside them, not against them. It's the most stable layer, at the top of the stack.
- Survives three audits. A lesson that gets walked back under pressure was never a rule. Three clean passes, or it stays an observation on the ledger.
- Generalizes past its first case. If it only explains the one bug that spawned it, it's a fix, not a rule. A rule generalizes beyond this project.
- Reduces to one line. If it can't be stated in a single line a tired person can follow at 2am, it won't get followed. Then /end-session promotes it, and it loads forever after.
In: Nothing. The instruction layer loads before anything else runs. Out: The rules every layer below is bound by, plus the gate that decides what becomes one.
Stage 1Vision, Global Plan, CampaignThe destination, the route, and one live effort
The plan hierarchy
Under the rules sit three layers of intent, from most stable to least: Vision & Identity is where the project ultimately lands; the Global Plan is the sequenced route from today to that vision; a Campaign is the one multi-phase effort active right now. Each decomposes the one above it — the vision into a route, the route into campaigns, a campaign into Phases and Steps.
Three layers of intent, ordered by stability: the destination that rarely changes, the route to it, and the single effort in flight. Each is the decomposition of the one above.
What happens
Vision & Identity is the yardstick: where the project ultimately lands, plus the stable brand and style constraints beside it. It rarely changes, which is why it sits high in the stack — everything downstream is judged against it. Below it, the Global Plan is the route, A to Z: the major efforts in order, and a plain "you are here." It decomposes the vision into campaigns and links down to each one's plan, so "what's next" is never a guess.
A Campaign is one multi-phase effort — a module, a feature, a redesign, a refactor. It breaks into Phases, then Steps, and owns its own plan document. Only one is active at a time. Its live position isn't copied around; it's tracked by the ledger below, which points at the breakdown and never duplicates it. That single-source rule is what keeps the plan from drifting out of sync with the work: the plan holds the structure, the ledger holds the cursor.
Who acts
- Vision & Identity, journey: The destination, plus the brand and style constraints. The most stable of the three, and the yardstick everything downstream is judged against.
- the Global Plan, journey: The route, A to Z: the major efforts in order and a "you are here." Decomposes the vision into campaigns, links down to each plan.
- a Campaign, journey: One multi-phase effort at a time, broken into Phases then Steps, owning its own plan. Its live position is tracked by the ledger, never copied.
The rules
- Stable at the top, in flight at the bottom. Vision rarely moves, the plan moves as efforts complete, a campaign moves within a session. Ordering them by stability is why they're separate files.
- Each layer decomposes the one above. The vision breaks into a route, the route into campaigns, a campaign into Phases and Steps. No layer restates its parent; it refines it.
- One campaign active at a time. A single effort is in flight. The rest wait their turn on the Global Plan, so focus stays on one thing and the ledger tracks one cursor.
- The plan holds structure, the ledger holds the cursor. The campaign owns its breakdown; the ledger only points at where you are in it. The plan is never copied into the ledger, so they can't disagree.
In: The instruction layer, which binds how the plan can change. Out: A sequenced route and one active campaign, whose live position the ledger tracks.
Stage 2The Stack, and the parking lotThe ledger everything converges on, plus Standing follow-ups
The live hub
The Stack is the ledger: the single always-current file for the active campaign — where you are, what's parked locally, the lessons so far, and the handoff to the next session. It's air traffic control: reads up to the plan, tracks the campaign's cursor, feeds lessons up to Memory. Beside it, low and loaded on demand, is the parking lot: the Standing follow-ups that can't finish inside any one campaign.
The most volatile state, rewritten every session, where anti-drift, continuity, and lesson-accrual all happen at once. The parking lot sits lowest, loaded only when needed.
What happens
The Stack is the live hub, the one file that's always current. It carries where you are in the active campaign, what's parked locally, the lessons accrued so far, and the handoff to the next session. It's the busiest, most volatile layer — rewritten every session, which is exactly why it's a separate file from the stable layers above. It reads up to the plan (never copying it), parks and retrieves with the parking lot, and feeds proven lessons upward into Memory. Anti-drift, continuity, and lesson-accrual, all in one place.
The parking lot (Standing-FUs.md) is the lowest layer, and the only one not loaded every session — that's deliberate, to keep context lean. It holds cross-cutting tasks that can't finish inside any one campaign, or that wait on a trigger: an Nth occurrence, a date, an aggregated pass. It receives promoted items when a phase closes and is drawn down when a trigger fires. Kept light: plain bullets, no heavy taxonomy. Together, the Stack and the parking lot are where every process converges.
Who acts
- STACK.md, state: The live hub: where you are, what's parked, lessons so far, and the handoff /start-session reads and /end-session rewrites. Rewritten every session.
- Standing-FUs.md, comet: The parking lot: cross-cutting tasks that wait on a trigger, not bound to any one campaign. Loaded on demand, receives phase-close promotions, kept light.
- the plan above, journey: The ledger reads up to the campaign plan for structure and tracks the cursor within it. It points; it never copies.
The rules
- Read at open, rewritten at close. Every session starts by reading the ledger and ends by rewriting the handoff. This one habit kills most of the drift on its own.
- Everything converges here. All three processes land on the ledger: session bookends maintain it, the follow-up lifecycle parks and retrieves through it, the lesson ratchet accrues in it.
- Points at the plan, never copies it. The ledger tracks the campaign's cursor by pointing up to the plan. Copying the breakdown down would let the two drift apart.
- The parking lot is loaded on demand. Standing follow-ups don't load every session, to keep context lean. They're trigger-gated, drawn down when the trigger fires, and kept to plain bullets.
In: The active campaign's plan, read for structure and the current cursor. Out: Continuity across sessions, and proven lessons fed up into Memory.
Stage 3The three processesBookends, follow-up lifecycle, lesson ratchet
The engine
The layers are inert documents; nothing moves them but three routines, and all three converge on the ledger. Session bookends open and close each session. The follow-up lifecycle routes each discovery to the right home, batches like with like, and garbage-collects at phase close. The lesson ratchet is how a repeated observation climbs from the ledger up into permanent Memory.
The engine that moves work between the layers. Three processes, all landing on the ledger, each backed by a slash-command so the system runs the same way every time.
What happens
Session bookends are the frame. Open reads the ledger and restates where you are. Close writes the handoff, files any new follow-ups, runs the lessons audit, and commits. Between them, every layer above stays maintained. The follow-up lifecycle is the routing: on discovery, route by kind — a bug by severity, a nice-to-have through a relevance filter — record it as local (on the Stack) or standing (in the parking lot), batch like items together, execute, and garbage-collect at phase close so nothing is left orphaned.
The lesson ratchet is the climb. A lesson earns a tally each time it proves useful. Clear the bar — recurs enough to survive three-plus audits, generalizes beyond this project, states in one line — and it graduates into permanent Memory, loaded forever after. This is the arc that curves from the ledger at the bottom of the stack back up to the top: the volatile layer teaching the stable one. Each process is backed by a command (/start-session, /end-session, /cluster-fus, the cleanup pipelines), so the system holds the standard, not your memory.
Who acts
- Session bookends, contract: Open reads the ledger and restates position; close writes the handoff, files follow-ups, runs the lessons audit, and commits. To /start-session, /end-session.
- Follow-up lifecycle, comet: Route each discovery by kind, record as local or standing, batch like items, execute, and garbage-collect at phase close so nothing is orphaned. To /cluster-fus and the cleanup pipelines.
- the lesson ratchet, shared: A lesson tallies each time it proves useful; clear the bar and it graduates into Memory. The one path from the volatile bottom up to the stable top.
The rules
- Every process converges on the ledger. The layers are inert. Bookends maintain the ledger, the follow-up lifecycle routes through it, the ratchet accrues in it. All roads lead to the Stack.
- Bookends maintain every layer above. Open restates position; close writes the handoff, files follow-ups, audits lessons, commits. Git history is the forensic trail.
- Route by kind, garbage-collect at phase close. A discovery is routed local or standing by its kind, batched with its like, and swept at phase close so nothing gets orphaned.
- A lesson ratchets, it doesn't teleport. It earns a tally each time it proves useful and only graduates after three-plus audits. One line, generalizes, or it stays on the ledger.
In: The six layers of state, and every new observation the work turns up. Out: Maintained layers, a routed backlog, and lessons promoted up into Memory.
Stage 4Lighter than the problemThe process stays lighter than what it solves
The one constraint
One rule governs the whole system: the process must stay lighter than the problem it solves. It's scaled to the stakes, not minimized for its own sake. Heavier problems — money, security, data — earn more ceremony; trivial ones earn less. If tracking a thing costs more than the thing is worth, you don't track it.
The governor on the whole system. Ceremony scales to stakes: more for money and security, less for the trivial. When the tracking costs more than the thing, stop tracking.
What happens
Every layer and every process above is optional weight. The constraint is what keeps them honest: a system that costs more than it saves is a worse system, no matter how complete it looks. So ceremony scales to stakes. A change that touches money, security, or data earns the full pipeline — plan, critics, adjudication, tests. A typo fix earns a one-line commit. Same system, different weight, chosen on purpose.
This is also the on-ramp. You don't need all six layers on day one. In order of leverage: write CLAUDE.md first (biggest return for the least effort), then STACK.md as the live handoff you read at open and rewrite at close (this alone kills most drift), then Standing-FUs.md as a parking lot, then GLOBAL-PLAN.md once the work spans more than a couple of sessions. Adopt one layer, feel where it's still drifting, add the next. The constraint decides when to stop.
Who acts
- scaled to the stakes, gate: Ceremony matches the cost of being wrong. Money, security, and data earn the full pipeline; trivial changes earn a one-line commit. Not minimized, right-sized.
- the cost test, rule: If tracking a thing costs more than the thing is worth, you don't track it. The constraint that keeps the system from outgrowing its own value.
- the on-ramp, state: Adopt in order of leverage: CLAUDE.md, then STACK.md, then Standing-FUs.md, then GLOBAL-PLAN.md. One layer today, the rest as you feel the drift.
The rules
- Lighter than the problem, always. The process must cost less than the drift it prevents. A system heavier than its payoff is a net loss, however thorough it looks.
- Ceremony scales to stakes. Heavier problems earn more process; trivial ones earn less. It's right-sized to the cost of being wrong, not minimized for its own sake.
- The cost test is explicit. If tracking a thing costs more than the thing is worth, you stop tracking it. That call is made on purpose, not by neglect.
- Start with one layer. You don't need all six on day one. CLAUDE.md first, then the ledger, then the parking lot, then the plan. Add each as you feel the need.
In: The full system: six layers, three processes. Out: A system right-sized to its stakes, and a four-step path to adopt it from zero.
Stage ✓Where we're least sureThe open questions, named
// where we're least sure
The honest edge: the parts of the model genuinely unsettled, named plainly so you can push on them. Reply on LinkedIn or open a GitHub issue. The work gets sharper when it gets challenged.
The honest edge of the model. Three open questions, named plainly, with two ways to push back: reply on LinkedIn or open a GitHub issue.
What happens
Here's where the model is soft. Each of these is a place it could be wrong, and it gets sharper when someone who does the work pushes on it. The six-vs-fewer question below is the one least settled.
Two ways in. Reply on LinkedIn for a conversation, or open a GitHub issue to track it against the artifact. Both land on a named question, not a contact form.
Who acts
- six layers, or fewer, question: Six is honest for a project this size, but the on-ramp starts at two. Is six the real shape, or a big project's shape drawn as if it were universal? Reply on LinkedIn.
- does the ledger scale down, question: On a solo weekend project, is rewriting STACK.md every session worth it, or does the constraint say drop it? Where's the real break-even? Tell us on LinkedIn.
- is stability the right axis, question: The stack is ordered by how often a layer changes. Is churn the axis that matters, or is it a proxy for something truer, like blast radius? Reply on LinkedIn.
The rules
- Six is a ceiling, not a floor. The full system has six layers; the on-ramp starts at two. Whether six is the true shape or just a large project's shape is surfaced here, not hidden.
- The constraint has to hold at small scale too. If the ledger isn't worth its weight on a weekend project, the one constraint says drop it. Where that break-even sits is still open.
- Stability is the chosen axis, on purpose. Layers are ordered by how often they change. Whether churn is the right axis, or a proxy for blast radius, is a fair place to push.
- Two reply paths, no sales surface. Reply on LinkedIn or open a GitHub issue. Each goes to a named question. Neither is a contact form or a pitch.
In: The full model: six layers, three processes, one constraint. Out: Your pushback, on LinkedIn or as a GitHub issue, and a sharper model.