File-backed plans
Use a plan file only when its persistence is valuable. For ordinary single-session work, use native planning instead.
Start
- Create
plans/<task>/plan.md from the template below.
- Record the raw request, branch/base, success criteria, and any constraints.
- Split the work into independently verifiable steps. Mark only one
IN_PROGRESS.
# <Task> plan
**Branch**: `<branch>`
**Base**: `<base>`
**PR**: `<URL or pending>`
## Goal
<Outcome and success criteria>
## Context
<Important constraints, decisions, and links needed to resume>
## Steps
### 1. <Step>
**Status**: IN_PROGRESS
**Verify**: <command or observable outcome>
**Notes**: <results, decisions, or blocker>
### 2. <Step>
**Status**: TODO
**Verify**: <command or observable outcome>
Maintain
- Read the plan at natural handoff points: starting a work block, changing steps, returning after interruption, and before a PR/review.
- Update it when a step completes, a material decision changes, a command fails, or a blocker appears. Do not turn routine reads or minor edits into plan churn.
- Keep durable facts in the plan: exact commands worth rerunning, validation results, PR links, unresolved questions, and decisions with rationale.
- Keep only one step
IN_PROGRESS; use TODO, DONE, BLOCKED, or SKIPPED for the rest.
- For a long plan, replace completed detail with a short verified-results summary. Preserve the commands and decisions needed for a safe resume.
Finish
Before handoff or PR, record the current commit/PR, validation performed, remaining risks, and the next concrete action. Do not commit plans/ unless repository convention or the user asks.
1---2name: plan3description: Create and maintain a concise file-backed plan for multi-session work, handoffs, or complex multi-PR tasks. Use only when the user explicitly requests a plan file or durable task state is needed; otherwise use the platform's native planning.4---56# File-backed plans78Use a plan file only when its persistence is valuable. For ordinary single-session work, use native planning instead.910## Start11121. Create `plans/<task>/plan.md` from the template below.132. Record the raw request, branch/base, success criteria, and any constraints.143. Split the work into independently verifiable steps. Mark only one `IN_PROGRESS`.1516```markdown17# <Task> plan1819**Branch**: `<branch>`20**Base**: `<base>`21**PR**: `<URL or pending>`2223## Goal24<Outcome and success criteria>2526## Context27<Important constraints, decisions, and links needed to resume>2829## Steps3031### 1. <Step>32**Status**: IN_PROGRESS33**Verify**: <command or observable outcome>34**Notes**: <results, decisions, or blocker>3536### 2. <Step>37**Status**: TODO38**Verify**: <command or observable outcome>39```4041## Maintain4243- Read the plan at natural handoff points: starting a work block, changing steps, returning after interruption, and before a PR/review.44- Update it when a step completes, a material decision changes, a command fails, or a blocker appears. Do not turn routine reads or minor edits into plan churn.45- Keep durable facts in the plan: exact commands worth rerunning, validation results, PR links, unresolved questions, and decisions with rationale.46- Keep only one step `IN_PROGRESS`; use `TODO`, `DONE`, `BLOCKED`, or `SKIPPED` for the rest.47- For a long plan, replace completed detail with a short verified-results summary. Preserve the commands and decisions needed for a safe resume.4849## Finish5051Before handoff or PR, record the current commit/PR, validation performed, remaining risks, and the next concrete action. Do not commit `plans/` unless repository convention or the user asks.
graphistry