---
name: tdd
description: Define testing conventions and TDD standards for the tech stack
summary: "Defines your testing approach — which types of tests to write at each layer, coverage targets, what to mock and what not to, test data patterns — so agents write the right tests from the start."
phase: "foundation"
order: 240
dependencies: [coding-standards]
outputs: [docs/tdd-standards.md]
reads: [create-prd, system-architecture]
conditional: null
knowledge-base: [testing-strategy]
---

## Purpose
Define the project's testing conventions, TDD workflow, test pyramid, coverage
goals, quality gates, and testing patterns. This tells agents how to test the
code they write and establishes testing standards before implementation begins.
Includes concrete reference examples for each test category using the project's
actual test framework and assertion library.

## Inputs
- docs/tech-stack.md (required) — determines test runner, assertion library, and framework-specific testing patterns
- docs/coding-standards.md (required) — naming conventions and code patterns that apply to test files
- docs/plan.md (required) — features inform which testing scenarios matter most
- docs/system-architecture.md (optional) — if available, layers to test
- docs/domain-models/ (optional) — if available, business rules to verify
- docs/adrs/ (optional) — if available, testing technology choices

## Expected Outputs
- docs/tdd-standards.md — testing approach with coverage goals and patterns

## Quality Criteria
- (mvp) Test pyramid (or equivalent testing model for non-layered architectures) defined with coverage targets per layer (defined per layer, e.g., 80% unit, 50% integration)
- (mvp) Testing patterns specified for each layer (unit, integration, e2e)
- (mvp) Quality gates defined: list of commands to run before merge, with expected pass criteria for each
- (mvp) Edge cases from domain invariants are test scenarios
- (deep) Performance testing approach for critical paths
- (deep) Contract testing strategy documented for service boundaries

## Methodology Scaling
- **deep**: Comprehensive strategy. Test matrix by layer and component. Specific
  test patterns per architecture pattern. Performance benchmarks. CI integration.
  Test data strategy. Mutation testing approach.
- **mvp**: Test pyramid overview. Key testing patterns. What must pass before deploy.
- **custom:depth(1-5)**:
  - Depth 1: Test pyramid overview with key patterns. What must pass before deploy.
  - Depth 2: Depth 1 + example test for each layer using the project's actual test framework.
  - Depth 3: Add per-layer test patterns, coverage targets, CI integration, and test data strategy.
  - Depth 4: Add performance benchmarks, mutation testing approach, and cross-module integration patterns.
  - Depth 5: Full suite with contract testing, visual regression strategy, and automated quality gate calibration.

## Mode Detection
Check for docs/tdd-standards.md. If it exists, operate in update mode: read
existing strategy and diff against current tech stack, coding standards, and
PRD. Preserve testing patterns, layer definitions, custom assertions, and test
data strategy. Update coverage goals if PRD scope or tech stack changed.
Re-generate only sections affected by upstream changes — do not rewrite
stable layer definitions or custom assertion patterns.

## Update Mode Specifics
- **Detect prior artifact**: docs/tdd-standards.md exists
- **Preserve**: test pyramid layer definitions, custom assertion helpers, test
  data strategy, quality gate thresholds, framework-specific patterns
- **Triggers for update**: tech-stack.md changed (new test runner or framework),
  coding-standards.md changed (naming conventions), PRD scope expanded (new
  features needing test scenarios)
- **Conflict resolution**: if tech stack changed test runner, migrate pattern
  examples to new runner syntax; preserve coverage targets unless user requests
  adjustment
