Model Domain

Quick Reference

HARD-GATE

DO NOT introduce repositories, aggregates, or domain events just to sound "DDD".
DO NOT fight simple Ruby defaults when a normal class or service expresses the domain clearly.
ALWAYS start from domain invariants, ownership, and lifecycle before choosing a pattern.
MODELING OUTPUT IS NOT IMPLEMENTATION: do not include Ruby implementation code,
database migrations, or service bodies unless the user explicitly asks to move from
modeling into build work.

Core Process

Core principle: Model real domain pressure, not textbook DDD vocabulary.

Modeling Order

1. List domain concepts: Entities, values, policies, workflows, and events from the ubiquitous language.
2. Identify invariants: Ask: what must always be true after any state change? What breaks if two callers mutate the same state simultaneously? Decide which object or boundary must keep each rule true.
3. Choose the aggregate entry point: Name the object that guards state transitions and consistency. Ask: is there exactly one place a caller must go to change this state?
4. Place behavior: Keep behavior on the entity/aggregate when cohesive; extract a domain service only when behavior spans multiple concepts cleanly. Ask: does moving this out clarify ownership, or just spread it?
5. Pick project homes: Choose the simplest directory location that matches the boundary and repo conventions.
6. Verify with tests: Hand off to test-planning-process and tdd-process before implementation.

Common Mistakes

Extended Resources

• assets/examples.md — Worked examples for multi-aggregate domains using pure Ruby.
• assets/modeling_template.md — Blank output template for a single domain concept.

[!NOTE] For Rails-specific DDD mapping (e.g. mapping ActiveRecord associations and migrations), see model-domain in rails-agent-skills when using the Rails pack.

Output Style

For each domain concept, return a compact entry covering:

1. Domain concept — name from the ubiquitous language
2. Recommended modeling choice — entity, value object, service, etc.
3. Suggested file path — file location (e.g., lib/ or services/)
4. Invariant or ownership reason — the rule that must stay true and the exact object responsible for enforcing it
5. Patterns to avoid — what not to reach for
6. Test handoff — first behavior to verify, likely test/spec type, and that implementation is deferred until test-planning-process selects the test and tdd-process writes it
7. Next skill to chain — e.g. test-planning-process

Inline Example — Order aggregate

Domain concept: Order | Modeling choice: Aggregate root | Suggested file path: lib/orders/order.rb

Invariant: An Order must never transition from cancelled back to active, and its total must always reflect current line items. Order is the single entry point; no external caller may mutate line items or status directly.

Avoid: Do not extract an OrderService just to hold place and cancel — that behavior belongs on the aggregate. Do not introduce OrderRepository unless a non-standard database persistence backend is required.

Test handoff: First behavior — Order#cancel raises when already cancelled. Spec type: unit model spec (spec/orders/order_spec.rb). Implementation deferred until test-planning-process selects this spec and tdd-process writes it.

Next: test-planning-process to select the first failing spec for Order#cancel.

Integration