@c0x12c/ai-toolkit 1.15.0

package/skills/api-endpoint-creator/testing-patterns.md

@@ -0,0 +1,302 @@
+# API Endpoint Testing Patterns
+
+How to write integration tests for API endpoints in the platform.
+
+---
+
+## Test Structure
+
+```
+Integration Test (Controller)
+    -> Retrofit HTTP Client
+    -> Actual HTTP Request
+    -> Controller -> Manager -> Repository -> Database
+    -> HTTP Response
+    -> Assertions
+```
+
+Integration tests check the full stack works together.
+
+---
+
+## Base Test Class
+
+All controller tests extend `AbstractControllerTest`:
+
+```kotlin
+@MicronautTest(environments = ["test"], transactional = false)
+@TestInstance(TestInstance.Lifecycle.PER_CLASS)
+class ProjectControllerTest : AbstractControllerTest() {
+
+  private lateinit var projectClient: ProjectClient
+
+  @BeforeAll
+  override fun beforeAll() {
+    val url = embeddedServer.url.toString()
+    val jackson = ObjectMapper().configured()
+    val retrofit = Retrofits
+      .newBuilder(url = url.toHttpUrl(), jackson = jackson)
+      .build()
+
+    projectClient = retrofit.create(ProjectClient::class.java)
+  }
+
+  @AfterEach
+  fun cleanupAfterEach() {
+    database.primary.truncateAllTables()
+  }
+}
+```
+
+**Key Points**:
+- `@MicronautTest(environments = ["test"])` - Use test environment
+- `@TestInstance(Lifecycle.PER_CLASS)` - Reuse test instance
+- Extend `AbstractControllerTest` for utilities
+- Create Retrofit client in `@BeforeAll`
+- Clean database in `@AfterEach`
+
+---
+
+## Retrofit Client
+
+**File**: `app/module-client/src/main/kotlin/com/yourcompany/client/ProjectClient.kt`
+
+```kotlin
+package com.yourcompany.client
+
+import com.yourcompany.client.request.{domain}.CreateProjectRequest
+import com.yourcompany.client.response.{domain}.ProjectResponse
+import com.yourcompany.client.response.{domain}.ProjectListResponse
+import retrofit2.http.*
+import java.util.UUID
+
+interface ProjectClient {
+
+  @GET("/api/v1/admin/projects")
+  suspend fun listProjects(
+    @Header("Authorization") authorization: String,
+    @Query("page") page: Int? = null,
+    @Query("limit") limit: Int? = null
+  ): ProjectListResponse
+
+  @GET("/api/v1/admin/project")
+  suspend fun getProject(
+    @Header("Authorization") authorization: String,
+    @Query("id") id: UUID
+  ): ProjectResponse
+
+  @POST("/api/v1/admin/project")
+  suspend fun createProject(
+    @Header("Authorization") authorization: String,
+    @Body request: CreateProjectRequest
+  ): ProjectResponse
+
+  @POST("/api/v1/admin/project/delete")
+  suspend fun deleteProject(
+    @Header("Authorization") authorization: String,
+    @Query("id") id: UUID
+  ): Boolean
+}
+```
+
+---
+
+## Test Pattern 1: Happy Path
+
+```kotlin
+@Test
+fun `getProject - returns project when exists`() = runBlocking {
+  val project = createTestProject()
+  val token = accessToken(prepareUser(), UserRole.ADMIN)
+
+  val response = projectClient.getProject(
+    authorization = token,
+    id = project.id
+  )
+
+  assertThat(response.id).isEqualTo(project.id)
+  assertThat(response.name).isEqualTo(project.name)
+}
+```
+
+## Test Pattern 2: Not Found (404)
+
+```kotlin
+@Test
+fun `getProject - returns 404 when not found`() = runBlocking {
+  val token = accessToken(prepareUser(), UserRole.ADMIN)
+
+  val exception = assertThrows<HttpException> {
+    runBlocking {
+      projectClient.getProject(
+        authorization = token,
+        id = UUID.randomUUID()
+      )
+    }
+  }
+
+  assertThat(exception.code()).isEqualTo(404)
+}
+```
+
+## Test Pattern 3: Authentication (401)
+
+```kotlin
+@Test
+fun `should return 401 when not authenticated`() = runBlocking {
+  val exception = assertThrows<HttpException> {
+    runBlocking {
+      projectClient.getProject(
+        authorization = "",
+        id = UUID.randomUUID()
+      )
+    }
+  }
+
+  assertThat(exception.code()).isEqualTo(401)
+}
+```
+
+## Test Pattern 4: Create and Verify
+
+```kotlin
+@Test
+fun `createProject - creates project successfully`() = runBlocking {
+  val token = accessToken(prepareUser(), UserRole.ADMIN)
+  val request = CreateProjectRequest(
+    name = "Test Project",
+    description = "A test project"
+  )
+
+  val response = projectClient.createProject(
+    authorization = token,
+    request = request
+  )
+
+  assertThat(response.name).isEqualTo("Test Project")
+  assertThat(response.description).isEqualTo("A test project")
+
+  // Verify in database
+  val saved = projectRepository.byId(response.id)
+  assertThat(saved).isNotNull
+  assertThat(saved?.name).isEqualTo("Test Project")
+}
+```
+
+## Test Pattern 5: List with Pagination
+
+```kotlin
+@Test
+fun `listProjects - returns paginated results`() = runBlocking {
+  createTestProject(name = "Project A")
+  createTestProject(name = "Project B")
+  createTestProject(name = "Project C")
+
+  val token = accessToken(prepareUser(), UserRole.ADMIN)
+
+  val response = projectClient.listProjects(
+    authorization = token,
+    page = 1,
+    limit = 2
+  )
+
+  assertThat(response.items).hasSize(2)
+  assertThat(response.total).isEqualTo(3)
+  assertThat(response.hasMore).isTrue()
+}
+```
+
+## Test Pattern 6: Soft Delete
+
+```kotlin
+@Test
+fun `deleteProject - soft deletes project`() = runBlocking {
+  val project = createTestProject()
+  val token = accessToken(prepareUser(), UserRole.ADMIN)
+
+  val result = projectClient.deleteProject(
+    authorization = token,
+    id = project.id
+  )
+
+  assertThat(result).isTrue()
+
+  // Verify not returned by queries
+  val exception = assertThrows<HttpException> {
+    runBlocking {
+      projectClient.getProject(authorization = token, id = project.id)
+    }
+  }
+  assertThat(exception.code()).isEqualTo(404)
+}
+```
+
+---
+
+## Test Helper Patterns
+
+```kotlin
+private val projectRepository: ProjectRepository by lazy {
+  DefaultProjectRepository(database)
+}
+
+private fun createTestProject(
+  name: String = "Test Project ${UUID.randomUUID()}",
+  description: String? = "Test description",
+  status: String = "active"
+): ProjectEntity {
+  return projectRepository.insert(
+    ProjectEntity(
+      name = name,
+      description = description,
+      status = status
+    )
+  )
+}
+```
+
+**Utility methods from `AbstractControllerTest`**:
+- `prepareUser(email, displayName, role)` - Create test user
+- `accessToken(user, role)` - Generate JWT token
+- `database` - DatabaseContext for direct DB access
+
+---
+
+## Test Scenarios Checklist
+
+For each endpoint, test:
+
+### Create
+- [ ] Happy path succeeds
+- [ ] Returns created resource
+- [ ] Resource exists in database
+- [ ] Requires authentication (401)
+
+### Read (Get by ID)
+- [ ] Returns resource when exists (200)
+- [ ] Returns 404 when not found
+- [ ] Requires authentication (401)
+
+### List
+- [ ] Returns paginated results
+- [ ] Pagination works (page/limit)
+- [ ] Returns empty list when no results
+- [ ] Requires authentication (401)
+
+### Delete
+- [ ] Soft deletes successfully
+- [ ] Resource not returned after deletion
+- [ ] Returns 404 when not found
+- [ ] Requires authentication (401)
+
+---
+
+## Best Practices
+
+1. **Isolation**: Clean database between tests (`@AfterEach`)
+2. **Random data**: Use UUIDs in names to avoid conflicts
+3. **AssertJ**: Use `assertThat` for readable assertions
+4. **Given/When/Then**: Structure tests clearly
+5. **Verify database**: Don't just check the response
+6. **Auth tests**: Always test with and without auth
+7. **Use Retrofit clients**: Never raw HttpRequest for API tests

package/skills/article-writing/SKILL.md

@@ -0,0 +1,109 @@
+---
+name: article-writing
+description: Write blog posts, guides, tutorials, and long-form content. Sounds like a real person, not AI. Use when the user wants polished written content.
+allowed_tools:
+  - Read
+  - Write
+  - WebSearch
+---
+
+# Article Writing
+
+Write long-form content that sounds like a person wrote it.
+
+## When to Use
+
+- Blog posts, essays, guides, tutorials
+- Turning notes or research into an article
+- Matching an existing voice from examples
+- Cleaning up and tightening existing writing
+
+> See `examples.md` for good vs bad writing examples that show what "sounds human" actually means.
+
+## Rules
+
+1. Start with something concrete: example, number, story, or code block.
+2. Explain after the example, not before.
+3. Short, direct sentences.
+4. Use real numbers when you have them.
+5. Never make up facts, company data, or quotes.
+
+## Banned Patterns
+
+Delete and rewrite any of these:
+- "In today's rapidly evolving landscape"
+- "Moreover", "Furthermore", "Additionally"
+- "game-changer", "cutting-edge", "revolutionary"
+- Vague claims with no proof
+- Bio claims you can't back up
+
+## Writing Process
+
+1. Know the audience and goal
+2. Outline: one purpose per section
+3. Start each section with evidence or example
+4. Only keep sentences that earn their spot
+5. Cut anything that sounds like a template
+
+## Structure Tips
+
+### Technical Guides
+- Open with what the reader gets
+- Code or terminal examples in every section
+- End with real takeaways, not soft summary
+
+### Essays / Opinion
+- Start with tension or a sharp point
+- One argument per section
+- Back opinions with examples
+
+### Newsletters
+- First screen must be strong
+- Mix insight with updates
+- Clear section labels, easy to skim
+
+## Interaction Style
+
+**No BS. Honest feedback only.**
+
+This is a two-way talk:
+- I ask you questions → you answer
+- You ask me questions → I think hard, give you options, then answer
+
+**When I ask you a question, I always:**
+1. Think about it first
+2. Give you 2-3 options with my honest take on each
+3. Tell you which one I'd pick and why
+4. Then ask what you think
+
+**When you ask me something:**
+- I give you a straight answer
+- I tell you if a section is boring, weak, or filler
+- I push for real examples over vague claims
+
+**Never:**
+- Ask a question without giving options
+- Let filler paragraphs stay in the draft
+- Say "it depends" without picking a side
+- Skip the "this part is weak" feedback
+- Write AI-sounding content and call it done
+
+## Gotchas
+
+- **The intro is where most articles die.** If the first paragraph starts with "In this article, we'll explore..." — delete it and start with a story, stat, or code block.
+- **AI-written articles all sound the same.** They hedge ("it's important to note"), use transition words nobody says out loud ("Moreover"), and avoid strong opinions. Cut all of that.
+- **Don't explain the obvious.** If your audience is developers, don't explain what an API is. Write for the person, not the lowest common denominator.
+- **Long ≠ thorough.** A 3,000-word article with 1,500 words of filler is worse than a 1,500-word article where every sentence earns its spot.
+- **Every section needs evidence.** A claim without a number, example, or code block is just an opinion. Back it up or cut it.
+
+## Before You Deliver
+
+- Facts match sources
+- No filler or corporate talk
+- Voice matches examples (if given)
+- Every section adds something new
+- Format fits the platform
+
+## Output
+
+Save to the project's research or build folder depending on context.

package/skills/article-writing/examples.md

@@ -0,0 +1,59 @@
+# Article Writing — Good vs Bad Examples
+
+> Read these examples to calibrate your writing style. The "bad" versions are typical AI output. The "good" versions sound like a person wrote them.
+
+## Intro Paragraphs
+
+### Bad (AI-style)
+> In today's rapidly evolving technological landscape, the importance of effective error handling cannot be overstated. This comprehensive guide will walk you through the various aspects of implementing robust error handling strategies in your Kotlin applications, enabling you to build more resilient and maintainable software systems.
+
+### Good (human-style)
+> Last Tuesday, our payment service threw 4,000 unhandled exceptions in 20 minutes. The fix was 3 lines of code. Here's what went wrong and how to make sure it doesn't happen to you.
+
+---
+
+## Explaining a Concept
+
+### Bad (AI-style)
+> Dependency injection is a crucial software design pattern that facilitates the development of loosely coupled, maintainable, and testable code. By leveraging this paradigm, developers can effectively manage the complex dependencies between various components of their application architecture.
+
+### Good (human-style)
+> Dependency injection means your class doesn't create its own dependencies — someone hands them in. Instead of `val db = Database()` inside your class, you write `class UserRepo(val db: Database)` and let the framework wire it up. That's it. The rest is details.
+
+---
+
+## Technical Guide Section
+
+### Bad (AI-style)
+> To implement this feature, you'll want to start by carefully considering the architectural implications. First, create a new service class that will handle the business logic. Then, implement the necessary repository methods. Finally, wire everything together in the controller layer. This approach ensures a clean separation of concerns.
+
+### Good (human-style)
+> Three files to create:
+> 1. `PaymentManager.kt` — validates the amount, calls Stripe, saves the record
+> 2. `PaymentRepository.kt` — insert and soft-delete methods
+> 3. `PaymentController.kt` — one POST endpoint, delegates to the manager
+>
+> Start with the manager. The other two are boilerplate.
+
+---
+
+## Transitions Between Sections
+
+### Bad (AI-style)
+> Now that we've explored the fundamentals of error handling, let's delve into the more advanced aspects of this topic. In the following section, we'll examine how to implement custom error types that can provide more granular control over your application's error handling mechanisms.
+
+### Good (human-style)
+> The basics work for 80% of cases. But when you need different error responses for different callers (API vs webhook vs internal), you need custom error types.
+
+---
+
+## Conclusions
+
+### Bad (AI-style)
+> In conclusion, we've covered a comprehensive overview of error handling patterns in Kotlin. By implementing these strategies, you'll be well-equipped to build robust, maintainable applications. Remember that error handling is not just about catching exceptions — it's about creating a resilient system that gracefully handles the unexpected.
+
+### Good (human-style)
+> Three things to remember:
+> 1. Return `Either`, don't throw. Your callers will thank you.
+> 2. Log the actual error, not a generic message.
+> 3. Test the error paths. They run more often than you think.

package/skills/backend-api-design/SKILL.md

@@ -0,0 +1,84 @@
+---
+name: backend-api-design
+description: Design RPC-style APIs with layered architecture (Controller → Manager → Repository). Use when creating new API endpoints, designing API contracts, or reviewing API patterns.
+allowed_tools:
+  - Read
+  - Write
+  - Edit
+  - Glob
+  - Grep
+---
+
+# Backend API Design — Quick Reference
+
+## URL Patterns
+
+```
+GET  /api/v1/employees              # List (plural)
+GET  /api/v1/employee               # Get one (?id=xxx)
+POST /api/v1/employee               # Create
+POST /api/v1/employee/update        # Update (?id=xxx)
+POST /api/v1/employee/delete        # Soft delete (?id=xxx)
+POST /api/v1/employee/restore       # Restore (?id=xxx)
+POST /api/v1/sync/employees         # Action
+```
+
+## Hard Rules
+
+- **NO path params** — always `@QueryValue`, never `@PathVariable`
+- **Singular for single resource** — `/employee` not `/employees/{id}`
+- **Plural for collections** — `/employees`
+- **Verb sub-paths for actions** — `/delete`, `/restore`, `/sync`
+
+## Layered Architecture
+
+```
+Controller  →  thin, just delegates
+    ↓
+Manager     →  business logic, transactions, Either returns
+    ↓
+Repository  →  data access only, no business logic
+```
+
+### Controller: Thin Wrapper
+- Parse query params with defaults
+- Delegate to manager
+- Unwrap Either with `.throwOrValue()`
+- NO business logic, NO repository access
+
+### Manager: Business Logic
+- Returns `Either<ClientException, T>`
+- Wraps DB ops in `transaction(db.primary) { }`
+- Orchestrates multiple repositories
+- Validates business rules
+
+### Repository: Data Access
+- Returns entities or null
+- `db.replica` for reads, `db.primary` for writes
+- Always checks `deletedAt.isNull()`
+
+## Quick Code Reference
+
+The core controller delegation pattern:
+
+```kotlin
+@Get("/employee")
+suspend fun getEmployee(@QueryValue id: UUID): EmployeeResponse {
+  return employeeManager.findById(id).throwOrValue()
+}
+```
+
+- **Response models** — `companion object { fun from(entity) }` in `module-client/response/{domain}/`
+- **Pagination** — offset-based, manager returns `EmployeeListResponse` with `items`, `total`, `page`, `limit`, `hasMore`
+- **Errors** — return `ClientError.NOT_FOUND.asException().left()` from managers, never throw
+- **Factory beans** — `@Factory` class with `@Singleton` method, wire repos + db into manager
+
+> See code-patterns.md for complete controller, response model, pagination, error handling, and factory bean templates.
+
+## Gotchas
+
+- **Multi-word `@QueryValue` params MUST have explicit snake_case names.** The frontend axios interceptor sends `project_id` but Micronaut matches the literal param name. Write `@QueryValue("project_id") projectId: UUID`, not bare `@QueryValue projectId: UUID`.
+- **Don't use `@Put`, `@Delete`, or `@Patch`.** This is RPC-style — all mutations are `@Post`. The only `@Get` is for reads.
+- **Controllers that inject repositories are a code smell.** If you see `private val fooRepository: FooRepository` in a controller, move it to the manager.
+- **`andWhere {}` not second `.where {}`.** Calling `.where {}` twice replaces the first condition. Use `.andWhere {}` to chain.
+- **Don't forget `@ExecuteOn(TaskExecutors.IO)`.** Without it, suspend functions may hang or run on the wrong thread pool. Every controller needs it.

package/skills/backend-api-design/code-patterns.md

@@ -0,0 +1,138 @@
+# API Design — Code Patterns
+
+> This file is referenced by SKILL.md. Read it when implementing actual endpoints.
+
+## Controller Template
+
+```kotlin
+@ExecuteOn(TaskExecutors.IO)    // REQUIRED for suspend
+@Validated
+@Controller("/api/v1/admin")
+@Secured(OAuthSecurityRule.ADMIN)
+class EmployeeController(
+  private val employeeManager: EmployeeManager  // Managers ONLY
+) {
+  @Get("/employee")
+  suspend fun getEmployee(@QueryValue id: UUID): EmployeeResponse {
+    return employeeManager.findById(id).throwOrValue()
+  }
+
+  @Get("/employees")
+  suspend fun listEmployees(
+    @QueryValue page: Int?,
+    @QueryValue limit: Int?,
+    @QueryValue status: String?
+  ): EmployeeListResponse {
+    return employeeManager.list(
+      page = page ?: 1,
+      limit = (limit ?: 20).coerceAtMost(100),
+      status = status
+    ).throwOrValue()
+  }
+}
+```
+
+## Response Models
+
+All in `module-client/response/{domain}/`:
+
+```kotlin
+data class EmployeeResponse(
+  val id: UUID,
+  val name: String,
+  val email: String,
+  val status: String,
+  val createdAt: Instant
+) {
+  companion object {
+    fun from(entity: EmployeeEntity) = EmployeeResponse(
+      id = entity.id,
+      name = entity.name,
+      email = entity.email,
+      status = entity.status,
+      createdAt = entity.createdAt
+    )
+  }
+}
+
+data class EmployeeListResponse(
+  val items: List<EmployeeResponse>,
+  val total: Int,
+  val page: Int,
+  val limit: Int,
+  val hasMore: Boolean
+)
+```
+
+## Pagination Pattern
+
+```kotlin
+override suspend fun list(
+  page: Int,
+  limit: Int,
+  status: String?
+): Either<ClientException, EmployeeListResponse> {
+  val offset = (page - 1) * limit
+
+  val (items, total) = transaction(db.replica) {
+    val query = EmployeesTable
+      .selectAll()
+      .where { EmployeesTable.deletedAt.isNull() }
+
+    if (status != null) {
+      query.andWhere { EmployeesTable.status eq status }
+    }
+
+    val total = query.count().toInt()
+    val items = query
+      .orderBy(EmployeesTable.createdAt to SortOrder.DESC)
+      .limit(limit)
+      .offset(offset.toLong())
+      .map { convert(it) }
+
+    items to total
+  }
+
+  return EmployeeListResponse(
+    items = items.map { EmployeeResponse.from(it) },
+    total = total,
+    page = page,
+    limit = limit,
+    hasMore = (page * limit) < total
+  ).right()
+}
+```
+
+## Error Pattern
+
+```kotlin
+// Not found
+val entity = repository.byId(id)
+  ?: return ClientError.NOT_FOUND.asException().left()
+
+// Already exists
+val existing = repository.byEmail(email)
+if (existing != null) {
+  return ClientError.ALREADY_EXISTS.asException().left()
+}
+
+// Validation
+if (request.name.isBlank()) {
+  return ClientError.INVALID_INPUT.asException("Name is required").left()
+}
+```
+
+## Factory Bean
+
+```kotlin
+@Factory
+class EmployeeManagerFactory {
+  @Singleton
+  fun provideEmployeeManager(
+    employeeRepository: EmployeeRepository,
+    db: DatabaseContext
+  ): EmployeeManager {
+    return DefaultEmployeeManager(employeeRepository, db)
+  }
+}
+```