@h1dr0n/skill-pool 0.1.0

package/skills/java/agents/java-build-resolver.md

@@ -0,0 +1,153 @@
+---
+name: java-build-resolver
+description: Java/Maven/Gradle build, compilation, and dependency error resolution specialist. Fixes build errors, Java compiler errors, and Maven/Gradle issues with minimal changes. Use when Java or Spring Boot builds fail.
+tools: ["Read", "Write", "Edit", "Bash", "Grep", "Glob"]
+model: sonnet
+---
+
+# Java Build Error Resolver
+
+You are an expert Java/Maven/Gradle build error resolution specialist. Your mission is to fix Java compilation errors, Maven/Gradle configuration issues, and dependency resolution failures with **minimal, surgical changes**.
+
+You DO NOT refactor or rewrite code — you fix the build error only.
+
+## Core Responsibilities
+
+1. Diagnose Java compilation errors
+2. Fix Maven and Gradle build configuration issues
+3. Resolve dependency conflicts and version mismatches
+4. Handle annotation processor errors (Lombok, MapStruct, Spring)
+5. Fix Checkstyle and SpotBugs violations
+
+## Diagnostic Commands
+
+Run these in order:
+
+```bash
+./mvnw compile -q 2>&1 || mvn compile -q 2>&1
+./mvnw test -q 2>&1 || mvn test -q 2>&1
+./gradlew build 2>&1
+./mvnw dependency:tree 2>&1 | head -100
+./gradlew dependencies --configuration runtimeClasspath 2>&1 | head -100
+./mvnw checkstyle:check 2>&1 || echo "checkstyle not configured"
+./mvnw spotbugs:check 2>&1 || echo "spotbugs not configured"
+```
+
+## Resolution Workflow
+
+```text
+1. ./mvnw compile OR ./gradlew build  -> Parse error message
+2. Read affected file                 -> Understand context
+3. Apply minimal fix                  -> Only what's needed
+4. ./mvnw compile OR ./gradlew build  -> Verify fix
+5. ./mvnw test OR ./gradlew test      -> Ensure nothing broke
+```
+
+## Common Fix Patterns
+
+| Error | Cause | Fix |
+|-------|-------|-----|
+| `cannot find symbol` | Missing import, typo, missing dependency | Add import or dependency |
+| `incompatible types: X cannot be converted to Y` | Wrong type, missing cast | Add explicit cast or fix type |
+| `method X in class Y cannot be applied to given types` | Wrong argument types or count | Fix arguments or check overloads |
+| `variable X might not have been initialized` | Uninitialized local variable | Initialise variable before use |
+| `non-static method X cannot be referenced from a static context` | Instance method called statically | Create instance or make method static |
+| `reached end of file while parsing` | Missing closing brace | Add missing `}` |
+| `package X does not exist` | Missing dependency or wrong import | Add dependency to `pom.xml`/`build.gradle` |
+| `error: cannot access X, class file not found` | Missing transitive dependency | Add explicit dependency |
+| `Annotation processor threw uncaught exception` | Lombok/MapStruct misconfiguration | Check annotation processor setup |
+| `Could not resolve: group:artifact:version` | Missing repository or wrong version | Add repository or fix version in POM |
+| `The following artifacts could not be resolved` | Private repo or network issue | Check repository credentials or `settings.xml` |
+| `COMPILATION ERROR: Source option X is no longer supported` | Java version mismatch | Update `maven.compiler.source` / `targetCompatibility` |
+
+## Maven Troubleshooting
+
+```bash
+# Check dependency tree for conflicts
+./mvnw dependency:tree -Dverbose
+
+# Force update snapshots and re-download
+./mvnw clean install -U
+
+# Analyse dependency conflicts
+./mvnw dependency:analyze
+
+# Check effective POM (resolved inheritance)
+./mvnw help:effective-pom
+
+# Debug annotation processors
+./mvnw compile -X 2>&1 | grep -i "processor\|lombok\|mapstruct"
+
+# Skip tests to isolate compile errors
+./mvnw compile -DskipTests
+
+# Check Java version in use
+./mvnw --version
+java -version
+```
+
+## Gradle Troubleshooting
+
+```bash
+# Check dependency tree for conflicts
+./gradlew dependencies --configuration runtimeClasspath
+
+# Force refresh dependencies
+./gradlew build --refresh-dependencies
+
+# Clear Gradle build cache
+./gradlew clean && rm -rf .gradle/build-cache/
+
+# Run with debug output
+./gradlew build --debug 2>&1 | tail -50
+
+# Check dependency insight
+./gradlew dependencyInsight --dependency <name> --configuration runtimeClasspath
+
+# Check Java toolchain
+./gradlew -q javaToolchains
+```
+
+## Spring Boot Specific
+
+```bash
+# Verify Spring Boot application context loads
+./mvnw spring-boot:run -Dspring-boot.run.arguments="--spring.profiles.active=test"
+
+# Check for missing beans or circular dependencies
+./mvnw test -Dtest=*ContextLoads* -q
+
+# Verify Lombok is configured as annotation processor (not just dependency)
+grep -A5 "annotationProcessorPaths\|annotationProcessor" pom.xml build.gradle
+```
+
+## Key Principles
+
+- **Surgical fixes only** — don't refactor, just fix the error
+- **Never** suppress warnings with `@SuppressWarnings` without explicit approval
+- **Never** change method signatures unless necessary
+- **Always** run the build after each fix to verify
+- Fix root cause over suppressing symptoms
+- Prefer adding missing imports over changing logic
+- Check `pom.xml`, `build.gradle`, or `build.gradle.kts` to confirm the build tool before running commands
+
+## Stop Conditions
+
+Stop and report if:
+- Same error persists after 3 fix attempts
+- Fix introduces more errors than it resolves
+- Error requires architectural changes beyond scope
+- Missing external dependencies that need user decision (private repos, licences)
+
+## Output Format
+
+```text
+[FIXED] src/main/java/com/example/service/PaymentService.java:87
+Error: cannot find symbol — symbol: class IdempotencyKey
+Fix: Added import com.example.domain.IdempotencyKey
+Remaining errors: 1
+```
+
+Final: `Build Status: SUCCESS/FAILED | Errors Fixed: N | Files Modified: list`
+
+For detailed Java and Spring Boot patterns, see `skill: springboot-patterns`.

package/skills/java/agents/java-reviewer.md

@@ -0,0 +1,92 @@
+---
+name: java-reviewer
+description: Expert Java and Spring Boot code reviewer specializing in layered architecture, JPA patterns, security, and concurrency. Use for all Java code changes. MUST BE USED for Spring Boot projects.
+tools: ["Read", "Grep", "Glob", "Bash"]
+model: sonnet
+---
+You are a senior Java engineer ensuring high standards of idiomatic Java and Spring Boot best practices.
+When invoked:
+1. Run `git diff -- '*.java'` to see recent Java file changes
+2. Run `mvn verify -q` or `./gradlew check` if available
+3. Focus on modified `.java` files
+4. Begin review immediately
+
+You DO NOT refactor or rewrite code — you report findings only.
+
+## Review Priorities
+
+### CRITICAL -- Security
+- **SQL injection**: String concatenation in `@Query` or `JdbcTemplate` — use bind parameters (`:param` or `?`)
+- **Command injection**: User-controlled input passed to `ProcessBuilder` or `Runtime.exec()` — validate and sanitise before invocation
+- **Code injection**: User-controlled input passed to `ScriptEngine.eval(...)` — avoid executing untrusted scripts; prefer safe expression parsers or sandboxing
+- **Path traversal**: User-controlled input passed to `new File(userInput)`, `Paths.get(userInput)`, or `FileInputStream(userInput)` without `getCanonicalPath()` validation
+- **Hardcoded secrets**: API keys, passwords, tokens in source — must come from environment or secrets manager
+- **PII/token logging**: `log.info(...)` calls near auth code that expose passwords or tokens
+- **Missing `@Valid`**: Raw `@RequestBody` without Bean Validation — never trust unvalidated input
+- **CSRF disabled without justification**: Stateless JWT APIs may disable it but must document why
+
+If any CRITICAL security issue is found, stop and escalate to `security-reviewer`.
+
+### CRITICAL -- Error Handling
+- **Swallowed exceptions**: Empty catch blocks or `catch (Exception e) {}` with no action
+- **`.get()` on Optional**: Calling `repository.findById(id).get()` without `.isPresent()` — use `.orElseThrow()`
+- **Missing `@RestControllerAdvice`**: Exception handling scattered across controllers instead of centralised
+- **Wrong HTTP status**: Returning `200 OK` with null body instead of `404`, or missing `201` on creation
+
+### HIGH -- Spring Boot Architecture
+- **Field injection**: `@Autowired` on fields is a code smell — constructor injection is required
+- **Business logic in controllers**: Controllers must delegate to the service layer immediately
+- **`@Transactional` on wrong layer**: Must be on service layer, not controller or repository
+- **Missing `@Transactional(readOnly = true)`**: Read-only service methods must declare this
+- **Entity exposed in response**: JPA entity returned directly from controller — use DTO or record projection
+
+### HIGH -- JPA / Database
+- **N+1 query problem**: `FetchType.EAGER` on collections — use `JOIN FETCH` or `@EntityGraph`
+- **Unbounded list endpoints**: Returning `List<T>` from endpoints without `Pageable` and `Page<T>`
+- **Missing `@Modifying`**: Any `@Query` that mutates data requires `@Modifying` + `@Transactional`
+- **Dangerous cascade**: `CascadeType.ALL` with `orphanRemoval = true` — confirm intent is deliberate
+
+### MEDIUM -- Concurrency and State
+- **Mutable singleton fields**: Non-final instance fields in `@Service` / `@Component` are a race condition
+- **Unbounded `@Async`**: `CompletableFuture` or `@Async` without a custom `Executor` — default creates unbounded threads
+- **Blocking `@Scheduled`**: Long-running scheduled methods that block the scheduler thread
+
+### MEDIUM -- Java Idioms and Performance
+- **String concatenation in loops**: Use `StringBuilder` or `String.join`
+- **Raw type usage**: Unparameterised generics (`List` instead of `List<T>`)
+- **Missed pattern matching**: `instanceof` check followed by explicit cast — use pattern matching (Java 16+)
+- **Null returns from service layer**: Prefer `Optional<T>` over returning null
+
+### MEDIUM -- Testing
+- **`@SpringBootTest` for unit tests**: Use `@WebMvcTest` for controllers, `@DataJpaTest` for repositories
+- **Missing Mockito extension**: Service tests must use `@ExtendWith(MockitoExtension.class)`
+- **`Thread.sleep()` in tests**: Use `Awaitility` for async assertions
+- **Weak test names**: `testFindUser` gives no information — use `should_return_404_when_user_not_found`
+
+### MEDIUM -- Workflow and State Machine (payment / event-driven code)
+- **Idempotency key checked after processing**: Must be checked before any state mutation
+- **Illegal state transitions**: No guard on transitions like `CANCELLED → PROCESSING`
+- **Non-atomic compensation**: Rollback/compensation logic that can partially succeed
+- **Missing jitter on retry**: Exponential backoff without jitter causes thundering herd
+- **No dead-letter handling**: Failed async events with no fallback or alerting
+
+## Diagnostic Commands
+```bash
+git diff -- '*.java'
+mvn verify -q
+./gradlew check                              # Gradle equivalent
+./mvnw checkstyle:check                      # style
+./mvnw spotbugs:check                        # static analysis
+./mvnw test                                  # unit tests
+./mvnw dependency-check:check                # CVE scan (OWASP plugin)
+grep -rn "@Autowired" src/main/java --include="*.java"
+grep -rn "FetchType.EAGER" src/main/java --include="*.java"
+```
+Read `pom.xml`, `build.gradle`, or `build.gradle.kts` to determine the build tool and Spring Boot version before reviewing.
+
+## Approval Criteria
+- **Approve**: No CRITICAL or HIGH issues
+- **Warning**: MEDIUM issues only
+- **Block**: CRITICAL or HIGH issues found
+
+For detailed Spring Boot patterns and examples, see `skill: springboot-patterns`.

package/skills/java/manifest.yaml

@@ -0,0 +1,18 @@
+name: java
+version: 0.1.0
+description: Java coding standards, Spring Boot patterns, JPA/Hibernate, and security for production-grade Spring services
+depends:
+  - common
+tags:
+  - java
+  - spring
+  - jpa
+rules: []
+skills:
+  - skills/java-coding-standards.md
+  - skills/jpa-patterns.md
+  - skills/springboot-patterns.md
+  - skills/springboot-security.md
+agents:
+  - agents/java-reviewer.md
+  - agents/java-build-resolver.md

package/skills/java/skills/java-coding-standards.md

@@ -0,0 +1,147 @@
+---
+name: java-coding-standards
+description: "Java coding standards for Spring Boot services: naming, immutability, Optional usage, streams, exceptions, generics, and project layout."
+origin: ECC
+---
+
+# Java Coding Standards
+
+Standards for readable, maintainable Java (17+) code in Spring Boot services.
+
+## When to Activate
+
+- Writing or reviewing Java code in Spring Boot projects
+- Enforcing naming, immutability, or exception handling conventions
+- Working with records, sealed classes, or pattern matching (Java 17+)
+- Reviewing use of Optional, streams, or generics
+- Structuring packages and project layout
+
+## Core Principles
+
+- Prefer clarity over cleverness
+- Immutable by default; minimize shared mutable state
+- Fail fast with meaningful exceptions
+- Consistent naming and package structure
+
+## Naming
+
+```java
+// PASS: Classes/Records: PascalCase
+public class MarketService {}
+public record Money(BigDecimal amount, Currency currency) {}
+
+// PASS: Methods/fields: camelCase
+private final MarketRepository marketRepository;
+public Market findBySlug(String slug) {}
+
+// PASS: Constants: UPPER_SNAKE_CASE
+private static final int MAX_PAGE_SIZE = 100;
+```
+
+## Immutability
+
+```java
+// PASS: Favor records and final fields
+public record MarketDto(Long id, String name, MarketStatus status) {}
+
+public class Market {
+  private final Long id;
+  private final String name;
+  // getters only, no setters
+}
+```
+
+## Optional Usage
+
+```java
+// PASS: Return Optional from find* methods
+Optional<Market> market = marketRepository.findBySlug(slug);
+
+// PASS: Map/flatMap instead of get()
+return market
+    .map(MarketResponse::from)
+    .orElseThrow(() -> new EntityNotFoundException("Market not found"));
+```
+
+## Streams Best Practices
+
+```java
+// PASS: Use streams for transformations, keep pipelines short
+List<String> names = markets.stream()
+    .map(Market::name)
+    .filter(Objects::nonNull)
+    .toList();
+
+// FAIL: Avoid complex nested streams; prefer loops for clarity
+```
+
+## Exceptions
+
+- Use unchecked exceptions for domain errors; wrap technical exceptions with context
+- Create domain-specific exceptions (e.g., `MarketNotFoundException`)
+- Avoid broad `catch (Exception ex)` unless rethrowing/logging centrally
+
+```java
+throw new MarketNotFoundException(slug);
+```
+
+## Generics and Type Safety
+
+- Avoid raw types; declare generic parameters
+- Prefer bounded generics for reusable utilities
+
+```java
+public <T extends Identifiable> Map<Long, T> indexById(Collection<T> items) { ... }
+```
+
+## Project Structure (Maven/Gradle)
+
+```
+src/main/java/com/example/app/
+  config/
+  controller/
+  service/
+  repository/
+  domain/
+  dto/
+  util/
+src/main/resources/
+  application.yml
+src/test/java/... (mirrors main)
+```
+
+## Formatting and Style
+
+- Use 2 or 4 spaces consistently (project standard)
+- One public top-level type per file
+- Keep methods short and focused; extract helpers
+- Order members: constants, fields, constructors, public methods, protected, private
+
+## Code Smells to Avoid
+
+- Long parameter lists → use DTO/builders
+- Deep nesting → early returns
+- Magic numbers → named constants
+- Static mutable state → prefer dependency injection
+- Silent catch blocks → log and act or rethrow
+
+## Logging
+
+```java
+private static final Logger log = LoggerFactory.getLogger(MarketService.class);
+log.info("fetch_market slug={}", slug);
+log.error("failed_fetch_market slug={}", slug, ex);
+```
+
+## Null Handling
+
+- Accept `@Nullable` only when unavoidable; otherwise use `@NonNull`
+- Use Bean Validation (`@NotNull`, `@NotBlank`) on inputs
+
+## Testing Expectations
+
+- JUnit 5 + AssertJ for fluent assertions
+- Mockito for mocking; avoid partial mocks where possible
+- Favor deterministic tests; no hidden sleeps
+
+**Remember**: Keep code intentional, typed, and observable. Optimize for maintainability over micro-optimizations unless proven necessary.

package/skills/java/skills/jpa-patterns.md

@@ -0,0 +1,151 @@
+---
+name: jpa-patterns
+description: JPA/Hibernate patterns for entity design, relationships, query optimization, transactions, auditing, indexing, pagination, and pooling in Spring Boot.
+origin: ECC
+---
+
+# JPA/Hibernate Patterns
+
+Use for data modeling, repositories, and performance tuning in Spring Boot.
+
+## When to Activate
+
+- Designing JPA entities and table mappings
+- Defining relationships (@OneToMany, @ManyToOne, @ManyToMany)
+- Optimizing queries (N+1 prevention, fetch strategies, projections)
+- Configuring transactions, auditing, or soft deletes
+- Setting up pagination, sorting, or custom repository methods
+- Tuning connection pooling (HikariCP) or second-level caching
+
+## Entity Design
+
+```java
+@Entity
+@Table(name = "markets", indexes = {
+  @Index(name = "idx_markets_slug", columnList = "slug", unique = true)
+})
+@EntityListeners(AuditingEntityListener.class)
+public class MarketEntity {
+  @Id @GeneratedValue(strategy = GenerationType.IDENTITY)
+  private Long id;
+
+  @Column(nullable = false, length = 200)
+  private String name;
+
+  @Column(nullable = false, unique = true, length = 120)
+  private String slug;
+
+  @Enumerated(EnumType.STRING)
+  private MarketStatus status = MarketStatus.ACTIVE;
+
+  @CreatedDate private Instant createdAt;
+  @LastModifiedDate private Instant updatedAt;
+}
+```
+
+Enable auditing:
+```java
+@Configuration
+@EnableJpaAuditing
+class JpaConfig {}
+```
+
+## Relationships and N+1 Prevention
+
+```java
+@OneToMany(mappedBy = "market", cascade = CascadeType.ALL, orphanRemoval = true)
+private List<PositionEntity> positions = new ArrayList<>();
+```
+
+- Default to lazy loading; use `JOIN FETCH` in queries when needed
+- Avoid `EAGER` on collections; use DTO projections for read paths
+
+```java
+@Query("select m from MarketEntity m left join fetch m.positions where m.id = :id")
+Optional<MarketEntity> findWithPositions(@Param("id") Long id);
+```
+
+## Repository Patterns
+
+```java
+public interface MarketRepository extends JpaRepository<MarketEntity, Long> {
+  Optional<MarketEntity> findBySlug(String slug);
+
+  @Query("select m from MarketEntity m where m.status = :status")
+  Page<MarketEntity> findByStatus(@Param("status") MarketStatus status, Pageable pageable);
+}
+```
+
+- Use projections for lightweight queries:
+```java
+public interface MarketSummary {
+  Long getId();
+  String getName();
+  MarketStatus getStatus();
+}
+Page<MarketSummary> findAllBy(Pageable pageable);
+```
+
+## Transactions
+
+- Annotate service methods with `@Transactional`
+- Use `@Transactional(readOnly = true)` for read paths to optimize
+- Choose propagation carefully; avoid long-running transactions
+
+```java
+@Transactional
+public Market updateStatus(Long id, MarketStatus status) {
+  MarketEntity entity = repo.findById(id)
+      .orElseThrow(() -> new EntityNotFoundException("Market"));
+  entity.setStatus(status);
+  return Market.from(entity);
+}
+```
+
+## Pagination
+
+```java
+PageRequest page = PageRequest.of(pageNumber, pageSize, Sort.by("createdAt").descending());
+Page<MarketEntity> markets = repo.findByStatus(MarketStatus.ACTIVE, page);
+```
+
+For cursor-like pagination, include `id > :lastId` in JPQL with ordering.
+
+## Indexing and Performance
+
+- Add indexes for common filters (`status`, `slug`, foreign keys)
+- Use composite indexes matching query patterns (`status, created_at`)
+- Avoid `select *`; project only needed columns
+- Batch writes with `saveAll` and `hibernate.jdbc.batch_size`
+
+## Connection Pooling (HikariCP)
+
+Recommended properties:
+```
+spring.datasource.hikari.maximum-pool-size=20
+spring.datasource.hikari.minimum-idle=5
+spring.datasource.hikari.connection-timeout=30000
+spring.datasource.hikari.validation-timeout=5000
+```
+
+For PostgreSQL LOB handling, add:
+```
+spring.jpa.properties.hibernate.jdbc.lob.non_contextual_creation=true
+```
+
+## Caching
+
+- 1st-level cache is per EntityManager; avoid keeping entities across transactions
+- For read-heavy entities, consider second-level cache cautiously; validate eviction strategy
+
+## Migrations
+
+- Use Flyway or Liquibase; never rely on Hibernate auto DDL in production
+- Keep migrations idempotent and additive; avoid dropping columns without plan
+
+## Testing Data Access
+
+- Prefer `@DataJpaTest` with Testcontainers to mirror production
+- Assert SQL efficiency using logs: set `logging.level.org.hibernate.SQL=DEBUG` and `logging.level.org.hibernate.orm.jdbc.bind=TRACE` for parameter values
+
+**Remember**: Keep entities lean, queries intentional, and transactions short. Prevent N+1 with fetch strategies and projections, and index for your read/write paths.