Skip to content

Plan Files as Resumable Artifacts

A plan committed to the repo is a resumable, version-controlled artifact — a pattern that holds for multi-session work, recurring workflows, and cross-functional review, and backfires without a supersession discipline.

What a persisted plan file is

A persisted plan lives in the repo at a stable path, tracked in git. It is the mutable companion to the frozen spec: the spec fixes goals and done-when, the plan tracks approach and progress. Claude Code's in-session plan mode defaults plansDirectory to ~/.claude/plans, outside the repo (Claude Code settings). Committing the plan turns session memory into a team-visible hand-off.

When it pays

The pattern is qualified. Treat these as prerequisites:

Outside these conditions, a disposable in-session plan is cheaper.

Three canonical shapes

No single convention has won. Three are in active use:

  • Ralph single-root. One IMPLEMENTATION_PLAN.md at the repo root, one task per iteration, one commit per update. The author "throws it out often", so durability is not the goal (Huntley on Ralph; how-to-ralph-wiggum).
  • Codex .agent/PLANS.md. Referenced from AGENTS.md, with the invariant that "it should always be possible to restart from only the ExecPlan." The plan is "fully self-contained": progress, decision log, surprises, and outcomes (Codex cookbook).
  • Manus tripartite. Split across task_plan.md, findings.md, and progress.md. Rewriting the todo list "recites objectives into the end of the context", so the plan doubles as attention bias (Manus; planning-with-files).

Pick by team size: Ralph for solo iteration, Codex for long-horizon runs, Manus for phase and findings separation.

Resumption mechanic

The next session reads the plan as context. It does not reconstruct reasoning. Anthropic frames resumption as "engineers working in shifts, where each new engineer arrives with no memory of what happened on the previous shift": read the git log and progress files, then pick the highest-priority unfinished feature (Anthropic harnesses). In Claude Code, accepting a plan auto-names the session from its content, which ties claude --resume <name> to the artifact (common workflows). The filesystem plays disk; the context window plays RAM (planning-with-files).

The supersession discipline

Persistence without invalidation is actively harmful. Claude Code issue #13740 reports plan mode "repeatedly displaying stale plans" instead of fresh analysis, and Cursor generates dozens of .plan.md snapshots per plan. Make supersession first-class:

  • Archive completed plans under a dated path; do not leave them active.
  • Use supersedes: / superseded-by: frontmatter for a machine-readable chain.
  • Add a CI staleness check that fails when a plan references missing code paths.
  • Treat drift as a pager event. Prassanna's "chain-of-thought that was correct at turn ten becomes actively misleading at turn sixty" applies to persisted plans (Agent Drift).

When not to use

  • Single-session work inside one context window. The PR round-trip is pure latency, so regenerate per task instead.
  • Teams without an invalidation discipline. The plan becomes a retrieval hazard, because outdated context creates mismatches the agent may rationalize rather than surface (Tacnode).
  • High-churn exploratory sessions. A speculative plan written before investigation is always wrong.
  • Regulated domains. A committed plan is a discoverable record. In legal, HR, or finance it may surface pre-decisional reasoning the team did not intend to preserve.

Example

A Codex-shape plan at .agent/PLANS.md, referenced from AGENTS.md:

# Plan: Migrate auth to OIDC

## Goals (frozen — see SPEC.json)
- Replace password auth with Auth0 OIDC on /login and /signup.
- Preserve existing session cookies during rollout.

## Phases
- [x] Phase 1: Add Auth0 provider, feature-flagged off.
- [ ] Phase 2: Dual-write sessions from OIDC callback.
- [ ] Phase 3: Flip flag for 10% of traffic, monitor error budget.

## Decision Log
- 2026-04-09: Chose Auth0 over Cognito — existing SSO contract.
- 2026-04-11: Kept legacy cookie name to avoid client churn.

## Surprises
- `/api/v1/me` implicitly depended on the password hash in the session blob.

## Next Action
Implement Phase 2 callback handler in `auth/oidc.ts`.

The self-contained invariant holds: a fresh session can resume from this file alone.

Key Takeaways

  • The persisted plan is a mutable, version-controlled artifact — the companion to the frozen spec, not a replacement for in-session plan mode.
  • The pattern pays for multi-session, recurring, or cross-functional work and costs negative value for single-session or undisciplined teams.
  • Pick a shape (Ralph, Codex, or Manus) by team size and review surface; none has won.
  • Supersession discipline is non-negotiable — stale plans are more dangerous than missing ones.
Established — multiple independent sources Last reviewed: 2026-05-27
Feedback