Cold Start, Cold Stop: The Two Commands That Bookend Every AI Coding Session

Every AI coding session has the same two failure modes, and almost nobody addresses them:

1. Cold start — you open a fresh session and the agent has no idea where it is. It writes plausible-looking code that ignores half your conventions because it's never seen them. You spend the first ten messages re-explaining the project before any real work begins.
2. Cold stop — you close the session mid-thought. Tomorrow's session inherits the code but not the reasoning, the dead ends, or the half-finished thread you left dangling. You re-derive everything from scratch, and sometimes re-walk the exact same dead end.

Both are context problems. And both have the same shape of fix: a tiny ritual at the session boundary that costs maybe a minute and pays back disproportionately.

The two commands I run on every meaningful session are /primer and /handoff. They are deliberately boring. That's the point.

/primer — solving the cold start

When an agent opens a fresh session, it sees a working directory and not much else. It doesn't know what the project is for, which conventions are load-bearing, where the deploy lives, or which file is the canonical source of truth. Without that, every suggestion is a guess shaped like a recommendation.

/primer is the single instruction at the start of the session that makes the agent earn its context before it touches any code. Mine, in full:

# Prime Context for Claude Code

Use the command `tree` to get an understanding of the project structure.

Start with reading the CLAUDE.md file if it exists to get an understanding of the project.

Read the README.md file to get an understanding of the project.

If a HANDOFF.md file exists in the project root, read it — it contains the prior session's reasoning, dead ends, and recommended first action.

Read key files in the src/ or root directory.

Explain back to me:
- Project structure
- Project purpose and goals
- Key files and their purposes
- Any important dependencies
- Any important configuration files
- If a HANDOFF.md was present, what the prior session left in progress and what it recommends doing first

Heads up on tree: the CLI isn't installed by default on macOS — brew install tree. Most Linux distros ship it. If your agent reports "command not found," a fallback like ls -R or find . -type d -not -path '*/node_modules/*' works fine; the point is just to surface the repo skeleton before any prose interpretation.

That's the entire command. The mechanics matter more than the brevity:

• tree first — establishes the shape of the repo before any prose interpretation. The agent sees the skeleton before it reads anyone's description of it.
• CLAUDE.md before README.md — the agent-instructions file (or your harness's equivalent) is more concentrated and more current than the README, which is usually written for humans onboarding from outside. If both exist, the agent should read the agent-targeted one first.
• HANDOFF.md if present — this is the part that makes the two bookends actually compound instead of just sitting at opposite ends of the same session. The session that ran /handoff last night wrote down what it was thinking; the session running /primer this morning reads it before doing anything else. Without this line, the bookends are decorative. With it, sessions chain.
• "Explain back to me" — this is the unlock. Forcing a summary surfaces whether the agent actually absorbed the codebase or just skimmed it. If the explanation is wrong, you correct it cheaply, right now — instead of three hours later when it's already misnamed a column or wired up an endpoint against the wrong service.

The principle is explicit context loading instead of hoping. You're not asking the agent to be smart; you're telling it where the load-bearing information is, and verifying it landed. This is the same point I made in AI's Power Isn't in Prompts. It's in Context. — but at the smallest scale. /primer is context engineering applied to the single session.

/handoff — solving the cold stop

The opposite end has the inverse problem. The session is over. Some code shipped (or didn't). Decisions were made; experiments failed; work was started and parked. Tomorrow, when you — or a teammate, or another agent — reopen the project, none of that is in the room.

/handoff writes a structured HANDOFF.md that captures the parts the code can't tell you. The template I use:

# Session Handoff — 2026-05-05

## Goal
What was the user trying to accomplish this session?

## Completed Work
- Bullet list of what shipped, with commit hashes.

## In Progress
- What was started, file paths, what remains.

## Key Decisions & Why
- Decision: the reasoning, not just the choice.

## Dead Ends (Don't Repeat These)
- What was tried, why it didn't work.

## Files Changed This Session
[git diff --stat output]

## Current State
- Build: passing/failing
- Tests: passing/failing/not run
- DB: schema synced? pending migrations?
- Services: running on which ports, or stopped

## Recommended First Action
The exact next step. Be specific.

Three of those sections do most of the work:

• Key Decisions & Why — a fresh session can read the code; it cannot read the reasoning. "We picked X over Y because Y leaked memory under load" is the kind of context that takes hours to recover otherwise.
• Dead Ends — stops the next session from cheerfully re-trying the exact approach you just spent two hours abandoning.
• Recommended First Action — removes the "where do I even start" friction at the top of tomorrow's session. Past-you knew. Future-you doesn't, until past-you writes it down.

The rest is bookkeeping: what shipped, what's broken, what's running, what's queued. The HANDOFF.md is gitignored — it's session ephemera, not history. Git already handles history; this file handles intent.

A small but important detail: the command itself should be defensive. Mine tolerates a fresh repo with no commits yet, and falls back to working-tree state if there's no HEAD to diff against. The boundary commands run on every session, including the messy ones; they need to not blow up on edge cases.

The honest tradeoff

Both commands feel like overhead the first time you use them. They are.

/primer costs tokens upfront. If your session is going to be five messages long, the priming pass dominates the conversation. The payoff only shows up on real sessions — the ones where the agent is making decisions across many files over an hour or more. For those, the cost amortizes immediately. For a quick one-line edit you can skip it; for anything substantial, skipping it is how you get the "this code looks plausible but quietly ignores three conventions" failure mode.

/handoff costs about a minute at end-of-session and feels like nothing the first time, because tomorrow you'll remember everything. You won't. You only feel the value the second time you open a session and discover that past-you already mapped the dead ends, named the running services, and pointed at the next move. After that, the minute feels like the cheapest minute you spend all day.

That's the tax structure: small fixed costs at the boundaries, large variable savings inside the work. Same shape as testing, version control, or documentation. The people who skip those argue they're moving faster. They aren't — they're just paying the cost in a less visible currency.

Sessions are units of context

There's a deeper reason these two commands matter, beyond the immediate productivity story.

A coding session is a unit of context, not just a unit of work. The agent's effective intelligence inside that session is bounded by what it can see — files, conventions, decisions, prior failures, current state. The PIV loop handles context at the per-ticket scale: small, scoped, validated cycles. /primer and /handoff handle the layer above — the per-session scale.

Without those bookends, every session is an island. The agent re-discovers the project from zero each morning, and your accumulated reasoning evaporates each night. With them, sessions chain. The next one starts where this one ended, with the load-bearing context already in the room.

That's not a minor convenience. It's the difference between AI-assisted development that compounds and AI-assisted development that resets every day.

How to start tomorrow

Two files. Five minutes.

1. Create .claude/commands/primer.md (or whatever your harness's equivalent is) with the steps above: tree (or a fallback if it's not installed), read your agent-instructions file, read README, read HANDOFF.md if present, read key files, summarize back.
2. Create .claude/commands/handoff.md with the eight-section template above. Make it tolerant of empty repos and missing services so it never fails when you need it most.
3. Run /primer at the start of your next real session.
4. Run /handoff at the end.
5. Open the next session and notice that the agent walks in already knowing where it is — and that you walk in already knowing where you left off.

The second time you reopen a project and find that past-you already wrote the dead-ends list, you'll never go back.

The unglamorous truth

The developers getting real leverage out of AI agents aren't the ones with the cleverest prompts or the most expensive subscriptions. They're the ones who've figured out that context is the work, and that the cheapest place to invest in context is at the session boundary, where everything else either lands or evaporates.

Cold start, cold stop. Two commands. Boring, deliberate, free.

Same conclusion I keep landing on: the model is the easy part.