Spec Driven Development

Spec-Driven Development (Phase 6: Behavior Contracts)

Overview

Phase 6 fills the gap between structural truth and execution proof in the anti-hallucination stack:

DDD (Phase 1-4)    → Semantic truth    (what to build)
Schema (Phase 5)   → Structural truth  (what shape — toolchain-consumable)
SDD (Phase 6)      → Conformity truth  (what names, what rules — agent-consumable)
TDD (Phase 7)      → Execution proof   (it works)

During Phase 7 coding, AI agents exhibit naming and structural drift: the agent substitutes its own names for the ones specified (e.g., writing xxxAdapter when the Blueprint says xxxPort, or vice versa); when a file should be named per convention, the agent creates an ad-hoc variant. Phase 5 schemas (proto, DDL) define structural shape for toolchain consumption, but there is no artifact that precisely maps schema elements to domain code names, files, and directories. The agent bridges this gap by inference — which is a hallucination entry point.

Additionally, behavioral rules (state machines, invariants, event emission rules) are currently inferred by TDD's MAP step from structural specs. Inference is inherently unreliable. These rules must be explicitly defined and human-approved before coding begins.

Foundational Principle: Behavior contracts are mandatory artifacts, not optional documentation. They provide conformity truth — explicit naming mappings and behavioral rules. Without them, the AI agent infers domain code names and business logic from structural schemas — inference is hallucination. All rules in this skill are mandatory constraints. There is no complexity threshold below which you may skip behavior contract generation.

SDD operates in two modes: Generate (no existing behavior contracts — create from scratch) and Merge (Phase 3/5 changes require behavior contract updates).

When to Use

• Phase 5 schema files exist (proto/openapi/DDL) and behavior contracts are needed before coding.
• Phase 3 contracts + Phase 5 schemas are approved; domain code naming and behavioral rules need explicit definition.

Do NOT use when:

• Phase 2 context map does not exist (run [mapping-bounded-contexts](../mapping-bounded-contexts/SKILL.md) first — BC boundaries and strategic classification determine derivation scope and depth).
• Phase 3 contracts do not exist (run [designing-contracts-first](../designing-contracts-first/SKILL.md) first).
• Phase 4 technical solution does not exist (run [architecting-technical-solution](../architecting-technical-solution/SKILL.md) first — tech stack decisions drive directory layout and naming conventions in the Code Structure Blueprint).
• Phase 5 schemas do not exist (run [defining-schemas](../defining-schemas/SKILL.md) first).
• Only structural schemas are needed without behavioral rules (use [defining-schemas](../defining-schemas/SKILL.md) instead).

Phase 1 dependency: Phase 1 domain events (docs/ddd/phase-1-domain-events.md) are used during DERIVE (event→scenario mapping) and VALIDATE (event coverage check). If Phase 1 is absent: emit WARNING "Phase 1 domain events missing — Scenario derivation will lack event traceability. Event coverage check in VALIDATE will be skipped." Proceed with contract-only derivation; the traceability chain shortens to Contract → Blueprint → Code.

Quick Reference

| Step | Action | Output | |:---|:---|:---| | 1 | INVENTORY — Read Phase 2 + Phase 3 + Phase 4 + Phase 5 + Phase 1 | Per-context derivation manifest | | 2 | DERIVE — Blueprint + Behavioral Rules per context | Per-context behavior contract files | | 3 | VALIDATE — Completeness cross-check | Completeness report (index file) | | 4 | PERSIST — Write index + context files + progress | phase-6-behavior-contracts.md + phase-6/*.md |

Ambiguity Handling

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

Phase 6 STOP triggers — confirm immediately:

| Ambiguity | Why STOP | |:----------|:---------| | Aggregate state machine unclear (Phase 3 lacks explicit state transitions) | Wrong state machine → all behavioral tests and domain code must redo | | Schema element ownership ambiguous (a proto message usable by multiple contexts) | Mapped to wrong domain directory → entire context Blueprint redone | | Port interface vs Adapter naming direction uncertain (Phase 3 description vague) | Wrong naming = Phase 6 core value is zero | | Invariant business rule interpretation ambiguous | Wrong invariant → wrong tests → wrong implementation |

Phase 6 ASSUME & RECORD — proceed with explicit assumption:

| Ambiguity | Default assumption | |:----------|:------------------| | Domain event struct naming suffix (Event vs none) | {EventName}Event (e.g., OrderCreatedEvent), record | | Command struct naming suffix | {CommandName}Command (e.g., CreateOrderCommand), record | | Error naming prefix | Err{Name} (e.g., ErrInsufficientStock), record | | Stateless aggregate (no state transitions) | Mark "stateless — no state machine", record | | Value Object file ownership | Single context → context directory; cross-context → domain root package (path per language conventions), record | | Query-only context (no aggregate state changes) | Blueprint only (no Behavioral Rules section), mark "query-only — no state machine, no invariants", record |

Orchestrator Mode Exception

When invoked by an orchestrator (full-ddd, iterating-ddd, piloting-ddd, restructuring-ddd, importing-technical-solution) in Autonomous Mode, the interactive validation step (3) is replaced by autonomous execution. The full INVENTORY → DERIVE → VALIDATE → PERSIST pipeline runs as a single autonomous pass:

• Execute all four steps (INVENTORY, DERIVE, VALIDATE, PERSIST) from the Phase 1-5 input artifacts. No human Q&A during the pass.
• Self-check replaces human validation (Step 3): The agent performs the VALIDATE completeness cross-check autonomously — per the "Autonomous Mode vs Standalone Mode" section of [ambiguity-handling-reference.md](../ddd-protocol/ambiguity-handling-reference.md). Flag issues as STOP triggers rather than asking the human inline.
• Apply STOP/ASSUME protocol: STOP for Phase 6 STOP triggers (above), ASSUME & RECORD for Phase 6 ASSUME items (above).
• Persist the behavior contracts (index file + per-context files) immediately (Step 4). Do NOT wait for human approval — the orchestrator manages the approval gate.
• Return the behavior contracts index 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 asks for behavior contract generation), the full interactive session is mandatory.

Implementation

Generate Mode

INVENTORY → DERIVE → VALIDATE → PERSIST

Step 1: INVENTORY

Read input sources and build derivation manifest:

1. Read docs/ddd/phase-2-context-map.md — BC boundaries, strategic classification (Core/Supporting/Generic), relationships, ubiquitous language
2. Read docs/ddd/phase-3-contracts.md — logical interfaces, boundary structs
3. Read docs/ddd/phase-4-technical-solution.md — tech stack decisions per BC (language, framework, persistence — drives directory layout and naming conventions)
4. Read docs/ddd/schema-manifest.md — Phase 5 schema index → locate proto/DDL files
5. Read actual schema files — proto message/service names, DDL table/column names

Cross-context import validation: Scan each proto file listed in the manifest for import statements referencing another context's package (e.g., import "{other_context}/v1/..."). For each such import, verify the imported file exists at the path resolved relative to the project's proto root. If missing → STOP and ask the user to resolve the missing dependency before proceeding. (Do NOT rely on the manifest's Source column for this — Source encodes phase traceability like "Phase 3 #1", not import paths.)

1. Read docs/ddd/phase-1-domain-events.md — event names for behavioral rule derivation
2. Read [language-conventions](../language-conventions/SKILL.md) → detect language, load naming rules

Output: per-context derivation manifest (which schema elements need mapping, which aggregates need behavioral rules).

Step 2: DERIVE

For each bounded context:

Code Structure Blueprint:

1. Extract port interface names and method names from Phase 3 contracts
2. Extract proto message / DDL table names from Phase 5 schemas
3. Apply naming conventions ([language-conventions](../language-conventions/SKILL.md) or defaults) to generate domain type names and file names
4. Produce Schema → Domain Mapping table + Directory Layout

Behavioral Rules:

1. Extract state transitions from Phase 1 events + Phase 3 contracts (command → event pairs)
2. Extract business invariants from Phase 3 contracts (constraint descriptions)
3. Extract error scenarios from Phase 5 schema error types
4. Extract authorization preconditions — for each command, ask: "Does this command have ownership or role-based preconditions beyond API-level auth?" (e.g., "only the order creator can cancel," "only attending physician can modify treatment plan"). If yes, add as invariant + error scenario. These are domain rules, not middleware concerns.
5. Assemble State Machine + Invariants + Scenarios tables

Package Placement Constraints (index file):

1. Read [package-placement-reference.md](./package-placement-reference.md) for the generic 4-layer placement rules. If [language-conventions](../language-conventions/SKILL.md) detected, overlay language-specific constraints on top of the generic rules.
2. Produce a "Package Placement Constraints" section in the index file with:

• Per-layer placement conditions and prohibitions (table format)
• Decision flow for new file creation (which check comes first)
• Dependency direction diagram

1. This section prevents the most common Phase 7 error: placing a file in the wrong layer by matching only one condition while ignoring another (e.g., a type is cross-domain but also has a third-party dependency — two conditions point to different layers)

Note: Package Placement Constraints are written to the index file (phase-6-behavior-contracts.md) as a global section, not per-context. Generate this section after completing all per-context DERIVE iterations.

Step 3: VALIDATE

Cross-check completeness:

• Every Phase 3 contract interface → has a corresponding Blueprint row
• Every Phase 1 domain event → has a corresponding Scenario
• Every Phase 5 error type → has a corresponding error Scenario
• Every command (write) use case → has at least one Scenario with a When column referencing the command (feeds category 8 Use Case Orchestration test derivation in TDD MAP). Cross-phase completeness gate: Compare the write commands from Phase 1 (loaded in Step 1) against the Scenario When columns across all per-context behavior contracts. If a Phase 1 write command has no matching Scenario in any context → STOP and flag the gap. This catches commands lost during Merge mode propagation that would silently drop TDD Category 8 tests.
• Every aggregate → has a State Machine or is explicitly marked "stateless"
• Blueprint naming → conforms to [language-conventions](../language-conventions/SKILL.md)
• Package Placement Constraints were derived during DERIVE and are staged for the index file (if language conventions loaded). (The index file is written in Step 4 PERSIST — do not check the filesystem here; verify the content exists in your working output.)
• Placement table covers all layers with both placement conditions AND prohibitions

Step 4: PERSIST

Persist to Filesystem:

• Write docs/ddd/phase-6-behavior-contracts.md (index)
• Write docs/ddd/phase-6/{context}.md (per-context details)
• Update docs/ddd/ddd-progress.md Phase 6 → complete
• Append key decisions to docs/ddd/decisions-log.md
• Backfill constraint files: For each context, append a ## Key Invariants section to the per-context constraint file (.claude/rules/{context}.md or platform equivalent). Format:

``` ## Key Invariants (from Phase 6)

• [Aggregate]: [invariant description] (source: phase-6/{context}.md)
• [Aggregate]: [state machine rule] (source: phase-6/{context}.md)

`` Extract top 3-5 critical invariants: state machine transitions, aggregate validation rules, domain constraints. If constraint file doesn't exist, create it with context definition from phase-2-context-map.md` + this section.

• This step is mandatory — do not skip even if behavior contracts are already visible in the conversation.

Merge Mode

Triggered during iteration (Phase 3/5 changes require Phase 6 update):

DETECT → IMPACT → RE-DERIVE → VALIDATE → PERSIST

1. DETECT — Run git diff on docs/ddd/phase-3-contracts.md and schema files listed in docs/ddd/schema-manifest.md to identify changes since last generation (per [spec-change-detection-reference](../ddd-protocol/spec-change-detection-reference.md))
2. IMPACT — Identify affected contexts and aggregates
3. RE-DERIVE — For each affected context (identified in IMPACT step), regenerate the entire context behavior contract file (docs/ddd/phase-6/{context}.md). Granularity is context-file level — do not attempt to patch individual sections within a file. Read the updated schema files and Phase 1-4 artifacts, then re-derive the Code Structure Blueprint and Behavioral Rules from scratch for that context.
4. VALIDATE — Full completeness check (not just changed parts)
5. PERSIST — Update affected files; git diff available for human review

No three-way merge hashing needed — the artifact is a DDD process document. Conflict resolution: When invoked by an orchestrator with a Project Init Gate (full-ddd, restructuring-ddd), human edits to behavior contracts are resolved at the Project Init Gate. When invoked standalone (no Project Init Gate): if git diff shows human edits to a behavior contract file that DETECT also flags for RE-DERIVE, present both versions (human edit vs RE-DERIVE output) to the user and ask which to keep. Do not silently overwrite human edits.

Artifact Structure

File Layout

docs/ddd/
├── phase-6-behavior-contracts.md        # Index: summary + completeness check (~50-80 lines)
└── phase-6/
    ├── order-context.md                  # Blueprint + Rules for OrderContext (~100-200 lines)
    ├── payment-context.md                # Blueprint + Rules for PaymentContext
    └── inventory-context.md              # ...

• Index file (phase-6-behavior-contracts.md): Generated date, source references, per-context summary, and Completeness Check table.
• Per-context files (phase-6/{context}.md): Full Code Structure Blueprint + Behavioral Rules for one bounded context.
• TDD processes one context at a time, loading only the relevant context file. Zero context waste.
• Per-context file size guideline: ~100-200 lines. If a context has many aggregates and exceeds ~250 lines, split into {context}-{aggregate}.md files and add entries to the index.
• Archive: entire phase-6/ directory + index file archived together.

Required Artifact Sections

Full templates with examples: [behavior-contract-templates-reference.md](./behavior-contract-templates-reference.md). Read during GENERATE step.

Per-context file must contain these sections (adapt file extensions to project language):

• ## Code Structure Blueprint → ### Directory Layout (domain/{context}/ tree) + ### Schema → Domain Mapping table (columns: Schema Source | Domain Type | File | Code Name)
• ## Behavioral Rules → per aggregate: #### State Machine (diagram + transition table) + #### Invariants (ID | Rule | Check After) + #### Scenarios (ID | Given | When | Then | Error)

Index file must contain:

• `##

…

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.