tdd

Test-Driven Development — Clear Tests, Written First

Under this skill the test is written before the implementation and is the spec the builder works from. A human (or a builder agent) should be able to read the test file top to bottom and understand exactly what the code is supposed to do — without opening the source. If a test isn't clear on its own, it isn't done.

Do not write implementation code under this skill until the tests exist, fail for the right reason, and the user has seen them.

🎯 Why clarity is the whole point

These tests are a guide handed to a builder agent. The builder implements against them with no other context, so every test must answer three questions by itself:

1. What behavior is being built (the test name).
2. With what inputs (the Arrange block).
3. What counts as correct (one assertion).

A clever, terse, or DRY-but-cryptic test fails as a guide even if it passes as a check. Optimize for the next reader, not for line count.

The cycle

Run it in order, one behavior at a time:

1. Red — write one failing test for the next behavior. Run bun test and confirm it fails because the behavior is missing, not because of a typo, bad import, or compile error. A test that errors out is not a red test.
2. Green — (builder's job, or yours if implementing) write the minimum code to pass.
3. Refactor — clean up with the test as the safety net. The test does not change during refactor; if it has to, you changed behavior, not structure.

Write the smallest next test that forces new code. Don't write ten tests against code that doesn't exist — write one, watch it fail, then move on. The suite grows behavior by behavior.

bun:test — the runner, always

This project uses Bun. Import from "bun:test", run with bun test. Do not auto-detect or ask.

import { test, expect } from "bun:test";

Use describe only to group tests around one subject — keep nesting shallow (one level). Prefer flat, fully-named test(...) calls over deep describe trees; the name carries the meaning. Use beforeEach for shared Arrange only when several tests need the identical setup.