tdd-cycle

name	tdd-cycle
description	Reference for the red-green-refactor test-first discipline used by the test-writer and implementer agents. Use when you need the canonical explanation of how Vibin's tests-first workflow works, or to settle a question about test ordering, "minimum" code, or trivially-passing tests.
disable-model-invocation	false

The TDD cycle in Vibin

Vibin is test-first, always (for feature and bug items). Tests are written from the spec before the implementation exists. This page is the canonical reference — the discipline itself is baked into the test-writer and implementer agent prompts, so it runs whether or not anyone invokes this skill.

The cycle

RED — test-writer

• Translate each requirement scenario in wiki/specs/<id>-<slug>.md into a test — one test per scenario, named by requirement ID (e.g. B<n>-R<k> / <scenario>).
• The tests must fail when first run — the feature does not exist yet.
• Verify they fail for the right reason (feature missing, or, for a bug item, the reported failure reproduced), not because of a typo or a broken test harness.
• No implementation code is written in this step.

What counts as trivially-passing

A trivially-passing test is one that would pass before any implementation exists — e.g. assert True, asserting against a constant the test sets itself, or checking "function exists" without exercising it. The test-writer does not write these. See .claude/agents/test-writer.md → "What counts as a trivially-passing test".

GREEN — implementer

• Write the minimum code that makes the failing tests pass.
• No extra features, no speculative abstractions, no scope beyond the spec and tests.
• Re-run until the targeted tests pass and the full suite is green.
• Tests are not weakened, deleted, or trivially rewritten to get green. A test that looks genuinely wrong is flagged, not silently changed.

What counts as "minimum"

Minimum = the smallest code that turns the tests green. If an inline check would pass, do not extract a helper; if a literal value would pass, do not generalise; if one file is enough, do not split it. See .claude/agents/implementer.md → "What counts as 'minimum'".

REFACTOR — implementer, optional, within the same item

• With the suite green, improve structure/readability without changing behaviour.
• The suite must stay green throughout. If it goes red, the refactor is the problem.
• Keep it minimal — refactoring is not a license for scope creep. Larger cleanups belong in a separate chore item.

Why tests first

• The requirement scenarios become executable — "done" is objective.
• The implementer gets an unambiguous target and a regression net.
• The reviewer can verify against a concrete contract, not an opinion.

Ground rules

• One backlog item flows RED → GREEN → (REFACTOR) before the next item starts.
• The full test suite — not just the new tests — must be green for an item to be done (moved to wiki/backlog/done/).
• If the spec is too vague to write a testable test, that is a spec problem: report it back up the pipeline rather than guessing.
• chore and research items skip this cycle — chore runs implementer → reviewer without tests-first; research produces a wiki/research/<topic>.md artifact. See the Tracks table in .claude/skills/manager/SKILL.md.

Anti-rationalization anatomy

The cycle only holds if agents resist the shortcuts that quietly defeat it ("too small to test", "the test mirrors the code", "I'll refactor later", "green is enough, pass it"). Each pipeline agent therefore carries three sections that name the temptation and the evidence that counters it — read them before you start:

• Rationalizations → rebuttals — common excuses paired with the reality.
• Red flags — symptoms to catch in yourself mid-task.
• Verification — the concrete evidence required to claim done.

See .claude/agents/test-writer.md, .claude/agents/implementer.md, .claude/agents/reviewer.md, and .claude/agents/spec-writer.md.