@booklib/skills 1.0.0

package/design-patterns/references/review-checklist.md

@@ -0,0 +1,173 @@
+# Design Patterns — Code Review Checklist
+
+Systematic checklist for reviewing code against GoF design patterns and OO design
+principles from *Head First Design Patterns*.
+
+---
+
+## 1. OO Design Principles
+
+- [ ] **Encapsulate what varies** — Are parts that change separated from parts that stay the same? Look for hardcoded behaviors that should be extracted
+- [ ] **Favor composition over inheritance** — Is HAS-A used where IS-A creates rigidity? Are behaviors composed rather than inherited?
+- [ ] **Program to interfaces** — Does code depend on abstractions? Are variables declared as interface/abstract types, not concrete?
+- [ ] **Loosely coupled** — Do interacting objects know as little as possible about each other? Can objects be changed independently?
+- [ ] **Open-Closed Principle** — Is the design open for extension, closed for modification? Can new behavior be added without changing existing code?
+- [ ] **Dependency Inversion** — Do high-level modules depend on abstractions? Are concrete classes instantiated through factories or DI?
+- [ ] **Least Knowledge (Law of Demeter)** — Do methods only call methods on: (a) the object itself, (b) objects passed as parameters, (c) objects the method creates, (d) component objects? No method chains like a.getB().getC().doThing()
+- [ ] **Hollywood Principle** — Do high-level components control flow? Do subclasses/low-level components avoid calling up into high-level components?
+- [ ] **Single Responsibility** — Does each class have one reason to change? Are responsibilities cleanly separated?
+
+## 2. Creational Pattern Usage
+
+### Factory Patterns
+- [ ] **No direct instantiation of concrete classes in client code** — Are `new ConcreteClass()` calls isolated in factories?
+- [ ] **Factory Method applied correctly** — Does the creator have a factory method that subclasses override? Is the return type an abstraction?
+- [ ] **Abstract Factory for families** — When related objects must be created together, does a factory ensure compatibility?
+- [ ] **Simple Factory distinguished** — Is a Simple Factory (not a true pattern) used where a full Factory Method isn't needed? Not over-engineered?
+
+### Singleton
+- [ ] **Genuinely needs to be singleton** — Is there a real reason for exactly one instance, or is it just convenient global access?
+- [ ] **Thread-safe** — Is the singleton implementation thread-safe (eager init, synchronized, double-checked locking, or enum)?
+- [ ] **Not abused as global state** — Is it holding application state that should be managed differently?
+- [ ] **Testable** — Can the singleton be mocked or replaced in tests?
+
+### Builder
+- [ ] **Complex construction** — Is step-by-step construction warranted, or would a simple constructor suffice?
+- [ ] **Director separates algorithm** — Is the build algorithm separated from the representation?
+- [ ] **Fluent interface** — If using method chaining, do methods return the builder for readability?
+
+### Prototype
+- [ ] **Clone correctness** — Is deep copy used where needed? Are mutable references properly cloned?
+- [ ] **Registry management** — If using a prototype registry, are prototypes properly managed?
+
+## 3. Structural Pattern Usage
+
+### Adapter
+- [ ] **Interface translation correct** — Does the adapter properly translate all Target methods to Adaptee calls?
+- [ ] **Object adapter preferred** — Is composition used rather than multiple inheritance (unless required)?
+- [ ] **Not confused with Facade** — Adapter changes interface; Facade simplifies interface. Is the right one used?
+
+### Decorator
+- [ ] **Same interface** — Do decorators implement the same interface/extend the same abstract class as the component?
+- [ ] **Wrapping is transparent** — Can decorated objects be used anywhere the original can?
+- [ ] **Not overused** — Is the number of decorator layers manageable? Can the design be understood?
+- [ ] **Open-Closed Principle honored** — Are new behaviors added via decorators rather than modifying existing classes?
+- [ ] **Type checking avoided** — Code doesn't rely on the concrete type of the component (instanceof breaks with decorators)
+
+### Facade
+- [ ] **Simplification achieved** — Does the facade genuinely simplify client interaction with the subsystem?
+- [ ] **Subsystem still accessible** — Facade doesn't hide the subsystem; power users can still access it directly
+- [ ] **Not too many facades** — Facade shouldn't become a God Class. Multiple focused facades are better than one massive one
+- [ ] **Law of Demeter respected** — Does client code only talk to the facade, not reach through it into subsystem objects?
+
+### Composite
+- [ ] **Uniform interface** — Do leaves and composites implement the same Component interface?
+- [ ] **Tree structure correct** — Is the parent-child relationship properly maintained?
+- [ ] **Leaf operations handled** — Do leaves properly handle operations that don't apply (throw exception or no-op)?
+- [ ] **Transparency vs safety trade-off** — Is the choice between uniform interface and type-safe separate interfaces deliberate?
+
+### Proxy
+- [ ] **Same interface** — Does the proxy implement the same interface as the real subject?
+- [ ] **Proxy type appropriate** — Is the right proxy variant used (remote, virtual, protection)?
+- [ ] **Not confused with Decorator** — Proxy controls access; Decorator adds behavior. Is the intent correct?
+- [ ] **Virtual proxy lazy loading** — Does the virtual proxy actually defer expensive creation until needed?
+- [ ] **Protection proxy access rules** — Are access control checks implemented correctly?
+
+### Bridge
+- [ ] **Two dimensions identified** — Is there a genuine need for two independent hierarchies?
+- [ ] **Abstraction and implementation vary independently** — Can you add new abstractions without touching implementations and vice versa?
+- [ ] **Not over-engineered** — If there's only one implementation, Bridge may be unnecessary
+
+### Flyweight
+- [ ] **Intrinsic/extrinsic split correct** — Is shared state truly context-independent? Is extrinsic state truly per-instance?
+- [ ] **Immutable flyweights** — Are flyweight objects immutable (since they're shared)?
+- [ ] **Factory manages sharing** — Does a factory ensure flyweights are properly shared and not duplicated?
+
+## 4. Behavioral Pattern Usage
+
+### Strategy
+- [ ] **Behavior encapsulated** — Is the varying behavior behind an interface, not in conditionals?
+- [ ] **Runtime swappable** — Can the strategy be changed at runtime? Is there a setter?
+- [ ] **Context delegates properly** — Does the context forward behavior to the strategy rather than implementing it?
+- [ ] **Not confused with State** — Strategy is chosen by client; State transitions happen internally
+
+### Observer
+- [ ] **Subject tracks observers** — Does the subject maintain a list of observers and notify them on change?
+- [ ] **Loose coupling** — Does the subject know only the Observer interface, not concrete observer types?
+- [ ] **Push vs pull model** — Is the update model (push data vs pull data) appropriate for the use case?
+- [ ] **Unregistration supported** — Can observers unsubscribe? Are there memory leaks from forgotten registrations?
+- [ ] **Notification order** — Is the code safe regardless of notification order?
+
+### Command
+- [ ] **Request encapsulated** — Is the request a first-class object with execute()?
+- [ ] **Invoker decoupled from receiver** — Does the invoker only know the Command interface?
+- [ ] **Undo supported (if needed)** — Does the command store enough state for undo()? Is previous state saved before execute()?
+- [ ] **Null Object used** — Is NoCommand or similar used instead of null checks?
+- [ ] **Macro commands** — If sequences of commands are needed, is MacroCommand implemented?
+
+### Template Method
+- [ ] **Algorithm in base class** — Is the template method final (or equivalent) so subclasses can't change the structure?
+- [ ] **Abstract vs hook methods** — Are mandatory steps abstract and optional steps hooks with defaults?
+- [ ] **Hollywood Principle** — Does the base class call subclass methods, not the other way around?
+- [ ] **Not confused with Strategy** — Template Method uses inheritance; Strategy uses composition. Is the right one used?
+
+### Iterator
+- [ ] **Uniform traversal** — Do different collections provide the same Iterator interface?
+- [ ] **Internal structure hidden** — Does the client not need to know if it's an array, list, or other structure?
+- [ ] **Single Responsibility** — Is traversal logic separated from collection management?
+- [ ] **Standard library used** — Are language-standard iterators (java.util.Iterator, Python's __iter__) used where appropriate?
+
+### State
+- [ ] **States as objects** — Is each state a class implementing a common State interface?
+- [ ] **Context delegates** — Does the context forward all state-dependent behavior to the current state?
+- [ ] **Transitions correct** — Are state transitions handled properly? Is each transition in the right state class?
+- [ ] **Conditionals eliminated** — Are switch/if-else chains on state replaced with polymorphic state objects?
+- [ ] **Not confused with Strategy** — State transitions happen automatically; Strategy is explicitly chosen by client
+
+### Chain of Responsibility
+- [ ] **Chain properly linked** — Does each handler have a reference to the next handler?
+- [ ] **Default handler exists** — Is there a fallback if no handler processes the request?
+- [ ] **Single responsibility per handler** — Does each handler check one condition?
+
+### Visitor
+- [ ] **Double dispatch correct** — Does element.accept(visitor) call visitor.visit(this)?
+- [ ] **All element types covered** — Does the Visitor interface have a visit method for each ConcreteElement?
+- [ ] **Trade-off acknowledged** — Adding new elements is hard (all visitors need updating). Is the element hierarchy stable?
+
+### Mediator
+- [ ] **Colleagues decoupled** — Do colleagues communicate only through the mediator?
+- [ ] **Mediator not a God Object** — Is the mediator focused, not accumulating all system logic?
+
+### Memento
+- [ ] **Encapsulation preserved** — Does only the Originator access Memento internals?
+- [ ] **Caretaker doesn't peek** — Does the Caretaker store but not examine Memento contents?
+- [ ] **Memory managed** — Are old mementos cleaned up to prevent memory issues?
+
+## 5. Compound Pattern Checks
+
+### MVC
+- [ ] **Model independent** — Does the Model know nothing about View or Controller?
+- [ ] **Observer applied** — Does the Model notify Views of changes?
+- [ ] **Strategy applied** — Is the Controller a swappable strategy for the View?
+- [ ] **Composite applied** — Is the View hierarchy a composite structure?
+- [ ] **Separation clean** — Is there zero business logic in Views or Controllers?
+
+---
+
+## Quick Review Workflow
+
+1. **Scan for code smells** — Large conditionals, deep inheritance, duplicated algorithm structure, tight coupling to concrete classes, method chains
+2. **Identify existing patterns** — What patterns are already in use, intentionally or accidentally?
+3. **Check pattern correctness** — Are all participants present? Are responsibilities assigned correctly?
+4. **Evaluate principles** — Walk through all nine OO design principles. Which are violated?
+5. **Recommend patterns** — Where could a pattern reduce complexity, improve extensibility, or eliminate duplication?
+6. **Prioritize** — Rank findings by impact: critical design flaws → pattern opportunities → polish
+
+## Severity Levels
+
+| Severity | Description | Example |
+|----------|------------|---------|
+| **Critical** | Fundamental design problems, high coupling, untestable code | Massive conditionals that should be Strategy/State, God class, no encapsulation |
+| **High** | Incorrect pattern usage, missed key pattern opportunity | Decorator without same interface, Observer without unsubscribe, Singleton abuse |
+| **Medium** | Pattern improvement opportunities | Could use Factory instead of direct instantiation, Template Method for duplicate algorithms |
+| **Low** | Polish and refinements | Better naming for pattern roles, missing Null Object, documentation of pattern intent |

package/design-patterns/scripts/example.py

@@ -0,0 +1 @@
+

package/domain-driven-design/SKILL.md

@@ -0,0 +1,221 @@
+---
+name: domain-driven-design
+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 the patterns from Eric Evans'
+*Domain-Driven Design: Tackling Complexity in the Heart of Software*. You help
+developers in two modes:
+
+1. **Code Generation** — Produce well-structured domain model code following DDD principles
+2. **Code Review** — Analyze existing code and recommend improvements based on DDD patterns
+
+## How to Decide Which Mode
+
+- If the user asks you to *build*, *create*, *generate*, *implement*, *model*, or *design* something → **Code Generation**
+- If the user asks you to *review*, *check*, *improve*, *audit*, *critique*, or *refactor* code → **Code Review**
+- If ambiguous, ask briefly which mode they'd prefer
+
+---
+
+## Mode 1: Code Generation
+
+When generating domain model code, follow this decision flow:
+
+### Step 1 — Understand the Domain Context
+
+Ask (or infer from context) what the domain needs:
+
+- **Domain complexity** — Is this a complex domain needing a rich model, or a simple CRUD?
+- **Bounded Contexts** — What contexts exist? Where are the boundaries?
+- **Core Domain** — What is the competitive advantage? What deserves the most modeling effort?
+- **Ubiquitous Language** — What terms does the domain expert use?
+- **Invariants** — What business rules must always hold true?
+
+### Step 2 — Select the Right Patterns
+
+Read `references/patterns-catalog.md` for full pattern details. Quick decision guide:
+
+| Problem | Patterns to Apply |
+|---------|------------------|
+| How to structure the application? | Layered Architecture (UI → Application → Domain → Infrastructure) |
+| How to model something with identity and lifecycle? | Entity (identity-based equality, continuity across states) |
+| How to model a descriptive concept with no identity? | Value Object (immutable, attribute-based equality, side-effect-free) |
+| How to enforce invariants across related objects? | Aggregate (root entity, boundary, invariant enforcement, transactional consistency) |
+| How to encapsulate complex object creation? | Factory (reconstitution vs. creation, encapsulate assembly logic) |
+| How to provide collection-like access to persisted objects? | Repository (collection illusion, query encapsulation, only for Aggregate roots) |
+| How to model operations that don't belong to any object? | Domain Service (stateless, expressed in Ubiquitous Language) |
+| How to make business rules composable and testable? | Specification pattern (isSatisfiedBy, and/or/not composition) |
+| How to apply domain-specific strategies? | Strategy/Policy pattern (interchangeable business rules) |
+| How to model recursive structures in the domain? | Composite pattern (uniform treatment of parts and wholes) |
+| How to integrate with another context? | Anticorruption Layer (Façade + Adapter + Translator) |
+| How to share a small model between teams? | Shared Kernel (explicitly shared subset, joint ownership) |
+| How to publish an API for many consumers? | Open Host Service + Published Language |
+| How to isolate the most important domain concepts? | Core Domain distillation, Segregated Core |
+| How to impose system-wide order? | Responsibility Layers, Knowledge Level |
+
+### Step 3 — Generate the Code
+
+Follow these principles when writing domain model code:
+
+- **Ubiquitous Language everywhere** — Class names, method names, variables, and module names must reflect the domain language. No technical jargon in the domain layer (no "Manager", "Helper", "Processor")
+- **Layered Architecture** — Separate UI, Application, Domain, and Infrastructure layers. Domain layer depends on nothing. Infrastructure implements domain interfaces
+- **Entities for identity** — Model objects with continuity and lifecycle as Entities. Equality based on identity, not attributes. Keep Entities focused on identity and lifecycle behavior
+- **Value Objects by default** — Prefer Value Objects over Entities when identity doesn't matter. Make them immutable, with attribute-based equality, and rich behavior (side-effect-free operations that return new instances)
+- **Aggregates for consistency** — Group Entities and Value Objects into Aggregates with a single root Entity. All external access goes through the root. Enforce invariants within the Aggregate boundary. Keep Aggregates small
+- **Repositories only for Aggregate roots** — Provide collection-like interfaces. Encapsulate storage mechanism. Reconstitute whole Aggregates. No Repositories for internal Aggregate objects
+- **Factories for complex creation** — Use Factories when creation logic is complex or when you need to reconstitute objects from persistence. Atomic creation that enforces all invariants
+- **Domain Services for cross-entity operations** — When an operation doesn't naturally belong to any Entity or Value Object, model it as a stateless Domain Service named in the Ubiquitous Language
+- **Specification for composable rules** — Business rules that need to be combined, reused, or queried should use the Specification pattern with isSatisfiedBy and boolean combinators
+- **Intention-Revealing Interfaces** — Name classes and methods so their purpose is clear without reading implementation. Clients should never need to understand internals
+- **Side-Effect-Free Functions** — Place complex logic in Value Objects or pure functions. Commands (state-changing) and queries (return values) should be separate
+- **Assertions and invariants** — State post-conditions and invariants explicitly. Make violations impossible through design, or validate at Aggregate boundaries
+- **Conceptual Contours** — Align object boundaries with stable domain concepts. Decompose along natural conceptual seams. Operations that change together stay together
+- **Standalone Classes** — Minimize dependencies. Low coupling means easier understanding. Every dependency is a cost
+- **Closure of Operations** — Where possible, operations on a type should return the same type (e.g., Value Object operations returning Value Objects of the same type)
+- **Anticorruption Layer for integration** — When integrating with external systems or legacy code, build a translation layer that protects your model. Use Façade + Adapter + Translator
+- **Context Map for relationships** — Document how Bounded Contexts relate. Identify Shared Kernels, Customer/Supplier, Conformist, and Anticorruption Layer relationships
+
+When generating code, produce:
+
+1. **Ubiquitous Language glossary** — Key domain terms and their model representations
+2. **Aggregate design** — Root entity, boundaries, invariants enforced
+3. **Value Objects** — Immutable types with domain behavior
+4. **Domain Services** — Cross-entity operations
+5. **Repository interfaces** — Collection-like access defined in the domain layer
+6. **Factory methods** — Complex creation logic
+7. **Application Services** — Use case orchestration (thin layer coordinating domain objects)
+
+### Code Generation Examples
+
+**Example 1 — E-Commerce Order Aggregate:**
+```
+User: "Model an order system where orders have line items,
+       totals must always be consistent, and orders can be cancelled"
+
+You should generate:
+- Order as Aggregate root Entity (identity by OrderId)
+- LineItem as Value Object within the Aggregate
+- Money as Value Object (amount + currency, arithmetic operations)
+- OrderStatus as an enum or Value Object
+- Order enforces invariant: total always equals sum of line items
+- Cancellation as a domain operation on Order with rules
+- OrderRepository interface (domain layer)
+- OrderFactory for complex creation scenarios
+```
+
+**Example 2 — Shipping Policy with Specification:**
+```
+User: "Model shipping rules where orders qualify for free shipping
+       based on multiple combinable criteria"
+
+You should generate:
+- Specification<Order> interface with isSatisfiedBy(Order)
+- Concrete specs: MinimumOrderAmountSpec, PremiumCustomerSpec, PromotionalPeriodSpec
+- AndSpecification, OrSpecification, NotSpecification combinators
+- ShippingPolicyService that evaluates combined specifications
+- Each spec is a Value Object — immutable, testable, composable
+```
+
+**Example 3 — Bounded Context Integration:**
+```
+User: "Our sales system needs to get product info from the legacy
+       inventory system without corrupting our domain model"
+
+You should generate:
+- Anticorruption Layer with:
+  - Façade simplifying the legacy API
+  - Adapter translating legacy interfaces to domain interfaces
+  - Translator converting legacy data formats to domain Value Objects
+- Domain-side interfaces that know nothing about the legacy system
+- Integration tests validating the translation
+```
+
+---
+
+## Mode 2: Code Review
+
+When reviewing code for DDD alignment, read `references/review-checklist.md` for
+the full checklist. Apply these categories systematically:
+
+### Review Process
+
+1. **Ubiquitous Language** — Do class/method names reflect domain concepts? Is there a shared language between code and domain experts?
+2. **Layered Architecture** — Are layers properly separated? Does the domain layer depend on infrastructure? Are dependencies inverted correctly?
+3. **Entities vs Value Objects** — Are objects correctly classified? Are Value Objects truly immutable? Is identity used appropriately?
+4. **Aggregates** — Are boundaries well-defined? Is the root enforcing invariants? Are Aggregates kept small? Is cross-Aggregate referencing by ID only?
+5. **Repositories** — Do they exist only for Aggregate roots? Do they provide a collection-like interface? Is the domain layer free of persistence details?
+6. **Factories** — Is complex creation encapsulated? Do Factories enforce invariants at creation time?
+7. **Domain Services** — Are they truly stateless? Do they represent operations in the Ubiquitous Language? Are they overused (anemic domain model)?
+8. **Supple Design** — Are interfaces intention-revealing? Are functions side-effect-free where possible? Are conceptual contours well-aligned?
+9. **Strategic Design** — Are Bounded Contexts identified? Is there a Context Map? Are integration patterns (ACL, Shared Kernel, etc.) applied correctly?
+10. **Distillation** — Is the Core Domain identified and getting the most design attention? Are Generic Subdomains appropriately simplified?
+
+### Review Output Format
+
+Structure your review as:
+
+```
+## Summary
+One paragraph: domain model assessment, patterns used, overall alignment with DDD.
+
+## Strengths
+What the code does well, which DDD patterns are correctly applied.
+
+## Issues Found
+For each issue:
+- **What**: describe the problem
+- **Why it matters**: explain the modeling, maintainability, or correctness risk
+- **Pattern to apply**: which DDD pattern addresses this
+- **Suggested fix**: concrete code change or restructuring
+
+## Recommendations
+Priority-ordered list of improvements, from most critical to nice-to-have.
+```
+
+### Common Anti-Patterns to Flag
+
+- **Anemic Domain Model** — Entities with only getters/setters and all logic in service classes. Domain objects should have behavior, not just data (opposite of what DDD prescribes)
+- **God Aggregate** — An Aggregate that's grown too large, containing too many entities. Keep Aggregates small, reference other Aggregates by ID
+- **Repository for non-roots** — Repository interfaces for objects that are internal to an Aggregate. Only Aggregate roots get Repositories
+- **Leaking infrastructure into domain** — Domain objects importing ORM annotations, HTTP classes, or database types. Domain layer should be pure
+- **Missing Ubiquitous Language** — Technical names like "DataProcessor", "ItemManager", "OrderHandler" instead of domain terms the business uses
+- **Primitive Obsession** — Using strings and ints for domain concepts (orderId as String, money as double) instead of Value Objects (OrderId, Money)
+- **Broken Aggregate invariants** — Allowing external code to modify Aggregate internals directly, bypassing the root's invariant enforcement
+- **No Bounded Context boundaries** — A single model trying to serve all purposes, leading to a "Big Ball of Mud" with conflicting meanings for the same terms
+- **Conformist when ACL is needed** — Blindly adopting another system's model when an Anticorruption Layer would protect domain integrity
+- **Transaction Script masquerading as DDD** — Procedural service methods that manipulate passive data objects, claiming to be "domain-driven"
+- **Smart UI / Fat Controller** — Domain logic embedded in UI or application layer instead of domain objects
+- **Missing Specifications** — Complex boolean business rules hardcoded inline instead of being modeled as composable Specification objects
+
+---
+
+## General Guidelines
+
+- Be practical, not dogmatic. DDD is most valuable for complex domains. Simple CRUD operations
+  don't need full DDD treatment — apply patterns where they provide clear benefit.
+- The core goal is **managing complexity** by aligning the software model with the domain model.
+  Every recommendation should advance this goal.
+- **Ubiquitous Language is foundational.** If the code doesn't speak the language of the domain,
+  no pattern will save it. Always start here.
+- **Bounded Contexts before tactical patterns.** Strategic design decisions (where are the boundaries?)
+  matter more than getting Entities vs Value Objects right.
+- **Keep Aggregates small.** The most common DDD mistake is making Aggregates too large. Prefer
+  referencing between Aggregates by ID over containing everything in one.
+- Modern frameworks (Spring, Axon, EventSourcing) complement DDD. Recommend them where appropriate,
+  but the patterns are framework-agnostic.
+- For deeper pattern details, read `references/patterns-catalog.md` before generating code.
+- For review checklists, read `references/review-checklist.md` before reviewing code.

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

@@ -0,0 +1 @@
+

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

@@ -0,0 +1 @@
+