Every decision, every task, every run — in versioned files. Not in the model's memory.

AI coding tools like Claude Code, Cursor, and Codex work inside a context window — the tool's short-term memory for a single chat session. When the session ends, that memory resets completely. If your project's decisions, task state, and rules live only in those conversations, they vanish.

You give your AI coding tool a task. It builds something. You close the tab. Next session, the tool has no memory of why that architectural choice was made, which files are in scope, or what "finished" even means. It starts guessing — sometimes brilliantly, sometimes catastrophically.

Without a reliable permanent record, every AI coding session is a fresh roll of the dice. Five specific failure modes appear again and again: decisions evaporate between sessions, tasks drift from reality, code changes become impossible to review, evaluations lack reproducible evidence, and templates multiply until no one maintains them. Every one of these is preventable.

The expensive lesson most teams learn the hard way: the session is ephemeral. The repo is permanent. Anything important that lives only in the conversation is gone when the conversation ends — and gone again the next time.

The problem

The root causeAI coding tools forget. Your repo does not. The fix is to put everything important into versioned files — and read them at the start of every session.

Copy 15 Markdown templates into your repo. Fill them in. Run one Python script. That is the entire installation — your AI coding tool now has a permanent, reliable source of truth for every session.

The Agentic Development Playbook is a set of 15 Markdown templates — each one designed to prevent a specific failure mode — plus a conformance check script that verifies the templates are properly structured. The conformance check is a single Python file; it runs in under 5 seconds and needs no extra packages.

There are two paths. The Core Path (7 templates) is for disciplined implementation when the plan already exists: an instruction file that grounds every session with rules and boundaries, a task backlog, a decision log, an atomic task card with explicit scope, a phase gate checklist, a current-state file, and a tool pointer for each AI coding assistant. The Proof-of-Concept Path (6 more templates) is for exploratory work that needs to produce decision-grade evidence — a structured brief, evaluation gate, and run record — before hardening further.

The templates are tool-agnostic. The instruction file works with any AI coding tool: Claude Code, Cursor, Codex, Gemini CLI. Each tool gets a one-line pointer to it. The discipline stays consistent regardless of which AI model is in use.

The big idea

Most teams fight the session-reset problem by trying to keep everything in the prompt — copying in context, re-explaining rules, restating decisions. This is an arms race with the context window that you cannot win.

The instruction file tells the AI coding tool exactly what to do at the start of every session: which files contain the spec, what the rules are, when to stop and ask a human. The task backlog shows what is in-progress, ready, blocked, and done. The decision log is append-only — every real choice is recorded with the question, the options considered, and the rationale. The task card defines a single atomic piece of work with explicit allowed and forbidden file paths and runnable verification commands.

The conformance check makes this structural, not just cultural. It runs in under 5 seconds and verifies that every template has its required fields. An evaluation gate without its 7 sub-checks fails the check. A run record without its 8 required keys fails the check. The check catches exactly what it promises to catch — no more, no less.

The aha

The Playbook inverts the approach: accept that sessions end, and put everything important into a file instead. The instruction file grounds every session. The task backlog always reflects reality. The decision log answers questions months later. The task card forces explicit scope before any code is written. The repo provides continuity that no chat session ever could.

The Playbook structures every AI coding session as a repeatable, reviewable loop. The agent reads the ground truth, picks a task, scopes it explicitly, implements it, verifies it, commits it, and updates the record.

The Core Loop: (1) Read AGENTS.md — rules, stop conditions, spec root. (2) Read TASKS.md — pick one Ready item (WIP limit: 1). (3) Create task-card.md with explicit Goal, allowed/forbidden file paths, acceptance criteria, and runnable verification commands. (4) Implement — only in-scope files, no drive-by refactors. (5) Run verification — if it fails, fix and re-verify; no bypasses. (6) Commit with a Task: T-XXX trailer. (7) Update TASKS.md and DECISIONS.md. (8) Archive the task card. Repeat.

The optional enforcement layer locks this discipline at the commit level: git hooks (via lefthook) require the task trailer in every commit message, require TASKS.md in every diff, and record every commit hash to an append-only ledger. Bypassed commits are reported as drift — not silently ignored. The layer is opt-in, universal (any agent), and ships in four components: hooks, an opencode plugin, a verifier subagent, and a cron/CI executor.

Architecture

Data flow

Anyone who builds software with AI assistance and has felt the pain of a session ending before the work is done — or a session starting with no idea where the last one left off.

In the real world

No tools to install. No account. No CLI. Just copy files, fill them in, and run one Python script that tells you immediately whether the structure is correct.

python eval/check.py

1. Clone the Playbook repo Run: — it takes a few seconds.
2. Copy the 4 core templates From the folder, copy , , , and into your project root. If you use Claude Code, also copy as a one-line pointer.
3. Fill in the instruction file Open and set your project name, your spec root directory, and any project-specific stop conditions. The template ships with sensible defaults — you are editing, not writing from scratch.
4. Add your first task Open and add one item in the Ready section. Then create using — fill in the Goal, the allowed file paths, the acceptance criteria, and the verification commands.
5. Run the conformance check Run from your project root (no dependencies needed, works on stdlib Python 3.12 or 3.13). You will see a line for each template: . If anything is missing, it prints the exact field that needs to be filled.
6. Start your AI coding tool Paste this into your AI coding tool of choice: "Read first. Use as the backlog. Create a task card for the first Ready item. Implement one task at a time. Follow the After Completing checklist." The tool reads the instruction file, picks a task, scopes it explicitly, implements it, verifies it, and commits it — then updates the backlog and archives the card.

Every explainer ships with a downloadable AI knowledge pack — the full contents of this repo embedded into a retrieval-ready knowledge base your AI tools can query directly.