Coding Isolated Domains

Coding Isolated Domains

Overview

This is the ultimate architectural defense skill. It explicitly forbids the generation of "Anemic Domain Models" (data bags with only getters/setters) and enforces Hexagonal Architecture. The Domain Core MUST be completely isolated from infrastructure, containing pure business logic (Rich Models) protected by strict unit tests.

Foundational Principle: All rules are mandatory constraints, not aspirational guidelines. No "temporarily" or "just for now."

When to Use

• When writing implementation of business rules, Entities, or Aggregates; when you detect an Entity with only properties and no behavior; when ORM tags or HTTP logic leak into the domain layer.

Do NOT use when: Working on Generic Subdomains with simple CRUD; writing adapter code without completing domain TDD first; dealing with legacy non-DDD code interfaces (use [mapping-legacy-landscape](../mapping-legacy-landscape/SKILL.md) to understand the legacy structure first); or when context boundaries and contracts are not yet defined (REQUIRED PREREQUISITES: [defining-schemas](../defining-schemas/SKILL.md) and [spec-driven-development](../spec-driven-development/SKILL.md) — Phase 5 schema files and Phase 6 behavior contracts must exist before domain code is written). Exception: when invoked by [full-ddd](../full-ddd/SKILL.md) in simplified mode (workflow_mode: simplified in ddd-progress.md), Phase 5 and Phase 6 artifacts do not exist — proceed using the Minimal Technical Checklist from decisions-log.md. The checklist MUST contain: (1) persistence type (SQL/NoSQL/file), (2) interface type (REST/gRPC/CLI), (3) error handling strategy (error codes/exceptions/result types). If any item is missing from decisions-log.md → STOP and ask the user.

Quick Reference

| Step | Action | Output | |:---|:---|:---| | 1 | Load Blueprint from Phase 6 | Directory structure + file skeletons created per Blueprint | | 2 | Zero Infrastructure Dependencies | No ORM/HTTP in domain structs confirmed | | 3 | Mandatory Rich Domain Models | Behavior methods defined, no public setters | | 4 | Eric Evans 4 Aggregate Rules | Consistency boundaries validated | | 5 | Domain TDD (MAP→ITERATE→DIFF) — delegates to [test-driven-development](../test-driven-development/SKILL.md) | test-map.md + test-coverage.md + test files + domain code | | 6 | App TDD + Adapter Implementation | App use case TDD (category 8) + Converter + Repo + Server + integration tests | | 7 | Persist Design Decisions | docs/ddd/decisions-log.md updated, ddd-progress.md Phase 7 = complete |

> Architecture red lines for the GREEN step: see [domain-architecture-reference.md](../ddd-protocol/domain-architecture-reference.md)

Ambiguity Handling

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

Phase 7 STOP triggers — confirm immediately:

| Ambiguity | Why STOP | |:----------|:---------| | Aggregate root boundary (what belongs inside vs outside the aggregate) | Wrong boundary = wrong consistency scope → aggregate design must redo | | Business invariant interpretation | Wrong invariant = wrong behavior methods → implementation must redo | | Entity vs Value Object classification | Wrong classification = wrong identity semantics → aggregate design must redo |

Phase 7 ASSUME & RECORD — proceed with explicit assumption:

| Ambiguity | Default assumption | |:----------|:------------------| | Internal helper method structure | Extract to private method when logic exceeds 3 lines | | Test data specific values | Use realistic but minimal values (e.g. price=100, quantity=1) | | Value Object internal representation | Use the simplest representation that satisfies the invariant |

Orchestrator Mode Exception

When dispatched as a subagent by an orchestrator (full-ddd, iterating-ddd, piloting-ddd, restructuring-ddd, importing-technical-solution), the interactive Q&A steps are replaced by autonomous execution:

• Skip all interactive "Ask:" prompts (Steps 1, 5, 6 approval gate). Instead, execute each step autonomously using the Phase 6 behavior contract as the sole source of truth.
• Apply STOP/ASSUME protocol: STOP for Phase 7 STOP triggers (above), ASSUME & RECORD for Phase 7 ASSUME items (above).
• Domain TDD: Runs autonomously per the [test-driven-development](../test-driven-development/SKILL.md) Orchestrator Mode Exception.
• Adapter approval gate (Step 6 prerequisite check 3): In orchestrated mode, the orchestrator manages the per-BC human checkpoint. Do NOT block waiting for a human "yes" inside the subagent — the orchestrator presents the checkpoint.
• Persist decisions-log.md and ddd-progress.md updates immediately (Step 7). Do NOT wait for human approval — the orchestrator manages the approval gate.
• Return the Step 7 completion status (test-map summary, test-coverage summary) to the orchestrator. If STOP was triggered, return the STOP reason instead.

This exception applies ONLY when dispatched as a subagent by an orchestrator. When invoked standalone (user directly runs domain coding), the full interactive session is mandatory.

Context-per-Session Execution Model

Phase 7 processes one bounded context per subagent (sequential, not parallel). This prevents context window pollution from accumulating code and tests across multiple contexts.

Orchestrator dispatches per context (Core Domain first, then Supporting, then Generic):

1. Read docs/ddd/phase-6-behavior-contracts.md (index) to get the context list.
2. For each context, dispatch a subagent with precisely scoped inputs:

• docs/ddd/phase-6-behavior-contracts.md (index — scope awareness)
• docs/ddd/phase-6/{this-context}.md (behavior contract for this context only)
• Relevant schema files (located via docs/ddd/schema-manifest.md)
• This skill (coding-isolated-domains) + test-driven-development skill instructions

On-demand reads (not preloaded — subagent reads during execution to avoid context window bloat):

• docs/ddd/phase-4-technical-solution.md — Step 1 (persistence strategy, architectural style)
• docs/ddd/phase-3-contracts.md — Step 6 adapter implementation (port interfaces the adapters must implement)
• docs/ddd/phase-1-domain-events.md + docs/ddd/phase-2-context-map.md — TDD MAP step (enrich test derivation)
• skills/ddd-protocol/domain-architecture-reference.md — TDD GREEN step (red line checklist)
• Language convention skill (skills/language-conventions/) — Step 6 adapter implementation (naming, structure)

1. Subagent executes Steps 1-7 for its context, commits, returns.
2. Orchestrator checks docs/ddd/test-map.md for completion status, dispatches next context.

Why sequential: Multiple subagents writing code simultaneously causes git conflicts, shared artifact races (test-map.md, ddd-progress.md), and build/test interference. One context at a time is safe.

Recovery: If a subagent crashes mid-context, the orchestrator re-dispatches — test-map.md records per-aggregate progress, so the new subagent resumes from the last completed aggregate.

Phase 7 Execution Order (per bounded context)

| Stage | Scope | Steps | Gate (must pass before next stage) | |:------|:------|:------|:------------------------------------| | 1. Structure | Directory scaffolding | Steps 1-4 | Files exist on disk | | 2. Domain TDD | All aggregates in context | Step 5 | test-coverage.md exists + all aggregates pass in test-map.md + explicit user approval | | 3. App TDD + Adapter (per aggregate) | App use case TDD (category 8) → Converter → Repo | Step 6.1-6.3 | App use case + adapter code exists per aggregate | | 4. Server handlers | All handlers for this context (batch) | Step 6.4 | All aggregates have completed Stage 3 | | 5. Wiring | DI assembly (cmd/main.go) | Step 6.5 | Compiles | | 6. Integration test | End-to-end verification | Step 6.6 | Tests pass. If fail → fix, do not proceed to Stage 7 | | 7. Completion | Persist decisions, update progress | Step 7 | User approval received + artifacts on disk |

Stage vs Step: Stages are execution phases with gates between them. Steps are the numbered instruction sections below. Step 6 spans Stages 3-6 (it contains sub-steps 6.1-6.6). Do NOT execute Step 6 as a monolithic pass — pause at each Stage gate to verify the gate condition before continuing to the next sub-step range.

Domain first, adapters second. Stage 2 completes ALL domain aggregates before ANY adapter code is written. Do not write Aggregate A's adapter while Aggregate B's domain TDD is pending — "parallelizing" domain and adapter work is a rationalization, not an optimization.

App use cases ARE TDD-driven (category 8). Use case orchestration has real wiring logic (load→command→save→publish) that domain tests cannot cover. Category 8 tests drive app code into existence at the start of Stage 3 via RED→GREEN→REFACTOR, mocking repo ports and event publisher ports while using real domain objects. See [test-driven-development](../test-driven-development/SKILL.md) § Use Case Orchestration TDD. Remaining adapters (converter, repo, server handler) are NOT TDD-driven — they are mechanical mapping with quality enforced via integration tests + [ddd-review](../ddd-review/SKILL.md).

Implementation: The Iron Laws of the Domain Core

CRITICAL RULE (standalone mode): Do NOT just generate the final code and stop. You must guide the user through an interactive, step-by-step domain implementation process. When dispatched by an orchestrator, see § Orchestrator Mode Exception — interactive prompts are skipped.

Step 1: Load Blueprint from Phase 6

1. Read docs/ddd/phase-6-behavior-contracts.md (index) — the Context Summary table lists all available contexts and their file paths. Identify the context to implement.

1b. Read docs/ddd/phase-6/{context}.md — the behavior contract for this bounded context.

1. Create directory structure per the Directory Layout section of the Blueprint.
2. Create file skeletons per the Schema → Domain Mapping table (file names + type signatures, no implementation).
3. Do NOT create domain files not in the Blueprint — if a new file is needed, STOP, return to Phase 6 to add it.
4. Reference the Technical Solution artifact (docs/ddd/phase-4-technical-solution.md) for persistence strategy and architectural style.

Architecture Red Lines

The complete checklist of architecture and domain modeling constraints is in [domain-architecture-reference.md](../ddd-protocol/domain-architecture-reference.md). Check every RED line from that reference during implementation — especially in the GREEN step of each TDD cycle. If a violation is detected, stop immediately, delete the violating code, and rewrite.

Architecture Constraints (hexagonal boundary — 7 red lines): domain layer has no infrastructure dependencies · no ORM/JSON tags on domain structs · no cross-aggregate direct imports · business logic in entities not services · ports are interfaces not implementations · no magic literals for business enums (use named constants from contract enums or domain consts) · adapter handlers do protocol conversion only (one handler → one app method call; no switch/if on business conditions in adapter)

Domain Modeling Constraints (DDD discipline — 4 red lines): value objects are immutable · no public setters on entities · domain events named in past tense · aggregates reference other aggregates by ID only

Step 2: Zero Infrastructure Dependencies

• NO ORM/HTTP/framework dependencies in domain structs. See Architecture Constraints in [domain-architecture-reference.md](../ddd-protocol/domain-architecture-reference.md).

Step 3: Mandatory Rich Domain Models

• Entities MUST have behavior methods. No public setters — expose shipOrder() not setStatus(). See Domain Modeling Constraints in [domain-architecture-reference.md](../ddd-protocol/domain-architecture-reference.md).

Step 4: Eric Evans 4 Aggregate Rules

• Consistency boundary: Model true invariants together — only place in one aggregate the data that must be consistent in a single transaction.
• Small aggregates: Keep aggregates small. Large aggregates cause lock contention and slow loads. When in doubt, make it smaller.
• Reference by ID: Reference other aggregates by identity only (a stored ID), never by direct object reference. This enforces loose coupling and allows separate persistence.
• Invariants in root: Only the Aggregate Root may enforce consistency rules across the entire aggregate. External code calls methods on the root; it never mutates child entities directly.

Step 5: Domain TDD

• Mandatory TDD: Execute [test-driven-development](../test-driven-development/SKILL.md) — run the MAP→ITERATE→DIFF cycle driven by the Phase 6 behavior contract for this Bounded Context.
• In the GREEN step of each TDD cycle, verify every Architecture Red Line from [domain-architecture-reference.md](../ddd-protocol/domain-architecture-reference.md). If a violation is detected, stop immediately, delete the violating code, and rewrite.
• Ask: "Do these tests cover all expected behaviors and edge cases? Shall I proceed to implement the logic to make these tests pass?"
• Note: The TDD skill drives a per-test RED→GREEN→REFACTOR cycle. Do NOT batch-write all tests before implementing — follow the TDD skill's own pacing.

Step 6: Adapter Implementation (post Domain TDD)

Hard prerequisite — verify ALL before writing any adapter code:

1. docs/ddd/test-coverage.md exists (DIFF completed)
2. Read docs/ddd/test-map.md — enumerate every aggregate for this context, confirm ALL show status pass
3. User has explicitly approved — ask: "Domain TDD for this context is complete. All aggregates pass. Shall I proceed to adapter implementation?" Do not interpret silence, brief acknowledgment, or topic change as approval. Wait for an explicit yes.

If any check fails → STOP. Finish Domain TDD (Step 5) first. Do NOT write adapter code for Aggregate A while Aggregate B's domain TDD is pending.

Per-aggregate cycle (app use case TDD → converter → repo → server → wiring → integration test): app use case is driven by category 8 TDD (RED→GREEN→REFACTOR, mocking ports, using real domain objects) — see [test-driven-development](../test-driven-development/SKILL.md) § Use Case Orchestration TDD. Then see [adapter-implementation-reference.md](./adapter-implementation-reference.md) for remaining adapter sub-steps. Key rules: one handler → one app method, no business logic in adapters, integration tests use real DB + mock external services, each test cleans own data only.

Step 7: Persist Design Decisions

Persist to Filesystem: After user approval of domain + adapter implementation, append architectural design decisions to docs/ddd/decisions-log.md. Record: the proposed Aggregate Root structure, user feedback, and any invariants added or modified. (TDD-specific decisions — test coverage summary, traceability gaps — are already recorded by TDD DIFF; do NOT duplicate them here.) Update docs/ddd/ddd-progress.md Phase 7 status to complete.

Verify CLAUDE.md DDD Architecture section: If CLAUDE.md does not exist, create it with the DDD Architecture section (using the template from [mapping-bounded-contexts](../mapping-bounded-contexts/SKILL.md) Step 6b). If CLAUDE.md exists but does not contain a ## DDD Architecture section (e.g., pipeline started before this feature existed, or the file was reset), append the section. Generate it using the context list from docs/ddd/phase-2-context-map.md and the Architecture Red Lines template from [mapping-bounded-contexts](../mapping-bounded-contexts/SKILL.md) Step 6b. Also verify the ### Mandatory Skill Loading subsection exists — if missing (e.g., generated before the mandatory enforcement update), add it per the templ

…

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.