plan-and-build
A Claude Code skill that turns a vague feature idea or bug report into working, tested code — one small feature at a time.
What it does
When you invoke /plan-and-build, Claude will:
- Detect your test framework — figures out the runner (Vitest, Jest, pytest, cargo, etc.) before anything else
- Explore your codebase — reads existing files, patterns, and conventions before asking anything
- Extract reference patterns — pulls naming, error handling, logging, and API shape from 2–3 similar features
- Ask clarifying questions — one at a time, to understand what you're building and how it should work
- Propose an approach — 2–3 options with trade-offs, waits for your approval
- Set up a task folder — creates
tasks/all-features.md, tasks/todo.md, and tasks/done.md
- Build feature by feature — picks one feature at a time, writes a failing test first (TDD), implements, marks done, repeats
- Recover from failures — structured debugging loop with a 15-minute cap; stuck features get marked blocked instead of grinding
- Create a testing guide — when all features are complete, writes
guide/<feature-name>.md with step-by-step manual testing instructions
What's New in v2.0
- Phase 0 — Test framework auto-detection. No more discovering "no test runner" mid-feature.
- Codebase pattern extraction. Picks up local conventions (naming, errors, logging) before writing code.
- Optional Git workflow. Opt-in feature branch with one commit per feature and a final docs commit.
- Error recovery with a 15-minute cap. Structured debug loop; stuck features get marked blocked and revisited later.
- Richer
done.md metadata. Test counts, file deltas, complexity rubric, and notes per feature.
- 5 new common-mistake entries covering framework detection, pattern drift, blocked-feature docs, commit granularity, and the debug cap.
See CHANGELOG.md for the full release history.
Why use it
Without structure, features get built all at once, tests get skipped, and you end up with no record of what was built or how to test it. This skill enforces:
- Small features — each one is scoped, testable, and completable in a single session
- Test-first (TDD) — no production code without a failing test first
- Progress tracking —
tasks/ folder is the source of truth; work can always be resumed
- Documentation — every feature ships with a manual testing guide
Usage
/plan-and-build
or with a description:
/plan-and-build add a cash payment flow for walk-up ticket sales
Claude will take it from there.
What gets created
tasks/
all-features.md ← full feature list with checkboxes + recorded test runner & patterns
todo.md ← current feature being worked on (and Blocked section)
done.md ← completed features with test counts, file deltas, and complexity
guide/
<feature-name>.md ← manual testing guide written at the end
Resuming work
If you close a session mid-way, just run /plan-and-build again in the same project. Claude reads the tasks/ folder — including the recorded test runner and patterns — and picks up exactly where you left off.
Example session
You: /plan-and-build build a POS system for walk-up ticket sales
Claude: What should a Sunmi operator be able to do from the POS?
A — Scan only
B — Scan + print pre-purchased tickets
C — Full cashier: sell, collect cash, print
You: C but cash only
Claude: Who operates the device?
A — Promoter only
B — Hired staff with their own login
C — Either — promoter hands device to staff
You: C
...
[After questions → proposes approach → you approve]
Claude: Creating tasks/all-features.md with 11 features...
Starting F01 — posService.createCashSale()
Writing failing test...
✓ RED confirmed
Implementing...
✓ GREEN — 5/5 tests passing
Moving F01 to done. Starting F02...
Requirements
- Claude Code CLI
- A project with a
src/ directory and a test runner (Vitest, Jest, pytest, cargo, etc.)
- For TDD to work, the project must have tests set up (or Claude will offer to scaffold one)
Updating
To pull the latest version of the skill, run this one-liner:
curl -fsSL https://raw.githubusercontent.com/jattanjie21/plan-and-build-skill/main/SKILL.md \
-o ~/.claude/skills/plan-and-build/SKILL.md
Or use the included update.sh script (recommended — verifies the download and prints the new version):
curl -fsSL https://raw.githubusercontent.com/jattanjie21/plan-and-build-skill/main/update.sh | bash
If you've already cloned the repo locally:
./update.sh
Restart Claude Code after updating so the new skill content is loaded.
Installation
The skill lives in ~/.claude/skills/plan-and-build/SKILL.md and is automatically available in all Claude Code sessions.
To install on a new machine:
mkdir -p ~/.claude/skills/plan-and-build
curl -o ~/.claude/skills/plan-and-build/SKILL.md \
https://raw.githubusercontent.com/jattanjie21/plan-and-build-skill/main/SKILL.md
For future updates, use the update.sh script or the one-liner from the Updating section above.
License
MIT
Version history →
