| name | plan-and-tasks |
|---|---|
| description | Draft an implementation plan as a repo-local, gitignored markdown file, then optionally decompose it into self-contained per-task files for incremental, resumable, tool-agnostic execution. Use in place of default Plan Mode for planning non-trivial work — when the user asks to plan a feature/change, says "plan this out", or wants a plan that survives across sessions or can be picked up by another AI coding tool. |
| model | opus |
| effort | high |
| allowed-tools | Read Write Edit Agent |
Replaces ad hoc use of native Plan Mode. Native Plan Mode writes to ~/.claude/plans
and expects the same session to execute it — on large plans the context window fills
up mid-execution, forcing a new session to re-derive what was/wasn't done. This skill
writes plans (and optionally tasks) as repo-local files instead, so they're easy to
find, easy to resume cheaply in a fresh session, and readable by any AI coding tool
working in the repo (Codex, OpenCode, etc.), not just Claude Code.
Write directly to ./.claude/plans/<plan-name>.md. Don't force an interview first —
only pause to ask clarifying questions if the request is genuinely ambiguous (unclear
goal, multiple plausible interpretations, missing key constraint). Otherwise draft
straight away.
The plan doc is free-form prose, not a rigid template. It should capture:
- the goal and why it matters
- key constraints and decisions made while planning
- enough context that someone with no prior conversation history understands the "what" and "why", not just a step list
It may optionally describe an end-state / acceptance picture, but this is never treated as a mandatory final gate later — see Step 4.
For all intents and purposes, this should be treated as a regular "Plan" session, albeit with a different output for plan artifacts.
Present the drafted plan and get explicit approval before doing anything else. Do not proceed to decomposition or start acting on the plan until approved.
After approval, judge whether the plan actually has separable, independently executable chunks of work. This is a judgment call about the shape of the plan, not a size or token-count threshold. Small or simple plans can just be executed directly from the single plan document — skip task files entirely.
If you are unsure, ask the user whether they want to decompose the plan into tasks.
One file per task at ./.claude/tasks/<NUMBER>-<TASK-SLUG>.md, flat directory
(no per-plan subfolders). Numbers are stable sort/reference IDs only, not an
execution order — real ordering is declared via an explicit Depends on field,
since independent tasks may run in parallel or out of number order.
Granularity: the smallest cohesive, independently-verifiable unit of change, grouped by functional cohesion — not by estimating token/size budget. Fitting in a session is a natural side effect of a good functional split, not the target itself.
Every task file must let a completely fresh agent — any AI tool, zero conversation history — execute it correctly. Optimize for that, not for cheap status-tracking. Include:
- Goal — what this task accomplishes and why, in the context of the overall plan
- Depends on — other task numbers, or
none - Context — all context/requirements/detail from the plan relevant to this task. Do not assume the executing agent has read the plan doc or any other task file; over-include rather than under-include.
- Steps — concrete steps to take
- Verification — how to confirm this task's own requirements are met (a specific test command, a specific manual check, a specific observable behavior). Reason this out now, during planning, as part of the task's requirements — not deferred to execution time.
- Cleanup — When a task finishes executing the agent should clean up the task file to avoid stale task files cluttering.
Do not add status fields (not-started/in-progress/done) or completion
checkboxes for the sake of resumability — a task file rich enough in context lets any
agent compare it against actual repo state and figure out what's done. Bookkeeping
fields are a substitute for that richness, not an addition to it.
Write everything tool-agnostically: describe what to run or check (e.g. "run
dotnet test Source/X", "confirm Y renders correctly in the browser"), never which
Claude Code tool to use (never "use the Explore agent" or "invoke Grep"). A human, or
any other coding agent, must be able to follow the file just as well.
Show the task list for adjustment (splitting, merging, reordering). This is a soft checkpoint, not a hard re-approval gate — proceed if nothing needs changing.
- Execution itself. This skill's job ends once the plan (and optional tasks) are written and adjusted. Same session, new session, a different AI tool entirely — that's decided at execution time, not by this skill.
- Mid-execution scope changes. A task turning out too big, or spawning new
discovered work, is a runtime judgment call. Do not prescribe a splitting scheme
(e.g.
03a/03b) — that decision is made in the moment it's needed, not in advance. - A final whole-plan verification gate. The unit of "done" is the task, not the plan. There is no required end-to-end check after all tasks finish beyond what each task already verified for itself.
Once a task's changes are committed, delete its task file. No archive, no done/
folder — .claude/plans and .claude/tasks are ephemeral, gitignored scratch space;
git history is the actual persistent record (the same principle this project applies
to ADRs/PIRs versus scratch planning notes).