Project Continuity

Version: 0.4.2

A lightweight on-disk continuity protocol for AI coding agents. Make sessions disposable while keeping project state, decisions, tasks, and handoffs persistent.

Repository = long-term memory
Session    = disposable worker
Context    = temporary working memory

The problem

AI coding sessions eventually run out of context. Traditional responses often look like:

• replaying the conversation;
• growing a giant context.md;
• summarizing history again and again;
• loading too much documentation “just in case”;
• depending on one long-lived agent session.

Those approaches treat the chat as memory. Chat is a bad database. It is lossy, expensive, and gone when the session ends.

Project Continuity does the opposite: the repository is long-term memory. The AI session is a disposable worker. The context window is temporary working memory.

A fresh coding agent should be able to reconstruct where a project stands from:

• a lightweight AGENTS.md kernel;
• tasks/ACTIVE.md;
• .agent/HANDOFF.md;
• Git state;
• selectively retrieved project documentation;
• the event-driven project-continuity skill.

It deliberately avoids giant context files, transcript replay, mandatory vector databases, and loading the whole repository every session.

How it works

Always loaded: the kernel

AGENTS.md is a small router. Every session it:

1. reads tasks/ACTIVE.md and .agent/HANDOFF.md;
2. inspects Git (status, relevant diff, recent commits);
3. continues from the verified next action.

The full protocol lives in the project-continuity skill and is loaded only when an event fires — bootstrap, a task change, a durable decision, a checkpoint, compaction, session end, or stale state.

Major components

AGENTS.md
→ lightweight always-loaded router/kernel

tasks/ACTIVE.md
→ pointer to current tracked work

.agent/HANDOFF.md
→ tactical latest-state snapshot

task files
→ goal, scope, acceptance criteria, current state

docs/architecture + docs/domains
→ durable system knowledge

docs/decisions
→ ADRs / important decisions and rationale

docs/runbooks
→ repeatable procedures

Git
→ actual change history and working-tree truth

Progressive disclosure

Load the smallest useful context first. Follow pointers. Do not ingest the whole tree.

AGENTS
→ ACTIVE
→ HANDOFF
→ relevant task
→ relevant docs
→ relevant source/tests

Other rules that keep it small

• Checkpoints — refresh on-disk state when reality moves a meaningful step, not after every command.
• Task lifecycle — backlog → in-progress → completed, with in-progress ↔ paused.
• Knowledge routing — each fact has one home; don’t duplicate it into a diary.
• Snapshots, not diaries — rewrite the present; don’t append session logs.
• Reality outranks summaries — source, tests, Git, and verified output beat a stale handoff.
• Lazy template loading — read only the template for the artifact being created.
• Git safety — inspect freely; don’t commit or rewrite history unless asked.
• One continuity writer per working tree — parallel agents use separate worktrees.

Invisibility

Project Continuity should not turn collaboration into bureaucracy.

You can still brainstorm, discuss architecture, ask questions, compare approaches, and plan for a long time without every conversation becoming a task or an ADR.

Lifecycle machinery engages when real work or a durable decision emerges. Bookkeeping happens underneath normal human–AI collaboration.

You do not need to say:

update ACTIVE.md
create a handoff
make an ADR
maintain continuity

Ask for the actual work:

Build authentication for this app.

The skill handles the rest.

Quick start

1. Install the project-continuity skill where your harness discovers skills.
2. Copy templates/AGENTS.md to the root of your repo.
3. Open a fresh coding-agent session.
4. Work normally.

You should not normally create these by hand:

tasks/
.agent/
docs/INDEX.md

The skill bootstraps them when it detects missing continuity state. Canonical empty directories also get a .gitkeep so they survive commit, push, and clone. The protocol does not git add or commit those files.

Full install notes: docs/installation.md.

Installation (Cursor / portable Agent Skills)

User-level install (example path used by this project’s authoring environment):

~/.agents/skills/project-continuity/
├── SKILL.md
└── assets/
    ├── ACTIVE.template.md
    ├── HANDOFF.template.md
    ├── TASK.template.md
    ├── ADR.template.md
    └── INDEX.template.md

Copy this repository’s skill/project-continuity/ directory to that location. Then put templates/AGENTS.md at the repository root.

General principle for other harnesses:

1. Install the Agent Skill somewhere the harness discovers skills.
2. Put the continuity kernel at the repository root as AGENTS.md.
3. Let the skill bootstrap the remaining structure.

Tool-specific discovery paths vary. Examples (not a guarantee that every tool uses all of these):

Harness (examples)	Typical skill locations
Cursor	~/.agents/skills/, ~/.cursor/skills/, project .cursor/skills/
Claude Code	~/.claude/skills/, project .claude/skills/
Agent Skills–compatible tools	a skill-name/SKILL.md directory on the tool’s documented search path

If a path above is wrong for your tool, follow that tool’s skill docs and keep the kernel at repo root regardless.

Real-world validation

We tested with fresh Cursor Agent sessions — no prior chat history in the later sessions.

Session 1

Empty repo plus AGENTS.md. The user only asked for a todo app.

The agent independently bootstrapped continuity, created and tracked the task, built the app, verified it, completed the task, and left resumable state on disk.

Session 2

A completely new agent. The user only asked:

Add the ability to edit an existing todo.

It reconstructed the existing project from disk and Git, then extended it correctly.

Session 3

Another totally fresh agent. The user typed:

hi

The agent inspected continuity state and Git and correctly determined what features already existed, that there was no active task, and that the working tree was still uncommitted.

Cold orientation used only a small portion of the available Cursor context. Most of the fixed context cost came from the harness and tooling itself, not from Continuity files. Those Cursor-specific observations are not a universal benchmark.

Conclusion: previous conversations were disposable; useful project state survived on disk.

Existing mature repository

Separately, v0.4.2 was adopted on one mature pre-existing project (Event Contact / Event Contact Normalizer; about 30 commits and substantial docs that predated Continuity). Conservative adoption inspected Git and existing docs, indexed them, and added continuity without inventing work or historical ADRs. A later, explicitly authorized documentation migration reorganized those docs while preserving Git rename history. Details: docs/case-studies/existing-repo-migration.md. This is one successful migration, not a claim that every repo will look the same.

Documentation

Doc	What it covers
docs/concepts.md	Repository over conversation; why forgetting is intentional
docs/architecture.md	Two-tier kernel + event-driven skill
docs/lifecycle.md	Tasks, discussion vs work, checkpoints
docs/installation.md	Install paths and bootstrap
docs/testing.md	Stress scenarios for contributors
docs/case-studies/existing-repo-migration.md	Mature-repo adoption (one v0.4.2 case)
docs/INDEX.md	Documentation router
examples/example-layout.md	What a bootstrapped repo looks like

Contributing

Improvements should come from observed failures, not theoretical feature accumulation. See CONTRIBUTING.md.

License

MIT. Use, fork, modify, distribute, and send evidence-based improvements.

Status

0.4.2 — current release. Clone-integrity fix for empty canonical directories. Not 1.0. Broader harness and model testing is still wanted.