code-tdd

Files (1)

• SKILL.md

SKILL.md (first lines)

!`bash ${CLAUDE_SKILL_DIR}/../../hooks/read-state.sh session-state`

<preflight-guard>
STOP. Before executing this skill, check: does .sweetclaude/state/sweetclaude.yaml or .sweetclaude/state/phase.yaml exist in the project directory? If NEITHER, do not proceed. Tell the user: "This project is not set up for SweetClaude. Running the pre-flight check now." Then invoke the sweetclaude master skill (Skill tool, skill: "sweetclaude:master") and run its pre-flight. Return here only after the pre-flight passes.
</preflight-guard>

# SweetClaude TDD

Tests specify behavior. Implementation satisfies tests. Hooks enforce this. No exceptions.

## Process Control Gate

Before any Level 2 or Level 3 subagent dispatch, and before any QA caucus, read
`skills/process-controls.md` and create or update
`.sweetclaude/state/process-control-ledger.yaml`.

Do not spawn a test writer, implementer, reviewer, or caucus if the ledger is
missing, over budget, stale, or in a stop disposition. Stop and ask the user
for a bounded decision instead.

Default budget for this skill without explicit user approval:

- one test-writer dispatch;
- one implementer dispatch;
- one three-reviewer QA caucus;
- no more than two caucus/correction rounds for the same story;
- no more than one blocking caucus failure before user decision or contract
  reopen.

If repeated caucus findings, repeated failed RED/GREEN correction, WLF/process
failure records, or pass-state bypasses indicate that the story/test contract is
unstable, stop. Do not keep patching tests or spawning more agents under the
same contract.

For large/high-rigor stories, TDD entry requires a frozen
`success_criteria_contract`, its `success_criteria_contract_hash`, and
`criterion_ids`. Tests must trace to the frozen criterion ids, and any missing
coverage becomes either a test gap before lock or a
`criteria-amendment-request.yaml`; it may not silently expand completion scope.
Completion of TDD/implementation requires `success-criteria-ledger.json` with
every frozen criterion evaluated and `all_success_criteria_passed == true`. No
review, caucus, verification, release, or completion step may add completion
criteria.

## Branch Check

```bash
git branch --show-current
```

If the current branch already starts with an issue ID prefix (e.g., `ISSUE-046/...`, `issue-42/...`) — continue. Branch setup was already handled by the calling skill.

If not (direct invocation): derive a branch name from session state `active_work_item.id` + title or from `$ARGUMENTS`. Format: `{ID}/{slug}`. Offer via AskUserQuestion: **Create branch `{branch-name}`** (Recommended) / **Stay on current branch** / **Something else**.

## Select TDD Level

| Level | When | Process |
|---|---|---|
| 0: Hotfix | Production emergency | Fix first. Write regression test in same session. No grace period. |
| 1: Light | Simple CRUD, config, straightforward | Single-context RED-GREEN-REFACTOR. Tests still first. Still confirmed RED. |
| 2: Standard | Features, bug fixes, behavior changes | Subagent separation: test writer ≠ implementer. Tests committed before impl. |
| 3: Full | Net-new features with Gherkin specs | Gherkin → test writer → QA caucus → user approval → implementer → verify |

Propose a level based on work complexity.

Use AskUserQuestion with these options:
- "Level 0: Hotfix" — production emergency, fix first, regression test immediately
- "Level 1: Light" — simple change, single-context RED-GREEN-REFACTOR
- "Level 2: Standard" — separate test writer and implementer, tests committed before implementation
- "Level 3: Full" — from Gherkin specs with QA caucus review

After the user selects a level, record the selection:

## Level 0: Hotfix

1. Fix the immediate issue
2. Write a regression test that would have caught it
3. Confirm the test fails without the fix (revert fix, run test, re-apply fix)
4. Commit test + fix together

## Level 1: Light

1. **RED:** Write a failing test for the behavior. Use the project's detected test runner.
2. **Verify RED:** Run the test. It must fail. If it passes, the test is wrong — rewrite it.

   Commit the failing test, naming the test files so they are included:
   ```bash
   bash ${CLAUDE_PLUGIN_ROOT}/hooks/git-checkpoint.sh "test: RED - [story-id] failing tests" <test files>
   ```

   Once RED is confirmed, freeze the tests:
   ```bash
   python3 ${CLAUDE_PLUGIN_ROOT}/scripts/tdd_phase.py set --phase implementing --project-dir .
   ```
   This is what makes "tests are immutable during implementation" real — the
   guardian hook reads this marker. Skipping it means the rule is documented
   and unenforced (ISSUE-282).

3. **GREEN:** Write the minimum code to pass the test.
4. **Verify GREEN:** Run the test. It must pass. All other tests must still pass.
5. **REFACTOR:** Clean up. Tests must stay green after each change.
6. **Repeat** for next behavior. Before writing the next test, unfreeze:
   ```bash
   python3 ${CLAUDE_PLUGIN_ROOT}/scripts/tdd_phase.py set --phase writing_tests --project-dir .
   ```

## Level 2: Standard

1. **Write tests** in the main context. Design the interface first: function names, module paths, parameter signatures, return types. Then write tests that import from modules that do not exist yet. Tests are complete behavioral contracts: happy path, validation errors, edge cases, side effects.

2. **Verify RED:** Run tests. All must fail (the modules do not exist).

3. **Commit tests:** Auto-commit with `test: RED - [story-id] failing tests`, naming the test files so they are included:
   ```bash
   bash ${CLAUDE_PLUGIN_ROOT}/hooks/git-checkpoint.sh "test: RED - [story-id] failing tests" <test files>
   ```
   This is the git checkpoint. Test files are now immutable — record that, or the immutability is a claim rather than a fact:
   ```bash

From carson-sweet/sweetclaude, AGPL-3.0.

More from carson-sweet/sweetclaude