@booklib/skills 1.0.0

package/domain-driven-design/references/review-checklist.md

@@ -0,0 +1,158 @@
+# Domain-Driven Design — Code Review Checklist
+
+Systematic checklist for reviewing code against DDD principles. Organized by
+category with specific items to inspect.
+
+---
+
+## 1. Ubiquitous Language
+
+- [ ] **Class names match domain terms** — Classes are named after domain concepts the business recognizes, not technical abstractions (e.g., `Policy` not `RuleEngine`, `Shipment` not `DataTransferObject`)
+- [ ] **Method names describe domain operations** — Methods read like domain actions (e.g., `order.cancel()` not `order.setStatus(CANCELLED)`, `account.debit(amount)` not `account.updateBalance(-amount)`)
+- [ ] **No technical jargon in domain layer** — Avoid names like Manager, Handler, Processor, Helper, Util, Data, Info in the domain layer
+- [ ] **Consistent vocabulary** — Same concept uses the same name everywhere. No synonyms (e.g., don't mix "client" and "customer" for the same concept)
+- [ ] **Language reflects current understanding** — Terms have been refined as the model evolved, not stuck with initial naive names
+- [ ] **Module/package names tell a domain story** — Packages are organized by domain concept, not by pattern type (not `entities/`, `services/`, `repositories/`)
+
+## 2. Layered Architecture
+
+- [ ] **Four layers identifiable** — UI/Presentation, Application, Domain, Infrastructure are clearly separated
+- [ ] **Domain layer has zero outward dependencies** — Domain classes don't import UI, Application, or Infrastructure classes
+- [ ] **Infrastructure implements domain interfaces** — Dependency Inversion: domain defines interfaces (e.g., `OrderRepository`), infrastructure implements them (e.g., `JpaOrderRepository`)
+- [ ] **Application layer is thin** — Application services coordinate but contain NO business logic. They manage transactions, security, and use-case flow
+- [ ] **No domain logic in controllers** — UI/API controllers delegate to application services, never contain business rules
+- [ ] **No domain logic in infrastructure** — Persistence logic doesn't enforce business rules; it only stores and retrieves
+- [ ] **No circular dependencies** — Lower layers never depend on higher layers
+
+## 3. Entities
+
+- [ ] **Identity is explicit** — Entity has a clear, typed identifier (preferably a Value Object like `OrderId`, not a raw `String` or `long`)
+- [ ] **Equality based on identity** — `equals()` and `hashCode()` use the identifier, not attributes
+- [ ] **Encapsulates behavior** — Entity contains domain logic, not just getters and setters
+- [ ] **Lifecycle management** — Entity handles its own state transitions and lifecycle events
+- [ ] **Not overloaded** — Entity is focused on identity and core behavior; ancillary logic is in Value Objects or Services
+- [ ] **Attributes that change are still same entity** — Design acknowledges that attributes can change while identity persists
+
+## 4. Value Objects
+
+- [ ] **Immutable** — No setters, no mutable state. All fields are final/readonly
+- [ ] **Equality by attributes** — `equals()` compares all attributes, not reference identity
+- [ ] **Rich behavior** — Value Objects contain domain logic (calculations, validations, transformations), not just data
+- [ ] **Side-effect-free methods** — Operations return new Value Objects rather than modifying state
+- [ ] **Used instead of primitives** — Domain concepts like money, dates, addresses, quantities are Value Objects, not raw types (no `double price`, `String email`, `int quantity`)
+- [ ] **Freely shareable** — No aliasing bugs because they're immutable
+- [ ] **Self-validating** — Value Object constructor validates invariants (e.g., `Email` rejects invalid format)
+
+## 5. Aggregates
+
+- [ ] **Clear root entity** — One Entity is the root with global identity; all access goes through it
+- [ ] **Boundary is defined** — It's clear which Entities and Value Objects are inside the Aggregate
+- [ ] **Invariants enforced by root** — The root ensures all business rules within the boundary are consistent
+- [ ] **No external references to internals** — Outside code cannot hold direct references to internal entities. References are through the root only
+- [ ] **Kept small** — Aggregate contains only what's needed for invariant enforcement. Other Aggregates are referenced by ID
+- [ ] **One Aggregate per transaction** — Changes to one Aggregate are committed in one transaction. Cross-Aggregate changes are eventually consistent
+- [ ] **Delete cascades from root** — Removing the root removes everything inside the boundary
+- [ ] **Internal entities have local identity** — IDs of internal entities are meaningful only within the Aggregate
+
+## 6. Repositories
+
+- [ ] **Only for Aggregate roots** — No Repository exists for internal Aggregate entities or Value Objects
+- [ ] **Collection-like interface** — API resembles an in-memory collection: add, remove, find, query
+- [ ] **Interface in domain layer** — The Repository interface is defined in the domain layer
+- [ ] **Implementation in infrastructure** — The concrete class (JPA, JDBC, etc.) is in the infrastructure layer
+- [ ] **Returns whole Aggregates** — Queries return fully reconstituted Aggregates, not partial objects or DTOs
+- [ ] **No persistence leakage** — Domain code has no awareness of SQL, ORM annotations, or storage details
+- [ ] **Encapsulates query strategy** — Complex queries are behind well-named methods, not scattered SQL
+- [ ] **Delegates to Factory for reconstitution** — Complex object rebuilding is handled by a Factory, not in the Repository itself
+
+## 7. Factories
+
+- [ ] **Used for complex creation** — If creation requires more than a simple constructor, a Factory exists
+- [ ] **Atomic creation** — Factory produces a valid, consistent object or fails entirely (no partially created objects)
+- [ ] **Invariants enforced at creation** — All Aggregate invariants are validated during Factory creation
+- [ ] **Abstracts concrete types** — Client code depends on abstractions, not on the specific class the Factory creates
+- [ ] **Reconstitution vs. creation distinguished** — Factories for loading from persistence don't re-validate business rules that only apply at creation time, and don't generate new IDs
+
+## 8. Domain Services
+
+- [ ] **Stateless** — Domain Services hold no mutable state between calls
+- [ ] **Named in Ubiquitous Language** — Service name describes a domain operation (e.g., `TransferService`, `PricingService`)
+- [ ] **Not overused** — Domain Services are the exception, not the rule. Most behavior belongs on Entities and Value Objects
+- [ ] **Parameters and return types are domain objects** — Service interfaces use domain types, not primitives or infrastructure types
+- [ ] **No anemic domain model** — If all logic is in Services and Entities are just data bags, the model is anemic
+- [ ] **Distinguished from Application Services** — Domain Services contain business logic; Application Services coordinate use cases
+
+## 9. Supple Design
+
+- [ ] **Intention-Revealing Interfaces** — Can a developer understand what a class/method does without reading the implementation?
+- [ ] **Side-Effect-Free Functions** — Complex logic lives in pure functions (especially on Value Objects). Commands are simple state changes
+- [ ] **Assertions / Post-conditions** — Critical invariants are documented or enforced. Tests verify post-conditions
+- [ ] **Conceptual Contours** — Object boundaries align with natural domain concepts. Things that change together are together
+- [ ] **Standalone Classes** — Dependencies are minimized. Each class can be understood with minimal context
+- [ ] **Closure of Operations** — Operations on a type return the same type where natural (e.g., `Money.add(Money): Money`)
+- [ ] **Declarative style** — Where possible, the code describes WHAT should happen, not HOW (e.g., specifications, rules)
+
+## 10. Specification Pattern
+
+- [ ] **Business rules as objects** — Complex boolean conditions are modeled as Specification objects, not inline conditionals
+- [ ] **isSatisfiedBy method** — Each Specification has a clear test method
+- [ ] **Composable** — Specifications can be combined with AND, OR, NOT
+- [ ] **Three use cases considered** — Validation (testing), Selection (querying), Building-to-order (generation)
+- [ ] **Named in domain language** — `OverdueInvoiceSpecification`, not `InvoiceFilter42`
+- [ ] **Implemented as Value Objects** — Specifications are immutable and side-effect-free
+
+## 11. Strategic Design — Bounded Contexts
+
+- [ ] **Contexts are explicitly defined** — Each Bounded Context has a clear name and boundary
+- [ ] **One model per context** — No concept is defined differently within the same context
+- [ ] **Context Map exists** — Relationships between contexts are documented
+- [ ] **Integration patterns identified** — Each context-to-context relationship uses a named pattern (Shared Kernel, ACL, Conformist, etc.)
+- [ ] **No model bleeding** — Types from one context don't appear in another context's domain layer
+- [ ] **Team boundaries align** — Ideally, one team per Bounded Context
+
+## 12. Integration Patterns
+
+- [ ] **Anticorruption Layer present where needed** — External systems and legacy integrations are wrapped in ACL
+- [ ] **ACL components identifiable** — Façade, Adapter, and Translator are present as needed
+- [ ] **Domain interfaces define integration** — The domain layer defines what it needs; infrastructure implements it
+- [ ] **Shared Kernel is minimal** — If two contexts share code, the shared portion is as small as possible with joint CI
+- [ ] **Open Host Service is well-documented** — Public APIs have clear protocols and versioning
+- [ ] **Published Language is formal** — Shared data formats are documented and standardized
+- [ ] **Conformist choice is conscious** — If a team conforms to an upstream model, it's a deliberate decision with documented trade-offs
+
+## 13. Distillation
+
+- [ ] **Core Domain identified** — The team knows which part of the system is the competitive differentiator
+- [ ] **Best talent on Core** — The most skilled developers are working on the Core Domain
+- [ ] **Generic Subdomains simplified** — Non-core parts use off-the-shelf solutions, simpler models, or outsourced implementations
+- [ ] **Domain Vision Statement exists** — A short document describes the Core Domain's value proposition
+- [ ] **Core is highlighted** — Developers can quickly identify which code is Core Domain (via packages, annotations, or documentation)
+- [ ] **Segregated Core** — Core Domain code is in its own module with minimal dependencies on supporting code
+
+## 14. Large-Scale Structure
+
+- [ ] **Structure serves the team** — If a large-scale structure exists, it helps developers navigate and make decisions
+- [ ] **Not over-engineered** — Structure is as simple as possible. No structure is better than bad structure
+- [ ] **Evolving** — Structure is allowed to change as understanding deepens
+- [ ] **Responsibility Layers (if used)** — Layers have clear domain-level responsibilities and dependencies flow downward
+- [ ] **Knowledge Level (if used)** — Configuration rules are separated from operational data in a meta-model
+
+---
+
+## Quick Review Workflow
+
+1. **Start with Ubiquitous Language** — Read the code. Does it speak the domain? Can a domain expert recognize the concepts?
+2. **Check architecture** — Are layers separated? Does the domain depend on nothing?
+3. **Inspect building blocks** — Are Entities, Value Objects, Aggregates, Repositories, and Services used correctly?
+4. **Evaluate design quality** — Is the design supple? Intention-revealing? Side-effect-free where possible?
+5. **Assess strategic alignment** — Are Bounded Contexts defined? Is the Core Domain getting the most attention?
+6. **Flag anti-patterns** — Look for anemic domain model, God Aggregates, primitive obsession, leaking infrastructure, missing ACL
+
+## Severity Levels
+
+| Severity | Description | Example |
+|----------|------------|---------|
+| **Critical** | Broken invariants, data corruption risk, no domain model | Anemic domain model, no Aggregate boundaries, infrastructure in domain |
+| **High** | Incorrect pattern application, model integrity issues | Repository for non-root, mutable Value Objects, leaked internals |
+| **Medium** | Design improvement opportunities | Missing Specifications, primitive types for concepts, overly large Aggregates |
+| **Low** | Polish and naming refinements | Inconsistent naming, missing documentation, suboptimal module organization |

package/domain-driven-design/scripts/example.py

@@ -0,0 +1 @@
+

package/effective-java/SKILL.md

@@ -0,0 +1,195 @@
+---
+name: effective-java
+description: >
+  Generate and review Java code using patterns and best practices from Joshua Bloch's
+  "Effective Java" (3rd Edition). Use this skill whenever the user asks about Java best
+  practices, API design, object creation patterns, generics, enums, lambdas, streams,
+  concurrency, serialization, method design, exception handling, or writing clean,
+  maintainable Java code. Trigger on phrases like "Effective Java", "Java best practices",
+  "builder pattern", "static factory", "defensive copy", "immutable class", "enum type",
+  "generics", "bounded wildcard", "PECS", "stream pipeline", "optional", "thread safety",
+  "serialization proxy", "checked exception", "try-with-resources", "composition over
+  inheritance", "method reference", "functional interface", or "Java API design."
+---
+
+# Effective Java Skill
+
+You are an expert Java architect grounded in the 90 items from Joshua Bloch's
+*Effective Java* (3rd Edition). You help developers in two modes:
+
+1. **Code Generation** — Produce well-structured Java code following Effective Java principles
+2. **Code Review** — Analyze existing Java code and recommend improvements
+
+## How to Decide Which Mode
+
+- If the user asks you to *build*, *create*, *generate*, *implement*, or *scaffold* something → **Code Generation**
+- If the user asks you to *review*, *check*, *improve*, *audit*, or *critique* code → **Code Review**
+- If ambiguous, ask briefly which mode they'd prefer
+
+---
+
+## Mode 1: Code Generation
+
+When generating Java code, follow this decision flow:
+
+### Step 1 — Understand the Requirements
+
+Ask (or infer from context) what the component needs:
+
+- **Object creation** — How should instances be created? (Factory, Builder, Singleton, DI)
+- **Mutability** — Does the class need to be mutable or can it be immutable?
+- **Inheritance model** — Composition, interface-based, or class hierarchy?
+- **Concurrency** — Will this be accessed from multiple threads?
+- **API surface** — Is this internal or part of a public API?
+
+### Step 2 — Select the Right Patterns
+
+Read `references/items-catalog.md` for full item details. Quick decision guide:
+
+| Problem | Items to Apply |
+|---------|---------------|
+| How to create objects? | Item 1 (static factories), Item 2 (Builder), Item 3 (Singleton), Item 5 (DI) |
+| How to design an immutable class? | Item 17 (minimize mutability), Item 50 (defensive copies) |
+| How to model types? | Item 20 (interfaces over abstract classes), Item 23 (class hierarchies over tagged classes) |
+| How to use generics safely? | Item 26 (no raw types), Item 31 (bounded wildcards / PECS), Item 28 (lists over arrays) |
+| How to use enums effectively? | Item 34 (enums over int constants), Item 37 (EnumSet), Item 38 (EnumMap) |
+| How to use lambdas and streams? | Item 42 (lambdas over anon classes), Item 43 (method refs), Item 45 (streams judiciously) |
+| How to design methods? | Item 49 (validate params), Item 50 (defensive copies), Item 51 (design signatures carefully) |
+| How to handle errors? | Item 69 (exceptions for exceptional conditions), Item 71 (avoid unnecessary checked), Item 73 (translate exceptions) |
+| How to handle concurrency? | Item 78 (synchronize shared mutable data), Item 79 (avoid excessive sync), Item 81 (concurrency utilities) |
+| How to handle serialization? | Item 85 (prefer alternatives), Item 90 (serialization proxies) |
+
+### Step 3 — Generate the Code
+
+Follow these principles when writing Java code:
+
+- **Static factories over constructors** — Use `of`, `from`, `valueOf`, `create` naming. Return interface types. Cache instances when possible (Item 1)
+- **Builder for many parameters** — Any constructor with more than 3-4 parameters should use the Builder pattern with fluent API (Item 2)
+- **Immutable by default** — Make fields `final`, make classes `final`, no setters, defensive copies in constructors and accessors (Item 17)
+- **Composition over inheritance** — Wrap existing classes with forwarding methods instead of extending them. Use the decorator pattern (Item 18)
+- **Program to interfaces** — Declare variables, parameters, and return types as interfaces, not concrete classes (Item 64)
+- **Generics everywhere** — No raw types. Use `<? extends T>` for producers, `<? super T>` for consumers (PECS). Prefer `List<E>` over `E[]` (Items 26, 28, 31)
+- **Enums over constants** — Never `public static final int`. Use enums with behavior, strategy enum pattern, and EnumSet/EnumMap (Items 34, 36, 37)
+- **Lambdas and method references** — Prefer lambdas to anonymous classes, method references to lambdas when clearer. Use standard functional interfaces (Items 42-44)
+- **Streams judiciously** — Don't overuse. Keep side-effect-free. Return `Collection` over `Stream` from APIs. Be careful with parallel streams (Items 45-48)
+- **Defensive programming** — Validate parameters with `Objects.requireNonNull`, use `@Nullable` annotations, return empty collections not null, use Optional for return types (Items 49, 54, 55)
+- **Exceptions done right** — Use unchecked for programming errors, checked for recoverable conditions. Translate exceptions at abstraction boundaries. Include failure-capture info (Items 69-77)
+- **Thread safety by design** — Document thread safety levels. Prefer concurrency utilities (`ConcurrentHashMap`, `CountDownLatch`) over `wait`/`notify`. Use lazy initialization only when needed (Items 78-84)
+- **Avoid Java serialization** — Use JSON, protobuf, or other formats. If you must use Serializable, use serialization proxies (Items 85-90)
+
+When generating code, produce:
+
+1. **Class design** — Access levels, mutability, type hierarchy
+2. **Object creation** — Factory methods, builders, dependency injection
+3. **API methods** — Parameter validation, return types, documentation
+4. **Error handling** — Exception hierarchy, translation, failure atomicity
+5. **Concurrency model** — Thread safety annotations, synchronization strategy
+
+### Code Generation Examples
+
+**Example 1 — Immutable Value Class with Builder:**
+```
+User: "Create a class to represent a nutritional facts label"
+
+You should generate:
+- Immutable class with private final fields (Item 17)
+- Builder pattern with fluent API for optional params (Item 2)
+- Static factory method NutritionFacts.builder() (Item 1)
+- Proper equals, hashCode, toString (Items 10-12)
+- Defensive copies for any mutable fields (Item 50)
+- @Override annotations (Item 40)
+```
+
+**Example 2 — Strategy Enum:**
+```
+User: "Model different payment processing strategies"
+
+You should generate:
+- Enum with abstract method and constant-specific implementations (Item 34)
+- Strategy pattern via enum (avoiding switch on enum)
+- EnumSet for combining payment options (Item 36)
+- EnumMap for payment-method-to-processor mapping (Item 37)
+```
+
+**Example 3 — Thread-Safe Service:**
+```
+User: "Build a caching service that handles concurrent access"
+
+You should generate:
+- ConcurrentHashMap for thread-safe cache (Item 81)
+- Documented thread safety level (Item 82)
+- Lazy initialization with double-check idiom if needed (Item 83)
+- Composition over inheritance for wrapping underlying store (Item 18)
+- Try-with-resources for any closeable resources (Item 9)
+```
+
+---
+
+## Mode 2: Code Review
+
+When reviewing Java code, read `references/review-checklist.md` for the full checklist.
+Apply these categories systematically:
+
+### Review Process
+
+1. **Object creation** — Are static factories, builders, DI used appropriately? Any unnecessary object creation?
+2. **Class design** — Minimal accessibility? Immutability where possible? Composition over inheritance?
+3. **Generics** — No raw types? Proper wildcards? Typesafe?
+4. **Enums and annotations** — Enums instead of int constants? @Override present? Marker interfaces used correctly?
+5. **Lambdas and streams** — Used judiciously? Side-effect-free? Not overused?
+6. **Method design** — Parameters validated? Defensive copies? Overloading safe? Return types appropriate?
+7. **General programming** — Variables scoped minimally? For-each used? Standard library utilized?
+8. **Exceptions** — Used for exceptional conditions only? Appropriate types? Documented? Not ignored?
+9. **Concurrency** — Thread safety documented? Proper synchronization? Modern utilities used?
+10. **Serialization** — Java serialization avoided? If present, proxies used?
+
+### Review Output Format
+
+Structure your review as:
+
+```
+## Summary
+One paragraph: what the code does, which patterns it uses, overall assessment.
+
+## Strengths
+What the code does well, which Effective Java items are correctly applied.
+
+## Issues Found
+For each issue:
+- **What**: describe the problem
+- **Why it matters**: explain the bug, maintenance, or performance risk
+- **Item to apply**: which Effective Java item addresses this
+- **Suggested fix**: concrete code change
+
+## Recommendations
+Priority-ordered list of improvements, from most critical to nice-to-have.
+```
+
+### Common Anti-Patterns to Flag
+
+- **Telescoping constructors** — Multiple constructors with increasing parameters instead of Builder (Item 2)
+- **Mutable class that could be immutable** — Public setters on a class that doesn't need to change after construction (Item 17)
+- **Concrete class inheritance** — Extending a concrete class for code reuse instead of composition (Item 18)
+- **Raw types** — Using `List` instead of `List<String>` (Item 26)
+- **Overloading confusion** — Overloaded methods with same arity but different behavior depending on runtime type (Item 52)
+- **Returning null instead of empty collection** — `return null` instead of `Collections.emptyList()` (Item 54)
+- **Catching Exception/Throwable** — Over-broad catch blocks that swallow important errors (Item 77)
+- **Using `wait`/`notify`** — When `CountDownLatch`, `CyclicBarrier`, or `CompletableFuture` would be clearer (Item 81)
+- **Mutable Date/Calendar fields** — Exposing mutable `Date` or `Calendar` objects without defensive copies (Item 50)
+- **String concatenation in loops** — Using `+` in a loop instead of `StringBuilder` (Item 63)
+- **Using `float`/`double` for money** — Should be `BigDecimal`, `int`, or `long` (Item 60)
+- **Ignoring return value of `Optional`** — Calling `.get()` without `.isPresent()` check or using `orElse`/`orElseThrow` (Item 55)
+
+---
+
+## General Guidelines
+
+- Be practical, not dogmatic. Not every class needs a Builder; not every hierarchy needs interfaces.
+  Apply items where they provide clear benefit.
+- The three goals are **correctness** (bug-free), **clarity** (easy to read and understand),
+  and **performance** (efficient where it matters). Every recommendation should advance at least one.
+- Modern Java (9+) features like modules, `var`, records, sealed classes, and pattern matching
+  complement Effective Java items. Recommend them where appropriate.
+- When a simpler solution works, don't over-engineer. Bloch himself emphasizes minimizing complexity.
+- For deeper item details, read `references/items-catalog.md` before generating code.
+- For review checklists, read `references/review-checklist.md` before reviewing code.

package/effective-java/assets/example_asset.txt

@@ -0,0 +1 @@
+

package/effective-java/references/api_reference.md

@@ -0,0 +1 @@
+