/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