dev_sandbox/.pi/agent/skills/planning/SKILL.md

name	description
planning	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.

# 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 for a fully worked example of a small feature broken into tasks.