Skip to content

Add TDD process discipline to testing agent rules #159

Description

@markcallen

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:

  1. Start from acceptance criteria: define or update acceptance criteria in PRD.md before implementation.
  2. Write a failing test first: create the smallest test that proves the requirement is not yet met and confirm it fails.
  3. Implement the minimum change: change only what is needed to make the failing test pass.
  4. Refactor with tests green: improve the design only after the tests pass.
  5. 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:

  1. When TDD applies: bug fixes, new features, refactors with behavioral impact, contract changes
  2. The five-step cycle: acceptance criteria → failing test → minimum implementation → green → refactor
  3. Test-first verification: confirm the test fails for the right reason before implementing
  4. Proof of completion: the previously-failing test must pass; record this as evidence
  5. Failure-path coverage: tests must assert error/edge paths, not only the happy path
  6. 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

  • A TDD process section is added to common/typescript-testing.md (and propagated to language-specific variants)
  • The section defines the five-step TDD cycle clearly
  • The rule specifies that test-first is required for behavioral changes, not optional
  • Failure-path coverage is explicitly called out as required
  • The rule connects tests to acceptance criteria / issue traceability
  • The rule distinguishes between tooling setup (Jest/Vitest config) and process discipline (TDD cycle) so neither is lost

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or request

    Type

    No type

    Fields

    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions