plan-and-build

name	plan-and-build
version	2.0.0
description	Use when a user wants to plan and implement a new feature or bug fix from scratch. Triggers on requests like "I want to build X", "add a feature for Y", "fix Z", or when the user invokes /plan-and-build. Guides through clarifying questions, breaks work into small features, sets up a tasks folder, implements each feature with TDD (test first), and produces a manual testing guide when complete.
user-invokable	true
argument-hint	[feature or fix description]
license	MIT
allowed-tools	Read, Grep, Glob, Bash, Write, Edit, Agent

Plan and Build

Overview

A structured workflow that turns a vague feature idea or bug report into working, tested code — one small feature at a time. Combines targeted clarifying questions, TDD, and task tracking in a reusable folder structure.

Core principle: Ask first, build small, test first, document last.

Process Flow

digraph plan_and_build {
    rankdir=TB;
    "Explore codebase context" [shape=box];
    "Detect test framework" [shape=box];
    "Extract existing patterns" [shape=box];
    "Ask clarifying questions\n(one at a time)" [shape=box];
    "Propose approach\nand get approval" [shape=box];
    "Create tasks/ folder\n(all-features, todo, done)" [shape=box];
    "Setup Git branch\n(optional)" [shape=box];
    "Pick next feature\nfrom all-features → todo" [shape=box];
    "Write failing test (RED)" [shape=box];
    "Implement (GREEN)" [shape=box];
    "Test failed?" [shape=diamond];
    "Debug & recover\n(or mark blocked)" [shape=box];
    "Move feature to done\n(with metadata)" [shape=box];
    "More features?" [shape=diamond];
    "Revisit blocked features?" [shape=diamond];
    "Create guide/<name>.md\nimplementation guide" [shape=box];

    "Explore codebase context" -> "Detect test framework";
    "Detect test framework" -> "Extract existing patterns";
    "Extract existing patterns" -> "Ask clarifying questions\n(one at a time)";
    "Ask clarifying questions\n(one at a time)" -> "Propose approach\nand get approval";
    "Propose approach\nand get approval" -> "Create tasks/ folder\n(all-features, todo, done)";
    "Create tasks/ folder\n(all-features, todo, done)" -> "Setup Git branch\n(optional)";
    "Setup Git branch\n(optional)" -> "Pick next feature\nfrom all-features → todo";
    "Pick next feature\nfrom all-features → todo" -> "Write failing test (RED)";
    "Write failing test (RED)" -> "Implement (GREEN)";
    "Implement (GREEN)" -> "Test failed?";
    "Test failed?" -> "Debug & recover\n(or mark blocked)" [label="yes"];
    "Test failed?" -> "Move feature to done\n(with metadata)" [label="no"];
    "Debug & recover\n(or mark blocked)" -> "Move feature to done\n(with metadata)" [label="recovered"];
    "Debug & recover\n(or mark blocked)" -> "More features?" [label="blocked"];
    "Move feature to done\n(with metadata)" -> "More features?";
    "More features?" -> "Pick next feature\nfrom all-features → todo" [label="yes"];
    "More features?" -> "Revisit blocked features?" [label="no"];
    "Revisit blocked features?" -> "Pick next feature\nfrom all-features → todo" [label="yes"];
    "Revisit blocked features?" -> "Create guide/<name>.md\nimplementation guide" [label="no"];
}

Phase 0 — Detect Test Framework

Before exploring the feature space, figure out how this project tests. The TDD loop in Phase 4 depends on a working test command.

Detection checklist:

1. Read package.json → check devDependencies and scripts.test for: vitest, jest, mocha, ava, playwright, cypress, bun test, deno test
2. Look for config files: vitest.config.*, jest.config.*, .mocharc*, pytest.ini, pyproject.toml ([tool.pytest]), phpunit.xml, Cargo.toml ([dev-dependencies]), go.mod
3. Look for existing test files: **/*.test.{ts,tsx,js,jsx}, **/*.spec.*, __tests__/, tests/, test/, *_test.go, test_*.py
4. Note the runner command (e.g. pnpm test, npm run test:unit, pytest -k, cargo test) and the single-file pattern (e.g. vitest run path/to/file.test.ts)

Decision rules:

• Framework found + tests exist → record the runner command and continue
• Framework found, no tests yet → record the runner, scaffold the first test in Phase 4
• No framework found → ask the user: "I don't see a test framework. (A) Set up Vitest, (B) Set up Jest, (C) Skip TDD for this work, (D) I'll tell you the framework"
• Unfamiliar framework → ask: "How do I run a single test file in this project?"

Record the answer in the tasks/all-features.md header (see Phase 3) so future sessions don't re-detect.

Phase 1 — Explore and Extract Patterns

Read the codebase before asking the user anything:

• Check existing files, services, routes, components related to the request
• Check CLAUDE.md for project conventions and patterns
• Check tasks/ folder — if features already exist, jump to Resuming Work below

Then identify 2–3 existing features that resemble what's being built and extract their patterns:

Pattern	What to look for
Naming	camelCase vs snake_case, file suffixes (.service.ts, _handler.py), test file naming
Directory layout	Where do similar features live? Co-located tests or separate __tests__/?
Error handling	Throw vs Result types vs error returns; centralized error middleware?
Logging	Which logger, what level conventions, what gets logged on error
API shape	REST resource style, RPC method names, response envelope ({ data, error } vs raw)
Validation	Zod, Pydantic, Joi, manual; where validation happens (boundary vs deep)

If the codebase is legacy or inconsistent (different files use different patterns), surface the conflict and ask: "I see two patterns for X — (A) the older approach in foo.ts, (B) the newer approach in bar.ts. Which should I follow?"

After extracting, ask clarifying questions one at a time. Prefer multiple choice (A/B/C). Stop when you have enough to propose an approach. Typical questions:

• What is the core workflow / user action?
• Who uses it and what access do they have?
• What data needs to be collected or shown?
• What happens after the action completes?
• Does it need to integrate with existing systems (payments, auth, etc.)?

Phase 2 — Propose and Approve

Present 2–3 approaches with trade-offs. Lead with your recommendation and why. Wait for explicit user approval before proceeding.

Phase 3 — Task Folder Setup

Create these three files (or append to them if they already exist):

tasks/all-features.md

# [Feature Name] — All Features

## Context
- **Test runner:** `<command from Phase 0>` (single-file: `<command> <path>`)
- **Patterns to follow:**
  - Naming: <e.g. camelCase, files end in `.service.ts`>
  - Errors: <e.g. throw `AppError`, caught by `errorMiddleware`>
  - Logging: <e.g. `pino` at `info`/`error`>
  - API shape: <e.g. REST, `{ data, error }` envelope>
- **Reference features:** `src/foo/`, `src/bar/`

## Features
- [ ] F01 — short description
- [ ] F02 — short description
...

tasks/todo.md

# TODO

## F01 — [current feature]
Steps:
1. ...

## Blocked
_(features paused mid-implementation — see Phase 4.5)_

tasks/done.md

# Done

_Completed features logged here with metadata._

Features must be small and independent — each one should be implementable in a single focused session. A feature that touches UI, service, and route is too big; split it.

Phase 3.5 — Git Branch (optional)

Ask once after the task folder is set up: "Want me to set up a feature branch and commit per feature, or do you handle git yourself?"

If the user opts in (or CLAUDE.md declares a convention like git-workflow: feature-branch-per-task):

• Branch: feature/<kebab-case-feature-name> off the current default branch
• Per-feature commits: one commit when each feature moves to done.md, message format F01: <short description>
• Final commit: the implementation guide gets its own commit, message docs: add <feature> manual testing guide

If the user declines, or if CLAUDE.md says the user manages version control manually, skip this phase entirely — do not run git commands.

This phase is opt-in. When in doubt, ask. Never force a branch on a user who hasn't asked for one.

Phase 4 — TDD Implementation (repeat per feature)

REQUIRED SUB-SKILL: Follow superpowers:test-driven-development strictly.

For each feature:

1. Update tasks/todo.md with the current feature
2. Write the failing test first — run it with the Phase 0 runner command and confirm it fails for the right reason
3. Write the minimal implementation to pass the test (follow patterns recorded in all-features.md header)
4. Run the test again — confirm green
5. Run the full test suite — confirm nothing else broke
6. Update tasks/all-features.md (check the box)
7. Append to tasks/done.md with metadata (see format below)
8. If Phase 3.5 was enabled, create the per-feature commit
9. Update tasks/todo.md to the next feature
10. Repeat

Auto mode: Unless the user has said to ask for permission, proceed through all features without pausing. Only stop if a feature requires a decision the user hasn't answered yet.

done.md entry format

Append one block per completed feature:

## F01 — [feature name] ✓
- **Tests:** 4/4 passing
- **Files changed:** 3 (1 new, 2 modified)
- **Lines:** +120 / -8
- **Complexity:** Medium — async DB write, external email call mocked
- **Notes:** <any non-obvious decision worth remembering>

Complexity rubric:

• Low — pure logic, single file, no I/O, no async
• Medium — async, one external dep, or touches 2–3 files
• High — multiple external deps, concurrency, transactions, or complex state machines

Phase 4.5 — Error Recovery

When a test fails unexpectedly during implementation (red→green never goes green, or green→red after a passing run):

REQUIRED SUB-SKILL: Follow superpowers:systematic-debugging for the diagnostic loop.

Quick recovery checklist (in order):

1. Re-read the test expectation — does it match what you actually intended to build? Often the test is wrong.
2. Run the failing test in isolation — <single-file runner> <path> — confirm it's not a side-effect from a sibling test
3. Add a logging line at the assertion — print the actual vs expected value
4. Check the patterns recorded in all-features.md — did you drift from the project's error-handling or validation convention?
5. Bisect the implementation — comment out half, see which half breaks the test

The 15-minute rule: if you've been stuck on the same failing test for ~15 minutes with no narrowing of the cause, stop and mark the feature blocked. Don't grind.

To mark blocked:

1. Move the feature's section in todo.md from the active area to the Blocked section
2. Add a short note: what was tried, the last error message, and the hypothesis you couldn't verify
3. Pick the next feature from all-features.md and continue
4. After all unblocked features are done, return to blocked features with fresh context (often the next feature reveals the missing piece)

Example blocked entry:

## Blocked
### F03 — webhook signature validation
- **Last error:** `Invalid signature` even with documented test vector
- **Tried:** swapped HMAC algorithms, checked encoding, verified secret
- **Hypothesis:** the upstream service may be using a non-standard canonical form — need their docs

Phase 5 — Implementation Guide

When all features in tasks/all-features.md are checked (and any blocked features have been resolved or explicitly deferred):

Create guide/<kebab-case-feature-name>.md with:

# [Feature Name] — Manual Testing Guide

## Prerequisites
[What must exist before testing — accounts, data, env vars]

## 1. [First test scenario]
Steps + expected result

## 2. [Second test scenario]
...

## Common Issues
| Issue | Likely cause | Fix |

The guide must be written for a human following it for the first time with no prior context.

If Phase 3.5 was enabled, commit the guide as the final commit on the branch.

Rules

• One question per message during Phase 1
• No production code before a failing test — Iron Law
• Features stay small — if a feature takes more than one file to explain, split it
• tasks/ folder is the source of truth — always check it at the start of a session to resume work
• Auto mode by default — don't ask for permission between features unless blocked
• 15-minute debug cap — mark blocked and move on rather than grinding

Resuming Work

If tasks/all-features.md already exists, start here instead of Phase 0/1:

1. Read the Context section of tasks/all-features.md — adopt the recorded test runner and patterns; don't re-detect
2. Read tasks/all-features.md — find unchecked features
3. Read tasks/done.md — understand what's already built (and the metadata of past features for sizing)
4. Read tasks/todo.md — check if a feature is in progress, and check the Blocked section
5. Continue from where work left off; consider blocked features first if you have new context

Common Mistakes

Mistake	Fix
Features too large	Split until each fits in one focused session
Test written after implementation	Delete the code, start over
Skipping the guide at the end	The guide is part of the deliverable — always write it
Stopping between features to ask permission	Work through all features unless blocked
Not reading codebase before questioning	Always explore first — avoids redundant questions
Not detecting test framework before starting	Detect in Phase 0 — discovering "no test runner" mid-implementation wastes the TDD cycle
Ignoring existing codebase patterns	Extract 2–3 reference features in Phase 1 — code that drifts from local convention is harder to review and maintain
Not documenting blocked features	Always write the Blocked entry with last error + hypothesis — without it, the next session re-treads the same dead ends
Committing all features in one giant commit	One commit per feature (when Phase 3.5 is enabled) — keeps review and rollback granular
Grinding past 15 minutes on a stuck test	Mark blocked, move on, return with fresh context