From design-to-code
Use after design-to-code:brainstorming-from-design completes and spec.md is user-approved. Reads spec.md and produces plan.md decomposed into subagent-ready functional units. MUST be followed by design-to-code:subagent-driven-development.
How this skill is triggered — by the user, by Claude, or both
Slash command
/design-to-code:writing-plansThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
Turn an approved `spec.md` into an implementation `plan.md`, decomposed into functional units that each a single subagent can deliver. Assume the implementer is a skilled engineer who knows nothing about this codebase, so the plan must be precise about files, boundaries, and completion criteria. DRY. YAGNI. TDD. Frequent commits.
Turn an approved spec.md into an implementation plan.md, decomposed into functional units that each a single subagent can deliver. Assume the implementer is a skilled engineer who knows nothing about this codebase, so the plan must be precise about files, boundaries, and completion criteria. DRY. YAGNI. TDD. Frequent commits.
This skill writes documentation only; no production code.
Announce at start: "I'm using the writing-plans skill to turn the spec into an implementation plan."
Save plans to: docs/design-to-code/<YYYY-MM-DD>-<topic>/plan.md (co-located with spec.md).
plan.md section headings may be in English, but all body content MUST be written in Chinese (Simplified). This applies to task names, goal descriptions, notes, acceptance descriptions, and any prose. Code identifiers, file paths, and proper nouns (framework names, library names) remain in their original form.
If spec.md covers multiple independent subsystems that don't share an acceptance surface, stop and ask the user to return to design-to-code:brainstorming-from-design to split the spec. One plan.md should produce one shippable, verifiable feature.
Do NOT regenerate or duplicate the acceptance checklist. spec.md is the single source of truth for acceptance; plan.md describes which acceptance a task covers semantically, and never copies or quotes the spec's wording.
Before defining tasks, map out which files will be created or modified and what each one owns. This is where decomposition decisions get locked in.
Common decomposition axes for a frontend feature (pick what fits; not a mandate):
Each task entry MUST have:
### Task N: <name>
- **Goal**: <one-line outcome>
- **Files**:
- Create: `exact/path/to/file.ts`
- Modify: `exact/path/to/existing.tsx`
- **Depends on**: <task ids or "none">
- **Acceptance**:
- Covers the spec.md acceptance item(s) about <semantic description, e.g. "empty-state copy + CTA visibility on the cart page">
- Type-check passes; this task introduces no compile errors
- **Notes for subagent**: <hints, reference patterns, gotchas>
Why semantic descriptions, not quoted text: the spec-reviewer subagent reads both spec.md and the implementation at review time and compares line-by-line; it does not need plan.md to anchor on verbatim strings. Quoting fragments of spec.md into plan.md creates a brittle link that silently breaks when spec.md is revised.
Each task must be:
spec.md acceptance(s) it covers, plus a local check (type-check / no compile errors).Depends on explicitly; dependency graph must be acyclic.Every plan.md MUST start with:
# Implementation Plan: <topic>
> **For agentic workers:** REQUIRED SUB-SKILL: Use `design-to-code:subagent-driven-development` to implement this plan task-by-task.
**Spec**: ./spec.md
**Created**: YYYY-MM-DD
## Overview
<2-3 sentences: overall approach and why this decomposition>
## Shared Context
<Project conventions every subagent needs: framework stack, path aliases,
linting rules in force, state-management conventions, i18n conventions —
whatever THIS project requires. The main agent decides the contents based
on project specifics; no fixed list.>
## Tasks
### Task 1: ...
Every task must contain the actual content a subagent needs. These are plan failures — never write them:
When invoked in a fresh session where the spec.md path was not passed from a previous skill:
find docs/design-to-code -name "spec.md" | sort to discover existing specs.spec.md was found under docs/design-to-code/; ask the user to run design-to-code:brainstorming-from-design first.You MUST create a task for each of these items and complete them in order:
spec.md in full — the main agent must hold the design intent to verify the subagent's output../plan-writer-prompt.md, fill the variables, and dispatch. The subagent reads the spec, explores the codebase, decomposes into tasks, and writes plan.md. The main agent does NOT do the decomposition itself.plan.md; fix inline (main agent edits plan.md directly for any self-review fixes).Read the plan.md into the conversation. On requested changes, return to step 3 with updated instructions.plan.md — once approved, commit the file with a message like docs: add plan.md for <topic>. Do not proceed until the commit succeeds.design-to-code:subagent-driven-development, passing the plan.md path.digraph writing_plans {
"Read spec.md in full" [shape=box];
"Explore shared context" [shape=box];
"Dispatch plan-writer subagent (./plan-writer-prompt.md)" [shape=box];
"Review subagent output" [shape=box];
"Self-review (fix inline)" [shape=box];
"User approves plan?" [shape=diamond];
"Commit plan.md" [shape=box];
"Invoke design-to-code:subagent-driven-development" [shape=doublecircle];
"Read spec.md in full" -> "Explore shared context";
"Explore shared context" -> "Dispatch plan-writer subagent (./plan-writer-prompt.md)";
"Dispatch plan-writer subagent (./plan-writer-prompt.md)" -> "Review subagent output";
"Review subagent output" -> "Self-review (fix inline)";
"Self-review (fix inline)" -> "User approves plan?";
"User approves plan?" -> "Dispatch plan-writer subagent (./plan-writer-prompt.md)" [label="changes requested"];
"User approves plan?" -> "Commit plan.md" [label="approved"];
"Commit plan.md" -> "Invoke design-to-code:subagent-driven-development";
}
After writing the complete plan, look at the spec with fresh eyes and check the plan against it.
spec.md is covered by at least one task's Acceptance (described semantically, not quoted). List any gaps and add tasks to fill them.clearLayers() in Task 3 and clearFullLayers() in Task 7 is a bug.spec.md. Remove any.Depends on list reflects real inputs.Fix inline. No re-review loop; fix and move on.
After the user approves plan.md, commit it immediately:
git add <plan.md path>
git commit -m "docs: add plan.md for <topic>"
Then hand off:
"Plan approved and committed. Handing off to
design-to-code:subagent-driven-developmentto execute task-by-task."
Do NOT invoke design-to-code:subagent-driven-development until the commit succeeds. Do NOT offer the "subagent-driven vs inline" choice. Within design-to-code, subagent-driven execution is the only path.
./plan-writer-prompt.md — template for the plan-writer subagent. The main agent copies this, fills in {{SPEC_PATH}}, {{PROJECT_ROOT}}, {{SHARED_CONTEXT}}, and {{PLAN_PATH}}, then dispatches it via the Agent tool.plan.md — committed to git by the user's project.Required workflow skills:
spec.md this skill consumes.plan.md this skill produces.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 zhangtianwei1998/design-to-code --plugin design-to-code