@booklib/core 2.0.0

package/skills/domain-driven-design/SKILL.md

@@ -0,0 +1,142 @@
+---
+name: domain-driven-design
+version: "1.0"
+license: MIT
+tags: [architecture, ddd, modeling]
+description: >
+  Design and review software using patterns from Eric Evans' "Domain-Driven
+  Design." Use for DDD tactical patterns (Entities, Value Objects, Aggregates,
+  Repositories, Factories, Domain Services), strategic patterns (Bounded Context,
+  Context Map, Anticorruption Layer, Shared Kernel, Open Host Service), supple
+  design (Intention-Revealing Interfaces, Side-Effect-Free Functions, Closure of
+  Operations), distillation (Core Domain, Segregated Core), large-scale structure
+  (Responsibility Layers, Knowledge Level), and Ubiquitous Language. Trigger on
+  "DDD", "domain-driven design", "bounded context", "aggregate root", "value
+  object", "entity", "repository pattern", "domain service", "anticorruption
+  layer", "context map", "ubiquitous language", "core domain", "specification
+  pattern", "supple design", "layered architecture", or "strategic design."
+---
+
+# Domain-Driven Design Skill
+
+You are an expert software architect grounded in Eric Evans' *Domain-Driven Design*. You help developers in three modes: **Code Generation**, **Code Review**, and **Domain Migration Planning**.
+
+- Generate/build/create/model/design → **Code Generation**
+- Review/check/improve/audit/critique/refactor → **Code Review**
+- Migrate to DDD/enrich domain/refactor toward DDD → **Migration Planning**
+
+---
+
+## Mode 1: Code Generation
+
+### Pattern Selection
+
+| Problem | Pattern |
+|---------|---------|
+| Application structure | Layered Architecture: UI → Application → Domain → Infrastructure |
+| Object with identity and lifecycle | Entity (identity-based equality) |
+| Descriptive concept without identity | Value Object (immutable, attribute-based equality, side-effect-free) |
+| Enforce invariants across related objects | Aggregate (root entity, single boundary, transactional consistency) |
+| Complex object creation | Factory (enforces all invariants atomically) |
+| Collection-like persistence access | Repository (only for Aggregate roots) |
+| Operation belonging to no single object | Domain Service (stateless, Ubiquitous Language name) |
+| Composable business rules | Specification (isSatisfiedBy, and/or/not combinators) |
+| Integration with external system | Anticorruption Layer (Façade + Adapter + Translator) |
+| Shared model between teams | Shared Kernel (explicit joint ownership) |
+| API for many consumers | Open Host Service + Published Language |
+| Core competitive advantage | Core Domain distillation, Segregated Core |
+
+### Code Generation Principles
+
+- **Ubiquitous Language** — Class/method/variable names reflect domain terms. No "Manager", "Helper", "Processor" in the domain layer.
+- **Layered Architecture** — Domain layer has zero dependencies on infrastructure. Infrastructure implements domain interfaces.
+- **Entities** — Identity-based equality. Focused on lifecycle behavior, not data bags.
+- **Value Objects** — Immutable. Attribute-based equality. Rich behavior (operations return new instances). Prefer over Entities when identity doesn't matter. Use for all domain concepts expressed as primitives: Money, OrderId, Email, Address, Dimensions.
+- **Aggregates** — Single root entity. All external access through root. Enforce invariants at boundaries. Keep small; reference other Aggregates by ID only.
+- **Repositories** — Collection-like interface. Domain layer defines the interface; infrastructure implements it. Only one Repository per Aggregate root.
+- **Factories** — Encapsulate complex creation. Use private constructors + static factory methods to enforce invariants at creation time.
+- **Domain Services** — Stateless. Named in Ubiquitous Language. Only for operations that genuinely don't belong on any Entity or Value Object.
+- **Specification** — Business rules that combine, reuse, or query use `isSatisfiedBy()` with boolean combinators.
+- **Anticorruption Layer** — Translate external models to your domain model. Domain interfaces know nothing about the external system.
+
+### Code Generation Output
+
+Produce: (1) Ubiquitous Language glossary, (2) Aggregate design with invariants, (3) Value Objects, (4) Domain Services, (5) Repository interfaces, (6) Factory methods, (7) Application Services for use-case orchestration.
+
+---
+
+## Mode 2: Code Review
+
+### Review Checklist
+
+1. **Ubiquitous Language** — Do names reflect domain concepts? No technical jargon in the domain layer?
+2. **Layered Architecture** — Does the domain layer import infrastructure/persistence/HTTP? Dependencies inverted?
+3. **Entities vs Value Objects** — Are identity-less concepts modeled as immutable Value Objects? Is Primitive Obsession present (strings/ints used for domain concepts like orderId, Money, Email)?
+4. **Aggregates** — Does the root enforce all invariants? Are external callers bypassing the root via setters? Are Aggregates small? Cross-Aggregate references by ID only?
+5. **Repositories** — Only for Aggregate roots? Collection-like interface? Domain layer free of persistence details?
+6. **Factories** — Is complex creation encapsulated with invariant enforcement? Private constructors + factory methods?
+7. **Domain Services** — Truly stateless? Named in domain language? Not overused (anemic model symptom)?
+8. **Supple Design** — Intention-Revealing Interfaces? Side-Effect-Free Functions? Conceptual Contours aligned?
+9. **Strategic Design** — Bounded Contexts identified? Integration patterns applied?
+10. **Distillation** — Core Domain getting the most design attention?
+
+### Anti-Patterns to Flag
+
+- **Anemic Domain Model / Transaction Script masquerading as DDD** — Entities with only getters/setters; all logic in service classes. Domain objects should have behavior, not just data. When service methods procedurally manipulate passive data objects, explicitly name this the *Transaction Script* anti-pattern.
+- **God Aggregate / God Entity** — An Entity or Aggregate that has grown too large, accumulating too many fields and responsibilities. Count the fields: an Entity with 15+ fields is almost always a sign of missing Value Objects (Address, Dimensions, Money). Keep Aggregates small; reference by ID.
+- **Repository for non-roots** — Only Aggregate roots get Repositories.
+- **Leaking infrastructure into domain** — ORM annotations, HTTP/database imports in domain objects.
+- **Missing Ubiquitous Language** — Technical names ("DataProcessor", "ItemManager") instead of domain terms.
+- **Primitive Obsession** — Raw strings/ints for domain concepts instead of Value Objects (OrderId, Money, Email, Address).
+- **Broken Aggregate invariants** — External code modifying Aggregate internals via setters, bypassing the root.
+- **No Bounded Context boundaries** — One model serving all purposes; conflicting meanings for same terms.
+- **Conformist when ACL is needed** — Blindly adopting another system's model instead of translating via ACL.
+- **Smart UI / Fat Controller** — Domain logic in UI or application layer.
+- **Missing Specifications** — Complex boolean rules hardcoded inline rather than composable Specification objects.
+
+### Review Output Format
+
+```
+## Summary
+Domain model assessment: patterns applied, overall DDD alignment.
+
+## Strengths
+DDD patterns correctly applied (be specific and genuine).
+
+## Issues Found
+- **What**: the problem
+- **Why it matters**: modeling/maintainability/correctness risk
+- **Pattern to apply**: which DDD pattern fixes this
+- **Suggested fix**: concrete code change
+
+## Recommendations
+Priority-ordered improvements (critical first).
+```
+
+**Important for well-designed code:** When code correctly applies DDD patterns, say so explicitly in Strengths. Do NOT manufacture issues to seem thorough. Optional enhancements (domain events, additional Value Objects) must be clearly framed as enhancements, not defects.
+
+---
+
+## Mode 3: Domain Migration Planning
+
+Produce a phased migration plan when users want to incrementally move toward DDD.
+
+**Phase 1 — Ubiquitous Language (zero-risk):** Rename classes/methods to domain terms. Build a glossary. Definition of done: domain expert can read names without a translator.
+
+**Phase 2 — Value Objects (low-risk):** Extract Primitive Obsession into immutable Value Objects with validation in constructors (OrderId, Money, Email). Replace one class at a time.
+
+**Phase 3 — Aggregate Boundaries (medium-risk):** Identify clusters that change together. Designate roots. Remove external setters; enforce invariants via domain methods. Cross-Aggregate references by ID only.
+
+**Phase 4 — Repositories & Services (medium-risk):** Add Repository interfaces (domain layer) per Aggregate root. Move persistence to infrastructure. Extract stateless Domain Services for cross-entity operations.
+
+**Phase 5 — Strategic Design (high-risk, optional):** Map Bounded Contexts. Build Anticorruption Layers for external integrations. Apply Strangler Fig pattern for monolith migration.
+
+---
+
+## General Guidelines
+
+- Be practical, not dogmatic. DDD is most valuable for complex domains — not every CRUD app needs full DDD.
+- **Ubiquitous Language is foundational.** No pattern compensates for misaligned naming.
+- **Bounded Contexts before tactical patterns.** Strategic boundaries matter more than Entity vs Value Object classification.
+- **Keep Aggregates small.** The most common DDD mistake is Aggregates that are too large.
+- For deeper reference, see `references/patterns-catalog.md` (generation) and `references/review-checklist.md` (review).

package/skills/domain-driven-design/assets/example_asset.txt

@@ -0,0 +1 @@
+

package/skills/domain-driven-design/evals/evals.json

@@ -0,0 +1,48 @@
+{
+  "evals": [
+    {
+      "id": "eval-01-anemic-domain-model",
+      "prompt": "Review this code for a loan application system:\n\n```java\n// Domain object — just data\npublic class LoanApplication {\n    private String applicantId;\n    private BigDecimal requestedAmount;\n    private int termMonths;\n    private String status; // PENDING, APPROVED, REJECTED, DISBURSED\n    private BigDecimal approvedAmount;\n    private String rejectionReason;\n    private LocalDate applicationDate;\n    private String reviewerId;\n    \n    // getters and setters for all fields...\n}\n\n// All logic lives here\npublic class LoanApplicationService {\n    private LoanApplicationRepository repository;\n    private CreditScoreService creditScoreService;\n    private RiskEngine riskEngine;\n    \n    public void approveLoan(String applicationId, String reviewerId, BigDecimal approvedAmount) {\n        LoanApplication application = repository.findById(applicationId);\n        if (!application.getStatus().equals(\"PENDING\")) {\n            throw new IllegalStateException(\"Can only approve PENDING applications\");\n        }\n        if (approvedAmount.compareTo(application.getRequestedAmount()) > 0) {\n            throw new IllegalArgumentException(\"Approved amount cannot exceed requested amount\");\n        }\n        application.setStatus(\"APPROVED\");\n        application.setApprovedAmount(approvedAmount);\n        application.setReviewerId(reviewerId);\n        repository.save(application);\n    }\n    \n    public void rejectLoan(String applicationId, String reviewerId, String reason) {\n        LoanApplication application = repository.findById(applicationId);\n        if (!application.getStatus().equals(\"PENDING\")) {\n            throw new IllegalStateException(\"Can only reject PENDING applications\");\n        }\n        application.setStatus(\"REJECTED\");\n        application.setRejectionReason(reason);\n        application.setReviewerId(reviewerId);\n        repository.save(application);\n    }\n    \n    public boolean isEligibleForFastTrack(String applicationId) {\n        LoanApplication application = repository.findById(applicationId);\n        int creditScore = creditScoreService.getScore(application.getApplicantId());\n        return creditScore > 750 && application.getRequestedAmount().compareTo(new BigDecimal(\"50000\")) <= 0;\n    }\n}\n```",
+      "expectations": [
+        "Identifies this as an Anemic Domain Model — LoanApplication is a data bag with no behavior, all logic pushed into the service layer",
+        "Flags that approve() and reject() are domain operations that belong on the LoanApplication aggregate, not in the service",
+        "Notes that the invariant 'can only approve PENDING applications' is a business rule that LoanApplication should enforce internally",
+        "Flags Primitive Obsession: status as String instead of a LoanStatus enum or Value Object; applicantId and reviewerId as raw Strings instead of typed Value Objects (ApplicantId, ReviewerId)",
+        "Notes that requestedAmount and approvedAmount should be a Money Value Object (amount + currency), not a bare BigDecimal",
+        "Points out that the service directly sets fields via setters (setStatus, setApprovedAmount) — bypasses any invariant enforcement and breaks encapsulation",
+        "Recommends moving approve(ReviewerId reviewerId, Money approvedAmount) and reject(ReviewerId reviewerId, String reason) methods onto LoanApplication itself",
+        "Suggests that the service layer should be thin: load aggregate → call domain method → save",
+        "References the anti-pattern: 'Transaction Script masquerading as DDD — procedural service methods that manipulate passive data objects'"
+      ]
+    },
+    {
+      "id": "eval-02-missing-value-object",
+      "prompt": "Review this code for a shipping system:\n\n```java\npublic class Shipment {\n    private String id;\n    private String recipientName;\n    private String streetAddress;\n    private String city;\n    private String stateCode;\n    private String postalCode;\n    private String countryCode;\n    private String senderName;\n    private String senderStreet;\n    private String senderCity;\n    private String senderStateCode;\n    private String senderPostalCode;\n    private String senderCountryCode;\n    private double weightKg;\n    private double lengthCm;\n    private double widthCm;\n    private double heightCm;\n    private String trackingNumber;\n    private String status;\n    \n    public double calculateVolumetricWeight() {\n        return (lengthCm * widthCm * heightCm) / 5000.0;\n    }\n    \n    public double getBillableWeight() {\n        double volumetric = calculateVolumetricWeight();\n        return Math.max(weightKg, volumetric);\n    }\n    \n    public boolean isInternational() {\n        return !senderCountryCode.equals(countryCode);\n    }\n    \n    public String formatRecipientAddress() {\n        return recipientName + \"\\n\" + streetAddress + \"\\n\" +\n               city + \", \" + stateCode + \" \" + postalCode + \"\\n\" + countryCode;\n    }\n    \n    public String formatSenderAddress() {\n        return senderName + \"\\n\" + senderStreet + \"\\n\" +\n               senderCity + \", \" + senderStateCode + \" \" + senderPostalCode + \"\\n\" + senderCountryCode;\n    }\n}\n```",
+      "expectations": [
+        "Identifies the missing Value Objects: Address (street, city, state, postal code, country) is a natural concept that is duplicated for sender and recipient",
+        "Identifies a second Value Object: Dimensions (length, width, height) with volumetric weight behavior",
+        "Identifies a third Value Object candidate: Weight (value + unit — kg is baked into the field name but not the type)",
+        "Notes that the Shipment Entity is bloated with 19 fields — a God Entity collecting too many responsibilities",
+        "Points out that formatRecipientAddress() and formatSenderAddress() are the same logic duplicated with different field names — a symptom of not having an Address Value Object",
+        "Notes that calculateVolumetricWeight() belongs on a Dimensions Value Object, not on Shipment",
+        "Flags Primitive Obsession: all fields are raw strings/doubles instead of typed domain concepts",
+        "Recommends concrete refactoring: extract Address, Dimensions, Weight Value Objects; Shipment holds Address recipient, Address sender, Dimensions, Weight",
+        "Notes Value Objects should be immutable with attribute-based equality"
+      ]
+    },
+    {
+      "id": "eval-03-well-designed-aggregate",
+      "prompt": "Review this domain model for a bank account system:\n\n```java\npublic class AccountId {\n    private final String value;\n    \n    public AccountId(String value) {\n        if (value == null || value.isBlank()) throw new IllegalArgumentException(\"AccountId cannot be blank\");\n        this.value = value;\n    }\n    \n    public String getValue() { return value; }\n    \n    @Override public boolean equals(Object o) {\n        if (this == o) return true;\n        if (!(o instanceof AccountId)) return false;\n        return value.equals(((AccountId) o).value);\n    }\n    @Override public int hashCode() { return value.hashCode(); }\n}\n\npublic class Money {\n    private final BigDecimal amount;\n    private final Currency currency;\n    \n    public Money(BigDecimal amount, Currency currency) {\n        if (amount == null || currency == null) throw new IllegalArgumentException();\n        this.amount = amount;\n        this.currency = currency;\n    }\n    \n    public Money add(Money other) {\n        if (!this.currency.equals(other.currency)) throw new IllegalArgumentException(\"Currency mismatch\");\n        return new Money(this.amount.add(other.amount), this.currency);\n    }\n    \n    public Money subtract(Money other) {\n        if (!this.currency.equals(other.currency)) throw new IllegalArgumentException(\"Currency mismatch\");\n        return new Money(this.amount.subtract(other.amount), this.currency);\n    }\n    \n    public boolean isNegative() { return amount.compareTo(BigDecimal.ZERO) < 0; }\n    \n    // equals, hashCode based on amount and currency\n}\n\npublic class BankAccount {\n    private final AccountId id;\n    private Money balance;\n    private final List<Transaction> ledger;\n    private AccountStatus status;\n    \n    private BankAccount(AccountId id, Money initialBalance) {\n        this.id = id;\n        this.balance = initialBalance;\n        this.ledger = new ArrayList<>();\n        this.status = AccountStatus.ACTIVE;\n    }\n    \n    public static BankAccount open(AccountId id, Money initialDeposit) {\n        if (initialDeposit.isNegative()) throw new IllegalArgumentException(\"Initial deposit must be positive\");\n        return new BankAccount(id, initialDeposit);\n    }\n    \n    public void deposit(Money amount) {\n        if (status != AccountStatus.ACTIVE) throw new IllegalStateException(\"Cannot deposit to a \" + status + \" account\");\n        if (amount.isNegative()) throw new IllegalArgumentException(\"Deposit amount must be positive\");\n        this.balance = this.balance.add(amount);\n        ledger.add(Transaction.credit(amount));\n    }\n    \n    public void withdraw(Money amount) {\n        if (status != AccountStatus.ACTIVE) throw new IllegalStateException(\"Cannot withdraw from a \" + status + \" account\");\n        if (amount.isNegative()) throw new IllegalArgumentException(\"Withdrawal amount must be positive\");\n        Money newBalance = this.balance.subtract(amount);\n        if (newBalance.isNegative()) throw new DomainException(\"Insufficient funds\");\n        this.balance = newBalance;\n        ledger.add(Transaction.debit(amount));\n    }\n    \n    public void close() {\n        if (!balance.equals(Money.zero(balance.getCurrency()))) {\n            throw new DomainException(\"Cannot close account with non-zero balance\");\n        }\n        this.status = AccountStatus.CLOSED;\n    }\n    \n    public Money getBalance() { return balance; }\n    public List<Transaction> getLedger() { return Collections.unmodifiableList(ledger); }\n    public AccountId getId() { return id; }\n}\n```",
+      "expectations": [
+        "Recognizes this as a well-designed Aggregate and says so explicitly",
+        "Praises AccountId and Money as properly modeled Value Objects — immutable, attribute-based equality, validated in constructor",
+        "Praises the factory method BankAccount.open() for enforcing invariants at creation time",
+        "Praises that all business rules (no overdraft, no deposit to closed account, cannot close with balance) are enforced inside the aggregate rather than in a service layer",
+        "Praises that getLedger() returns an unmodifiable list — protecting the internal collection from external mutation",
+        "Praises the closed constructor — external code cannot create a BankAccount without going through the factory method",
+        "Does NOT manufacture fake issues just to have something to say",
+        "May offer optional suggestions (domain events for deposit/withdrawal, separate TransactionId Value Object) but clearly frames them as enhancements, not defects"
+      ]
+    }
+  ]
+}

package/skills/domain-driven-design/evals/results.json

@@ -0,0 +1,13 @@
+{
+  "pass_rate": 1,
+  "passed": 26,
+  "total": 26,
+  "baseline_pass_rate": 0.654,
+  "baseline_passed": 17,
+  "baseline_total": 26,
+  "delta": 0.346,
+  "model": "default",
+  "evals_run": 3,
+  "date": "2026-03-28",
+  "non_standard_provider": true
+}

package/skills/domain-driven-design/examples/after.md

@@ -0,0 +1,80 @@
+# After
+
+`Order` becomes a rich aggregate root that owns its invariants and exposes domain-language behavior; `OrderService` becomes a thin application-layer coordinator.
+
+```java
+// Rich aggregate root — enforces all invariants internally
+public class Order {
+    private final OrderId id;
+    private final List<OrderLine> lines = new ArrayList<>();
+    private OrderStatus status;
+    private Money total;
+
+    private Order(OrderId id, CustomerId customerId) {
+        this.id = id;
+        this.status = OrderStatus.PENDING;
+        this.total = Money.ZERO;
+    }
+
+    public static Order place(OrderId id, CustomerId customerId) {
+        return new Order(id, customerId);
+    }
+
+    public void addItem(Product product, int quantity) {
+        Validate.isTrue(quantity > 0, "Quantity must be positive");
+        Validate.isTrue(status == OrderStatus.PENDING, "Cannot modify a non-pending order");
+        lines.add(OrderLine.of(product.getId(), product.getPrice(), quantity));
+        recalculateTotal();
+    }
+
+    public void confirm() {
+        if (lines.isEmpty()) {
+            throw new DomainException("Cannot confirm an order with no items");
+        }
+        this.status = OrderStatus.CONFIRMED;
+    }
+
+    public void cancel() {
+        if (!status.isCancellable()) {
+            throw new DomainException("Order in status " + status + " cannot be cancelled");
+        }
+        this.status = OrderStatus.CANCELLED;
+    }
+
+    private void recalculateTotal() {
+        this.total = lines.stream()
+            .map(OrderLine::lineTotal)
+            .reduce(Money.ZERO, Money::add);
+    }
+
+    // Getters return immutable views only
+    public List<OrderLine> lines() { return Collections.unmodifiableList(lines); }
+    public Money total()           { return total; }
+    public OrderStatus status()    { return status; }
+}
+
+// Application service is thin — orchestrates, does not contain business rules
+public class PlaceOrderUseCase {
+    private final OrderRepository orderRepository;
+    private final ProductRepository productRepository;
+
+    public OrderId execute(PlaceOrderCommand cmd) {
+        Order order = Order.place(OrderId.generate(), cmd.customerId());
+        for (var item : cmd.requestedItems()) {
+            Product product = productRepository.findById(item.productId())
+                .orElseThrow(() -> new ProductNotFoundException(item.productId()));
+            order.addItem(product, item.quantity());
+        }
+        order.confirm();
+        orderRepository.save(order);
+        return order.getId();
+    }
+}
+```
+
+Key improvements:
+- Business rules (`confirm`, `cancel`, `addItem`) live inside `Order` — the anemic model anti-pattern is eliminated
+- `Order.status.isCancellable()` encapsulates the cancellation-eligibility rule in an enum method rather than in a service
+- External code cannot corrupt the aggregate: `lines` is returned as an unmodifiable view; `total` is always recalculated internally
+- `OrderService` is renamed to `PlaceOrderUseCase` per the Ubiquitous Language (application command, not a generic "service")
+- `Money` is a Value Object, preventing `double` arithmetic errors on financial amounts (Primitive Obsession eliminated)

package/skills/domain-driven-design/examples/before.md

@@ -0,0 +1,43 @@
+# Before
+
+An anemic domain model where the `Order` class is a passive data container with no behavior, and all business logic is scattered across `OrderService`.
+
+```java
+// Anemic entity — just a data bag
+public class Order {
+    public Long id;
+    public List<OrderLine> lines;
+    public String status;
+    public BigDecimal totalAmount;
+    public String customerId;
+}
+
+// All logic lives in the service
+public class OrderService {
+
+    public void addItem(Order order, Product product, int quantity) {
+        OrderLine line = new OrderLine();
+        line.productId = product.id;
+        line.quantity = quantity;
+        line.unitPrice = product.price;
+        order.lines.add(line);
+        order.totalAmount = order.lines.stream()
+            .map(l -> l.unitPrice.multiply(BigDecimal.valueOf(l.quantity)))
+            .reduce(BigDecimal.ZERO, BigDecimal::add);
+    }
+
+    public void cancel(Order order) {
+        if (!order.status.equals("PENDING") && !order.status.equals("CONFIRMED")) {
+            throw new IllegalStateException("Cannot cancel");
+        }
+        order.status = "CANCELLED";
+    }
+
+    public void confirm(Order order) {
+        if (order.lines == null || order.lines.isEmpty()) {
+            throw new IllegalStateException("Cannot confirm empty order");
+        }
+        order.status = "CONFIRMED";
+    }
+}
+```

package/skills/domain-driven-design/references/api_reference.md

@@ -0,0 +1 @@
+