---
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]
detect:
  all:
    - path: docs/tdd-standards.md
reads: [create-prd, system-architecture]
conditional: null
knowledge-base: [testing-strategy, test-impact-analysis]
---

## 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) Two-gate contract defined: `make check-affected` (fast, selection-based —
  the merge gate; falls back to full `make check` when it cannot classify a
  change) and `make check` (full, authoritative — post-merge and nightly, always
  uncached). Force-full-run triggers listed explicitly (lockfiles, tool config,
  shared test utils, global setup, env files, migrations). When the targets do
  not exist yet, seed them: `scaffold agent-ops install --component gate`
  generates `scripts/gate-check.sh` + `scripts/gate-check-affected.sh`
  satisfying this contract — CONFIRM its printed classification (gate commands
  vs environment-sensitive suites excluded to `make check-visual`) with the
  user before committing the seeds
- (mvp) e2e excluded from the merge gate (tagged smoke subset at most); full e2e
  runs post-merge/nightly
- (deep) Flake policy documented: quarantine list location (`.mq/quarantine.txt`),
  quarantined tests excluded from the merge gate but still run post-merge, with a
  fix-SLA convention
- (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.
  Affected-test selection mechanism chosen per stack (see the
  test-impact-analysis knowledge entry) with declared inputs and force-full
  triggers. Test data strategy. Mutation testing approach.
- **mvp**: Test pyramid overview. Key testing patterns. What must pass before
  deploy. Defines check-affected alongside check.
- **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

## Adoption Mode Specifics
- **Codify from repo evidence**: the test stack as-built — runner and config
  (vitest/jest/pytest/playwright config files), observed test directory
  layout and naming, coverage thresholds already configured, and which CI
  workflow steps actually run tests.
- **Interview only for**: target coverage goals versus the measured current
  baseline, which untested areas matter most to the user, and appetite for
  TDD on new work versus retrofitting tests onto existing code.
- **Do not**: prescribe a different test runner; set coverage gates the
  current suite immediately fails (ratchet upward from the measured baseline
  instead); mark legacy untested modules as rewrite candidates — record them
  as coverage gaps with evidence.