Plans

Numbered Plans

A plan system where every unit of work is a numbered markdown file, and one index lists all of them.

First: read the repo's parameters

This skill describes the shared convention. Each repo declares its own settings in a ## Plans block in its AGENTS.md or CLAUDE.md:

- plans dir:   `plans/`
- index:       `plans/000-INDEX.md`
- statuses:    designing, planned, in-progress, completed, deferred, superseded
- artifacts:   `plans/artifacts/`
- superpowers: override

Read that block before anything else. If the repo has no such block, it does not use this system — do not create one uninvited.

A plan is the spec

Not a summary that points at one. The design lives in the plan file in full — problem, decisions and the alternatives rejected, architecture, data flow, error handling, testing, risks — and stays there as work proceeds, gaining progress notes and findings.

There is no separate design document to keep in sync, and no two-hop read to find out what was decided.

Finding a plan

Read the index first. It is the only list of what is tracked. If a file isn't in the index, it isn't a tracked plan.

Do not glob the plans directory to enumerate plans — artifacts and untracked files live nearby, and you will read things that are not plans.

Anatomy

plans/NNN-name.md, three-digit zero-padded number, lowercase slug.

---
name: Human-readable name
status: designing
created: 2026-08-12
completed: 2026-08-14      # only when status is `completed`
description: >
  Two to four sentences. What the plan covers, what it depends on, what it
  explicitly excludes. Wrapped at 80 columns.
---

• Field order is fixed: name, status, created, completed, description.
• completed carries the date the plan reached completed, and appears only then. Not used for deferred or superseded. Omit the field rather than leaving it bare — a lone completed: reads as "completed, date unknown" when it means "not completed."
• description uses a folded block (>), wrapped at 80 columns.
• Quote name only when YAML requires it — a : inside the name, or a leading >, | or #.
• Extra fields are allowed. If a repo uses one routinely it will be declared in its parameter block.

Two descriptions, two jobs

They are different fields with different contracts. The index cell is not a copy of the frontmatter description.

The index cell carries no status, no progress, no measurements and no design reasoning. All of that lives in the plan file, the only place it can be kept current. A cell that restates the plan makes the index unscannable, which is the one thing it exists to be.

Where this rule is written down it is followed and index descriptions average 23 words; where it isn't, they drift past 150. Keep them short.

Statuses

The default vocabulary. A repo's parameter block may declare a different set — use whatever it declares.

Creating a plan

1. Pick the number: the highest in the plans directory plus one — not the highest in the index. Untracked files must not cause a collision.
2. Write plans/NNN-name.md with complete frontmatter.
3. Add its index row in the same change. A plan without a row is not tracked.

Changing a status

Status is stored twice — in the plan's frontmatter and in its index row.

1. Change the frontmatter.
2. Change the index row.
3. Re-read both and confirm they agree.

Step 3 is not optional. Skipping it is how an index comes to advertise shipped work whose plan file still says it was never started.

Artifacts are not plans

Execution scripts, ledgers, diagnoses, measurement output, benchmarks, reproducers, pitches and decision records go in the artifacts directory, named plan-number-first so a listing groups by owner:

plans/
  000-INDEX.md
  042-organize-engine.md
  artifacts/
    042-organize-engine-execution.md
    046-vec-delete-repro.cpp

• Committed. They are the evidence behind decisions recorded in completed plans — a reproducer is what lets a bug be re-verified later, a ledger is what shows where execution diverged from the plan.
• Owned by exactly one plan, and linked from it.
• Never carries a status, and never gets an index row.

Anything directly in the plans directory is a tracked plan with a row. That makes "is this in the index?" a question with a real answer.

Scratch is a third thing. Intermediate data for a single session belongs in a gitignored path — not a dot-prefixed file, which lands in git status as untracked noise forever.

Superpowers

Applies only where the repo declares superpowers: override. The workflow is unchanged; only the output locations move.

So the plan is the brainstorming output and the artifact is the writing-plans output for that same plan.

Completed plans

Do not edit a completed plan unless asked; adding cross-references to other plans is fine. A change to a shipped feature gets a new plan rather than an edit to the original.

Always write a plan and get approval before implementing.