tdd

Use test-driven development to deliver features/fixes in small behavior-focused increments.

Core principles

• Test observable behavior via public interfaces.
• Avoid coupling tests to internal implementation details.
• Work in vertical slices: one failing test -> minimal passing code -> repeat.
• Refactor only while green.

Workflow

1) Plan behavior and boundaries

Before coding:

• Confirm target behavior with the user (or issue AC)
• Identify public interface changes
• Select highest-value behaviors to test first
• Spot deep-module opportunities (simple interface, deep internals)

2) Tracer bullet first

Create one thin end-to-end test that proves a real path.

RED: write one failing behavior test
GREEN: write minimal code to pass

3) Incremental red-green loop

For each next behavior:

RED: next failing behavior test
GREEN: minimal implementation

Rules:

• One test at a time
• No speculative implementation
• Keep assertions on externally visible outcomes

4) Refactor pass

When all current tests are green:

• Remove duplication
• Deepen modules where complexity is leaking
• Tighten names/interfaces
• Re-run test suite after each refactor step

Never refactor while red.

Test quality checklist

• Test describes behavior (not internals)
• Test uses public interfaces only
• Test survives internal refactor
• Added code is minimal for current failing test
• No dead code or TODO placeholders

Harness verification gates

After meaningful changes, run:

bun run typecheck
bun run lint
bun test

If a sub-repo defines different commands, follow that sub-repo's AGENTS.md.

Beads integration

Use beads to track TDD slices:

bd create --type task --title "TDD slice: <behavior>" --description "<expected behavior and test scope>" --priority 2 --repo .
bd comments add <id> "worklog: red->green completed for <behavior>"

Deep-dive references

Bundled with this skill (self-contained — no external repos required):

• tests.md — concrete good vs. bad test examples
• interface-design.md — designing interfaces for testability
• deep-modules.md — small interface, deep implementation
• mocking.md — mock only at system boundaries
• refactoring.md — refactor candidates after green

Attribution

The bundled deep-dive docs (tests.md, interface-design.md, deep-modules.md, mocking.md, refactoring.md) are vendored verbatim from the tdd skill in mattpocock/skills. This SKILL.md is an Agent Forge adaptation of the same concepts (Beads tracking + harness quality gates). Original work © 2026 Matt Pocock, MIT License:

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND.