75 lines
3.5 KiB
Markdown
75 lines
3.5 KiB
Markdown
---
|
||
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.
|