/tdd

name: tdd
description: >
  Write code through a disciplined, BDD-framed Test-Driven Development loop: build a behavior test list, then drive each
  behavior through red-green-refactor with an enforced observed-failure gate. Use when the user wants to implement,
  build, or write code test-first, "do TDD", follow "red-green-refactor", drive code from tests, choose the next test by
  the Transformation Priority Premise (TPP) or ZOMBIES ordering, or grow a feature behavior-by-behavior with tests
  leading. This skill writes and changes code; it does not produce a test plan document (use automated-test-planning, or manual-test-planning for a plan a person
  runs by hand), review or
  audit existing code (use code-review), restructure existing code outside a TDD loop (use refactor, or plan-a-change to
  plan a multi-module restructure), specify what a feature should do (use plan-a-feature), or find the root cause of a
  bug (use investigate). Runs its loop to
  completion without pausing for review; to review each behavior as it lands, use pairing.
argument-hint: "[what to build, a behavior to drive, or a path to a spec/plan]"
allowed-tools:
  Read, Write, Edit, Glob, Grep, Agent, Bash(git *), Bash(find *), Bash(npm *), Bash(npx *), Bash(pnpm *), Bash(yarn *),
  Bash(pytest *), Bash(python3 *), Bash(go *), Bash(cargo *), Bash(make *), Bash(bundle *), Bash(rake *),
  Bash(bash "${CLAUDE_PLUGIN_ROOT}/scripts/han-config-dir.sh")

Project Context

• git installed: !`which git 2>/dev/null || echo "not installed"`
• current branch: !`git branch --show-current 2>/dev/null || echo unknown`
• CLAUDE.md: !`find . -maxdepth 1 -name "CLAUDE.md" -type f`
• project-discovery.md: !`find . -maxdepth 3 -name "project-discovery.md" -type f`
• personal config directory: !`bash "${CLAUDE_PLUGIN_ROOT}/scripts/han-config-dir.sh" 2>/dev/null || echo "$HOME/.claude"`
• project .han/config.md: !`cat .han/config.md 2>/dev/null || echo ""`

As your first action, use the Read tool on `.han/config.md` inside the `personal config directory` path above. A read that returns no file is no personal configuration: continue silently. When that file or the `project .han/config.md` probe supplies content, apply it per [config-rule.md](../../references/config-rule.md), which governs precedence between the two files, relative-path resolution, and what to do with a file that reads but cannot be used.

Constraints (read before anything else)

This skill writes production and test code in your working tree. It is an execution skill, not a document generator. These constraints shape every step and override any instinct to move faster.

• **The observed-failure gate is load-bearing.** No production-code change until a test has been run and observed to

fail for the intended reason in this loop. A test that passes on first run is a stop-and-diagnose signal, not progress. This single rule is what separates real TDD from TDD-flavored code. The verbatim Three Laws and Canon TDD steps it derives from are in [references/tdd-loop.md](./references/tdd-loop.md); pull that reference when a step needs the canon or the implementation gears.

• **The scope gate is the observed-failure gate's companion.** The observed-failure gate proves a red is genuine. It

does not prove the test deserved to exist in this build. No production-code change outside the scope boundary recorded in Step 1, and least of all in shared or cross-application code other consumers depend on. A list item whose green requires an out-of-scope edit is a stop, never an implement; Step 2 carries the resolution ladder that Step 3 works.

• **Two hats.** Never refactor while any test is red. See [references/tdd-loop.md](./references/tdd-loop.md) for the

canonical statement.

• **One behavior at a time.** Exactly one test list item becomes one runnable test per loop. Newly discovered scenarios

are written to the list and deferred, never implemented in the current loop.

• **BDD framing.** Tests describe observable behavior, named in the project's existing test-naming convention, asserting

outcomes through the public interface — never private state. The behavior-naming and Given/When/Then protocol is in [references/bdd-framing.md](./references/bdd-framing.md); pull it when Step 2 needs it.

• **You will be tempted to fake this.** The specific ways an agent fakes TDD, and the discipline that catches each, are

in [references/failure-modes.md](./references/failure-modes.md); pull it when a loop feels off (a test passes on first run, no red is shown, the implementation has outrun the test, refactor is being skipped).

• **YAGNI governs the refactor step and the test list.** Apply the rule in

[../../references/yagni-rule.md](../../references/yagni-rule.md): remove duplication, but do not add abstractions, configuration, or indirection without evidence. Speculative structure added "for flexibility" during refactor is a YAGNI candidate. Speculative scenarios on the test list are deferred with a reopen trigger, never silently added.

Test-Driven Development

Step 1: Resolve Project Config and Confirm Scope

**Resolve commands.** Read CLAUDE.md's `## Project Discovery` section for the test command (under `### Commands and Tests`, not `### Frameworks and Tooling`), the lint command, the build command, language, and framework. If absent, fall back to `project-discovery.md`. If still absent, run `${CLAUDE_SKILL_DIR}/scripts/detect-tdd-context.sh` and parse its output for git state and manifest-inferred commands. Store the resolved test, lint, and build commands for use in every later step.

**Resolve standards and decisions.** Resolve the coding-standards directory and ADR directory the same way: read CLAUDE.md's `## Project Discovery` section; fall back to `project-discovery.md`; fall back to Glob defaults (`docs/`, `docs/adr/`, `docs/coding-standards/`, `docs/decisions/`). Also check `CLAUDE.md` and `AGENTS.md` for inline standards. **Read the standards