Using Planflow

PlanFlow — Plan-Driven, Short-Session Workflow

Long conversations degrade: details get lost, context rots, and the agent starts re-deriving or contradicting earlier decisions. PlanFlow routes around this by externalizing state to files and keeping each working session short and focused on exactly one task.

When to use this

• The user hands you a substantial, multi-step goal (a feature, refactor, data pipeline, migration).
• A PLAN.md or HANDOFF.md already exists in the project — read it FIRST.
• The user mentions planning, tasks, checklists, or "fresh session".

For a small one-off change, skip the ceremony and just do it.

The memory spine

• PLAN.md (project root): the source of truth for WHAT to do — the work broken into small, ordered, checkbox tasks, each with acceptance criteria and the files it touches.
• CLAUDE.md: durable decisions and conventions, never to be re-derived.
• HANDOFF.md: an emergency snapshot, only when a single task runs long.

What goes where (keep the files clean)

Mixing transient state into long-term files is what re-rots your context. Be strict about which file holds what:

• PLAN.md — tasks and their status. Nothing else.
• CLAUDE.md — ONLY decisions that stay true many sessions from now (architecture, naming rules, "always do X", verified findings). Do NOT put here: task status, one-run values (a temporary batch size), one-off paths, or experiment results.
• HANDOFF.md — a transient snapshot of an in-progress task; overwrite freely.
• (optional) WORKLOG.md — an append-only log of results/experiments if your project produces them, so results never leak into CLAUDE.md.

How to size a task

A good task is something ONE fresh session can finish without approaching the context limit: one coherent unit (a module, function, fix, or thin slice), doesn't need the whole codebase in context, has a concrete "Done when…" condition, and is ordered so earlier tasks unblock later ones. If a task needs more than ~1 hour or touches many files at once, split it further.

Session discipline

• On starting work: read PLAN.md and (if present) HANDOFF.md FIRST.
• Work ONE task at a time (two only if tiny and tightly related).
• Read ONLY the files that task references — never load the whole repo.
• When done: verify against "Done when…" with real evidence, tick the checkbox in PLAN.md, add a one-line result note, and record any durable decision in CLAUDE.md. Never tick a box you could not verify.
• Then STOP and tell the user to open a FRESH session for the next task. Do NOT roll into the next task in the same conversation.
• If context grows long mid-task: write HANDOFF.md and stop.

The three action skills

• plan (/planflow:plan <goal>) — turn a goal into an ordered PLAN.md task list. No coding yet.
• next (/planflow:next) — execute the next unchecked task: read only its files, implement, verify with evidence, tick the box, then print a closure summary (changed files + the command that verified it + a suggested commit message), then STOP. Manual-invoke only by design: advancing is the human's decision, in a fresh session.
• handover (/planflow:handover) — snapshot the working state to HANDOFF.md before a long session ends.

Typical loop: plan once → next per fresh session until every box is ticked → handover only if a single session must pause mid-task.