@c0x12c/ai-toolkit 1.15.0

package/rules/ux-design/DESIGN_PROCESS.md

@@ -0,0 +1,176 @@
+# Design Process Rules
+
+## The 7-Phase Workflow
+
+World-class design follows this order. Don't skip to pixels before understanding the problem.
+
+| Phase | What | Output |
+|-------|------|--------|
+| 1. Research | User interviews, competitor audit, data analysis | `design/research/insights.md` |
+| 2. Define | Problem statement, personas, journey map, scope | `design/definition/brief.md` |
+| 3. Ideate | Brainstorm solutions, user flows, information architecture | `design/ideation/flows.md` |
+| 4. Design System | Tokens (color, type, spacing), component inventory | `design/system/tokens.md` |
+| 5. Prototype | Screen design, all states, responsive, motion, accessibility | `design/screens/{feature}.md` |
+| 6. Test | Usability testing plan, findings, severity ratings | `design/test-results.md` |
+| 7. Handoff + QA | Dev specs, implementation checklist, design QA | Updated screen files |
+
+## Time Allocation Rule
+
+| Phase | Average team | World-class team |
+|-------|-------------|-----------------|
+| Research + Define | 10% | 40% |
+| Ideate | 10% | 10% |
+| Design + Prototype | 50% | 25% |
+| Test | 10% | 15% |
+| Handoff | 15% | 5% (design system handles it) |
+| Iterate | 5% | ongoing |
+
+**Rule:** Spend at least 30% of design time BEFORE opening any design tool. Understand the problem first.
+
+---
+
+## Design Token Rules
+
+### Tokens Are the Source of Truth
+
+Once design tokens exist in `.planning/design/system/tokens.md` or `.planning/design-config.md`, they are BINDING.
+
+**FORBIDDEN:**
+- Using Tailwind color defaults (`bg-blue-500`, `bg-purple-600`) when project tokens exist
+- Using generic fonts (`Inter`, `Roboto`, `Arial`, `system-ui`) when project font is defined
+- Using arbitrary spacing (`p-[13px]`, `mt-[7px]`) when spacing scale exists
+- Inventing new colors or fonts not in the token list
+
+**REQUIRED:**
+- Read tokens BEFORE generating any UI code
+- Use token names or CSS variables, not raw hex values
+- Follow the spacing grid (4px or 8px base)
+- Use project border radius, not generic `rounded-lg`
+
+### Token Format
+
+Tokens file must include these sections:
+
+```markdown
+## Colors
+| Role | Token | Value | Usage |
+|------|-------|-------|-------|
+| Primary | --color-primary | #hex | Buttons, links, active states |
+| ... | ... | ... | ... |
+
+## Typography
+- Font family: [name]
+- Scale: h1 (32px/700) → h6 (14px/600) → body (16px/400) → caption (12px/400)
+
+## Spacing
+- Base: [4px or 8px]
+- Scale: xs (4) / sm (8) / md (16) / lg (24) / xl (32) / 2xl (48)
+
+## Radius
+- Card: [value]
+- Button: [value]
+- Badge: [value]
+
+## Shadows
+- sm: [value]
+- md: [value]
+- lg: [value]
+```
+
+---
+
+## Design All States
+
+Every screen and component MUST design these states:
+
+| State | What to show |
+|-------|-------------|
+| Default | Normal, populated view |
+| Loading | Skeleton screen or spinner |
+| Empty | Helpful message + action prompt |
+| Error | Friendly message + recovery action |
+| Success | Confirmation feedback |
+| Edge case | Long text, missing data, single item, 100+ items |
+
+**FORBIDDEN:** Designing only the happy path. If you don't design the empty state, the developer will show a blank screen.
+
+---
+
+## Responsive Breakpoints
+
+Every screen must work at these widths:
+
+| Breakpoint | Width | Device |
+|-----------|-------|--------|
+| Mobile | 375px | iPhone SE / small Android |
+| Tablet | 768px | iPad / medium screens |
+| Desktop | 1440px | Standard laptop/desktop |
+
+**FORBIDDEN:** Designing only for desktop. Mobile-first or at least mobile-aware.
+
+---
+
+## Accessibility Checklist
+
+Every design must pass:
+
+- [ ] Color contrast: 4.5:1 minimum for normal text, 3:1 for large text
+- [ ] Touch targets: 44x44px minimum on mobile
+- [ ] Keyboard navigation: tab order matches visual order
+- [ ] Focus states: visible focus ring on all interactive elements
+- [ ] Screen reader: all images have alt text, icon buttons have aria-label
+- [ ] Color not sole indicator: don't use color alone to show status
+- [ ] Motion: respect `prefers-reduced-motion`
+
+---
+
+## Anti-AI-Generic Rules
+
+Designs MUST avoid these generic AI patterns:
+
+**Colors:**
+- No purple/violet gradients on white backgrounds
+- No neon accent colors on dark backgrounds
+- No gray-on-gray low-contrast layouts
+- Use the PROJECT'S accent color, not a random one
+
+**Layout:**
+- Break the grid sometimes — asymmetry over centered-everything
+- No blob/wave backgrounds unless that's the brand
+- Cards should have visual variety, not all identical rectangles
+
+**Typography:**
+- Clear hierarchy: big headlines, medium subheads, small body
+- Font weight contrast matters — don't use 400 for everything
+- Real copy, not "Lorem ipsum" or "Unlock your potential"
+
+**Components:**
+- Button hierarchy: one primary, rest secondary/ghost
+- Not every feature needs an icon
+- Empty states should feel designed, not like a bug
+
+---
+
+## Folder Structure
+
+All design artifacts live in `.planning/design/`:
+
+```
+.planning/design/
+├── research/
+│   ├── interviews.md        ← User interview notes + synthesis
+│   ├── competitors.md       ← Competitor audit
+│   └── insights.md          ← Key findings, "How Might We" questions
+├── definition/
+│   ├── personas.md          ← 2-3 behavior-based personas
+│   ├── journey-map.md       ← Current user journey with pain points
+│   └── brief.md             ← Problem statement, success metrics, scope
+├── ideation/
+│   ├── ideas.md             ← Brainstorm output, ranked ideas
+│   └── flows.md             ← User flows, information architecture
+├── system/
+│   ├── tokens.md            ← Color, typography, spacing tokens
+│   └── components.md        ← Component inventory with specs
+└── screens/
+    └── {feature-name}.md    ← Per-feature screen designs
+```

package/skills/api-endpoint-creator/SKILL.md

@@ -0,0 +1,455 @@
+---
+name: api-endpoint-creator
+description: Creates RPC-style endpoint following layered architecture (Controller → Manager → Repository). Use when creating new API endpoints or CRUD operations.
+allowed_tools:
+  - Read
+  - Write
+  - Edit
+  - Glob
+  - Grep
+---
+
+# API Endpoint Creator Skill
+
+Creates complete RPC-style API endpoints following strict layered architecture patterns.
+
+## When to Use
+
+- Creating a new REST API endpoint from scratch
+- Adding CRUD operations for a new domain entity
+- Setting up the full stack: Controller → Manager → Repository → Tests
+- Need a Retrofit client for integration testing
+
+## Process
+
+### 1. Create Response/Request Models
+
+Location: `app/module-client/src/main/kotlin/com/yourcompany/client/response/{domain}/`
+
+```kotlin
+package com.yourcompany.client.response.{domain}
+
+import com.yourcompany.postgresql.entity.{Domain}Entity
+import java.time.Instant
+import java.util.UUID
+
+data class {Domain}Response(
+  val id: UUID,
+  val name: String,
+  val status: String,
+  val createdAt: Instant,
+  val updatedAt: Instant?
+) {
+  companion object {
+    fun from(entity: {Domain}Entity): {Domain}Response = {Domain}Response(
+      id = entity.id,
+      name = entity.name,
+      status = entity.status,
+      createdAt = entity.createdAt,
+      updatedAt = entity.updatedAt
+    )
+  }
+}
+
+data class {Domain}ListResponse(
+  val items: List<{Domain}Response>,
+  val total: Int,
+  val page: Int,
+  val limit: Int,
+  val hasMore: Boolean
+)
+```
+
+Location: `app/module-client/src/main/kotlin/com/yourcompany/client/request/{domain}/`
+
+```kotlin
+package com.yourcompany.client.request.{domain}
+
+data class Create{Domain}Request(
+  val name: String,
+  val description: String? = null
+)
+
+data class Update{Domain}Request(
+  val name: String? = null,
+  val description: String? = null,
+  val status: String? = null
+)
+```
+
+**Key**: All models in module-client, never in controllers or managers.
+
+### 2. Create Controller
+
+Location: `app/api-application/src/main/kotlin/com/yourcompany/controller/{Domain}Controller.kt`
+
+```kotlin
+package com.yourcompany.controller
+
+import com.yourcompany.{domain}.contract.{Domain}Manager
+import com.yourcompany.client.request.{domain}.Create{Domain}Request
+import com.yourcompany.client.request.{domain}.Update{Domain}Request
+import com.yourcompany.client.response.{domain}.{Domain}Response
+import com.yourcompany.client.response.{domain}.{Domain}ListResponse
+import com.yourcompany.exception.throwOrValue
+import io.micronaut.http.annotation.*
+import io.micronaut.scheduling.TaskExecutors
+import io.micronaut.scheduling.annotation.ExecuteOn
+import io.micronaut.security.annotation.Secured
+import io.micronaut.validation.Validated
+import io.swagger.v3.oas.annotations.tags.Tag
+import jakarta.validation.Valid
+import java.util.UUID
+
+@ExecuteOn(TaskExecutors.IO)
+@Validated
+@Controller("/api/v1/{domain}")
+@Tag(name = "{Domain}", description = "{Domain} API")
+@Secured(SecurityRule.IS_AUTHENTICATED)
+class {Domain}Controller(
+  private val {domain}Manager: {Domain}Manager
+) {
+
+  @Get("/{domain}s")
+  suspend fun list(
+    @QueryValue page: Int?,
+    @QueryValue limit: Int?,
+    @QueryValue status: String?
+  ): {Domain}ListResponse {
+    return {domain}Manager.list(
+      page = page ?: 1,
+      limit = limit ?: 20,
+      status = status
+    ).throwOrValue()
+  }
+
+  @Get("/{domain}")
+  suspend fun getById(
+    @QueryValue id: UUID
+  ): {Domain}Response {
+    return {domain}Manager.byId(id).throwOrValue()
+  }
+
+  @Post("/{domain}")
+  suspend fun create(
+    @Valid @Body request: Create{Domain}Request
+  ): {Domain}Response {
+    return {domain}Manager.create(request).throwOrValue()
+  }
+
+  @Post("/{domain}/update")
+  suspend fun update(
+    @QueryValue id: UUID,
+    @Valid @Body request: Update{Domain}Request
+  ): {Domain}Response {
+    return {domain}Manager.update(id, request).throwOrValue()
+  }
+
+  @Post("/{domain}/delete")
+  suspend fun delete(
+    @QueryValue id: UUID
+  ): Boolean {
+    return {domain}Manager.deleteById(id).throwOrValue()
+  }
+}
+```
+
+**Key Points**:
+- `@ExecuteOn(TaskExecutors.IO)` required for suspend functions
+- Query params for ALL identifiers (`@QueryValue id: UUID`)
+- Thin methods - just delegate to manager
+- `.throwOrValue()` to unwrap Either
+- Inject Manager only (never Repository)
+- NO inline data classes
+
+### 3. Create Manager Interface
+
+Location: `app/module-{domain}/module-api/src/main/kotlin/com/yourcompany/{domain}/contract/{Domain}Manager.kt`
+
+```kotlin
+package com.yourcompany.{domain}.contract
+
+import arrow.core.Either
+import com.yourcompany.client.request.{domain}.Create{Domain}Request
+import com.yourcompany.client.request.{domain}.Update{Domain}Request
+import com.yourcompany.client.response.{domain}.{Domain}Response
+import com.yourcompany.client.response.{domain}.{Domain}ListResponse
+import com.yourcompany.exception.ClientException
+import java.util.UUID
+
+interface {Domain}Manager {
+  suspend fun list(
+    page: Int,
+    limit: Int,
+    status: String?
+  ): Either<ClientException, {Domain}ListResponse>
+
+  suspend fun byId(id: UUID): Either<ClientException, {Domain}Response>
+
+  suspend fun create(
+    request: Create{Domain}Request
+  ): Either<ClientException, {Domain}Response>
+
+  suspend fun update(
+    id: UUID,
+    request: Update{Domain}Request
+  ): Either<ClientException, {Domain}Response>
+
+  suspend fun deleteById(id: UUID): Either<ClientException, Boolean>
+}
+```
+
+### 4. Create Manager Implementation
+
+Location: `app/module-{domain}/module-impl/src/main/kotlin/com/yourcompany/{domain}/impl/Default{Domain}Manager.kt`
+
+```kotlin
+package com.yourcompany.{domain}.impl
+
+import arrow.core.Either
+import arrow.core.left
+import arrow.core.right
+import com.yourcompany.database.DatabaseContext
+import com.yourcompany.{domain}.contract.{Domain}Manager
+import com.yourcompany.client.request.{domain}.Create{Domain}Request
+import com.yourcompany.client.request.{domain}.Update{Domain}Request
+import com.yourcompany.client.response.{domain}.{Domain}Response
+import com.yourcompany.client.response.{domain}.{Domain}ListResponse
+import com.yourcompany.exception.ClientError
+import com.yourcompany.exception.ClientException
+import com.yourcompany.postgresql.entity.{Domain}Entity
+import com.yourcompany.postgresql.repository.{Domain}Repository
+import org.jetbrains.exposed.sql.transactions.transaction
+import java.util.UUID
+
+class Default{Domain}Manager(
+  private val {domain}Repository: {Domain}Repository,
+  private val db: DatabaseContext
+) : {Domain}Manager {
+
+  override suspend fun byId(id: UUID): Either<ClientException, {Domain}Response> {
+    val entity = {domain}Repository.byId(id)
+      ?: return ClientError.{DOMAIN}_NOT_FOUND.asException().left()
+
+    return {Domain}Response.from(entity).right()
+  }
+
+  override suspend fun create(
+    request: Create{Domain}Request
+  ): Either<ClientException, {Domain}Response> {
+    val entity = {Domain}Entity(
+      name = request.name,
+      description = request.description
+    )
+
+    val inserted = transaction(db.primary) {
+      {domain}Repository.insert(entity)
+    }
+
+    return {Domain}Response.from(inserted).right()
+  }
+
+  override suspend fun update(
+    id: UUID,
+    request: Update{Domain}Request
+  ): Either<ClientException, {Domain}Response> {
+    val existing = {domain}Repository.byId(id)
+      ?: return ClientError.{DOMAIN}_NOT_FOUND.asException().left()
+
+    val updated = transaction(db.primary) {
+      {domain}Repository.update(
+        id = id,
+        name = request.name,
+        description = request.description,
+        status = request.status
+      )
+    } ?: return ClientError.{DOMAIN}_NOT_FOUND.asException().left()
+
+    return {Domain}Response.from(updated).right()
+  }
+
+  override suspend fun deleteById(id: UUID): Either<ClientException, Boolean> {
+    val deleted = transaction(db.primary) {
+      {domain}Repository.deleteById(id)
+    }
+
+    return if (deleted != null) {
+      true.right()
+    } else {
+      ClientError.{DOMAIN}_NOT_FOUND.asException().left()
+    }
+  }
+}
+```
+
+**Key Points**:
+- Use `{Domain}Response.from(entity)` for conversions (companion object pattern)
+- `transaction(db.primary)` for writes
+- Return `Either.left()` for errors, `Either.right()` for success
+- NO `!!` operators
+
+### 5. Register Factory Bean
+
+Location: `app/module-{domain}/module-impl/src/main/kotlin/com/yourcompany/runtime/factory/{Domain}ManagerFactory.kt`
+
+```kotlin
+package com.yourcompany.runtime.factory
+
+import com.yourcompany.database.DatabaseContext
+import com.yourcompany.{domain}.impl.Default{Domain}Manager
+import com.yourcompany.{domain}.contract.{Domain}Manager
+import com.yourcompany.postgresql.repository.{Domain}Repository
+import io.micronaut.context.annotation.Factory
+import jakarta.inject.Singleton
+
+@Factory
+class {Domain}ManagerFactory {
+
+  @Singleton
+  fun provide{Domain}Manager(
+    {domain}Repository: {Domain}Repository,
+    db: DatabaseContext
+  ): {Domain}Manager {
+    return Default{Domain}Manager({domain}Repository, db)
+  }
+}
+```
+
+### 6. Create Retrofit Client
+
+Location: `app/module-client/src/main/kotlin/com/yourcompany/client/{Domain}Client.kt`
+
+```kotlin
+package com.yourcompany.client
+
+import com.yourcompany.client.request.{domain}.Create{Domain}Request
+import com.yourcompany.client.request.{domain}.Update{Domain}Request
+import com.yourcompany.client.response.{domain}.{Domain}Response
+import com.yourcompany.client.response.{domain}.{Domain}ListResponse
+import retrofit2.http.*
+import java.util.UUID
+
+interface {Domain}Client {
+
+  @GET("/api/v1/{domain}s")
+  suspend fun list(
+    @Header("Authorization") authorization: String,
+    @Query("page") page: Int? = null,
+    @Query("limit") limit: Int? = null,
+    @Query("status") status: String? = null
+  ): {Domain}ListResponse
+
+  @GET("/api/v1/{domain}")
+  suspend fun getById(
+    @Header("Authorization") authorization: String,
+    @Query("id") id: UUID
+  ): {Domain}Response
+
+  @POST("/api/v1/{domain}")
+  suspend fun create(
+    @Header("Authorization") authorization: String,
+    @Body request: Create{Domain}Request
+  ): {Domain}Response
+
+  @POST("/api/v1/{domain}/update")
+  suspend fun update(
+    @Header("Authorization") authorization: String,
+    @Query("id") id: UUID,
+    @Body request: Update{Domain}Request
+  ): {Domain}Response
+
+  @POST("/api/v1/{domain}/delete")
+  suspend fun delete(
+    @Header("Authorization") authorization: String,
+    @Query("id") id: UUID
+  ): Boolean
+}
+```
+
+### 7. Create Integration Test
+
+Location: `app/api-application/src/test/kotlin/com/yourcompany/{Domain}ControllerTest.kt`
+
+> See `testing-patterns.md` for complete test examples.
+
+### 8. Run Tests
+
+```bash
+./gradlew :app:api-application:test --tests "{Domain}ControllerTest"
+./gradlew test
+```
+
+## Interaction Style
+
+- Always generates the full stack: models, controller, manager, factory, client, tests
+- Follows the project's exact patterns — no shortcuts or creative alternatives
+- Uses query parameters for all IDs, never path parameters
+- Asks which domain entity before starting if not clear from context
+
+## Rules
+
+### RPC-Style API (POST for Mutations, Query Params Only)
+
+This project uses **RPC-style endpoints: @Get for reads, @Post for all mutations, query parameters for all IDs**:
+
+```
+GET  /api/v1/employees              # List employees (plural)
+GET  /api/v1/employee               # Get one employee (?id=xxx)
+POST /api/v1/employee               # Create employee
+POST /api/v1/employee/update        # Update employee
+POST /api/v1/employee/delete        # Delete employee (soft)
+```
+
+**Rules from API_RULES.md:**
+- NEVER use path parameters (`/{id}`)
+- Use query parameters: `@QueryValue id: UUID`
+- Singular nouns for single resource, plural for collections
+- Use verb sub-paths for actions (`/delete`, `/restore`)
+
+### Layered Architecture
+
+```
+HTTP Request → Controller → Manager → Repository → Database
+```
+
+**Controller**: Thin (just delegation), HTTP annotations, @ExecuteOn(TaskExecutors.IO), @Secured, unwrap Either with `.throwOrValue()`
+
+**Manager**: All business logic, returns `Either<ClientException, T>`, wraps DB operations in transactions, never throws exceptions
+
+**Repository**: Data access only (already exists)
+
+### NO !! Operator
+
+```kotlin
+val employee = employeeRepository.byId(id)
+  ?: return ClientError.EMPLOYEE_NOT_FOUND.asException().left()
+```
+
+### Error Handling Patterns
+
+#### Not Found
+```kotlin
+val entity = repository.byId(id)
+  ?: return ClientError.{DOMAIN}_NOT_FOUND.asException().left()
+```
+
+#### Already Exists
+```kotlin
+val existing = repository.byEmail(email)
+if (existing != null) {
+  return ClientError.EMAIL_ALREADY_IN_USE.asException().left()
+}
+```
+
+## Output
+
+- Controller is thin (just delegation)
+- Controller has `@ExecuteOn(TaskExecutors.IO)`
+- NO path parameters (use `@QueryValue` for all IDs)
+- Manager returns Either (never throws)
+- Transactions wrap DB operations
+- No `!!` operator
+- Response models in module-client with `companion object { fun from() }`
+- NO inline data classes in controllers
+- Integration tests use Retrofit client
+- All tests pass