feat(java-spring): add java-resilience skill

README.md

@@ -7,7 +7,7 @@ A Claude Code plugin marketplace with 3 focused plugins for Java developers. All
 | Plugin | Skills | Commands | Agents | Install when |
 |---|---|---|---|---|
 | `java-core` | 14 | 2 | `java-architect`, `java-build-resolver` | Every Java project |
-| `java-spring` | 7 | 2 | `java-spring-expert` | Spring Boot projects |
+| `java-spring` | 8 | 2 | `java-spring-expert` | Spring Boot projects |
 | `java-quality` | 3 | 1 | `java-security-reviewer`, `java-performance-reviewer`, `java-test-engineer` | Quality enforcement |
 
 ## Quick Setup (5 minutes)
@@ -76,6 +76,7 @@ Skills activate automatically based on context, or invoke them explicitly.
 | `/java-spring:java-security` | Review or generate Spring Security config — JWT, OAuth2, method security, CORS (Boot 2.x & 3.x) |
 | `/java-spring:java-openapi` | Generate or review OpenAPI/Swagger docs — `@Tag`, `@Operation`, `@Schema`, JWT auth scheme (springdoc v1/v2) |
 | `/java-spring:java-spring-ai` | Add AI features to Spring Boot — ChatClient, RAG, tool calling, memory (Spring AI 1.x / LangChain4J) |
+| `/java-spring:java-resilience` | Add Resilience4J patterns — circuit breaker, retry, rate limiter, bulkhead, timeout (Boot 2.x & 3.x) |
 
 ### java-quality
 

plugins/java-spring/skills/java-resilience/SKILL.md

@@ -0,0 +1,112 @@
+---
+name: java-resilience
+description: Use when the user asks to add resilience patterns, handle service failures, implement circuit breaker, retry, rate limiter, bulkhead, or timeout in a Spring Boot project using Resilience4J.
+version: 1.0.0
+authors: [java-plugins contributors]
+tags: [java, spring-boot, resilience4j, circuit-breaker, retry, rate-limiter, bulkhead, timeout]
+allowed-tools: [Read, Glob, Grep, Edit, Write]
+---
+
+# Resilience4J Skill
+
+Detect the existing setup, then apply the correct pattern.
+
+## Step 1 — Detect setup
+
+Check `pom.xml` or `build.gradle`:
+- `resilience4j-spring-boot3` → Spring Boot 3.x (use `io.github.resilience4j:resilience4j-spring-boot3`)
+- `resilience4j-spring-boot2` → Spring Boot 2.x
+- `spring-cloud-starter-circuitbreaker-resilience4j` → Spring Cloud Circuit Breaker abstraction
+- None present → offer to add (recommend `resilience4j-spring-boot3` for Boot 3.x)
+
+Check Java version: Java 17+ enables records for fallback DTOs; Java 8+ supported throughout.
+
+---
+
+## Mode: `review`
+
+User asks to review existing Resilience4J config. Check for:
+
+- [ ] Circuit breaker thresholds are tuned — `slidingWindowSize`, `failureRateThreshold`, `waitDurationInOpenState` set explicitly (not defaults)
+- [ ] `slowCallDurationThreshold` and `slowCallRateThreshold` configured — slow calls should also trip the breaker
+- [ ] Fallback methods match the same signature as the guarded method (same return type + `Throwable` param)
+- [ ] `@CircuitBreaker` and `@Retry` not stacked without `fallbackMethod` on the outer annotation — will swallow exceptions silently
+- [ ] Retry has `ignoreExceptions` for business errors (e.g. `IllegalArgumentException`, `EntityNotFoundException`) — don't retry 4xx errors
+- [ ] `RateLimiter` uses `limitForPeriod` appropriate for downstream SLA — not an arbitrary number
+- [ ] Bulkhead `maxConcurrentCalls` sized against thread pool or reactive scheduler
+- [ ] Actuator endpoints exposed: `management.endpoints.web.exposure.include=health,circuitbreakers,retries,ratelimiters`
+- [ ] Circuit breaker state changes logged via `CircuitBreakerEvent` listener — not silent
+- [ ] No `@Retry` on `@Transactional` methods — retries after a rolled-back transaction reopen a new transaction
+
+---
+
+## Mode: `circuit-breaker`
+
+User asks to add a circuit breaker to protect a downstream call.
+
+1. Add dependency (see `references/patterns.md` → Setup)
+2. Configure in `application.yml` — set `sliding-window-size`, `failure-rate-threshold`, `wait-duration-in-open-state`
+3. Annotate the method with `@CircuitBreaker(name = "serviceName", fallbackMethod = "fallback")`
+4. Write the fallback method — same return type, extra `Throwable` parameter
+5. Expose circuit breaker health: `management.health.circuitbreakers.enabled=true`
+6. Add event listener to log state transitions (CLOSED→OPEN→HALF_OPEN)
+
+Version note:
+- Spring Boot 3.x → `resilience4j-spring-boot3`
+- Spring Boot 2.x → `resilience4j-spring-boot2`
+
+---
+
+## Mode: `retry`
+
+User asks to add automatic retry for flaky remote calls.
+
+1. Configure retry in `application.yml` — `max-attempts`, `wait-duration`, `exponential-backoff-multiplier`
+2. Set `ignore-exceptions` for non-retryable errors (validation errors, 4xx responses)
+3. Set `retry-exceptions` explicitly (e.g. `IOException`, `TimeoutException`)
+4. Annotate with `@Retry(name = "serviceName", fallbackMethod = "fallback")`
+5. For HTTP clients: check response status before retrying — use `retryOnResultPredicate` to retry on 5xx, not 4xx
+6. Warn if stacking with `@CircuitBreaker` — retry fires first, circuit breaker wraps it; set `retry.max-attempts` lower than circuit breaker `sliding-window-size`
+
+---
+
+## Mode: `rate-limiter`
+
+User asks to limit how often a method can be called (outgoing rate limiting or incoming API protection).
+
+1. Configure `limit-for-period` (requests per window), `limit-refresh-period`, `timeout-duration`
+2. Annotate with `@RateLimiter(name = "serviceName", fallbackMethod = "fallback")`
+3. For incoming API protection: place on controller method or use a filter
+4. For outgoing: place on the service/client method calling the downstream
+
+---
+
+## Mode: `bulkhead`
+
+User asks to limit concurrent calls to isolate failures (prevent thread starvation).
+
+Two types — choose based on context:
+- **Semaphore bulkhead** (default): limits concurrent calls via a counter — lightweight, same thread pool
+- **ThreadPool bulkhead**: executes in a dedicated pool — true isolation, for blocking I/O
+
+Configure `max-concurrent-calls` and `max-wait-duration` (semaphore) or pool size (thread pool).
+Annotate with `@Bulkhead(name = "serviceName", type = Bulkhead.Type.SEMAPHORE)`.
+
+---
+
+## Mode: `timeout`
+
+User asks to add a timeout to a method.
+
+1. Use `@TimeLimiter` for reactive/async methods (returns `CompletableFuture` or `Flux`/`Mono`)
+2. For blocking methods: use `@CircuitBreaker` with `slowCallDurationThreshold` instead
+3. Configure `timeout-duration` in `application.yml`
+4. `@TimeLimiter` requires the method to return `CompletableFuture<T>` — wrap synchronous calls if needed
+
+---
+
+## Output format
+
+For **review mode**: list findings as `[CRITICAL] / [HIGH] / [MEDIUM] / [LOW]` with file:line references.
+
+For **implementation modes**: show exact Maven/Gradle snippet, full `application.yml` config block, and complete annotated Java example. State minimum Spring Boot version where relevant.