Using Planflow

---
name: using-planflow
description: Use when starting any substantial, multi-step task, or when the user mentions planning, a PLAN.md, breaking work into tasks, or short focused sessions, or when a PLAN.md/HANDOFF.md already exists in the project — establishes the plan-driven, short-session workflow and points to the plan, next, and handover skills.
---

# 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.