claude-code-pilot 2.0.0 → 3.0.0

package/src/skills/java-coding-standards/SKILL.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
+// ✅ Classes/Records: PascalCase
+public class MarketService {}
+public record Money(BigDecimal amount, Currency currency) {}
+
+// ✅ Methods/fields: camelCase
+private final MarketRepository marketRepository;
+public Market findBySlug(String slug) {}
+
+// ✅ Constants: UPPER_SNAKE_CASE
+private static final int MAX_PAGE_SIZE = 100;
+```
+
+## Immutability
+
+```java
+// ✅ 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
+// ✅ Return Optional from find* methods
+Optional<Market> market = marketRepository.findBySlug(slug);
+
+// ✅ Map/flatMap instead of get()
+return market
+    .map(MarketResponse::from)
+    .orElseThrow(() -> new EntityNotFoundException("Market not found"));
+```
+
+## Streams Best Practices
+
+```java
+// ✅ Use streams for transformations, keep pipelines short
+List<String> names = markets.stream()
+    .map(Market::name)
+    .filter(Objects::nonNull)
+    .toList();
+
+// ❌ 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/src/skills/jpa-patterns/SKILL.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.

package/src/skills/kotlin-coroutines-flows/SKILL.md

@@ -0,0 +1,284 @@
+---
+name: kotlin-coroutines-flows
+description: Kotlin Coroutines and Flow patterns for Android and KMP — structured concurrency, Flow operators, StateFlow, error handling, and testing.
+origin: ECC
+---
+
+# Kotlin Coroutines & Flows
+
+Patterns for structured concurrency, Flow-based reactive streams, and coroutine testing in Android and Kotlin Multiplatform projects.
+
+## When to Activate
+
+- Writing async code with Kotlin coroutines
+- Using Flow, StateFlow, or SharedFlow for reactive data
+- Handling concurrent operations (parallel loading, debounce, retry)
+- Testing coroutines and Flows
+- Managing coroutine scopes and cancellation
+
+## Structured Concurrency
+
+### Scope Hierarchy
+
+```
+Application
+  └── viewModelScope (ViewModel)
+        └── coroutineScope { } (structured child)
+              ├── async { } (concurrent task)
+              └── async { } (concurrent task)
+```
+
+Always use structured concurrency — never `GlobalScope`:
+
+```kotlin
+// BAD
+GlobalScope.launch { fetchData() }
+
+// GOOD — scoped to ViewModel lifecycle
+viewModelScope.launch { fetchData() }
+
+// GOOD — scoped to composable lifecycle
+LaunchedEffect(key) { fetchData() }
+```
+
+### Parallel Decomposition
+
+Use `coroutineScope` + `async` for parallel work:
+
+```kotlin
+suspend fun loadDashboard(): Dashboard = coroutineScope {
+    val items = async { itemRepository.getRecent() }
+    val stats = async { statsRepository.getToday() }
+    val profile = async { userRepository.getCurrent() }
+    Dashboard(
+        items = items.await(),
+        stats = stats.await(),
+        profile = profile.await()
+    )
+}
+```
+
+### SupervisorScope
+
+Use `supervisorScope` when child failures should not cancel siblings:
+
+```kotlin
+suspend fun syncAll() = supervisorScope {
+    launch { syncItems() }       // failure here won't cancel syncStats
+    launch { syncStats() }
+    launch { syncSettings() }
+}
+```
+
+## Flow Patterns
+
+### Cold Flow — One-Shot to Stream Conversion
+
+```kotlin
+fun observeItems(): Flow<List<Item>> = flow {
+    // Re-emits whenever the database changes
+    itemDao.observeAll()
+        .map { entities -> entities.map { it.toDomain() } }
+        .collect { emit(it) }
+}
+```
+
+### StateFlow for UI State
+
+```kotlin
+class DashboardViewModel(
+    observeProgress: ObserveUserProgressUseCase
+) : ViewModel() {
+    val progress: StateFlow<UserProgress> = observeProgress()
+        .stateIn(
+            scope = viewModelScope,
+            started = SharingStarted.WhileSubscribed(5_000),
+            initialValue = UserProgress.EMPTY
+        )
+}
+```
+
+`WhileSubscribed(5_000)` keeps the upstream active for 5 seconds after the last subscriber leaves — survives configuration changes without restarting.
+
+### Combining Multiple Flows
+
+```kotlin
+val uiState: StateFlow<HomeState> = combine(
+    itemRepository.observeItems(),
+    settingsRepository.observeTheme(),
+    userRepository.observeProfile()
+) { items, theme, profile ->
+    HomeState(items = items, theme = theme, profile = profile)
+}.stateIn(viewModelScope, SharingStarted.WhileSubscribed(5_000), HomeState())
+```
+
+### Flow Operators
+
+```kotlin
+// Debounce search input
+searchQuery
+    .debounce(300)
+    .distinctUntilChanged()
+    .flatMapLatest { query -> repository.search(query) }
+    .catch { emit(emptyList()) }
+    .collect { results -> _state.update { it.copy(results = results) } }
+
+// Retry with exponential backoff
+fun fetchWithRetry(): Flow<Data> = flow { emit(api.fetch()) }
+    .retryWhen { cause, attempt ->
+        if (cause is IOException && attempt < 3) {
+            delay(1000L * (1 shl attempt.toInt()))
+            true
+        } else {
+            false
+        }
+    }
+```
+
+### SharedFlow for One-Time Events
+
+```kotlin
+class ItemListViewModel : ViewModel() {
+    private val _effects = MutableSharedFlow<Effect>()
+    val effects: SharedFlow<Effect> = _effects.asSharedFlow()
+
+    sealed interface Effect {
+        data class ShowSnackbar(val message: String) : Effect
+        data class NavigateTo(val route: String) : Effect
+    }
+
+    private fun deleteItem(id: String) {
+        viewModelScope.launch {
+            repository.delete(id)
+            _effects.emit(Effect.ShowSnackbar("Item deleted"))
+        }
+    }
+}
+
+// Collect in Composable
+LaunchedEffect(Unit) {
+    viewModel.effects.collect { effect ->
+        when (effect) {
+            is Effect.ShowSnackbar -> snackbarHostState.showSnackbar(effect.message)
+            is Effect.NavigateTo -> navController.navigate(effect.route)
+        }
+    }
+}
+```
+
+## Dispatchers
+
+```kotlin
+// CPU-intensive work
+withContext(Dispatchers.Default) { parseJson(largePayload) }
+
+// IO-bound work
+withContext(Dispatchers.IO) { database.query() }
+
+// Main thread (UI) — default in viewModelScope
+withContext(Dispatchers.Main) { updateUi() }
+```
+
+In KMP, use `Dispatchers.Default` and `Dispatchers.Main` (available on all platforms). `Dispatchers.IO` is JVM/Android only — use `Dispatchers.Default` on other platforms or provide via DI.
+
+## Cancellation
+
+### Cooperative Cancellation
+
+Long-running loops must check for cancellation:
+
+```kotlin
+suspend fun processItems(items: List<Item>) = coroutineScope {
+    for (item in items) {
+        ensureActive()  // throws CancellationException if cancelled
+        process(item)
+    }
+}
+```
+
+### Cleanup with try/finally
+
+```kotlin
+viewModelScope.launch {
+    try {
+        _state.update { it.copy(isLoading = true) }
+        val data = repository.fetch()
+        _state.update { it.copy(data = data) }
+    } finally {
+        _state.update { it.copy(isLoading = false) }  // always runs, even on cancellation
+    }
+}
+```
+
+## Testing
+
+### Testing StateFlow with Turbine
+
+```kotlin
+@Test
+fun `search updates item list`() = runTest {
+    val fakeRepository = FakeItemRepository().apply { emit(testItems) }
+    val viewModel = ItemListViewModel(GetItemsUseCase(fakeRepository))
+
+    viewModel.state.test {
+        assertEquals(ItemListState(), awaitItem())  // initial
+
+        viewModel.onSearch("query")
+        val loading = awaitItem()
+        assertTrue(loading.isLoading)
+
+        val loaded = awaitItem()
+        assertFalse(loaded.isLoading)
+        assertEquals(1, loaded.items.size)
+    }
+}
+```
+
+### Testing with TestDispatcher
+
+```kotlin
+@Test
+fun `parallel load completes correctly`() = runTest {
+    val viewModel = DashboardViewModel(
+        itemRepo = FakeItemRepo(),
+        statsRepo = FakeStatsRepo()
+    )
+
+    viewModel.load()
+    advanceUntilIdle()
+
+    val state = viewModel.state.value
+    assertNotNull(state.items)
+    assertNotNull(state.stats)
+}
+```
+
+### Faking Flows
+
+```kotlin
+class FakeItemRepository : ItemRepository {
+    private val _items = MutableStateFlow<List<Item>>(emptyList())
+
+    override fun observeItems(): Flow<List<Item>> = _items
+
+    fun emit(items: List<Item>) { _items.value = items }
+
+    override suspend fun getItemsByCategory(category: String): Result<List<Item>> {
+        return Result.success(_items.value.filter { it.category == category })
+    }
+}
+```
+
+## Anti-Patterns to Avoid
+
+- Using `GlobalScope` — leaks coroutines, no structured cancellation
+- Collecting Flows in `init {}` without a scope — use `viewModelScope.launch`
+- Using `MutableStateFlow` with mutable collections — always use immutable copies: `_state.update { it.copy(list = it.list + newItem) }`
+- Catching `CancellationException` — let it propagate for proper cancellation
+- Using `flowOn(Dispatchers.Main)` to collect — collection dispatcher is the caller's dispatcher
+- Creating `Flow` in `@Composable` without `remember` — recreates the flow every recomposition
+
+## References
+
+See skill: `compose-multiplatform-patterns` for UI consumption of Flows.
+See skill: `android-clean-architecture` for where coroutines fit in layers.