Model Domain
Quick Reference
| DDD concept |
Ruby default |
Avoid by default |
Typical home |
| Entity |
Plain class when persisted identity matters |
Extra wrapper object with no added meaning |
models/ or project namespace |
| Value object |
PORO — immutable, equality by value |
Shoving logic into helpers or primitives |
models/ or near the domain |
| Aggregate root |
The class that guards invariants and is the single entry point |
Splitting invariants across multiple models/classes |
models/ or project namespace |
| Domain service |
PORO for behavior spanning multiple entities |
Arbitrary model chosen just to hold code |
services/ |
| Application service |
Orchestrator for one use case |
Fat controllers, callback chains, or leaking rules |
services/ |
| Repository |
Only when a real persistence boundary exists beyond simple data access |
Repositories for every query |
repositories/ |
| Domain event |
Explicit object when multiple downstream consumers justify it |
Callback-driven hidden side effects |
events/ or project namespace |
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
- List domain concepts: Entities, values, policies, workflows, and events from the ubiquitous language.
- 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.
- 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?
- 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?
- Pick project homes: Choose the simplest directory location that matches the boundary and repo conventions.
- Verify with tests: Hand off to
test-planning-process and tdd-process before implementation.
Common Mistakes
| Mistake |
Reality |
| Turning every concept into a service |
Many behaviors belong naturally on entities or value objects |
| Treating aggregates as folder names only |
Aggregates exist to protect invariants, not to look architectural |
| Adding domain events for one local callback |
Events justify their cost only when multiple downstream consumers exist |
| Pattern choice justified only with "DDD says so" |
The reason must be an invariant, ownership boundary, or clear coordination need |
| Same invariant enforced from multiple unrelated entry points |
Single aggregate root guards state transitions — one entry point per invariant |
| New abstractions that increase indirection without clarifying ownership |
If the boundary is unclear after modeling, the abstraction is premature |
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:
- Domain concept — name from the ubiquitous language
- Recommended modeling choice — entity, value object, service, etc.
- Suggested file path — file location (e.g.,
lib/ or services/)
- Invariant or ownership reason — the rule that must stay true and the exact object responsible for enforcing it
- Patterns to avoid — what not to reach for
- 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
- 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
| Skill |
When to chain |
| define-domain-language |
When the terms are not clear enough to model yet |
| review-domain-boundaries |
When the modeling problem is really a context boundary problem |
| test-planning-process |
When the next step is choosing the best first failing spec |
1---2name: model-domain3description: Use when modeling DDD concepts in Ruby: start from domain invariants and ownership before choosing patterns (document each concept with its invariant example, e.g., cancelled→active state transition guard, and patterns to avoid), prefer default Ruby classes over extra abstractions, entity when identity matters, value object when equality by value is correct, aggregate root guards state transitions as single entry point, domain service for behavior spanning multiple entities, application service orchestrates one use case — hand off to test-planning-process and tdd-process before implementation, and only add repository when real persistence boundary exists. Covers mapping of entities, aggregates, value objects, domain services, application services, repositories, and domain events without over-engineering.4license: MIT5---6# Model Domain78## Quick Reference910| DDD concept | Ruby default | Avoid by default | Typical home |11|-------------|---------------------|------------------|--------------|12| Entity | Plain class when persisted identity matters | Extra wrapper object with no added meaning | `models/` or project namespace |13| Value object | PORO — immutable, equality by value | Shoving logic into helpers or primitives | `models/` or near the domain |14| Aggregate root | The class that guards invariants and is the single entry point | Splitting invariants across multiple models/classes | `models/` or project namespace |15| Domain service | PORO for behavior spanning multiple entities | Arbitrary model chosen just to hold code | `services/` |16| Application service | Orchestrator for one use case | Fat controllers, callback chains, or leaking rules | `services/` |17| Repository | Only when a real persistence boundary exists beyond simple data access | Repositories for every query | `repositories/` |18| Domain event | Explicit object when multiple downstream consumers justify it | Callback-driven hidden side effects | `events/` or project namespace |1920## HARD-GATE2122```text23DO NOT introduce repositories, aggregates, or domain events just to sound "DDD".24DO NOT fight simple Ruby defaults when a normal class or service expresses the domain clearly.25ALWAYS start from domain invariants, ownership, and lifecycle before choosing a pattern.26MODELING OUTPUT IS NOT IMPLEMENTATION: do not include Ruby implementation code,27database migrations, or service bodies unless the user explicitly asks to move from28modeling into build work.29```3031## Core Process3233**Core principle:** Model real domain pressure, not textbook DDD vocabulary.3435### Modeling Order36371. **List domain concepts:** Entities, values, policies, workflows, and events from the ubiquitous language.382. **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.393. **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?404. **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?415. **Pick project homes:** Choose the simplest directory location that matches the boundary and repo conventions.426. **Verify with tests:** Hand off to `test-planning-process` and `tdd-process` before implementation.4344### Common Mistakes4546| Mistake | Reality |47|---------|----------|48| Turning every concept into a service | Many behaviors belong naturally on entities or value objects |49| Treating aggregates as folder names only | Aggregates exist to protect invariants, not to look architectural |50| Adding domain events for one local callback | Events justify their cost only when multiple downstream consumers exist |51| Pattern choice justified only with "DDD says so" | The reason must be an invariant, ownership boundary, or clear coordination need |52| Same invariant enforced from multiple unrelated entry points | Single aggregate root guards state transitions — one entry point per invariant |53| New abstractions that increase indirection without clarifying ownership | If the boundary is unclear after modeling, the abstraction is premature |5455## Extended Resources5657- [assets/examples.md](assets/examples.md) — Worked examples for multi-aggregate domains using pure Ruby.58- [assets/modeling_template.md](assets/modeling_template.md) — Blank output template for a single domain concept.5960> [!NOTE]61> For Rails-specific DDD mapping (e.g. mapping ActiveRecord associations and migrations), see `model-domain` in `rails-agent-skills` when using the Rails pack.6263## Output Style6465For each domain concept, return a compact entry covering:66671. **Domain concept** — name from the ubiquitous language682. **Recommended modeling choice** — entity, value object, service, etc.693. **Suggested file path** — file location (e.g., `lib/` or `services/`)704. **Invariant or ownership reason** — the rule that must stay true and the exact object responsible for enforcing it715. **Patterns to avoid** — what not to reach for726. **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 it737. **Next skill to chain** — e.g. `test-planning-process`7475### Inline Example — Order aggregate7677**Domain concept:** Order | **Modeling choice:** Aggregate root | **Suggested file path:** `lib/orders/order.rb`7879**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.8081**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.8283**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.8485**Next:** `test-planning-process` to select the first failing spec for `Order#cancel`.8687## Integration8889| Skill | When to chain |90|-------|---------------|91| **define-domain-language** | When the terms are not clear enough to model yet |92| **review-domain-boundaries** | When the modeling problem is really a context boundary problem |93| **test-planning-process** | When the next step is choosing the best first failing spec |
igmarin