Context Management

PP Core treats the AI's context window as scarce and unreliable, so it never relies on conversation history to remember anything that matters. State lives on disk in the .planning/ directory, which means work survives session boundaries, context resets, and the gradual decay that sets in as a chat grows long.

The Problem With Conversation Memory

An AI coding session keeps every message it has ever seen: the productive steps, the detours, and the dead ends alike. As the window fills, the model's attention spreads thin and its answers drift. Worse, the moment the session ends, all of it is gone. The next session has no idea what was decided yesterday, which conventions were chosen, or why a trade-off was made the way it was. PP Core is built to neutralize both failures by externalizing memory.

Durable State on Disk

Two documents carry the project's continuity between sessions.

STATE.md is the living memory of the project. PP Core updates it after every significant action so it always reflects the current position in the phase loop, the decisions in force, any open blockers, and progress metrics. When you begin a new session, running /pp-progress reads STATE.md and tells you precisely where you left off and what to do next, without you having to reconstruct anything by hand.

continue-here.md is a structured handoff written by /pp-pause-work. Where STATE.md is a standing snapshot, this file captures the momentum of a session in progress: what was just finished, what is mid-flight, the concrete next steps, and any questions still open. It exists so that stopping in the middle of a phase is safe.

Because both files, along with every other artifact, live under .planning/, the guiding principle is simple: nothing important is held in the conversation, so clearing context loses nothing of value.

Resuming Without Re-Reading History

When you pick work back up, /pp-resume-work reads both STATE.md and continue-here.md and uses them to restore the full picture. The agent arrives already oriented to the project, its decisions, and the task at hand, without having to replay the entire transcript that produced them. You do not re-explain the project; the files do.

session ends
   │
   ├─ STATE.md          ← standing snapshot of phase position + decisions
   └─ continue-here.md  ← mid-phase handoff (in-progress work, next steps)
   │
session resumes  →  /pp-resume-work reads both  →  agent is grounded

Keeping Agents Grounded

Beyond cross-session recovery, PP Core keeps agents grounded during a session too. The specialist agents each run in a fresh, isolated context window and receive only the artifacts relevant to their job, so they reason against a focused brief rather than a cluttered history. A lightweight bridge file tracks real-time context usage between tool calls, allowing PP Core to warn an agent before its window is exhausted and steer it to checkpoint its work to disk in time.

Why It Matters

This discipline is what lets PP Core run genuinely long projects. Every decision is anchored to a file, every session can hand off cleanly to the next, and no agent has to trust a fading memory to know what is true. The conversation becomes disposable; the .planning/ directory becomes the source of truth.