robsonkades/agent-skills/java-ddd

Java DDD

Translate confirmed business examples into domain code following the reference's actual contracts. This skill owns the common domain foundation and coordinates the specialists. It does not replace a domain task with an application or infrastructure slice.

For the common bases, use the complete source files: AggregateRoot.java, Entity.java, Identifier.java and ValueObject.java. When an implementation or one of its imported types is needed, read the domain source index. It maps all 49 production types to one complete source file each in this hub or its required specialists, including the exceptions and utilities owned here. Read the affected contracts before adapting them; the individual files depend on other indexed types and are not isolated snippets.

Reference and scope

The sole technical authority is the current user-designated ddd-example/domain module. The bundled references capture the inspected revision and its source paths; they are portable instructions, not a requirement for a Windows directory to exist. Do not substitute an older ddd-example-master checkout, installed foundation, external DDD prescription or a preferred implementation style.

Use the user's business vocabulary with the reference's implementation shape. A new business rule, ownership boundary or choice between its different aggregate families needs evidence. Inspect the available source and requirements first; ask a focused question when that evidence does not resolve a consequential choice. Do not silently turn an unknown into a rule. Continue independent work whose contract is established.

For package placement, shared base types, exceptions or utilities, read reference conventions. For a new capability, conflicting requirements or a missing reference family, read modeling decisions.

Establish the implementation contract

1. Read the affected family and its tests. Identify the operation, accepted and

rejected inputs, current state, identity, lifecycle and expected result. Reuse explicit business examples; an existing table or field name cannot supply an unmentioned business rule. Record the exact reference types/methods being followed.

1. Check the target's compatibility. Inspect compiler settings, toolchain,

dependencies and test configuration. The source uses Java 17-compatible constructs; its buildSrc targets Java 17, while the shared Java conventions do not explicitly fix the domain compiler release/toolchain. Do not infer that setting or upgrade Java, Gradle or dependencies. No Spring, JPA or validation-framework annotations appear in the reference domain production code.

1. Map the domain package. Keep the common base types directly under domain,

aggregate families under domain.<aggregate>, and shared validation, exceptions, events, pagination and utilities in their named packages. Colocate a root with its <Root>ID, <Root>Gateway, <Root>Validator and relevant domain types. Reuse existing matching base contracts; do not create a parallel base hierarchy.

1. Preserve the selected contract. Keep factory names, constructor visibility,

equality, failure types/messages, validation timing, copying and fluent return behavior from that family. Creation and with(...) reconstruction are different operations. Reconstruction restores identity and lifecycle data instead of generating them again. Do not normalize the source's deliberate or observed differences without an explicit request to change the contract.

1. Implement and verify the domain behavior. Check the actual transition and

rejection result, including state after failure. Domain tests use real domain objects and no mocks, spies or Mockito. Every unit test method must have a meaningful @DisplayName, including parameterized tests when used. This display-name rule is an explicit user requirement in addition to the source, whose existing tests omit it. Keep tests simple, behavior-focused and readable; do not add getter/class-existence checks solely to increase a test count. For temporal transitions, initialize fixed past timestamps through an existing with(...) factory; do not use sleeps or mocks to force the clock forward. This is also an explicit user testing requirement.

Contracts that must remain visible

• ValueObject is an empty abstract base. Identifier extends it and declares

String getValue(). Neither base supplies automatic value equality, immutability or validation. Follow each concrete type's implementation.

• Entity<ID extends Identifier> owns a non-null, protected final ID id, abstract

validate(ValidationHandler), runtime-class-and-ID equality and recorded events. AggregateRoot<ID extends Identifier> adds only forwarding constructors.

• Category and Video expose explicit validate(handler); their constructors and

updates do not call it. CastMember and Genre call selfValidate() in construction and after updating fields. A failed update does not imply rollback. Preserve the relevant family's validation path instead of making every root reject at creation.

• An unmodifiable view is not a defensive snapshot. The source has live views,

copied collections, aliased collections and mutable resource bytes. Preserve the actual method's behavior; do not promise deep immutability or add copying by habit.

• Use the reference exception hierarchy and validation.Error contracts. Do not

translate a domain error into an HTTP status, introduce error codes, or replace Notification with Bean Validation as part of this domain implementation.

• Gateways are domain interfaces, and events are recorded domain facts. Their presence

does not establish persistence, commit timing, message delivery or thread safety. Keep those claims outside the evidence this module supplies.

Load the specialist for the affected decision

These six domain specialists install alongside this hub; read only the ones required by the affected contracts. java-ddd-use-cases owns a separately requested application operation. Spring composition and adapters belong to spring-boot-clean-architecture or spring-boot-hexagonal-architecture. bounded-context-design and domain-logic-organization can support a separately requested architecture discussion; they do not override this domain implementation reference.

Make the result reviewable

Match the requested mode. A review identifies the mismatched contract, source evidence, consequence and correction. A design identifies the domain types, reference family and unresolved business questions. An implementation delivers the requested domain code and meaningful tests. A short change report should name the behavior, owning type, relevant reference, checks actually run and any unresolved requirement.

Distinguish source observations from user additions and proposed changes. If a requested guarantee contradicts the reference, explain the exact conflict and ask before changing that guarantee. Do not modify the reference repository merely because it was consulted. Compilation and source comparison do not establish production concurrency or measured skill improvement; report only the validation performed.