Skip it for single-file changes with obvious scope, or when the spec already holds well-defined tasks.
Write no code during planning. The output is a plan document and a task list in the task list target, not implementation. The output_files block describes both.
Database schema
│
├── API models/types
│ │
│ ├── API endpoints
│ │ │
│ │ └── Frontend API client
│ │ │
│ │ └── UI components
│ │
│ └── Validation logic
│
└── Seed data / migrations
Implementation follows the graph from the foundation up, so build the foundation first.
Task 1. Build entire database schema
Task 2. Build all API endpoints
Task 3. Build all UI components
Task 4. Connect everything
Vertical slicing builds every layer for one feature in each task, as in this good plan.
Task 1. User can create an account (schema + API + UI for registration)
Task 2. User can log in (auth schema + API + UI for login)
Task 3. User can create a task (task schema + API + UI for creation)
Task 4. User can view task list (query + API + UI for list view)
Each vertical slice delivers working, testable functionality.
- [ ] Task [N]. [Short descriptive title]
[One paragraph that explains what this task accomplishes.]
It is done when [specific, testable condition] and [specific, testable condition].
This check verifies it.
- [ ] [The check that would fail if this task were wrong, such as the repository's focused-test command, its build, or a manual check of the behavior.]
It depends on [task numbers, or no other task].
It likely touches `src/path/to/file.ts` and `tests/path/to/test.ts`.
Its size is [XS, S, M, or L], from the file counts in the `task_sizing` table.
Add explicit checkpoints to the task list target. This checkpoint follows tasks 1-3.
Checkpoint after tasks 1-3.
- [ ] The tests that cover tasks 1-3 pass.
- [ ] The core user flow works end to end.
| Size | Files | Scope | Example |
|---|---|---|---|
| XS | 1 | Single function or config change | Add a validation rule |
| S | 1-2 | One component or endpoint | Add a new API endpoint |
| M | 3-5 | One feature slice | User registration flow |
| L | 6-8 | Multi-component feature | Search with filtering and pagination |
| XL | 9+ | Too large, so break it down further | None |
Break an L or larger task into smaller tasks, because S and M tasks are easier to verify and review.
Four signs show that a task needs a further split.
- It would take more than one focused session.
- You cannot describe its acceptance criteria in 3 or fewer points.
- It touches two or more independent subsystems, such as auth and billing.
- Its title contains "and", which signals two tasks.
The plan directory is tasks/ in the repository when the user or the project's agent rules ask for plans there. Otherwise it is the session's scratchpad or temporary directory. The repository then gets no files the user did not ask for. Create the directory if it does not exist. Below, tasks/plan.md and tasks/todo.md mean these files in the plan directory.
The same rule holds for an external task list target. Never bulk-close or delete the open tracker items of another plan to make room for new ones.
By default it is a checklist-style markdown file named todo.md in the plan directory defined by output_files. Mirror the current tasks in the session's task tool when one exists.
The user or the project's agent rules, such as CLAUDE.md or AGENTS.md, may name an issue tracker. Examples are GitHub Issues, Jira, Linear, and bd (beads). Then create one tracker item per task instead of writing tasks/todo.md. Map the task template onto the tracker fields. Acceptance criteria and verification steps go in the item body. Dependencies use the tracker's links, such as bd dep add or "blocked by".
Record the checkpoints as tracker items too. If the tracker has no natural equivalent, keep them as a checklist in the plan document. Note the tracker in tasks/plan.md, as in "Tasks tracked in Linear project FOO." Later steps and future sessions then know where to look. The task list in the plan document then holds an ordered index of tracker items. It is not a duplicate checklist.
This plan covers [feature or project name]. [One paragraph that sums up what we are building.]
These decisions shape the architecture.
- [Key decision 1], chosen because [rationale].
- [Key decision 2], chosen because [rationale].
Phase 1 builds the foundation.
- [ ] Task 1. ...
- [ ] Task 2. ...
- [ ] The foundation checkpoint passes when tests pass and the build is clean.
Phase 2 builds the core features.
- [ ] Task 3. ...
- [ ] Task 4. ...
- [ ] The core checkpoint passes when the end-to-end flow works.
Phase 3 finishes the remaining requested work.
- [ ] Task 5. ...
- [ ] Task 6. ...
- [ ] The final checkpoint passes when all acceptance criteria are met.
| Risk | Impact | Mitigation |
|------|--------|------------|
| [Risk] | [High, medium, or low] | [Strategy] |
These questions need the user's input.
- [Question]?
Acceptance criteria belong to each task and answer whether we built the right thing. They sit on top of the verification block of the coding instructions. That block is the standing bar every task clears before it counts as done.