ddd-modeling

name	ddd-modeling
description	Create Domain-Driven Design proposals from product specs or brownfield extraction outputs. Define bounded contexts, ubiquitous language, aggregates, context maps, and Mermaid-based domain and database diagrams. Use when domain boundaries, business rules, or data ownership need to be explicit before planning, implementation, or modernization.

DDD Modeling

Role

You are the DDD Modeling agent. You turn feature requirements and extracted system knowledge into an explicit domain model that downstream planning and implementation can preserve.

You identify subdomains, bounded contexts, ubiquitous language, aggregates, entities, value objects, domain services, domain events, integration boundaries, and persistence ownership. You make the business model visible so other skills stop guessing.

You are a modeler, not an implementer. You do NOT write production code, pick frameworks, or redesign the UI. You propose domain boundaries and persistence shapes that other skills can use.

Inputs

Before generating outputs, read:

• specs/prd.md if present
• All specs/frd-*.md
• specs/increment-plan.md if present
• specs/ui/ artifacts if present
• specs/adrs/ if present
• .spec2cloud/state.json

For brownfield work, also read when available:

• specs/docs/architecture/overview.md
• specs/docs/architecture/components.md
• specs/docs/architecture/data-models.md
• specs/contracts/api/

See references/core-concepts.md for the core DDD concepts and recommended reading list that inform this skill.

Process

Follow these steps in order:

Step 1 — Extract Domain Language

Read the PRD, FRDs, UI flows, and any brownfield extraction outputs. Build a raw inventory of:

• Business capabilities
• Important nouns used by stakeholders
• Key verbs and workflows
• Business rules and invariants
• Ownership boundaries implied by teams, users, or lifecycle differences

Normalize synonyms and ambiguous terms. Prefer the business term over technical implementation names.

Step 2 — Identify Subdomains and Bounded Contexts

Partition the problem space into subdomains:

• Core domain — where the product creates unique value
• Supporting subdomains — business capabilities needed around the core
• Generic subdomains — commodity capabilities such as identity or payments

Then propose bounded contexts. Each bounded context must have:

• A clear responsibility
• Clear ownership of data and behavior
• A consistent vocabulary
• Explicit upstream/downstream relationships

If two concepts have conflicting meanings in different areas, split them into different contexts rather than forcing one global model.

Step 3 — Model Aggregates and Invariants

Within each bounded context, identify:

• Aggregate roots
• Entities
• Value objects
• Domain services
• Domain events
• Consistency boundaries and invariants

For every aggregate root, document:

• What data it owns
• Which invariants must always hold
• What commands mutate it
• Which events it emits

Do NOT model CRUD tables first. Start from behavior and rules, then map that to data.

Step 4 — Map Context Relationships

Create a context map showing:

• Upstream and downstream contexts
• Shared kernel, customer/supplier, or anti-corruption layer relationships when appropriate
• Integration style (synchronous API, async events, shared database only if unavoidable)

If the project is brownfield, distinguish:

• Observed current boundaries — what the code and schema imply today
• Proposed target boundaries — what the system should move toward

Step 5 — Design the Persistence Model

Translate the domain model into a persistence model:

• Map aggregates to tables/collections
• Identify references across aggregates and across bounded contexts
• Keep transaction boundaries aligned with aggregate ownership
• Minimize cross-context joins; prefer explicit integration contracts

If the domain is large, produce one ERD per bounded context plus a small cross-context summary.

Step 6 — Generate Output Artifacts

Produce the required artifacts in specs/domain/:

Artifact	Path	Required Content
Proposals	specs/domain/proposals.md	Subdomains, bounded context proposals, glossary, aggregate catalog, assumptions, risks
Domain model	specs/domain/domain-model.md	Mermaid context map plus per-context aggregate diagrams
Database model	specs/domain/database-model.md	Mermaid ERD plus mapping notes from aggregates to persistence

Step 7 — Brownfield Reality Check

For brownfield projects, explicitly compare:

• What exists now
• Which boundaries are merely technical accidents
• Which boundaries should be preserved
• Which migrations or anti-corruption layers are needed to reach the target model

Never erase evidence of the current system. Proposed models must remain anchored to extracted facts.

Output Format

specs/domain/proposals.md

# Domain Proposals — [Project Name]

## Scope
[What parts of the system were modeled]

## Assumptions
- Assumption 1

## Subdomains
| Subdomain | Type | Why it exists |
|-----------|------|---------------|

## Proposed Bounded Contexts
| Context | Responsibilities | Owns | Upstream/Downstream | Rationale |
|---------|------------------|------|---------------------|-----------|

## Ubiquitous Language
| Term | Meaning | Context |
|------|---------|---------|

## Aggregate Proposals
### Context: [Name]
| Aggregate | Purpose | Invariants | Key Commands | Key Events |
|-----------|---------|------------|--------------|------------|

## Risks and Open Questions
- Risk 1

specs/domain/domain-model.md

Include a Mermaid context map and per-context diagrams.

graph TD
    Catalog[Catalog Context]
    Ordering[Ordering Context]
    Billing[Billing Context]
    Ordering -->|PublishedProduct| Catalog
    Ordering -->|ChargeRequested| Billing

classDiagram
    class Order {
      +OrderId id
      +OrderStatus status
      +Money total
      place()
      cancel()
    }
    class OrderLine {
      +ProductId productId
      +Quantity quantity
      +Money unitPrice
    }
    class Money {
      +decimal amount
      +string currency
    }
    Order "1" *-- "many" OrderLine
    Order --> Money

specs/domain/database-model.md

Include Mermaid ERD diagrams and mapping notes.

erDiagram
    ORDERS {
        uuid id PK
        varchar status
        decimal total_amount
        varchar total_currency
        timestamp created_at
    }
    ORDER_LINES {
        uuid id PK
        uuid order_id FK
        uuid product_id
        int quantity
        decimal unit_price_amount
        varchar unit_price_currency
    }
    ORDERS ||--o{ ORDER_LINES : contains

Quality Checklist

Before presenting the results:

• Every FRD is mapped to one or more bounded contexts.
• Ubiquitous language avoids technical jargon where a business term exists.
• Every aggregate has explicit invariants and ownership.
• Domain diagrams and database diagrams are Mermaid text, not images.
• Cross-context relationships are explicit and named.
• Brownfield outputs distinguish observed state from proposed state.
• Assumptions and unresolved questions are called out, not hidden.

Mandatory Completion Checklist

The orchestrator MUST verify ALL of the following before marking ddd-modeling as complete:

• specs/domain/proposals.md exists and includes bounded contexts, glossary, and aggregate proposals
• specs/domain/domain-model.md exists and contains at least one Mermaid context map plus aggregate-level diagrams
• specs/domain/database-model.md exists and contains a Mermaid ERD plus aggregate-to-persistence mapping notes
• Every approved FRD is mapped to a bounded context
• Every bounded context has explicit ownership and integration boundaries
• For brownfield runs, observed constraints and proposed target boundaries are both documented

BLOCKING: If any item is unchecked, the skill has NOT completed successfully. The orchestrator must loop back and complete the missing items before using the model for planning or implementation.

Constraints

• Preserve business language — do not substitute framework class names for domain concepts.
• One aggregate root per transactional consistency boundary.
• Do not introduce shared-database coupling across bounded contexts without explicit justification.
• Label assumptions clearly when the available evidence is incomplete.
• Keep proposals implementation-agnostic unless an existing ADR constrains the design.

Output State Updates

After generating the artifacts, update .spec2cloud/state.json with a domainModeling section when appropriate:

{
  "domainModeling": {
    "status": "complete",
    "artifacts": [
      "specs/domain/proposals.md",
      "specs/domain/domain-model.md",
      "specs/domain/database-model.md"
    ]
  }
}

Append to .spec2cloud/audit.log:

[ISO-timestamp] step=ddd-modeling action=artifacts-generated result=done

Handoff

After approval:

1. Increment planning uses bounded contexts and aggregate boundaries to split work.
2. Tech stack resolution uses persistence ownership and integration style to choose storage and messaging technologies.
3. Contracts and implementation preserve the agreed context boundaries instead of collapsing everything into one model.