---
name: planning
description: Creates and maintains a structured plan document for multi-step tasks. The plan lives at PLAN.md and contains an ordered, checkbox-driven task list the agent keeps in sync as work progresses. Use when the user asks for a plan, when a task has multiple non-trivial steps, or when you need to track progress across a longer session.
---

# Planning

Track a multi-step project using a markdown checklist.

## When to use

Use this skill when any of the following is true:
- The user explicitly asks for a plan, todo list, or breakdown.
- Work will continue across several turns and progress needs to be tracked.
- You need to confirm scope with the user before executing.

For trivial one-shot edits, do not create a plan.

## Plan location

- Default path: `./PLAN.md` in the current working directory.
- If a plan path is specified by the user, use that instead.
- If `PLAN.md` already exists, read it first and update it in place rather than overwriting unrelated content.

## Plan document format

The plan is plain Markdown. Every task is a GitHub-style checkbox list item. Keep it scannable.

```markdown
# Plan: <short title of the overall goal>

<1–3 sentence summary of the goal and any important constraints.>

## Tasks

- [ ] 1. <First concrete, verifiable task>
- [ ] 2. <Next task>
  - [ ] 2a. <Sub-step, if the task naturally decomposes>
  - [ ] 2b. <Sub-step>
- [ ] 3. <...>

## Notes
- <Open questions, assumptions, decisions, links, or context worth preserving.>
```

Rules for tasks:
- One action per checkbox. If a step has "and" in it, consider splitting.
- Each task must be concrete and verifiable ("Add `--json` flag to `cli.ts` and update `--help` output"), not vague ("improve CLI").
- Number tasks so they can be referenced in conversation ("done with 2, starting 3").
- Use nested checkboxes for sub-steps only when it adds clarity.
- Prefer 3–12 top-level tasks. If you have more, group them under `##` section headings.

Checkbox states:
- `[ ]` not started
- `[~]` in progress (optional; use when a task spans multiple turns)
- `[x]` done
- `[-]` skipped or no longer applicable (add a short reason in the same line or in Notes)

## Workflow

1. **Draft.** On first use, read any existing `PLAN.md`, then write a complete plan with all tasks as `[ ]`. Keep the plan focused on the user's current goal.
2. **Confirm (when useful).** If scope is ambiguous or the work is large, show the plan to the user and ask for confirmation before executing. For clear requests, proceed.
3. **Execute one task at a time.** Before starting a task, mark it `[~]` (or announce which task you're starting). After finishing, mark it `[x]` and update `Last updated` and `Current step`.
4. **Keep the plan in sync.** If you discover new work, add new checkboxes. If a task becomes unnecessary, mark it `[-]` with a brief reason rather than deleting it, so the history stays readable.
5. **Summarize at the end.** When every task is `[x]` or `[-]`, add a short `## Summary` section describing what was done and any follow-ups.

## Editing the plan

- Use the `edit` tool to flip individual checkboxes and update the `Status` block — avoid rewriting the whole file.
- Only use `write` when creating the plan for the first time or doing a full restructure.
- Never silently drop tasks. Either complete them, skip them with `[-]` and a reason, or move them to a `## Deferred` section.

## Example

See [example-plan.md](example-plan.md) for a fully worked example of a small feature broken into tasks.