@c0x12c/ai-toolkit 1.15.0

package/rules/backend-micronaut/API_DESIGN.md

@@ -0,0 +1,313 @@
+# API Design Rules
+
+> Full guide: use `/backend-api-design` or `/testing-strategies` skill
+
+---
+
+## RPC Style — No REST Verbs
+
+All mutations use `@Post`. Never use `@Put`, `@Delete`, or `@Patch`.
+
+| Action | HTTP Method | Example |
+|--------|-------------|---------|
+| Read one | `@Get` | `@Get("/item")` |
+| Read list | `@Get` | `@Get("/items")` |
+| Create | `@Post` | `@Post` |
+| Update | `@Post("/update")` | `@Post("/update")` |
+| Delete | `@Post("/delete")` | `@Post("/delete")` |
+| Custom action | `@Post("/close")` | `@Post("/close")` |
+
+### Bad — REST Verbs (NEVER use these)
+
+```kotlin
+// ❌ BAD — REST verbs
+@Patch("/{id}")
+suspend fun update(@PathVariable id: UUID, @Body request: UpdateRequest): Response
+
+@Delete("/{id}")
+suspend fun delete(@PathVariable id: UUID): Boolean
+
+@Put("/{id}")
+suspend fun replace(@PathVariable id: UUID, @Body request: ReplaceRequest): Response
+```
+
+### Good — RPC-Style
+
+```kotlin
+// ✅ GOOD — RPC-style
+@Post("/update")
+suspend fun update(@QueryValue id: UUID, @Body request: UpdateRequest): Response
+
+@Post("/delete")
+suspend fun delete(@QueryValue id: UUID): Boolean
+```
+
+---
+
+## URL Design
+
+### NEVER Use Path Parameters
+
+**Do NOT use path parameters (e.g., `/{id}`, `/{userId}`). Always use query parameters.**
+
+Why:
+- Query parameters are more explicit and self-documenting
+- Easier to add optional parameters without breaking API
+- Consistent pattern across all endpoints
+- Simpler routing configuration
+- Better for caching and logging
+
+#### Bad - Path Parameters
+```kotlin
+// DON'T DO THIS
+@Get("/employees/{id}")
+suspend fun getEmployee(@PathVariable id: UUID): EmployeeResponse
+
+@Get("/employees/{id}/metrics")
+suspend fun getMetrics(@PathVariable id: UUID): MetricsResponse
+
+@Delete("/employees/{id}")
+suspend fun deleteEmployee(@PathVariable id: UUID): Boolean
+```
+
+#### Good - Query Parameters
+```kotlin
+// DO THIS
+@Get("/employee")
+suspend fun getEmployee(@QueryValue id: UUID): EmployeeResponse
+
+@Get("/employee/metrics")
+suspend fun getMetrics(@QueryValue id: UUID): MetricsResponse
+
+@Post("/employee/delete")
+suspend fun deleteEmployee(@QueryValue id: UUID): Boolean
+```
+
+### Endpoint Naming
+
+Use singular nouns for single resource, plural for collections:
+
+```kotlin
+// Collection endpoints (plural)
+@Get("/employees")           // List employees
+@Get("/organizations")       // List organizations
+
+// Single resource endpoints (singular)
+@Get("/employee")            // Get one employee (with ?id=xxx)
+@Get("/organization")        // Get one organization (with ?id=xxx)
+```
+
+Use verb sub-paths for actions:
+
+```kotlin
+// Actions use sub-paths, not HTTP verbs alone
+@Post("/employee/delete")     // Delete employee
+@Post("/employee/restore")    // Restore employee
+@Post("/sync/employees")      // Trigger employee sync
+@Post("/sync/github")         // Trigger GitHub sync
+```
+
+### Controller Organization
+
+Group related endpoints under common prefixes:
+
+```kotlin
+@Controller("/api/v1/admin")
+class AdminController {
+  // Sync operations
+  @Post("/sync/employees")
+  @Post("/sync/github")
+
+  // Employee operations
+  @Get("/employees")
+  @Get("/employee")
+  @Get("/employee/metrics")
+}
+```
+
+### Request/Response Patterns
+
+Required vs optional query parameters:
+
+```kotlin
+// Required parameter - no default, will fail if missing
+@Get("/employee")
+suspend fun getEmployee(
+  @QueryValue id: UUID  // Required - no ? nullable
+): EmployeeResponse
+
+// Optional parameters - nullable with defaults
+@Get("/employees")
+suspend fun listEmployees(
+  @QueryValue search: String?,      // Optional
+  @QueryValue status: String?,      // Optional
+  @QueryValue page: Int?,           // Optional, default in code
+  @QueryValue limit: Int?           // Optional, default in code
+): EmployeeListResponse {
+  val effectivePage = page ?: 1
+  val effectiveLimit = limit ?: 20
+  // ...
+}
+```
+
+Consistent pagination pattern:
+
+```kotlin
+// Request
+@Get("/employees")
+suspend fun listEmployees(
+  @QueryValue page: Int?,    // 1-based page number
+  @QueryValue limit: Int?    // Items per page (max 100)
+)
+
+// Response
+data class EmployeeListResponse(
+  val items: List<EmployeeResponse>,
+  val total: Int,
+  val page: Int,
+  val limit: Int,
+  val hasMore: Boolean
+)
+```
+
+### Quick Reference
+
+| Rule | Example |
+|------|---------|
+| No path params | `@Get("/employee")` with `@QueryValue id` |
+| Plural for lists | `@Get("/employees")` |
+| Singular for single | `@Get("/employee")` |
+| Actions as sub-paths | `@Post("/employee/delete")` |
+| Query params for all IDs | `?id=xxx` not `/{id}` |
+
+---
+
+## Model Location
+
+### Rule: All API models live in `module-client` ONLY
+
+**NEVER duplicate request or response models across modules.**
+
+```
+module-client/src/main/kotlin/com/yourcompany/client/
+├── request/           # API request models
+│   ├── conversation/
+│   ├── message/
+│   └── {domain}/
+└── response/          # API response models
+    ├── conversation/
+    ├── message/
+    ├── attachment/
+    └── {domain}/
+```
+
+### NEVER create request/response models in module-api or module-impl
+
+```kotlin
+// WRONG:
+// module-communication/module-api/model/response/ConversationResponse.kt
+package com.yourcompany.communication.model.response
+data class ConversationResponse(...)  // DON'T DO THIS
+
+// CORRECT:
+// module-client/response/conversation/ConversationResponse.kt
+package com.yourcompany.client.response.conversation
+data class ConversationResponse(...)  // PUT IT HERE
+```
+
+### Import from module-client
+
+```kotlin
+// In ConversationManager.kt or any other file
+import com.yourcompany.client.response.conversation.ConversationResponse
+import com.yourcompany.client.request.conversation.CreateConversationRequest
+```
+
+### Add module-client dependency
+
+```gradle
+dependencies {
+  implementation(project(":module-client"))
+}
+```
+
+### Naming
+
+| Type | Pattern | Example |
+|------|---------|---------|
+| Response | `{Entity}Response` | `ConversationResponse` |
+| List response | `{Entity}ListResponse` | `ConversationListResponse` |
+| Item in list | `{Entity}Item` | `ConversationItem` |
+| Brief/summary | `{Entity}Brief` | `ContactBrief` |
+| Request | `{Action}{Entity}Request` | `CreateConversationRequest` |
+
+### Request Validation Annotations
+
+All required fields in request DTOs MUST have validation annotations:
+
+```kotlin
+import jakarta.validation.constraints.NotBlank
+import jakarta.validation.constraints.NotNull
+
+data class CreateItemRequest(
+  @field:NotBlank(message = "name is required")
+  val name: String,                                // String → @field:NotBlank
+
+  @field:NotNull(message = "amount is required")
+  val amount: BigDecimal,                          // Non-String → @field:NotNull
+
+  val note: String? = null                         // Optional → no annotation
+)
+```
+
+**Message format:** snake_case field name + " is required" (e.g., `"participant_id is required"`).
+
+Response DTOs do NOT need validation annotations.
+
+Why this matters:
+- Single source of truth
+- No sync issues between duplicates
+- Clear ownership
+- Easier refactoring
+
+---
+
+## Specs Must Include Frontend
+
+### Rule: Every spec that touches the UI MUST have a "Frontend Changes" section
+
+When writing a spec (`/spec`), if the feature touches anything the user sees, you MUST include:
+
+### What to put in the Frontend Changes section
+
+1. **Files to change** - List every frontend file that needs edits (components, types, API clients, pages)
+2. **TypeScript type changes** - Show the before/after for any type changes (interfaces, enums)
+3. **Component changes** - Describe what each component gains or loses:
+   - New UI elements (inputs, buttons, badges, columns)
+   - Where they go in the layout (which card, which section, before/after what)
+   - State management (new state? uses existing parent state?)
+4. **API client changes** - New methods on the API client, with function signature
+5. **UI behavior** - How the user interacts with the new stuff:
+   - What triggers actions (click, enter key, toggle)
+   - Validation (what's rejected, what error shows)
+   - Save flow (which button, which API call)
+   - Default values for new fields
+
+### When does this apply?
+
+- New API endpoint that returns data shown in UI
+- Changes to existing API response shape (new fields)
+- New config/settings the admin can change
+- Any feature the user mentioned UI/UX for
+
+### When does this NOT apply?
+
+- Pure backend changes (scheduler fixes, sync logic, internal refactors)
+- Features with no UI component at all
+
+### Why this rule exists
+
+Frontend gets forgotten in specs. Then during implementation, the FE work is vague and inconsistent. Specifying FE changes upfront means:
+- The plan phase knows exactly which FE files to touch
+- The implementation team doesn't have to guess UI layout
+- Type changes are designed alongside API changes (no mismatches)

package/rules/backend-micronaut/BATCH_PROCESSING.md

@@ -0,0 +1,92 @@
+# Batch Processing Patterns
+
+## Core Rule
+
+Any operation that processes a dataset that could grow beyond memory MUST use chunked pagination with safety guards.
+
+---
+
+## The Pattern
+
+```kotlin
+companion object {
+  const val CHUNK_SIZE = 500
+  const val MAX_CHUNKS = 100  // Prevents infinite loops / OOM
+}
+
+suspend fun processAllUsers(action: suspend (User) -> Unit): BatchResult {
+  var offset = 0
+  var chunksProcessed = 0
+  val failures = mutableListOf<BatchFailure>()
+
+  while (chunksProcessed < MAX_CHUNKS) {
+    val chunk = userRepository.findAll(limit = CHUNK_SIZE, offset = offset)
+    if (chunk.isEmpty()) break
+
+    chunk.forEach { user ->
+      runCatching { action(user) }
+        .onFailure { e ->
+          logger.warn("Failed to process user ${user.id}", e)
+          failures.add(BatchFailure(userId = user.id, error = e.message))
+        }
+    }
+
+    if (chunk.size < CHUNK_SIZE) break  // Last page
+    offset += CHUNK_SIZE
+    chunksProcessed++
+  }
+
+  return BatchResult(processed = offset, failures = failures)
+}
+```
+
+---
+
+## Rules
+
+- Always define `CHUNK_SIZE` and `MAX_CHUNKS` as named constants (see KOTLIN.md § No Magic Numbers)
+- `MAX_CHUNKS` guard prevents runaway loops if the dataset keeps growing
+- Early exit when `chunk.size < CHUNK_SIZE` (last page)
+- Never `findAll()` without limit — always paginate
+- Log + collect failures per item, don't abort the whole batch for one bad record
+- Return a result with failure count so the caller can decide
+- Small fixed-size lists (< 100 items) don't need chunking
+
+---
+
+## Cancellation Check
+
+For long-running jobs, check cancellation inside the loop:
+
+```kotlin
+while (chunksProcessed < MAX_CHUNKS) {
+  if (context.isCancelled(selfId, initiatorId)) {
+    logger.info("Batch cancelled after $chunksProcessed chunks")
+    break
+  }
+  // ... process chunk
+}
+```
+
+---
+
+## Bad Patterns
+
+```kotlin
+// WRONG — loads entire table into memory
+val allUsers = userRepository.findAll()  // 2M users → OOM
+allUsers.forEach { sendEmail(it) }
+
+// WRONG — no safety limit
+var offset = 0
+while (true) {  // Never terminates if new records keep appearing
+  val chunk = repo.findAll(limit = 500, offset = offset)
+  if (chunk.isEmpty()) break
+  offset += 500
+}
+
+// WRONG — one bad record kills the whole batch
+chunk.forEach { user ->
+  action(user)  // Throws on user #47 → users #48-500 never processed
+}
+```