khairold
← Back to Systems

The .plan/ protocol

Four files that replace standups, sprint planning, and handoff meetings when building with AI.

·
ProtocolAI CollaborationWorkflow

Every project I build with AI uses the same four files. They sit in a .plan/ directory at the root, and they replace most of what teams use Jira, standups, and Slack threads for.

This isn’t theoretical. I’ve shipped two products and a personal site using this protocol — each built across multiple sessions where the AI starts fresh every time with zero memory of what came before. The files are the memory.

The problem they solve

AI coding assistants have no persistent memory. Every session starts from scratch. This creates a specific failure mode: you make progress, close the session, come back tomorrow, and spend 20 minutes re-explaining context that existed yesterday.

The human equivalent is onboarding a new contractor every morning who’s talented but has amnesia.

Most people solve this by keeping context in their head and re-prompting. That works for small tasks. It falls apart the moment a project spans more than one session — which is every real project.

The four files

PLAN.md — where we are

The master plan. Phases, checkboxes, exit criteria. This is what the AI reads first to know exactly where things stand.

## Phase 2 — Content Collections & Page Templates

- [x] 2.1 — Define work collection schema
- [x] 2.2 — Define blog collection schema
- [x] 2.3 — Build /work page
- [ ] 2.4 — Build /work/[slug] page
- [ ] 2.5 — Build /blog page
...

Exit criteria: All pages render with content.
Navigation between all pages works.

The key design choice: phases, not a flat backlog. Each phase is self-contained — it delivers something testable. You can stop after any phase and have a working product. This matters because AI sessions have natural length limits, and you want clean stopping points.

I typically decompose into 3–5 phases. Each phase has 5–10 items. Each item is one task — if you can’t describe it in one line, split it.

MEMORY.md — what we decided and why

This is the file that changes everything. It holds every decision, every architectural choice, every gotcha — with rationale.

Here’s a real excerpt from khairold.com’s MEMORY.md:

## Key Decisions

| # | Decision | Rationale | Date |
|---|----------|-----------|------|
| 7 | No React — pure Astro components | Workers had MessageChannel issue with React in SG Legal SEO | 2026-03-01 |
| 8 | Hero subtext: builder-first tone | "I build things — products, tools, systems. AI is how I work." — user dislikes "copilot" terminology | 2026-03-01 |
| 10 | Switched to static output | Removed @astrojs/cloudflare adapter — no SSR needed | 2026-03-01 |

## Gotchas & Warnings

- MessageChannel issue: Cloudflare Workers + React don't play well — stick to pure Astro
- FOUC prevention: The inline theme script MUST stay in <head> — don't move it
- npm create astro needs empty dir — had to scaffold in /tmp and copy

Without this file, session 4 would repeat session 2’s mistakes. With it, every session inherits the accumulated judgment of all previous sessions.

The rationale column matters. It’s not enough to record what was decided — the AI needs to know why, so it doesn’t accidentally reverse a deliberate choice.

DRIFT.md — what changed from the original plan

Plans change. Features get added, approaches get revised, scope gets cut. DRIFT.md tracks every deviation from the original spec.

| # | Date | What Changed | Why | Spec Updated? |
|---|------|-------------|-----|---------------|
| 1 | 2026-03-01 | Switched from SSR to static | No database needed, simpler deploy | Yes |
| 2 | 2026-03-01 | Deferred DNS migration | Domain on Vercel, user wants to handle separately | No |

This prevents a subtle problem: the AI reads the original spec, sees “use Cloudflare adapter for SSR,” and re-adds it — undoing a deliberate change from three sessions ago. DRIFT.md is the canonical record of “we know the spec says X, but we actually do Y now.”

SESSION-LOG.md — what happened each time

A chronological record of every session. What was done, what broke, what the next session needs to know.

The critical part is the handoff note at the end of each entry:

## Session 2 — Phase 2: Content Collections (2026-03-01)

**What happened:**
- Switched to static output, created content collections, built all dynamic routes
- 8 pages generated and deployed

**Handoff to next session:**
- Next: Phase 3 — Polish & Interactions, starting with View Transitions
- @astrojs/cloudflare still in package.json — should uninstall
- Prose styles hand-rolled — verify on real markdown content
- Consider adding @astrojs/sitemap

The handoff is the most valuable part. It’s not a summary — it’s a briefing. It tells the next session exactly where to pick up, what’s hanging, and what to watch out for. It’s the equivalent of leaving a note for your future self, except the future self has zero memory.

The session protocol

Every session follows the same rhythm:

Start:

  1. Read PLAN.md — know where we are
  2. Read MEMORY.md — absorb decisions and context
  3. Read DRIFT.md — check for spec changes
  4. State what you’ll do this session

End:

  1. Check off completed items in PLAN.md
  2. Add new decisions to MEMORY.md
  3. Log any drift in DRIFT.md
  4. Write session entry + handoff in SESSION-LOG.md

This is rigid by design. The start protocol prevents wasted time re-discovering context. The end protocol prevents context loss. Skip either one and the system degrades.

Why this works better than I expected

Documentation becomes the product

When you know the AI will start fresh next session, you can’t be lazy about recording decisions. The .plan/ files aren’t documentation about the project — they are the project’s institutional knowledge.

The side effect: better architecture. Writing “why are we doing it this way?” before writing code catches bad ideas earlier than code review ever did.

Sessions become natural work units

Instead of “I’ll work on this until I’m tired,” each session has a clear scope: execute one phase, update the files. The AI proposes what it’ll tackle, you agree, it executes, it closes cleanly. No half-finished states.

My khairold.com was built in 4 sessions. Session 0 was planning. Sessions 1–3 were phases 1–3. Session 4 was real content. Each session picked up exactly where the last left off — zero re-explanation needed.

The files are portable

The .plan/ directory doesn’t care which AI you use. It’s four markdown files. You could switch models between sessions, hand them to a human developer, or come back six months later. The context is in the files, not in any system’s memory.

The template

I’ve turned this into a reusable protocol. For any new project:

  1. Write a spec (what you’re building)
  2. Run the phased-plan process — decompose into phases, create .plan/ files
  3. Execute one phase per session using the execute-phase protocol
  4. Repeat until done

The decomposition rules:

  • Each phase delivers something testable — not “set up half the database”
  • Each phase is completable in one session — if too large, split
  • Order by dependency, then value
  • 3–5 phases total, 5–10 items per phase
  • Each item describable in one line

What I’d change

MEMORY.md gets long. After 4–5 sessions, it’s dense. I’m considering splitting it — DECISIONS.md for the table, CONTEXT.md for architecture notes and gotchas. Haven’t done it yet because one file is simpler to read.

The protocol is overkill for small tasks. If the whole project fits in one session, you don’t need .plan/. I only reach for it when work will clearly span multiple sessions.

Session handoffs could be richer. Sometimes the handoff misses something subtle — a design intention, a half-formed concern. I’m experimenting with a “open questions” section in the handoff to capture things that aren’t blockers but should be on the radar.

The .plan/ protocol isn’t clever. It’s four markdown files and a discipline. But it’s the difference between “AI that generates code” and “AI that builds projects” — and that gap is entirely about memory management.