plan

name	plan
description	Use for multi-step work that benefits from a short, durable task plan or handoff. Do not require a plan file for routine, single-session changes.

Practical Planning

Plan location and identity

Use plans/<task>/plan.md unless the repository specifies another location. Start with:

# <Task> plan

## Goal
<Outcome, not a list of implementation steps>

## Context
- Success criteria: <observable completion conditions>
- Scope and constraints: <included, excluded, safety and compatibility rules>
- Branch/base: <head, base, starting commit>
- PRs/issues/specs: <stable references>
- Decisions: <important choices and why>

## Steps

### 1.1 <Workstream>

#### 1.1.1 <First step>
**Status:** IN_PROGRESS
**Intent:** <what this establishes>
**Evidence:** <commands, files, results, or still pending>

#### 1.1.2 <Discovered step>
**Status:** TODO
**Depends on:** <step IDs or none>

Hierarchical step IDs

• Give every executable step a stable three-part dotted ID such as 1.1.1, 1.1.2, 1.2.1, or 2.1.1. Use one- and two-part headings only to group steps; never give a grouping heading a status.
• Add deeper levels such as 1.1.1.1 only when a step genuinely needs decomposition.
• Add discovered work beneath its parent instead of renumbering unrelated steps. Refer to dependencies and findings by ID.
• Keep exactly one step IN_PROGRESS while actionable work remains. Use none when the plan is complete or no step can currently proceed. Other statuses are TODO, DONE, BLOCKED, and SKIPPED.
• A step is DONE only when its stated evidence proves the intended result.

Keeping the plan useful

Update the plan at meaningful milestones: a discovery changes later work, a decision is made, a step completes, validation changes confidence, a blocker appears, or ownership is handed off. Do not reload or rewrite it before every command.

When a completed step produces information needed later, copy that fact into the dependent step as From <step-id>: <fact and how to re-verify>. This keeps the plan resumable without turning it into a command transcript.

Reload the plan after a context reset, when resuming after a gap, before a handoff, or when current work no longer matches the recorded goal. If scope changes materially, update the goal, constraints, and affected steps before continuing.

Resumption and handoff

End a working session with a compact resumption block:

## Resumption
- Current step: <ID and status>
- Completed: <IDs and evidence>
- Branch/PR: <head, base, URL>
- Validation: <passed, failed, not run>
- Decisions/blockers: <only what affects continuation>
- Next action: <one concrete action>

Preserve user changes, distinguish assumptions from verified facts, and never mark the overall goal complete while required evidence is missing.