@c0x12c/spartan-ai-toolkit 1.0.1

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 Insight 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/insight/c0x12c/client/ProjectClient.kt`
+
+```kotlin
+package insight.c0x12c.client
+
+import insight.c0x12c.client.request.insight.CreateProjectRequest
+import insight.c0x12c.client.response.insight.ProjectResponse
+import insight.c0x12c.client.response.insight.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,95 @@
+---
+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.
+---
+
+# 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
+
+## 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
+
+## 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/backend-api-design/SKILL.md

@@ -0,0 +1,187 @@
+---
+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.
+---
+
+# 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`
+
+## 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()
+  }
+}
+```
+
+## 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()`
+
+## 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)
+  }
+}
+```

package/skills/brainstorm/SKILL.md

@@ -0,0 +1,85 @@
+---
+name: brainstorm
+description: Run a structured brainstorm session for startup ideas. Takes a theme or problem and generates ideas with quick gut-checks. Use when the user wants to explore a space or generate new ideas.
+---
+
+# Brainstorm
+
+Turn a vague direction into a list of concrete ideas worth testing.
+
+## When to Use
+
+- User has a theme, problem, or space they want to explore
+- Generating new project ideas
+- Expanding on a half-baked idea
+- Looking for adjacent opportunities
+
+## Process
+
+### 1. Set the Frame
+Ask or confirm:
+- What space? (health, finance, dev tools, etc.)
+- Who's the user? (founders, students, parents, etc.)
+- Any limits? (no hardware, must be B2B, etc.)
+- What's the goal? (side project, VC-backed, bootstrap)
+
+### 2. Generate Ideas (Go Wide)
+Produce 8-15 ideas. For each:
+- **Name** - Working title
+- **One-liner** - What it does in 10 words
+- **Who** - Target user
+- **Problem** - What pain it fixes
+- **Why now** - Why this didn't work before
+- **Quick risk** - Biggest thing that could kill it
+
+### 3. Gut-Check Filter
+Rate each idea on:
+- Demand signal (0-5): Are people searching for this? Paying for alternatives?
+- Buildability (0-5): Can you build an MVP in 2 weeks?
+- Moat potential (0-5): Can you defend this?
+
+### 4. Pick Top 3
+Pick the 3 best ideas. For each, write:
+- The key bet (what must be true for this to work)
+- First validation step (cheapest way to test)
+- Existing competitors (who's doing something close)
+
+## 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 what's wrong with your thinking if I see it
+- I push back if your idea is weak
+
+**Never:**
+- Ask a question without giving options
+- Sugarcoat bad ideas
+- Say "it depends" without picking a side
+- Give soft answers to hard questions
+- Skip the tough feedback to be nice
+
+## Rules
+
+- No idea is too dumb during generation
+- But be brutal during filtering
+- "Interesting" is not enough. Need a real pain point.
+- If the user already has a direction, skip to expanding that
+- Don't fall in love with clever solutions to fake problems
+
+## Output
+
+Save to the project's `01-brainstorm/` folder.
+
+After delivering, suggest: "Want me to run /validate on any of these?"