PlanFlow

A plan-driven, short-session workflow for Claude Code. Externalize your state to files and do one task per fresh session, so long-context rot stops eating your details and decisions.

Status: v0.2.0 — small, opinionated, and battle-tested on real multi-week projects before it was packaged up.

Why this exists

Long agent conversations degrade. Past a certain length the model starts to:

• forget decisions it made earlier,
• re-derive things you already settled,
• lose track of which files actually matter,
• and quietly contradict itself.

PlanFlow's bet: don't fight context rot, route around it. Keep the plan and the durable decisions in files, and keep each working session short enough that the model never approaches its limit.

The idea in one picture

/planflow:plan      →  writes PLAN.md   (the task list — once)
       │
       ▼
/planflow:next      →  does ONE task in a fresh session, verifies it, ticks the
       │                box, prints a closure summary, then STOPS
       │  (open a NEW session, repeat — one task at a time)
       ▼
/planflow:handover  →  writes HANDOFF.md — only if a task must pause mid-way

Files form the memory spine — and each holds exactly one kind of thing:

Install

PlanFlow is both a plugin and its own marketplace, so installation is two lines in Claude Code:

/plugin marketplace add huangyun111/planflow
/plugin install planflow@planflow

If Claude Code doesn't pick the skills up immediately:

/reload-plugins

/plugin is a Claude Code CLI feature — run it in the terminal, not a web/desktop chat panel. Requires a Claude Code version with plugin support.

Use it

1. Plan once. Hand Claude a goal:

/planflow:plan add OAuth login with Google and GitHub

It restates the goal, asks up to 3 sharp questions if something's genuinely ambiguous, briefly explores the code, and writes a PLAN.md of small ordered tasks — self-checking that every task has a concretely checkable "Done when…". It does not write code yet; you confirm the plan first.

2. Execute one task per fresh session. Open a new Claude Code session and run:

/planflow:next

It reads only the files the next task references, implements it, verifies against the task's "Done when…" with real command output (and refuses to tick a box it couldn't verify), records any durable decision in CLAUDE.md, and ends with a closure summary — changed files, the command it ran to verify, and a one-line suggested commit message — then stops, telling you to open a fresh session for the next task.

3. Hand off if you must pause. If a single task runs long and the session is getting heavy:

/planflow:handover

writes a complete HANDOFF.md so a brand-new session resumes with zero loss.

The using-planflow skill is model-invoked: when you hand Claude a substantial multi-step goal — or when a PLAN.md/HANDOFF.md already exists in the project — Claude reaches for this workflow on its own and reads the plan first.

How to size a task

A good task fits in one fresh session without approaching the context limit: one coherent unit (a module, function, fix, or thin slice), needs only a few files in context, and has a concrete "Done when…" condition. If a task would take more than ~1 hour or touch many files at once, split it. See examples/PLAN.example.md for a worked plan, and examples/PLAN.research.example.md for a research/ML variant whose tasks carry an Experiment block.

Design philosophy: discipline, not a babysitter

PlanFlow is intentionally instruction-based, not an enforcement engine. It does not try to police the model with validators that "block" it — that would mean shell hooks (cross-platform fragility) and brittle heuristics that can't truly judge whether a task is done. Instead it leans on two things that actually hold:

1. A real structural constraint. next and handover are manual-invoke

only (disable-model-invocation), so the model literally cannot roll itself into the next task — you advance by starting a fresh session.

1. Evidence over assertion. next must verify "Done when…" with real

command output, must not tick a box it couldn't verify, and ends with a closure summary (changed files + the command it ran + a suggested commit). The work is auditable, not hidden behind a green checkmark.

Want hard automated gates (lint PLAN.md, run the suite on Stop, block commits)? Add a hook in your own project — PlanFlow stays dependency-free so that's your choice, not a forced one.

Repo layout

planflow/
├── .claude-plugin/
│   ├── plugin.json          # plugin manifest
│   └── marketplace.json     # makes this repo its own marketplace (source: "./")
├── skills/
│   ├── using-planflow/      # entry skill (model-invoked) — the protocol
│   ├── plan/                # /planflow:plan <goal>
│   ├── next/                # /planflow:next   (manual-invoke only)
│   └── handover/            # /planflow:handover (manual-invoke only)
├── examples/
│   ├── PLAN.example.md          # a worked plan
│   └── PLAN.research.example.md # optional research/ML plan with Experiment blocks
├── README.md
├── CHANGELOG.md
└── LICENSE

Optional: the short /plan form

Plugin skills are namespaced (/planflow:plan). If you prefer the bare /plan, /next, /handover forms, copy the skill bodies into your personal commands after cloning the repo:

cp skills/plan/SKILL.md      ~/.claude/commands/plan.md
cp skills/next/SKILL.md      ~/.claude/commands/next.md
cp skills/handover/SKILL.md  ~/.claude/commands/handover.md

The description and argument-hint frontmatter fields are valid for commands too, so they carry over.

Optional: a "read PLAN.md first" SessionStart hook

PlanFlow intentionally ships no shell hook, to stay dependency-free and cross-platform — the using-planflow skill already nudges Claude to read PLAN.md/HANDOFF.md at the start of substantial work. If you want a hard reminder, add a SessionStart hook in your project .claude/settings.json that surfaces those files (e.g. prints their contents into the session). Keep the command portable for your OS.

Contributing

Issues and PRs welcome. PlanFlow is small on purpose; changes that keep it small, file-centric, and dependency-free are the easiest to land. If you add a skill, give its description a clear "Use when…" trigger.

License

MIT © 2026 huangyun111