English | 简体中文

Project Context Lifecycle

A platform-agnostic protocol for managing the context of long-running projects, written for people who use AI (Claude Code / Codex / any agent) on long-running, cross-session, multi-workstream work.

The core claim in one line: however long the context window gets, don't stuff everything about a project into one ever-growing chat log. A window that can hold it all is not the same as a model that can reliably find, compare, and correctly use what actually matters inside it. Past a certain length, the first thing a model loses is usually not memory but judgment — it starts going along with you instead of pushing back.

This protocol does not solve the problem by "clearing the chat." It puts information of different kinds into different containers, so that each new session carries only the part of its brain the current task needs.

What it solves

Mixing "why we're doing this" and "how to do this step" in the same chat forces the model to re-read early open-ended discussion while handling the implementation detail in front of it — rewriting the "why" with the "how" at every step. Over time it loses focus.

Project Context Lifecycle splits project context into three layers, each with a single authoritative file:

• project context (project-brief.md) — project-level stable facts: goals, deliverables, hard constraints, confirmed key decisions. Not rewritten with every day's execution detail.
• workstream (workstreams/<name>.md) — the full state of one continuous line of work: goal and boundary, input dependencies, what was tried, where the evidence and artifacts are, what open questions remain. Can span many sessions, but serves only this one line.
• handoff (handoff.md) — not a long chat summary but a recovery card: what phase we're in, what was just finished, where the active workstream is, what the next step is, and the fewest files the next session should read.

When the three are mixed, every new session is forced to inherit an entire life story; once separated, a new session simply sets out again carrying only the brain the current task needs.

Four modes

The protocol governs how a project's context flows from kickoff to wrap-up through four explicit modes, rather than leaving it to the AI's discretion:

Mode	When	What it does
init	Project kickoff	Locate the project root and real consumers, create only the files needed now, initialize the handoff
intake	New-session recovery	Read only the common anchors + the one workstream relevant to the current task; do not swallow all history
handoff	Switching session / workstream / phase	Update the authoritative files that changed first, then overwrite the handoff recovery card
archive	Workstream or phase wrap-up	After the result is absorbed downstream and no state is left untransferred, snapshot the archive

For the full document model, state ownership table, single-source-of-truth rule, and state tests, see SKILL.md.

How to use it

SKILL.md is a platform-agnostic skill core with standard frontmatter (name + description), usable directly as an agent skill.

Its design follows a core / adapter split: the core protocol (that file) is platform-agnostic; each platform writes only a thin adapter that handles discovery, explicit triggering, and platform-specific paths, without copying the core rules. To wire it into your own agent:

1. Put SKILL.md in your skill directory (per each platform's convention — Claude Code, Codex, etc.).
2. If the platform needs it, add a few-line adapter pointing to it, supplying only the platform-specific triggers and paths.
3. In a project, use init to set up the structure, then intake to recover and handoff to hand off across sessions.

Companion article

"1M context is not the same as owning a 1M GPT-5.6 — why I still keep a single conversation under 200K" (in Chinese). The article lays out the judgment behind this protocol: how judgment quietly degrades in long context, and why you should give the model "a fresh brain" rather than "wipe its memory."

License

MIT © Eric Sun