claudecode-omc 5.6.4 → 5.6.6

package/bundled/upstream/ecc/skills/java-coding-standards/SKILL.md

@@ -1,20 +1,31 @@
 ---
 name: java-coding-standards
-description: "Java coding standards for Spring Boot services: naming, immutability, Optional usage, streams, exceptions, generics, and project layout."
+description: "Java coding standards for Spring Boot and Quarkus services: naming, immutability, Optional usage, streams, exceptions, generics, CDI, reactive patterns, and project layout. Automatically applies framework-specific conventions."
 origin: ECC
 ---
 
 # Java Coding Standards
 
-Standards for readable, maintainable Java (17+) code in Spring Boot services.
+Standards for readable, maintainable Java (17+) code in Spring Boot and Quarkus services.
 
-## When to Activate
+## When to Use
 
-- Writing or reviewing Java code in Spring Boot projects
+- Writing or reviewing Java code in Spring Boot or Quarkus 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
+- **[QUARKUS]**: Working with CDI scopes, Panache entities, or reactive pipelines
+
+## How It Works
+
+### Framework Detection
+
+Before applying standards, determine the framework from the build file:
+
+- Build file contains `quarkus` → apply **[QUARKUS]** conventions
+- Build file contains `spring-boot` → apply **[SPRING]** conventions
+- Neither detected → apply shared conventions only
 
 ## Core Principles
 
@@ -22,6 +33,13 @@ Standards for readable, maintainable Java (17+) code in Spring Boot services.
 - Immutable by default; minimize shared mutable state
 - Fail fast with meaningful exceptions
 - Consistent naming and package structure
+- **[QUARKUS]**: Favor build-time over runtime processing; avoid runtime reflection where possible
+
+## Examples
+
+The sections below show concrete Spring Boot, Quarkus, and shared Java examples
+for naming, immutability, dependency injection, reactive code, exceptions,
+project layout, logging, configuration, and tests.
 
 ## Naming
 
@@ -36,6 +54,12 @@ public Market findBySlug(String slug) {}
 
 // PASS: Constants: UPPER_SNAKE_CASE
 private static final int MAX_PAGE_SIZE = 100;
+
+// PASS: [QUARKUS] JAX-RS resources named as *Resource, not *Controller
+public class MarketResource {}
+
+// PASS: [SPRING] REST controllers named as *Controller
+public class MarketController {}
 ```
 
 ## Immutability
@@ -49,14 +73,33 @@ public class Market {
   private final String name;
   // getters only, no setters
 }
+
+// PASS: [QUARKUS] Panache active-record entities use public fields (Quarkus convention)
+@Entity
+public class Market extends PanacheEntity {
+  public String name;
+  public MarketStatus status;
+  // Panache generates accessors at build time; public fields are idiomatic here
+}
+
+// PASS: [QUARKUS] Panache MongoDB entities
+@MongoEntity(collection = "markets")
+public class Market extends PanacheMongoEntity {
+  public String name;
+  public MarketStatus status;
+}
 ```
 
 ## Optional Usage
 
 ```java
 // PASS: Return Optional from find* methods
+// [SPRING]
 Optional<Market> market = marketRepository.findBySlug(slug);
 
+// [QUARKUS] Panache
+Optional<Market> market = Market.find("slug", slug).firstResultOptional();
+
 // PASS: Map/flatMap instead of get()
 return market
     .map(MarketResponse::from)
@@ -75,6 +118,77 @@ List<String> names = markets.stream()
 // FAIL: Avoid complex nested streams; prefer loops for clarity
 ```
 
+## Dependency Injection
+
+```java
+// PASS: [SPRING] Constructor injection (preferred over @Autowired on fields)
+@Service
+public class MarketService {
+  private final MarketRepository marketRepository;
+
+  public MarketService(MarketRepository marketRepository) {
+    this.marketRepository = marketRepository;
+  }
+}
+
+// PASS: [QUARKUS] Constructor injection
+@ApplicationScoped
+public class MarketService {
+  private final MarketRepository marketRepository;
+
+  @Inject
+  public MarketService(MarketRepository marketRepository) {
+    this.marketRepository = marketRepository;
+  }
+}
+
+// PASS: [QUARKUS] Package-private field injection (acceptable in Quarkus — avoids proxy issues)
+@ApplicationScoped
+public class MarketService {
+  @Inject
+  MarketRepository marketRepository;
+}
+
+// FAIL: [SPRING] Field injection with @Autowired
+@Autowired
+private MarketRepository marketRepository; // use constructor injection
+
+// FAIL: [QUARKUS] @Singleton when interception or lazy init is needed
+@Singleton // non-proxyable — use @ApplicationScoped instead
+public class MarketService {}
+```
+
+## Reactive Patterns [QUARKUS]
+
+```java
+// PASS: Return Uni/Multi from reactive endpoints
+@GET
+@Path("/{slug}")
+public Uni<Market> findBySlug(@PathParam("slug") String slug) {
+  return Market.find("slug", slug)
+      .<Market>firstResult()
+      .onItem().ifNull().failWith(() -> new MarketNotFoundException(slug));
+}
+
+// PASS: Non-blocking pipeline composition
+public Uni<OrderConfirmation> placeOrder(OrderRequest req) {
+  return validateOrder(req)
+      .chain(valid -> persistOrder(valid))
+      .chain(order -> notifyFulfillment(order));
+}
+
+// FAIL: Blocking call inside a Uni/Multi pipeline
+public Uni<Market> find(String slug) {
+  Market m = Market.find("slug", slug).firstResult(); // BLOCKING — breaks event loop
+  return Uni.createFrom().item(m);
+}
+
+// FAIL: Subscribing more than once to a shared Uni
+Uni<Market> shared = fetchMarket(slug);
+shared.subscribe().with(m -> log(m));
+shared.subscribe().with(m -> cache(m)); // double subscribe — use Uni.memoize()
+```
+
 ## Exceptions
 
 - Use unchecked exceptions for domain errors; wrap technical exceptions with context
@@ -85,6 +199,34 @@ List<String> names = markets.stream()
 throw new MarketNotFoundException(slug);
 ```
 
+### Centralised Exception Handling
+
+```java
+// [SPRING]
+@RestControllerAdvice
+public class GlobalExceptionHandler {
+  @ExceptionHandler(MarketNotFoundException.class)
+  public ResponseEntity<ErrorResponse> handle(MarketNotFoundException ex) {
+    return ResponseEntity.status(404).body(ErrorResponse.from(ex));
+  }
+}
+
+// [QUARKUS] Option A: ExceptionMapper
+@Provider
+public class MarketNotFoundMapper implements ExceptionMapper<MarketNotFoundException> {
+  @Override
+  public Response toResponse(MarketNotFoundException ex) {
+    return Response.status(404).entity(ErrorResponse.from(ex)).build();
+  }
+}
+
+// [QUARKUS] Option B: @ServerExceptionMapper (RESTEasy Reactive)
+@ServerExceptionMapper
+public RestResponse<ErrorResponse> handle(MarketNotFoundException ex) {
+  return RestResponse.status(Status.NOT_FOUND, ErrorResponse.from(ex));
+}
+```
+
 ## Generics and Type Safety
 
 - Avoid raw types; declare generic parameters
@@ -94,7 +236,9 @@ throw new MarketNotFoundException(slug);
 public <T extends Identifiable> Map<Long, T> indexById(Collection<T> items) { ... }
 ```
 
-## Project Structure (Maven/Gradle)
+## Project Structure
+
+### [SPRING] Maven/Gradle
 
 ```
 src/main/java/com/example/app/
@@ -110,6 +254,24 @@ src/main/resources/
 src/test/java/... (mirrors main)
 ```
 
+### [QUARKUS] Maven/Gradle
+
+```
+src/main/java/com/example/app/
+  config/              # @ConfigMapping, @ConfigProperty beans, Producers
+  resource/            # JAX-RS resources (not "controller")
+  service/
+  repository/          # PanacheRepository implementations (if not using active record)
+  domain/              # JPA/Panache entities, MongoDB entities
+  dto/
+  util/
+  mapper/              # MapStruct mappers (if used)
+src/main/resources/
+  application.properties   # Quarkus convention (YAML supported with quarkus-config-yaml)
+  import.sql               # Hibernate auto-import for dev/test
+src/test/java/... (mirrors main)
+```
+
 ## Formatting and Style
 
 - Use 2 or 4 spaces consistently (project standard)
@@ -124,24 +286,98 @@ src/test/java/... (mirrors main)
 - Magic numbers → named constants
 - Static mutable state → prefer dependency injection
 - Silent catch blocks → log and act or rethrow
+- **[QUARKUS]**: `@Singleton` where `@ApplicationScoped` is intended — breaks proxying and interception
+- **[QUARKUS]**: Mixing `quarkus-resteasy-reactive` and `quarkus-resteasy` (classic) — pick one stack
+- **[QUARKUS]**: Panache active-record + repository pattern in the same bounded context — pick one
 
 ## Logging
 
 ```java
+// [SPRING] SLF4J
 private static final Logger log = LoggerFactory.getLogger(MarketService.class);
 log.info("fetch_market slug={}", slug);
 log.error("failed_fetch_market slug={}", slug, ex);
+
+// [QUARKUS] JBoss Logging (default, zero-cost at build time)
+private static final Logger log = Logger.getLogger(MarketService.class);
+log.infof("fetch_market slug=%s", slug);
+log.errorf(ex, "failed_fetch_market slug=%s", slug);
+
+// [QUARKUS] Alternative: simplified logging with @Inject
+@Inject
+Logger log; // CDI-injected, scoped to declaring class
 ```
 
 ## Null Handling
 
 - Accept `@Nullable` only when unavoidable; otherwise use `@NonNull`
 - Use Bean Validation (`@NotNull`, `@NotBlank`) on inputs
+- **[QUARKUS]**: Apply `@Valid` on `@BeanParam`, `@RestForm`, and request body parameters
+
+## Configuration
+
+```java
+// [SPRING] @ConfigurationProperties
+@ConfigurationProperties(prefix = "market")
+public record MarketProperties(int maxPageSize, Duration cacheTtl) {}
+
+// [QUARKUS] @ConfigMapping (type-safe, build-time validated)
+@ConfigMapping(prefix = "market")
+public interface MarketConfig {
+  int maxPageSize();
+  Duration cacheTtl();
+}
+
+// [QUARKUS] Simple values with @ConfigProperty
+@ConfigProperty(name = "market.max-page-size", defaultValue = "100")
+int maxPageSize;
+```
 
 ## Testing Expectations
 
+### Shared
 - JUnit 5 + AssertJ for fluent assertions
 - Mockito for mocking; avoid partial mocks where possible
 - Favor deterministic tests; no hidden sleeps
 
+### [SPRING]
+- `@WebMvcTest` for controller slices, `@DataJpaTest` for repository slices
+- `@SpringBootTest` reserved for full integration tests
+- `@MockBean` for replacing beans in Spring context
+
+### [QUARKUS]
+- Plain JUnit 5 + Mockito for unit tests (no `@QuarkusTest`)
+- `@QuarkusTest` reserved for CDI integration tests
+- `@InjectMock` for replacing CDI beans in integration tests
+- Dev Services for database/Kafka/Redis — avoid manual Testcontainers setup when Dev Services suffice
+- `@QuarkusTestResource` for custom external service lifecycle
+
+```java
+// [SPRING] Controller test
+@WebMvcTest(MarketController.class)
+class MarketControllerTest {
+  @Autowired MockMvc mockMvc;
+  @MockBean MarketService marketService;
+}
+
+// [QUARKUS] Integration test
+@QuarkusTest
+class MarketResourceTest {
+  @InjectMock
+  MarketService marketService;
+
+  @Test
+  void should_return_404_when_market_not_found() {
+    given().when().get("/markets/unknown").then().statusCode(404);
+  }
+}
+
+// [QUARKUS] Unit test (no CDI, no @QuarkusTest)
+@ExtendWith(MockitoExtension.class)
+class MarketServiceTest {
+  @Mock MarketRepository marketRepository;
+  @InjectMocks MarketService marketService;
+}
+```
+
 **Remember**: Keep code intentional, typed, and observable. Optimize for maintainability over micro-optimizations unless proven necessary.

package/bundled/upstream/ecc/skills/make-interfaces-feel-better/SKILL.md

@@ -0,0 +1,151 @@
+---
+name: make-interfaces-feel-better
+description: Apply concrete design-engineering details that make interfaces feel polished. Use when reviewing or improving UI spacing, typography, borders, shadows, motion, hit areas, icons, text wrapping, and interaction states.
+origin: community
+---
+
+# Make Interfaces Feel Better
+
+Use this skill for the small design-engineering details that compound into a
+more polished interface.
+
+Source: salvaged from stale community PR #1659 by `linus707`.
+
+## When to Use
+
+- The user says the UI feels off, flat, generic, cramped, jumpy, or unfinished.
+- You are building controls, cards, lists, dashboards, navigation, forms, or
+  toolbars.
+- A component needs hover, active, focus, enter, exit, loading, or empty states.
+- A frontend review needs specific before/after recommendations.
+
+## Core Principles
+
+### Concentric Radius
+
+For nearby nested rounded surfaces:
+
+```text
+outer radius = inner radius + padding
+```
+
+If padding is large, treat layers as separate surfaces instead of forcing the
+math. The point is optical coherence, not formula worship.
+
+### Optical Alignment
+
+Geometric centering is not always visual centering. Icon buttons, play
+triangles, arrows, stars, and asymmetric icons often need a small offset. Fix the
+SVG when possible; otherwise adjust with a pixel-level margin or padding change.
+
+### Shadows And Borders
+
+Use borders for separation and focus rings. Use layered shadows when a card,
+button, dropdown, or popover needs depth. Shadows should be transparent and
+subtle enough to work across backgrounds.
+
+### Text Wrapping
+
+- Use `text-wrap: balance` on headings and short titles.
+- Use `text-wrap: pretty` on short-to-medium body text, captions, descriptions,
+  and list items.
+- Avoid both on long prose, code, and preformatted content.
+- Use `font-variant-numeric: tabular-nums` for counters, timers, prices, tables,
+  and other updating numbers.
+
+### Font Smoothing
+
+On macOS, apply antialiased font smoothing at the root layout when the project
+does not already do so:
+
+```css
+html {
+  -webkit-font-smoothing: antialiased;
+  -moz-osx-font-smoothing: grayscale;
+}
+```
+
+### Image Outlines
+
+Images often need a subtle inset outline so their edges do not blur into the
+surface.
+
+```css
+img {
+  outline: 1px solid rgba(0, 0, 0, 0.1);
+  outline-offset: -1px;
+}
+
+@media (prefers-color-scheme: dark) {
+  img {
+    outline-color: rgba(255, 255, 255, 0.1);
+  }
+}
+```
+
+Use neutral black or white alpha outlines. Do not tint image outlines with the
+brand palette.
+
+### Motion
+
+Use CSS transitions for interactive state changes because they can retarget
+when the user changes intent mid-motion. Reserve keyframes for staged
+one-shot entrances or loading sequences.
+
+Good motion defaults:
+
+- Enter: combine opacity, small `translateY`, and optionally blur.
+- Exit: shorter and quieter than enter, usually 150ms.
+- Press: `scale(0.96)` for tactile buttons, with a way to disable it when the
+  movement distracts.
+- Icon swaps: cross-fade with opacity, scale, and blur instead of instant
+  visibility toggles.
+
+### Transition Scope
+
+Never use `transition: all`. Specify the changed properties:
+
+```css
+.button {
+  transition-property: transform, background-color, box-shadow;
+  transition-duration: 150ms;
+  transition-timing-function: ease-out;
+}
+```
+
+Use `will-change` only for first-frame stutter on compositor-friendly
+properties such as `transform`, `opacity`, and `filter`. Never use
+`will-change: all`.
+
+### Hit Areas
+
+Interactive controls should have at least a 40x40px hit area, ideally 44x44px
+where the layout allows it. Expand with a pseudo-element when the visible icon
+is smaller, but do not let expanded hit areas overlap.
+
+## Review Output
+
+When reviewing a UI polish pass, report concrete changes in before/after rows:
+
+| Principle | Before | After |
+| --- | --- | --- |
+| Concentric radius | Same radius on parent and child | Parent radius accounts for padding |
+| Tabular numbers | Counter shifts as digits change | Counter uses `tabular-nums` |
+| Transition scope | `transition: all` | Explicit transition properties |
+
+Include file paths and properties when they are not obvious from the snippets.
+Omit principles that you checked but did not change.
+
+## Checklist
+
+- Nested rounded elements are optically coherent.
+- Icons are visually centered.
+- Buttons, cards, and popovers use borders or shadows for the right reason.
+- Headings and short text avoid awkward wrapping.
+- Dynamic numbers use tabular numerals.
+- Images have neutral outlines where needed.
+- Enter and exit animations are split, subtle, and interruptible where
+  appropriate.
+- Buttons have tactile active states without exaggerated motion.
+- `transition: all` and `will-change: all` are absent.
+- Small controls still have usable hit areas.