Add design patterns support —> 123-java-design-patterns

[jabrena]

User Story: 123-java-design-patterns

As a Java developer using this cursor-rules-java project
I want to add a new 123-java-design-patterns skill for Java design patterns support
So that I can get consistent, practical guidance for selecting, implementing, and refactoring toward appropriate design patterns in Java projects without over-engineering the codebase.

Acceptance Criteria

Feature: Java design patterns skill

Background:
  Given the repository generates skills from XML sources under "skills-generator/src/main/resources"
  And generated content under "skills/" is not edited directly
  And the Java design guidance currently includes neighboring skills such as "121-java-object-oriented-design" and "122-java-type-design"

@acceptance-test
Scenario: Generate the Java design patterns skill from XML sources
  Given a new Java design patterns skill is defined in the skill generator sources
  When the skills-generator module is installed
  Then the generated skills include "123-java-design-patterns"
  And the skill explains when design patterns should and should not be applied
  And the skill provides practical Java examples for common creational, structural, and behavioral patterns
  And the skill emphasizes maintainability, simplicity, testability, and avoiding pattern overuse

@integration-test
Scenario: Register the Java design patterns skill in the skill catalog
  Given the Java design patterns skill XML source exists
  When the skill index and skill list are generated
  Then "123-java-design-patterns" appears in the generated skills inventory
  And the skill can be discovered with prompts such as "apply Java design patterns" or "refactor this code using an appropriate pattern"

@integration-test
Scenario: Align the new skill with existing Java design guidance
  Given the repository already contains object-oriented and type-design skills
  When the Java design patterns skill is authored
  Then it complements "121-java-object-oriented-design" and "122-java-type-design"
  And it avoids duplicating broad SOLID, type-design, and generic refactoring guidance that belongs in neighboring skills

@integration-test
Scenario: Keep generated artifacts reproducible
  Given the Java design patterns skill is generated from XML
  When "./mvnw clean verify -pl skills-generator" is executed
  Then the build succeeds
  And no generated skill content requires manual edits under "skills/"

@integration-test
Scenario: Validate generated skill quality
  Given the generated Java design patterns skill exists under "skills/"
  When "npx skill-check@latest skills --no-security-scan --format github" is executed
  Then the skill passes the formatter and structural checks
  And any behavioral scan findings are reviewed before promoting the change

Notes

• Implement changes in XML sources under skills-generator/src/main/resources/, including the relevant skill reference, skill index, and catalog wiring.
• Do not edit generated skills/ content directly; regenerate it through the Maven pipeline.
• Place the skill numerically between 122-java-type-design and 124-java-secure-coding as 123-java-design-patterns.
• Cover the most useful Java design pattern families: creational, structural, and behavioral patterns.
• Include guidance for deciding whether a pattern is justified, with explicit warnings against pattern-driven design when simpler code is enough.
• Keep examples compatible with the repository guidance for Java 25 and Maven-based workflows.

INVEST Validation

• Independent: The design patterns skill can be added as a new Java design skill without changing the behavior of existing OOP, type-design, or secure-coding skills.
• Negotiable: The exact set of patterns, examples, and anti-pattern warnings can be refined while preserving the intent of practical Java design-pattern guidance.
• Valuable: Java developers gain a focused skill for selecting and applying patterns thoughtfully, improving code structure while avoiding unnecessary complexity.
• Estimable: The work is bounded by creating and wiring one generated skill plus validation through the existing generator and skill-check workflows.
• Small: The scope should fit in one iteration because it follows the existing single-skill generation pattern.
• Testable: Completion can be verified by generated skill output, catalog discovery, Maven verification, and skill validation commands.

[jabrena]

Suggested design patterns to cover in 123-java-design-patterns:

Creational patterns

• Factory Method - for delegating object creation behind stable interfaces.
• Abstract Factory - for creating related families of objects without coupling clients to concrete classes.
• Builder - for readable construction of complex immutable objects, especially records and configuration objects.
• Singleton - mainly as a cautionary pattern; explain safer alternatives such as dependency injection and enum singletons when truly needed.
• Prototype - for cloning/copying object templates when construction is expensive or stateful.

Structural patterns

• Adapter - for integrating legacy APIs, third-party libraries, or incompatible interfaces.
• Facade - for simplifying complex subsystems behind a small, intention-revealing API.
• Decorator - for adding behavior without inheritance, useful for streams, clients, validators, and middleware-style flows.
• Composite - for tree-like structures where single items and groups share a common abstraction.
• Proxy - for lazy loading, access control, caching, remote calls, or instrumentation boundaries.
• Bridge - for separating abstraction from implementation when both vary independently.

Behavioral patterns

• Strategy - for replacing conditional logic with interchangeable algorithms or policies.
• Template Method - for defining a stable workflow with customizable steps; include cautions about inheritance coupling.
• Command - for encapsulating actions, undo/redo, queues, retries, and task execution.
• Observer / Publish-Subscribe - for event-driven collaboration while managing coupling and lifecycle risks.
• Chain of Responsibility - for request processing pipelines, filters, validators, and handlers.
• State - for replacing complex state conditionals with explicit state objects.
• Iterator - for traversal abstractions, including modern Java collection usage.
• Mediator - for coordinating complex object interactions without every component knowing every other component.

Enterprise and Java-specific patterns

• Repository - for persistence boundaries and domain-focused data access.
• Unit of Work - for transaction-scoped change coordination where applicable.
• Specification - for composable business rules and query criteria.
• DTO / Mapper - for API and persistence boundaries, including when not to overuse DTOs.
• Dependency Injection - as a practical architectural pattern, especially in Spring, Quarkus, and Micronaut contexts.
• Ports and Adapters / Hexagonal Architecture - for isolating domain logic from frameworks, databases, and external services.
• Service Layer - for application use cases and transaction boundaries.

Anti-patterns and decision guidance

• Pattern overuse - prefer simple code until variation or duplication justifies a pattern.
• God Object / God Service - identify when a pattern is being used to hide poor responsibility boundaries.
• Singleton abuse - highlight hidden global state, test pain, and concurrency issues.
• Anemic Domain Model - explain when behavior should move closer to domain types.
• Factory explosion - avoid unnecessary factories where constructors or static factory methods are clearer.

A good shape for the skill could be: problem signal -> pattern fit -> Java 25 example -> testability impact -> trade-offs -> when not to use it.

[jabrena]

Additional pattern families worth covering beyond classic Java design patterns:

REST API patterns

• Resource-oriented API - model endpoints around nouns/resources, not internal actions.
• Controller-Service-Repository - keep HTTP concerns, use-case logic, and persistence concerns separated.
• DTO / Request / Response models - isolate public API contracts from domain and persistence models.
• API versioning - URI, header, or media-type versioning for controlled contract evolution.
• Pagination, filtering, and sorting - consistent collection access patterns for large result sets.
• Idempotency key - make retries safe for create/payment/order-style operations.
• Optimistic concurrency with ETag / If-Match - prevent lost updates in RESTful workflows.
• Problem Details for HTTP APIs - standardize error responses with machine-readable details.
• HATEOAS / hypermedia links - useful when clients benefit from discoverable state transitions.
• Bulk endpoint - batch related operations while defining partial-success behavior clearly.
• Backend for Frontend (BFF) - tailor APIs for specific clients without polluting core services.
• API gateway - centralize routing, auth, rate limits, and cross-cutting edge concerns.
• Rate limiting / throttling - protect services and express fair-use policies.
• Circuit breaker / timeout / retry - handle downstream instability without cascading failures.

Kafka and event-driven patterns

• Event notification - publish that something happened, with consumers fetching details if needed.
• Event-carried state transfer - publish enough state for consumers to update local views.
• Command message - express an intent for one consumer or service to perform work.
• Competing consumers - scale processing with multiple consumers in the same consumer group.
• Consumer group per use case - allow independent services/use cases to process the same topic.
• Partitioning by key - preserve ordering for an aggregate, customer, account, or other business key.
• Idempotent consumer - make repeated message delivery safe.
• Transactional outbox - atomically persist domain changes and outgoing events.
• Change Data Capture (CDC) - publish database changes to Kafka without coupling application code to event emission.
• Saga / process manager - coordinate long-running workflows across services with compensating actions.
• Retry topic - move failed records through controlled retry delays.
• Dead Letter Topic (DLT) - isolate poison messages for later inspection and replay.
• Schema evolution - manage Avro/JSON Schema/Protobuf compatibility over time.
• Topic per event type vs topic per aggregate - decide topic boundaries intentionally.
• CQRS read model projection - consume events to build optimized query views.
• Event sourcing - store state changes as an append-only event stream when auditability and replay are core requirements.

Database and persistence patterns

• Repository - provide domain-oriented collection access without leaking storage details.
• Unit of Work - coordinate changes within a transaction boundary.
• Data Mapper - separate domain objects from persistence mapping concerns.
• Active Record - acceptable in simpler CRUD models, but risky for rich domains.
• Specification - compose query criteria and business rules in reusable objects.
• DAO - isolate low-level data access when a full repository abstraction is not needed.
• Aggregate boundary - define consistency and transaction boundaries around domain aggregates.
• Optimistic locking - prevent lost updates with version columns or equivalent mechanisms.
• Pessimistic locking - reserve rows/resources when concurrent modification must be blocked.
• Database migration pattern - use versioned migrations with repeatable, reviewable schema changes.
• Read replica - separate read-heavy traffic from primary write workloads.
• CQRS - separate command/write models from query/read models when read and write needs diverge.
• Materialized view - precompute expensive query results for read performance.
• Audit log - track who changed what and when, especially for regulated domains.
• Soft delete - retain records while hiding them from active workflows; include retention and uniqueness caveats.
• Multi-tenancy patterns - separate database, separate schema, or shared schema with tenant discriminator.
• Sharding / partitioning - split data by key or time when scale requires it.
• Connection pool - manage database connections safely and observably.
• N+1 query avoidance - design fetch strategies and query boundaries deliberately.

Cross-cutting integration patterns

• Anti-corruption layer - protect the domain model from external systems and legacy APIs.
• Strangler fig - incrementally replace legacy behavior behind stable interfaces.
• Bulkhead - isolate resources so one failing dependency does not exhaust the whole service.
• Timeout, retry, and backoff - standardize resilience behavior for remote calls and message processing.
• Correlation ID / trace context propagation - connect logs, metrics, traces, HTTP requests, and Kafka messages.
• Inbox pattern - persist consumed messages to support idempotency and replay safety.
• Outbox + inbox - combine reliable publishing and reliable consuming across service boundaries.

For the skill, these should probably be presented as separate sections from classic GoF patterns: REST API patterns, event-driven/Kafka patterns, persistence/database patterns, and cross-cutting resilience/integration patterns.