Problem
Ballast's testing rules (testing.md, typescript-testing.md, typescript/typescript-testing.md, common/typescript-testing.md, etc.) describe how to configure the test runner (Jest/Vitest setup, coverage thresholds, GitHub Actions integration) but say nothing about TDD process discipline — the workflow an agent or developer must follow when writing tests.
The global AGENTS.md execution framework mandates strict TDD for all behavioral changes:
For any bug fix, feature, refactor with behavioral impact, or contract change:
- Start from acceptance criteria: define or update acceptance criteria in
PRD.md before implementation.
- Write a failing test first: create the smallest test that proves the requirement is not yet met and confirm it fails.
- Implement the minimum change: change only what is needed to make the failing test pass.
- Refactor with tests green: improve the design only after the tests pass.
- Proof of completion: demonstrate the previously failing test passes and record the evidence.
This process discipline is completely absent from Ballast testing rules. An agent following only Ballast rules will configure the test tooling correctly but will write tests after-the-fact rather than driving implementation from tests.
Proposed Resolution
Add a TDD section to the Ballast testing agent rules (common and language-specific variants) covering:
- When TDD applies: bug fixes, new features, refactors with behavioral impact, contract changes
- The five-step cycle: acceptance criteria → failing test → minimum implementation → green → refactor
- Test-first verification: confirm the test fails for the right reason before implementing
- Proof of completion: the previously-failing test must pass; record this as evidence
- Failure-path coverage: tests must assert error/edge paths, not only the happy path
- Traceability: tests should be traceable to acceptance criteria (link to
PRD.md section or issue)
The TDD rules should complement (not replace) the existing tooling setup rules — configuration and process both need to be present.
Acceptance Criteria
Problem
Ballast's testing rules (
testing.md,typescript-testing.md,typescript/typescript-testing.md,common/typescript-testing.md, etc.) describe how to configure the test runner (Jest/Vitest setup, coverage thresholds, GitHub Actions integration) but say nothing about TDD process discipline — the workflow an agent or developer must follow when writing tests.The global
AGENTS.mdexecution framework mandates strict TDD for all behavioral changes:This process discipline is completely absent from Ballast testing rules. An agent following only Ballast rules will configure the test tooling correctly but will write tests after-the-fact rather than driving implementation from tests.
Proposed Resolution
Add a TDD section to the Ballast testing agent rules (common and language-specific variants) covering:
PRD.mdsection or issue)The TDD rules should complement (not replace) the existing tooling setup rules — configuration and process both need to be present.
Acceptance Criteria
common/typescript-testing.md(and propagated to language-specific variants)