Specs and Todos

Two ways to hold work that is not done in this message. A todo is a note for later: one small thing, parked in one file. A spec is a contract for now: a written plan with steps and checks that an agent executes and an independent reviewer approves. Most work needs neither — you ask, the agent does it, /test and /review check it.

Which one do I need?

Situation	Use	Example
Small change, done in this session	nothing — just ask	"Fix the typo in the footer"
Small change, not now	todo	/todo retry the upload when the token expired
Several small, independent items for later	one todo each	three findings from a review
A larger handoff another agent executes	spec	a /wave slice, above the size threshold
More than 5 steps, or more than 6 files across 2+ subsystems	spec	"Add dark mode to shop and admin"
A decision you must make before anyone can start	spec (or a todo with --status decision if it waits)	"Stripe or Mollie?"
You want a written plan	spec	"Plan this out"

Rule of thumb: a todo remembers, a spec commits. A small item that only waits for a later session is a todo, not a handoff. A small immediate task needs only a short brief, and a todo can later grow into a spec.

Todos

A todo is a Markdown file under devkit/todos/<id>.md with an id, title, status, dependencies and a short note. It is tracked in Git, so every teammate and every worktree sees the same list.

Everyday use

You type	What happens
/todo <text> or todo: <text>	Parks the text as a new file and commits only that file. Nothing is worked on.
/todo or /todo list	Lists every todo with its state.
/todo next	Works the oldest ready todo.
/todo next --parallel N	Up to N todos without shared files, in parallel via delegates.
/todo pick <id>	Works exactly that todo.

The agent also offers a todo when it notices side work, and parks one on its own in long sessions, so nothing gets lost when the chat ends.

What "working a todo" means

One run owns exactly one todo, from claim to commit:

1. Claim — the todo is locked for this worktree, so a parallel session cannot take it too.
2. Isolate — a clean checkout works in place; a dirty one gets its own todo/<id> worktree.
3. Implement — only this todo.
4. Check — the project's checks and the affected tests must pass.
5. Commit — one commit with the fix, the deleted todo file and a Todo: <id> trailer.

A red check or an open question releases the todo with a note, and only the files that run touched are restored.

States in /todo list

State	Meaning
open	Ready to work. /todo next picks from these.
claimed	Someone is working on it right now.
blocked	Waits on another todo in dependencies.
decision	Needs a human decision first; cannot be claimed.
spec	Grew into a spec; work continues there.
done	Finished.

Parking several items at once makes one todo file each; working stays one todo per run so every fix is one reviewable commit.

For the steps of the work running now, devkit todo plan keeps one plan per worktree across sessions, compaction and runtimes; the statusline shows it and plan park turns open steps into todos.

Specs

A spec is a self-contained Markdown contract: a fresh session, or a different model, can execute it without the chat that produced it. It carries the goal, the steps with their verify commands, the acceptance criteria and the files in scope. /spec picks the cheapest route that is still safe:

Route	When	What you get
todo	Deferred or several independent small items	Todo files, no spec
direct	Small enough to do now	A short brief in chat, no file
compact	One spec trigger holds — size, a larger handoff, an open decision, or your request	A short spec file
full	A spec is needed, plus high risk, irreversible migration, security boundary, public contract, 3+ subsystems or novel architecture	A full spec; independent authoring review unless a documented exception applies

Lifecycle

Stage	What happens
/spec "<goal>"	Writes and validates the plan and shows a plain-language summary; correct it if it misread you.
/spec-work NNN	Starting it is the approval — no separate question. A fresh session is cheaper because the spec carries everything.
Implement and verify	Every step and acceptance criterion runs green.
Independent review	A separate reviewer checks the diff against the contract; green ACs alone never count as done.
Completed	The spec is done; you commit with /commit.

Statuses

Status	Meaning
draft	Written, ready to start.
in-progress	/spec-work is implementing it.
paused	Deliberately stopped; the Progress Log says where.
in-review	Code frozen, reviewer is checking.
blocked	A stop condition or repeated failure needs you.
completed	Review passed, file moved out of the active list.

When things change

Situation	Do
Session ended mid-run	/spec-work NNN again — it resumes at the first open step.
The plan no longer matches the code, or you need more scope	/spec-update NNN "<change>" — rewrites the contract and reopens the affected steps.
Small fix after completed	Just ask — the spec is a record now; no update needed.
Several approved specs touching different files	/wave runs them in parallel worktrees.
Work spans sibling repositories	/workspace writes one spec per repository.

Related

• Workflows — where specs and todos sit in daily work.
• Skill Overview — choose a skill and open its reference.