Working memory that survives sessions, agents, and parallel features. One line: plans hold the work; docs hold the truth.
.plans/<name>.md= working memory for ONE piece of work. Live, brainstorm-friendly, ephemeral. Deleted when shipped._docs/= source of truth. How the system works today, third-party API behavior, established patterns. Durable, authoritative.- Plans link to docs, never duplicate them. A durable fact discovered
while working gets promoted into
_docs/before the plan is deleted. Never let truth die with the plan.
Tool-agnostic: the same files serve Claude Code, Codex, or any agent (reference this procedure from AGENTS.md so every agent follows it).
Entry point — invoked with a feature name
When asked to start or resume work on <feature> (e.g. "feature-workflow
risk-profiling", "pick up the bottom-nav work"), hydrate in this order —
do not touch code before step 4:
_docs/features/<feature>/roadmap.md— the feature's items, statuses, debt sections. Create it if starting something new.- The linked plan (
→ .plans/<name>.mdon the in-progress item), or create one from the format below (and set the roadmap item[in-progress]). - Every doc the plan's Source of Truth section links.
- Run reconcile-on-open (below). Only then act.
- Report to the human: current state, drift found, next step about to be taken.
Plan format
# Plan: <name>
Status: brainstorm | approved | in-progress | blocked | shipped
Last reconciled: <date> — <matches reality? what drifted?>
## Goal
## Decisions ← locked choices + why (crystallized brainstorm)
## Open Questions ← still-live brainstorm (resolve → move to Decisions)
## Current State ← VERIFIED ground truth now, not assumed
## Next Steps ← ordered resume point: exact place to pick up
## Regression Guard ← how to avoid breaking existing behavior
## Out of Scope
## Source of Truth ← links to _docs/, API docs, key file:line
Task lists, test cases, data models slot under Next Steps / Current State. One-line, actionable, agent-register (terse facts, file:line — plans are agent-read; docs for humans stay prose).
Reconcile-on-open — never stale
The resume guarantee is a cheap ritual, not "the agent remembers":
read plan → VERIFY each "done" claim against real code/db → note drift in
Current State → rewrite Next Steps → stamp Last reconciled → then act
Never trust a checkbox. A plan whose "done" you haven't verified is a
rumor. During work: update the plan in the same turn as the change,
never batched for later. On stop/handoff: Next Steps points at the
exact resume point; no done that isn't.
Brainstorm in the plan
The plan is where thinking out loud lives — options weighed, discussion recorded. Keep it from rotting: resolved → one-line Decision with the why; unresolved → Open Questions; loose musing either crystallizes or dies.
Roadmap contract
Every plan implements a roadmap item:
- Find (or create)
_docs/features/<feature>/roadmap.md - Set the item
[in-progress]and link it:→ .plans/<name>.md - On ship:
[shipped], remove the plan link, promote durable facts, delete the plan - On abandon: revert to
[planned], delete the plan
Tech debt and product debt live in the same roadmap.md under their own
sections — one place per feature, not a separate debts folder.
Cross-cutting infra debt → _docs/architecture/roadmap.md.
Don't invent
Before touching a third-party integration or existing subsystem, read its
_docs/ entry — it is authoritative. If docs and reality disagree,
reality wins: fix the docs and cite the source (API URL, file:line,
commit) so the correction is verifiable, not another invention.
With gated-build
For high-stakes adversarial builds (see the gated-build skill), the
feature's plan file IS that build's anchor document — the grill trail,
evidence ledger, and tombstones live as sections inside it. Multiple
concurrent gated builds = multiple plans, each hydrated by name through
the entry point above.
Provenance: production workflow from a live Laravel/fintech monorepo (mfstack), where multiple concurrent features + two agents (Claude Code, Codex) share the same plans and docs.