cleo-plan-then-doc

A Claude Code rule that separates design artifacts (plans, specs — short-lived) from module docs (long-lived, describe what currently is).

Install

With cleo:

cleo require surt/cleo-plan-then-doc

Manually:

mkdir -p .claude/rules
curl -o .claude/rules/plan-then-doc.md \
  https://raw.githubusercontent.com/Surt/cleo-plan-then-doc/main/rules/plan-then-doc.md

The rule

The canonical source is rules/plan-then-doc.md. The content below mirrors it.

---

Plans → Docs

Planning docs are scaffolding. Design with them, ship the work, replace them with module docs that describe what the system now is.

When to write a plan

• New feature, new module, architectural change → write a plan.
• Bug fix, small refactor, type swap, single-call cleanup → skip. Commit message + diff carry it.
• Unsure → ask before creating the file.

How to write a plan

Use superpowers:writing-plans — it owns the format (bite-sized tasks with checkboxes, complete code in steps, no placeholders, self-review pass). Brainstorm first via superpowers:brainstorming to lock the spec before drafting the plan.

Every plan also includes:

1. Status legend — phases shipped (with SHAs), in progress, queued. A fresh reader triages live vs done without chasing PR history.
2. Operating-discipline preamble — one short paragraph naming the skills + conventions the executor loads (superpowers:writing-plans, superpowers:executing-plans, superpowers:test-driven-development, plus project-specific rules).

Default save location: docs/plans/YYYY-MM-DD-<feature-name>.md. Match whatever your team already uses.

How to execute a plan

• Isolate the workspace first via superpowers:using-git-worktrees — implementation work shouldn't pollute the main checkout.
• Then either superpowers:subagent-driven-development (one fresh subagent per task, two-stage review) or superpowers:executing-plans (batch with checkpoints).
• Tasks with disjoint file scopes → superpowers:dispatching-parallel-agents permits parallel implementer dispatch.

Plan review

Plans are design artifacts — get them reviewed by a human before they land. Commit and PR shape is your team's call; this rule doesn't prescribe.

After ship — delete the plan, write the doc

Once the work ships, remove the plan file:

git rm docs/plans/<plan-filename>.md

Add or update module docs describing the system as it now is. Drop migration steps, alternatives considered, PR-specific framing. Keep behaviour, schema, file paths, public APIs.

Why

• Plans rot fast — stale plan misleads readers and adds noise to greps.
• Module docs survive refactors because they describe the present, not a snapshot.
• Git history preserves the plan if anyone needs it.

Keeps the planning step — genuinely valuable — without polluting the long-lived doc surface.

---

License

MIT.