Test Driven Development

Test-Driven Development

Overview

TDD IS the Phase 7 coding process. It is the sole driving skill during implementation. The MAP→ITERATE→DIFF cycle replaces ad-hoc coding. TDD embeds key constraints from Phase 6 (behavioral conformity) and coding-isolated-domains (architecture rules) via shared references — no need to load three skills simultaneously.

Anti-hallucination role: Tests are executable proof, not discovery aids. Position in the stack: DDD (semantic truth) → Phase 5 (structural truth) → Phase 6 (conformity truth) → TDD (execution proof).

Foundational Principle: Tests are executable proof, not optional verification. Code without corresponding tests is unproven. Tests derived from implementation (not from behavior contracts) are biased. All rules in this skill are mandatory constraints — the MAP→ITERATE→DIFF cycle is the sole coding process, not an optional add-on. There is no complexity threshold below which you may skip TDD.

Execution model: This skill runs inside a per-context subagent dispatched by the orchestrator. Each subagent receives only the Phase 6 behavior contract and schema files for its own bounded context — not the full project's artifacts. This keeps the context window clean and prevents cross-context pollution. See [coding-isolated-domains](../coding-isolated-domains/SKILL.md) § Context-per-Session Execution Model for details.

When to Use

• Phase 7 coding begins and Phase 6 behavior contracts + Phase 5 schemas exist
• Domain code needs to be implemented from behavior contract or schema definitions
• When tempted to write code before tests, skip test output verification, or derive tests from implementation
• When returning to a project where specs have changed since last coding session

Do NOT use when: No Phase 6 behavior contracts exist (run [spec-driven-development](../spec-driven-development/SKILL.md) first), making trivial changes (single config line, typo fix), or working on pure infrastructure adapters outside domain layer. REQUIRED PREREQUISITES: Phase 6 behavior contracts in docs/ddd/phase-6/ (from [spec-driven-development](../spec-driven-development/SKILL.md)) AND Phase 5 schema files (from [defining-schemas](../defining-schemas/SKILL.md)).

Simplified Mode Exception: When ddd-progress.md shows workflow_mode: simplified, Phase 5 and Phase 6 do not exist. In this case, TDD is NOT dispatched — [coding-isolated-domains](../coding-isolated-domains/SKILL.md) uses its Minimal Technical Checklist path from decisions-log.md instead. If an orchestrator dispatches TDD without Phase 6 artifacts, return STOP immediately: "Phase 6 behavior contracts required but not found — cannot derive test plan."

Quick Reference

| Step | Action | Output | |:---|:---|:---| | Entry Check | git diff on Phase 6 + Phase 5 source files; if changed → RECONCILE | Mode decision | | RECONCILE | Diff spec changes → update test-map + affected tests → re-run ITERATE for changed tests only | Updated test-map.md + re-verified tests | | MAP | Read Phase 6 behavior contracts + Phase 5 schemas + derive complete test plan + adversarial review | docs/ddd/test-map.md | | ITERATE | Per test: RED → GREEN → REFACTOR; per 5 tests: Focus Refresh | Test files + domain code | | DIFF | Spec↔Test↔Code coverage + chain integrity check | docs/ddd/test-coverage.md | | Post-DIFF | Use Case Orchestration TDD (category 8: RED→GREEN→REFACTOR per write use case) then adapter implementation (converter → repo → server → wiring → integration test) | See [coding-isolated-domains Step 6](../coding-isolated-domains/SKILL.md) |

Ambiguity Handling

Follow the [Ambiguity Handling Protocol](../ddd-protocol/ambiguity-handling-reference.md) throughout this skill.

TDD STOP triggers — confirm immediately:

| Ambiguity | Why STOP | |:---|:---| | Phase 6 behavior contract has no error types defined | Cannot derive error path tests — Phase 6 may have missed this; surface upstream | | Test fails for unexpected reason (not "feature missing") | Could indicate spec inconsistency or environment issue — diagnose before proceeding | | Architecture red line violated and no obvious fix | Domain boundary decision needed — may require revisiting Phase 3 contracts |

TDD ASSUME & RECORD — proceed with explicit assumption:

| Ambiguity | Default assumption | |:---|:---| | Test execution framework unspecified | Use project's existing framework; if new project, follow Phase 4 tech stack conventions; record | | Spec does not specify concurrency behavior | Assume single-threaded for domain tests; record; note for integration test phase | | Mock boundary unclear for port tests | Mock only external ports (database, external API); never mock domain internals; record | | Mock boundary unclear for use case orchestration tests | Mock repo ports + event publisher ports; use real domain objects; never mock aggregates or value objects; record |

Orchestrator Mode Exception

When dispatched by an orchestrator, TDD runs autonomously: MAP in single pass, ITERATE without per-test human interaction (Focus Refresh still triggers), DIFF writes immediately, RECONCILE auto-commits, Golden Reference auto-captures. STOP triggers return to orchestrator. Post-DIFF results persist and return — orchestrator manages human checkpoint. Standalone mode: full interactive session mandatory.

Implementation

Core Cycle

Entry Check → MAP → ITERATE → DIFF
                      ↑         │
                      └─────────┘  (per aggregate unit: mini-DIFF → next unit)

The aggregate is the universal chunking boundary — it serves as consistency boundary (DDD), behavior contract organization unit (Phase 6), and AI working memory chunk (TDD). Three methodologies converge naturally at the aggregate. Process one aggregate at a time through the full cycle before moving to the next.

Context budget per aggregate: MAP ~200 lines active, ITERATE ~280 lines, DIFF ~550 lines (peak). Safe for any context window. If an aggregate's behavior contract section exceeds 200 lines, the aggregate is too large — split it upstream in Phase 6.

Entry Check

Before starting MAP, check whether Phase 6 or Phase 5 source files have changed:

1. If docs/ddd/test-map.md does not exist → normal flow (first run). Proceed to MAP.
2. If docs/ddd/test-map.md exists → use git diff --name-only to check whether the Phase 6 context files (docs/ddd/phase-6/*.md) or Phase 5 schema files (listed in docs/ddd/schema-manifest.md) have changed since test-map.md was last committed.

• No changes → normal flow. Resume from where test-map.md progress left off.
• Any changes detected → RECONCILE mode. Phase 6 behavior contracts or Phase 5 schemas changed since last MAP (human edit, Phase 6 merge, or new iteration). Run the RECONCILE Protocol before continuing normal flow.

MAP

Per aggregate unit (aggregate | saga | query):

1. Discover available contexts — read docs/ddd/phase-6-behavior-contracts.md (index). The Context Summary table lists every context name and its corresponding file path. Pick the context matching this aggregate unit.
2. Read Phase 6 behavior contract for this unit: docs/ddd/phase-6/{context}.md (REQUIRED — behavioral rules, state machines, invariants, scenarios).
3. Read Phase 5 schema files for this aggregate (REQUIRED — field constraints, value ranges for boundary tests). Locate via docs/ddd/schema-manifest.md.
4. Read Phase 1 domain events + Phase 2 ubiquitous language (if they exist — enrich test derivation; see Graceful Degradation if absent).
5. Derive complete test plan across all 8 categories:

• Behavioral — command → event mapping (e.g., CreateOrder → OrderCreated) ← Phase 6 scenarios
• Invariant — aggregate business rules that must always hold (e.g., order total > 0) ← Phase 6 invariants
• Domain rule — specific business rules from ubiquitous language ← Phase 6 + Phase 2
• Value object — immutability, validation, equality semantics ← Phase 5 schema constraints
• Port — interface contract compliance (port methods accept and return expected types) ← Phase 6 Blueprint
• Error path — every domain error type defined in the spec gets at least one test ← Phase 6 scenarios
• Boundary — field constraint edge cases ← Phase 5 schema constraints. For each constrained field, derive boundary tests per the Boundary Derivation Protocol in [test-derivation-reference.md](./test-derivation-reference.md) section 5. This is NOT a suggestion list — derive one test per applicable boundary per constrained field.
• Use Case Orchestration — command (write) use case wiring correctness ← Phase 6 command scenarios + Blueprint app structure. Scope: write use cases only; query use cases defer to integration tests. See [test-derivation-reference.md](./test-derivation-reference.md) section 8 for derivation rules. These tests are planned in MAP but executed in Stage 3 (Post-DIFF), when app layer code is driven into existence via RED→GREEN→REFACTOR.

1. Adversarial self-review — after deriving the initial plan, challenge it:

• "What error paths did I miss? Does every behavior contract error type have a test?"
• "What happens at zero, empty, max, concurrent? Are boundary values covered?"
• "What if dependencies fail? Are port failure paths tested?"
• "Am I only testing happy paths?" (Happy-path bias is AI's systematic deficiency.)
• "Does every write use case have an orchestration test? Load→command→save→publish — can any step be forgotten? What if save or publish fails?"
• Add any discovered gaps to the test plan before writing.

1. Write traceability test plan → docs/ddd/test-map.md (see Artifact: test-map.md below).

ITERATE

Per-test cycle: RED → GREEN → REFACTOR. Focus Refresh every 5 tests. Full checklists for each phase: see [tdd-cycle-reference.md](./tdd-cycle-reference.md).

Key rules (always in context):

• RED: actual failure output MUST appear in context. "It should fail" is not evidence.
• GREEN: minimal code only. Architecture red lines checked per [domain-architecture-reference](../ddd-protocol/domain-architecture-reference.md). Violation = delete and redo.
• REFACTOR: no behavior changes. Full test suite + linter must pass.
• Focus Refresh: every 5 tests, re-read Phase 6 contract + test-map progress. Not optional.

RED essentials: (1) Write the test BEFORE any implementation code exists. (2) Run the test and confirm it fails for the expected reason (not a compile error or wrong import). (3) Test name must reflect the behavioral rule from Phase 6, not the implementation.

GREEN essentials: (1) Write the MINIMUM code to make the failing test pass — no extra logic. (2) Do not modify the test to make it pass. (3) Verify no architecture red lines are violated (no ORM tags in domain, no HTTP in domain).

REFACTOR essentials: (1) Improve code structure without changing behavior — tests must still pass. (2) Extract duplication only if it appears 3+ times. (3) Do not add new functionality during refactor.

After completing each test: update test-map.md, mark test status (pass or pending with reason).

After completing each aggregate's domain TDD (Stage 2):

1. Mini-DIFF: coverage check for this unit only — are all behavior contract methods and error types tested?
2. Checkpoint: update test-map.md with completed status and pass/pending markers for this unit.
3. Context cleanup: prior units' raw test output and implementation detail can be dropped from working memory. Keep only summaries (pass counts, any notable issues). This prevents context bloat across multi-aggregate sessions and keeps the active context within budget.

Use Case Orchestration TDD (Stage 3 — NOT during domain TDD):

After DIFF passes for ALL aggregates and user approves, execute category 8 tests first in Stage 3. Per write use case: RED→GREEN→REFACTOR (same cycle as domain TDD). Mock boundary per ASSUME table. See [test-derivation-reference.md](./test-derivation-reference.md) § 8 for derivation rules and procedural steps. After all use case TDD completes, proceed to remaining adapters (converter → repo → server → wiring → integration test). Checkpoint: update test-map.md with use case orchestration test status.

DIFF

After all aggregate units are complete, run the 5-dimension coverage check:

1. Contract → Test: every Phase 6 behavior contract method/scenario and Phase 5 schema error type has a corresponding test? Any contract item without a test is a coverage gap. Every constrained field (from Phase 5 schemas) has boundary tests? Edge cases derived per the Boundary Derivation Protocol are covered?
2. Test → Code: every test exercises real code (not mock bypasses)? Tests that only exercise mocks prove nothing about production behavior. All 7+4 architecture red lines verified (from [domain-architecture-reference](../ddd-protocol/domain-architecture-reference.md))?
3. Code → Contracts: code types, fields, and method signatures match Phase 6 behavior contract + Phase 5 schema definitions? Code that deviates from contracts is drift — even if tests pass.
4. Chain integrity: Event → Contract (Phase 6) → Test → Code — each link present? (PRD → Event is optional, only if Phase 1 annotated it.) A broken link means something in the chain was invented, not derived.
5. Use Case Orchestration: every write use case has orchestration tests (happy path + error propagation + port failures + event publishing)? Query use cases explicitly deferred to integration tests?

Persist to Filesystem: Output → docs/ddd/test-coverage.md (format template: [test-coverage-template](../full-ddd/templates/test-coverage-template.md)). DIFF Decision: all 5 dimensions pass → next aggregate, or gaps found → re-enter ITERATE.

Update docs/ddd/ddd-progress.md TDD status to in-progress (not complete — Phase 7 completes only after adapter implementation in Step 7). Append TDD-specific decisions to docs/ddd/decisions-log.md: test coverage summary, traceability gaps found, spec deviations resolved. This step is mandatory — do not skip even if all tests are green in the conversation. Architectural design decisions (aggregate proposals, invariant changes) are recorded later by coding-isolated-domains Step 7 — do NOT duplicate them here.

Post-DIFF: Adapter Implementation

User approval gate: After DIFF passes, present the DIFF summary to the user and ask explicitly: "Domain TDD for this context is complete. All aggregates pass. Shall I proceed to adapter implementation (Step 6)?" Do not interpret silence, brief acknowledgment, or topic change as approval. Wait for an explicit yes.

After the user approves, domain code for this context is complete. The remaining Phase 7 work — app use case TDD (category 8) then adapter implementation (converter, repo), server handlers, wiring, and integration tests — is guided by [coding-isolated-domains](../coding-isolated-domains/SKILL.md) Step 6. See the [Phase 7 Execution Order](../coding-isolated-domains/SKILL.md#phase-7-execution-order-per-bounded-context) for the full stage sequence.

RECONCILE Protocol

Triggered when Entry Check detects spec changes. See [reconcile-protocol-reference.md](./reconcile-protocol-reference.md) for the full 7-step protocol (DETECT → DELTA → IMPACT → RE-MAP → RE-ITERATE → RE-DIFF → commit).

Golden Reference Aggregate

The first aggregate implemented gets a human style review — an advisory checkpoint (not a formal gate):

1. Complete first aggregate's full MAP → ITERATE → DIFF cycle.
2. Present code to human: "This is the first aggregate. Please review code style, naming conventions, and structural patterns. Your corrections become the golden reference for all subsequent aggregates."
3. Human corrects or approves → this becomes the style reference.
4. Subseq

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: lockp111
• Source: lockp111/agent-ddd-engineering
• License: MIT

Install and usage instructions live in the source repository linked above.