From workflow-skills
Write a multi-step implementation plan as markdown files under dev_docs/tasks/<name>_plan/ instead of printing it inline, then refine the plan through clarifying questions. Use when the user runs /plan-with-docs, asks to "plan X to files", or has just approved a plan in plan mode and wants it persisted. Default for any plan that is more than ~3 tasks or spans multiple PRs.
How this skill is triggered — by the user, by Claude, or both
Slash command
/workflow-skills:plan-with-docsThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
Plan mode renders the plan inline via `ExitPlanMode` and that's fine for small plans. For larger projects this skill writes a structured set of markdown files instead, so the plan can be edited, committed, and worked through PR by PR. It also preserves the best part of plan mode — clarifying back-and-forth — by surfacing open questions after the files exist, so the user can refine the plan in p...
Plan mode renders the plan inline via ExitPlanMode and that's fine for small plans. For larger projects this skill writes a structured set of markdown files instead, so the plan can be edited, committed, and worked through PR by PR. It also preserves the best part of plan mode — clarifying back-and-forth — by surfacing open questions after the files exist, so the user can refine the plan in place instead of restarting.
A plan is a set of tasks in the same format the task loop uses (skills/task/SKILL.md). Each <name>_task_N.md is born status: new, so once the plan exists the user can run /promote-tasks and /do-tasks over it like any other backlog — plan output feeds the same pipeline.
Task files are prefixed with the plan
<name>and numbered uniquely across the whole plan.is_blocked_byresolves slugs (filename stems) globally acrossdev_docs/tasks/**/*.md, so a baretask_1.mdcollides with every other plan'stask_1.md, and reused numbers across phases collide within one plan. Prefixing with<name>and never reusing a number keeps every slug unique; keep<name>short.
Legacy migration preflight. Older versions wrote plans under
dev_docs/todo/. Before writing, if a legacydev_docs/todo/directory exists, run the Legacy migration prompt fromskills/task/SKILL.mdto move it todev_docs/tasks/, then continue.
For a plan named <name> (snake_case, derived from the project/feature):
dev_docs/tasks/<name>_plan/
<name>_plan.md # top-level overview + index of tasks (the epic file, NOT a task itself)
<name>_task_1.md # one PR-sized task per file, canonical task format
<name>_task_2.md
...
If tasks naturally cluster into phases, nest them — but keep the task numbers unique across the whole plan, not per-folder:
dev_docs/tasks/<name>_plan/
<name>_plan.md
phase_1/
<name>_task_1.md
<name>_task_2.md
phase_2/
<name>_task_3.md
Use phases only when there are clear groupings (e.g. "backend → frontend → migration"). Don't invent phases to look organized.
Resolve <name>.
_plan — the directory adds that).Confirm the working directory. Files go under <repo_root>/dev_docs/tasks/<name>_plan/. Find repo root with git rev-parse --show-toplevel. If not in a git repo, use the current working directory and say so. Create dev_docs/tasks/<name>_plan/ (and any missing parents) if it doesn't exist — Write handles parents, but mkdir -p first if you're shelling out.
Check for collisions. If dev_docs/tasks/<name>_plan/ already exists, list its contents and ask whether to overwrite (replace existing files), append (add new <name>_task_N.md files with the next available numbers, leaving existing files untouched and updating only the overview's index), or pick a new name. Don't silently clobber. When the existing plan uses phase_N/ nesting, append defaults to the last existing phase unless the user says otherwise; numbering is unique across the whole plan (not per-folder — phase_2/<name>_task_3.md continues from phase_1/<name>_task_2.md), so pick the next free integer across all phases.
Write <name>_plan.md — the overview, written as the plan's epic file (see Epics in skills/task/SKILL.md). Give it epic frontmatter so /list-tasks can roll the plan's tasks up under it:
---
type: epic
title: <human-readable plan title>
status: active # active | done | abandoned
owner: <the user, if known — else omit>
created: <today, ISO date>
---
The type: epic marker is what keeps /promote-tasks and /do-tasks from ever scoring or executing the overview as a task (it is the epic, not a task card). Below the frontmatter, keep the body tight:
<name>_task_N.md (or phase_N/<name>_task_N.md). One line per task describing the deliverable.Write each <name>_task_N.md in the canonical task format (see skills/task/SKILL.md for the full field reference) — a single-PR-sized task:
title, priority, size (Fibonacci 1/2/3/5 — see Task size; if a task estimates > 5, split it), status: new, created, source_branch (the current branch), related_files (the files the task touches, path:line where useful), is_blocked_by (the slug of the earlier task this one depends on — the slug is the prerequisite's filename stem, e.g. <name>_task_1; this is how the plan's ordering is encoded), parent: <name> (the plan's epic slug, so the task rolls up under the overview — <name> is the plan name, the overview stem with _plan stripped), expires, tags.## Context: the bare minimum a developer needs to start — relevant files, prior decisions, gotchas. Written for someone who has never seen this code.## Task: concrete edits / new files / commands. Concrete enough that someone (or another agent) can pick it up cold.## Acceptance Criteria: how we know it's done (≥ 1 bullet, required for promotion). Where useful, split into:
localhost:3000/foo, click Save, confirm toast appears", "run migration on staging snapshot, verify row count matches".Other optional fields are available when they help: assignee (who's accountable) and impact (Fibonacci value estimate 1/2/3/5, mirroring size). Skip optional frontmatter that doesn't apply. Don't pad. (parent is set above to the plan epic; only override it if a task belongs to a different epic.)
Cross-link. Each <name>_task_N.md links back to <name>_plan.md at the top. The overview links forward to each task. Encode hard ordering with is_blocked_by (slug of the prerequisite task), not just prose.
Report. Print the directory tree of what was written and the absolute path to the overview. Don't re-print the plan body — the user can open the files. Mention they can run /promote-tasks to score the new tasks and /list-tasks to see the board. On a tracker handler (Linear/Jira/gh-issue), add a one-line pointer: once they're happy with the plan, /push-plan <name> syncs it to the configured tracker (local-first — the files are always written here first; pushing is a separate, explicit step).
Review with the user. Surface every open question and judgment call you noted while drafting — assumptions you made, alternatives you considered and rejected, gaps in your understanding of the codebase. Ask them one by one (or grouped if tightly related). Update the affected files in place as the user answers; don't make the user restart the planning round-trip. Stop when the user says the plan is good.
[[<name>_task_1]]) are fine when files are in the same folder; use relative paths (phase_1/<name>_task_1.md) across folders so they render in plain GitHub too.skills/task/SKILL.md: if a task would exceed size 5 (~300 lines of diff or > ~5 unrelated files), split it into multiple tasks and chain them with is_blocked_by. (This skill slices a fresh plan; when an existing task card outgrows size 5, the break-down-task skill — skills/break-down-task/SKILL.md — performs the same split on it.)dprint post-processing inside this skill — the user runs that themselves.dev_docs/tasks/<name>_plan/, regardless of the configured task handler. Syncing a vetted plan to an external tracker (Linear/Jira/gh-issue) is a separate, explicit act — /push-plan <name> — never an auto-sync on write.Guides creation, editing, and verification of skills for AI coding agents using test-driven development with subagent scenarios. Use when authoring or debugging skills.
npx claudepluginhub bestdan/workflow-skills --plugin workflow-skills