@c0x12c/ai-toolkit 1.15.0

package/rules/backend-micronaut/SERVICES_AND_BEANS.md

@@ -0,0 +1,325 @@
+# Service Layer and Bean Management
+
+## Service Layer Rules
+
+### Core Principle
+
+**Services fetch data. Managers persist data.**
+
+### Services MUST NOT Call Repositories
+
+```kotlin
+// ❌ WRONG - Service calling repository
+class DefaultGitHubSyncService(
+  private val commitRepository: GitHubCommitRepository,  // NO!
+  private val prRepository: GitHubPullRequestRepository  // NO!
+) : GitHubSyncService {
+
+  override suspend fun syncCommits(org: String) {
+    val commits = gitHubClient.fetchCommits(org)
+    commitRepository.insert(...)  // Services should NOT do this!
+  }
+}
+
+// ✓ CORRECT - Service returns data, Manager persists
+class DefaultGitHubDataFetcher(
+  private val gitHubClient: GitHubGraphQLClient,
+  private val identityResolver: IdentityResolver
+) : GitHubDataFetcher {
+
+  override suspend fun fetchCommits(org: String): Either<ClientException, List<GitHubCommitData>> {
+    val commits = gitHubClient.fetchCommits(org)
+    return commits.map { it.toData(identityResolver) }.right()  // Return DTOs!
+  }
+}
+```
+
+### Services Return DTOs, Not Entities
+
+Services should return data transfer objects that represent fetched data:
+
+```kotlin
+// DTO returned by service
+data class GitHubCommitData(
+  val sha: String,
+  val authorUsername: String?,
+  val employeeId: UUID?,  // Resolved by service
+  val committedAt: Instant,
+  val additions: Int,
+  val deletions: Int
+)
+
+// Manager converts DTO to Entity for persistence
+class DefaultGitHubSyncManager(...) : GitHubSyncManager {
+
+  override suspend fun syncCommits(org: String) {
+    val commitData = dataFetcher.fetchCommits(org)
+      .fold({ return it.left() }, { it })
+
+    for (data in commitData) {
+      val entity = GitHubCommitEntity(
+        sha = data.sha,
+        employeeId = data.employeeId,
+        // ...
+      )
+      commitRepository.insert(entity)  // Manager does persistence
+    }
+  }
+}
+```
+
+### Service Allowed Dependencies
+
+| Allowed | Not Allowed |
+|---------|-------------|
+| External API clients (GitHubGraphQLClient, SlackClient) | Repositories |
+| Identity resolvers (for mapping external IDs) | Database context |
+| Configuration classes | Transaction management |
+| Logging | Other managers |
+| Token providers | |
+
+### Manager Allowed Dependencies
+
+| Allowed | Not Allowed |
+|---------|-------------|
+| Repositories | External API clients (use Services instead) |
+| Services | Direct HTTP calls |
+| Other managers | |
+| Database context | |
+| Distributed locks | |
+
+### Data Flow Examples
+
+#### Correct: Manager Orchestrates, Service Fetches
+
+```
+1. Controller receives sync request
+         ↓
+2. Manager.syncCommits() called
+         ↓
+3. Manager calls Service.fetchCommits()
+         ↓
+4. Service calls GitHubGraphQLClient
+         ↓
+5. Service resolves identities
+         ↓
+6. Service returns List<GitHubCommitData>
+         ↓
+7. Manager iterates data, calls Repository.insert()
+         ↓
+8. Manager updates sync cursor
+         ↓
+9. Manager returns SyncResult to Controller
+```
+
+#### Wrong: Service Does Everything
+
+```
+1. Controller receives sync request
+         ↓
+2. Service.syncCommits() called
+         ↓
+3. Service calls GitHubGraphQLClient
+         ↓
+4. Service calls Repository.insert()  ← VIOLATION!
+         ↓
+5. Service returns SyncResult
+```
+
+### Naming Conventions
+
+| Layer | Interface Suffix | Implementation Prefix | Example |
+|-------|------------------|----------------------|---------|
+| Service | `*Fetcher` or `*Service` (readonly) | `Default*` | `GitHubDataFetcher` / `DefaultGitHubDataFetcher` |
+| Manager | `*Manager` | `Default*` | `GitHubSyncManager` / `DefaultGitHubSyncManager` |
+| Repository | `*Repository` | `Default*` | `GitHubCommitRepository` / `DefaultGitHubCommitRepository` |
+
+### When to Use Service vs Manager
+
+#### Use Service (Fetcher) When:
+- Calling external APIs (GitHub, Slack, Notion, Atlas)
+- Transforming external data formats
+- Resolving identities (external ID → employee_id)
+- No database writes needed
+
+#### Use Manager When:
+- Orchestrating multiple operations
+- Persisting data to database
+- Managing transactions
+- Business logic that needs DB state
+- Distributed locking
+
+### Refactoring Guide: Service Calling Repositories
+
+When you find a Service calling repositories:
+
+1. **Create a new Manager interface** that defines the operation
+2. **Create a new Fetcher interface** for the external data fetch
+3. **Move DB operations to Manager**
+4. **Move API calls to Fetcher**
+5. **Manager calls Fetcher, then Repository**
+
+#### Before (Wrong)
+```kotlin
+class DefaultSyncService(
+  private val apiClient: ExternalApiClient,
+  private val repository: DataRepository  // ← Problem
+) : SyncService {
+
+  override suspend fun sync() {
+    val data = apiClient.fetch()
+    repository.insert(data)  // ← Service doing persistence
+  }
+}
+```
+
+#### After (Correct)
+```kotlin
+// Service: Fetch only
+class DefaultDataFetcher(
+  private val apiClient: ExternalApiClient
+) : DataFetcher {
+
+  override suspend fun fetch(): List<DataDTO> {
+    return apiClient.fetch().map { it.toDTO() }
+  }
+}
+
+// Manager: Orchestrate and persist
+class DefaultSyncManager(
+  private val fetcher: DataFetcher,
+  private val repository: DataRepository
+) : SyncManager {
+
+  override suspend fun sync() {
+    val data = fetcher.fetch()
+    repository.insertAll(data.map { it.toEntity() })
+  }
+}
+```
+
+---
+
+## Bean Management (3-Tier Hierarchy)
+
+```
+Application Beans (top)    — business logic, depends on module + shared
+       ↓
+Module Beans (middle)      — reusable module components, depends on shared only
+       ↓
+Shared Beans (bottom)      — infrastructure (DB, Redis, AWS), no dependencies
+```
+
+### Bean Creation Rules
+
+1. **Always use `@Factory` classes** — never `@Singleton` on implementations directly
+2. **Depend on interfaces**, not concrete classes
+3. **`@Named`** for multiple implementations of same interface
+4. **`@Primary`** for default implementation
+5. **`@Requires`** for conditional bean creation
+6. **No circular dependencies** — fix with interface extraction (see below)
+
+```kotlin
+// CORRECT — Factory pattern
+@Factory
+class UserFactory {
+  @Singleton
+  fun provideUserRepository(db: DatabaseContext): UserRepository {
+    return DefaultUserRepository(db)
+  }
+}
+
+// WRONG — @Singleton on implementation
+@Singleton
+class DefaultUserRepository(private val db: DatabaseContext) : UserRepository
+```
+
+### Bean Testing
+
+Use `@Replaces` to swap beans at any tier in tests:
+```kotlin
+@Singleton
+@Replaces(DatabaseContext::class)
+fun testDatabaseContext(): DatabaseContext = InMemoryDatabaseContext()
+```
+
+### Bean Scope
+
+- `@Singleton` — default, use this for most beans
+- `@Prototype` — rare, new instance per injection
+- `@RequestScope` — per HTTP request, controllers only
+
+---
+
+## Enforcement Checklists
+
+### Service Layer Checklist
+
+- [ ] Services have NO repository imports
+- [ ] Services have NO `insert`, `update`, `delete` calls
+- [ ] Services return DTOs, not entities
+- [ ] Managers handle all DB operations
+- [ ] Managers wrap DB operations in transactions
+- [ ] External API calls go through Services, not Managers
+
+### Bean Checklist
+
+- [ ] Determine tier: Shared / Module / Application
+- [ ] Create `@Factory` class with right naming
+- [ ] Define bean method with `@Singleton` (or right scope)
+- [ ] Inject dependencies via method parameters
+- [ ] Verify dependency direction (no upward dependencies)
+- [ ] Return interface type, not concrete implementation
+- [ ] Use `@Named` for multiple implementations
+- [ ] Use `@Primary` for default implementation
+- [ ] Use `@Requires` for conditional creation
+- [ ] No circular dependencies (see "Breaking Circular Dependencies" below)
+- [ ] Bean is testable (can be replaced with `@Replaces`)
+
+---
+
+## Breaking Circular Dependencies
+
+`Provider<T>` for lazy initialization is a code smell for a circular dependency. Fix the root cause.
+
+### The Problem
+
+```
+ProjectManager → WorkspaceManager → SomeService → ProjectManager  (cycle!)
+```
+
+**Bad workaround:**
+```kotlin
+// Provider<T> hides the cycle — DON'T DO THIS
+class DefaultProjectManager(
+  private val workspaceManagerProvider: Provider<WorkspaceManager>,  // Lazy
+) : ProjectManager
+```
+
+### The Fix: Interface Extraction + Layer Split
+
+**Step 1** — Find the shared functionality causing the cycle.
+
+**Step 2** — Extract it into a focused interface:
+```kotlin
+interface ProjectThumbnailResolver {
+  suspend fun resolveProjectThumbnailUrl(entity: ProjectEntity): String?
+}
+```
+
+**Step 3** — Move the logic to a new component with lower-level dependencies:
+```kotlin
+class DefaultProjectThumbnailResolver(
+  private val storageService: StorageService  // No cycle
+) : ProjectThumbnailResolver { ... }
+```
+
+**Step 4** — Inject directly, no Provider needed:
+```kotlin
+class DefaultProjectManager(
+  private val workspaceManager: WorkspaceManager,         // Direct injection
+  private val projectThumbnailResolver: ProjectThumbnailResolver  // New!
+) : ProjectManager
+```
+
+**Rule:** If you reach for `Provider<T>`, stop. Extract the shared functionality into its own interface at a lower layer.

package/rules/core/NAMING_CONVENTIONS.md

@@ -0,0 +1,208 @@
+# Naming Conventions
+
+## Overview
+
+This document defines the naming conventions used across different layers of the stack. Consistent naming reduces bugs, makes the codebase easier to understand, and helps everyone move faster.
+
+## Convention Summary
+
+| Layer | Convention | Example |
+|-------|-----------|---------|
+| **Database (SQL)** | `snake_case` | `points_balance`, `user_id`, `created_at` |
+| **Kotlin Code** | `camelCase` | `pointsBalance`, `userId`, `createdAt` |
+| **API JSON (over wire)** | `snake_case` | `"points_balance"`, `"user_id"` |
+| **TypeScript Code** | `camelCase` | `pointsBalance`, `userId`, `createdAt` |
+
+## How It Works
+
+### Backend (Kotlin + Micronaut)
+
+**Jackson ObjectMapper** is configured globally with `SNAKE_CASE` naming strategy:
+
+```kotlin
+// In your Jackson configuration module
+fun ObjectMapper.configured(): ObjectMapper {
+  propertyNamingStrategy = PropertyNamingStrategies.SNAKE_CASE
+  // ... other configuration
+}
+```
+
+This means:
+- **Write Kotlin code in `camelCase`** (idiomatic Kotlin)
+- **Jackson automatically converts to `snake_case`** when serializing to JSON
+- **Jackson automatically converts from `snake_case`** when deserializing JSON
+
+**Example:**
+```kotlin
+// Kotlin DTO (use camelCase)
+@Serdeable
+data class CreateRecognitionRequest(
+  val receiverIds: List<UUID>,      // camelCase in code
+  val coreValueIds: List<UUID>,     // camelCase in code
+  val points: Int,
+  val message: String
+)
+```
+
+**JSON sent/received (automatic snake_case):**
+```json
+{
+  "receiver_ids": ["uuid-1", "uuid-2"],
+  "core_value_ids": ["uuid-3"],
+  "points": 10,
+  "message": "Great work!"
+}
+```
+
+### Frontend (TypeScript + React)
+
+**Axios interceptors** automatically convert between conventions:
+
+```typescript
+// src/lib/case-converter.ts
+export function toSnakeCase<T>(obj: T): T    // camelCase -> snake_case
+export function toCamelCase<T>(obj: T): T    // snake_case -> camelCase
+```
+
+```typescript
+// src/lib/api.ts
+// Request interceptor: Convert camelCase to snake_case before sending
+api.interceptors.request.use((config) => {
+  if (config.data && typeof config.data === 'object') {
+    config.data = toSnakeCase(config.data)
+  }
+  return config
+})
+
+// Response interceptor: Convert snake_case to camelCase after receiving
+api.interceptors.response.use((response) => {
+  if (response.data && typeof response.data === 'object') {
+    response.data = toCamelCase(response.data)
+  }
+  return response
+})
+```
+
+This means:
+- **Write TypeScript code in `camelCase`** (idiomatic JavaScript/TypeScript)
+- **Interceptors automatically convert to `snake_case`** when sending requests
+- **Interceptors automatically convert to `camelCase`** when receiving responses
+
+**Example:**
+```typescript
+// TypeScript interface (use camelCase)
+export interface CreateRecognitionRequest {
+  receiverIds: string[]     // camelCase in code
+  coreValueIds: string[]    // camelCase in code
+  points: number
+  message: string
+}
+
+// Usage - just use camelCase everywhere
+const data: CreateRecognitionRequest = {
+  receiverIds: ['uuid-1', 'uuid-2'],
+  coreValueIds: ['uuid-3'],
+  points: 10,
+  message: 'Great work!'
+}
+
+// Interceptor automatically sends as snake_case
+await api.post('/recognitions', data)
+```
+
+### Database (PostgreSQL)
+
+All database objects use `snake_case`:
+
+```sql
+-- Tables (plural, snake_case)
+CREATE TABLE users (...)
+CREATE TABLE core_values (...)
+CREATE TABLE recognition_receivers (...)
+
+-- Columns (snake_case)
+id UUID PRIMARY KEY
+points_balance INTEGER
+allowance_balance INTEGER
+created_at TIMESTAMP
+updated_at TIMESTAMP
+deleted_at TIMESTAMP
+
+-- Indexes (idx_tablename_column)
+CREATE INDEX idx_users_email ON users(email)
+CREATE INDEX idx_recognitions_giver_id ON recognitions(giver_id)
+```
+
+## CRITICAL: @QueryValue Must Use Explicit snake_case Names
+
+**The frontend axios interceptor converts ALL query params to `snake_case` (e.g., `projectId` → `project_id`). But Micronaut's `@QueryValue` does NOT auto-convert — it matches the EXACT param name from the URL.**
+
+**Jackson's SNAKE_CASE config only affects JSON body serialization/deserialization, NOT query parameter binding.**
+
+This means ALL multi-word `@QueryValue` params MUST have explicit snake_case names:
+
+```kotlin
+// ✅ CORRECT — explicit snake_case name matches what frontend sends
+@QueryValue("project_id") projectId: UUID,
+@QueryValue("alert_id") alertId: UUID,
+@QueryValue("repo_full_name") repoFullName: String,
+
+// ❌ WRONG — Micronaut expects ?projectId=xxx but frontend sends ?project_id=xxx
+@QueryValue projectId: UUID,
+@QueryValue alertId: UUID,
+@QueryValue repoFullName: String,
+
+// ✅ OK — single-word params don't need explicit name (no case conversion needed)
+@QueryValue status: String,
+@QueryValue limit: Int,
+@QueryValue id: UUID,
+```
+
+**Rule: If a `@QueryValue` param name has more than one word (contains uppercase letters), ALWAYS add explicit `@QueryValue("snake_case_name")`.**
+
+## Rules
+
+### DO
+
+1. **Use `camelCase` in all Kotlin code** (properties, variables, function parameters)
+2. **Use `camelCase` in all TypeScript code** (interfaces, variables, function parameters)
+3. **Use `snake_case` in all SQL** (tables, columns, indexes)
+4. **Let the framework handle conversion** (Jackson for backend, Axios interceptors for frontend)
+5. **ALWAYS add explicit snake_case name to multi-word `@QueryValue` params**
+
+### DON'T
+
+1. **DON'T manually convert case in API calls** - interceptors handle this
+2. **DON'T use `@JsonProperty` unless mapping external APIs** (like Google OAuth)
+3. **DON'T mix conventions within the same layer**
+4. **DON'T use `snake_case` in Kotlin or TypeScript code**
+5. **DON'T use `camelCase` in SQL or JSON API contracts**
+6. **DON'T use bare `@QueryValue` for multi-word param names** — always add explicit snake_case
+
+### When to Use `@JsonProperty`
+
+Only use `@JsonProperty` annotation when:
+- Mapping responses from **external APIs** that don't follow your conventions
+- Field names must differ from the automatic conversion for **backwards compatibility**
+
+```kotlin
+// ONLY for external APIs (like Google OAuth)
+@Serdeable
+data class GoogleTokenResponse(
+  @JsonProperty("access_token")
+  val accessToken: String,
+  @JsonProperty("expires_in")
+  val expiresIn: Int,
+  @JsonProperty("id_token")
+  val idToken: String?
+)
+```
+
+## Code Review Checklist
+
+- [ ] No manual `snake_case` in Kotlin DTO properties
+- [ ] No manual `snake_case` in TypeScript interfaces
+- [ ] No manual case conversion in API calls (let interceptors handle it)
+- [ ] `@JsonProperty` only used for external API mappings
+- [ ] Database columns and tables use `snake_case`
+- [ ] Exposed Table definitions match database column names

package/rules/core/SKILL_AUTHORING.md

@@ -0,0 +1,174 @@
+# Skill Authoring Rules
+
+Rules for creating and modifying skills in the Spartan AI Toolkit. Follow these when writing new skills or improving existing ones.
+
+## Frontmatter (REQUIRED)
+
+Every SKILL.md must have these fields:
+
+```yaml
+---
+name: skill-name
+description: "What it does. Use when [trigger conditions]."
+allowed_tools:
+  - Read
+  - Write
+  # ... tools the skill needs
+---
+```
+
+### Description Must Be a Trigger
+
+The description tells the model WHEN to activate the skill, not WHAT the skill is.
+
+| Bad (summary) | Good (trigger) |
+|----------------|----------------|
+| "Database design patterns including schemas and migrations" | "Database design patterns. Use when creating tables, writing migrations, or implementing repositories." |
+| "The full startup pipeline from brainstorm to outreach" | "Coordinates the full startup pipeline. Use when the user starts a new idea project or references stages/gates." |
+
+**Rule:** Every description must contain "Use when" followed by specific trigger conditions.
+
+### allowed_tools Must Match the Skill's Needs
+
+| Skill type | Typical tools |
+|------------|--------------|
+| Code/backend (writes files) | Read, Write, Edit, Glob, Grep, Bash |
+| Research/analysis (web searches) | WebSearch, WebFetch, Read |
+| Content/writing (creates + researches) | Read, Write, WebSearch |
+| Review/audit (reads only) | Read, Glob, Grep |
+
+---
+
+## Folder Structure (Skills Are Folders, Not Files)
+
+A skill is a directory, not just a markdown file. Use the file system for progressive disclosure.
+
+```
+toolkit/skills/my-skill/
+  SKILL.md              # Main definition — short, high-level (required)
+  code-patterns.md      # Code examples (if code-heavy skill)
+  examples.md           # Good/bad examples (if teaching a style)
+  checklists.md         # Review checklists (if audit/review skill)
+  workflows.md          # Ready-to-use templates (if scaffolding skill)
+```
+
+### When to Split Into Multiple Files
+
+| SKILL.md is... | Action |
+|-----------------|--------|
+| Under 100 lines | One file is fine |
+| 100-150 lines with code blocks | Split code into a reference file |
+| 150+ lines | Must split — too much for one read |
+
+### SKILL.md Should Be the Summary
+
+Keep SKILL.md short (60-120 lines). It should have:
+- Frontmatter
+- "When to Use" section
+- Key rules and principles (without detailed code)
+- Gotchas section
+- References to supporting files
+
+Move into supporting files:
+- Detailed code templates and examples
+- Long checklists
+- Good/bad comparisons
+- Ready-to-use templates
+
+Reference with: `> See code-patterns.md for complete implementation templates.`
+
+---
+
+## Gotchas Section (REQUIRED)
+
+Every skill must have a `## Gotchas` section. This is the highest-value content in any skill.
+
+### Format
+
+```markdown
+## Gotchas
+
+- **Bold lead-in sentence.** Explanation of why this matters and what to do instead.
+- **Another gotcha.** Details.
+```
+
+### What Makes a Good Gotcha
+
+- Specific failure patterns Claude hits when using this skill
+- Things that look right but are wrong
+- Common mistakes users make in this domain
+- Counter-intuitive rules that violate defaults
+
+### What is NOT a Gotcha
+
+- General best practices (put those in Rules)
+- Obvious things Claude already knows
+- Restating the instructions in negative form
+
+**Minimum 3 gotchas per skill. Build this section over time as you find new failure patterns.**
+
+---
+
+## Content Rules
+
+### Don't State the Obvious
+
+Claude already knows how to code, research, and write. Focus on information that pushes Claude OUT of its normal patterns.
+
+| Bad (obvious) | Good (non-obvious) |
+|----------------|---------------------|
+| "Use proper error handling" | "`!!` is banned — use `?.`, `?:`, or null check" |
+| "Write clean code" | "Don't add docstrings to code you didn't change" |
+| "Research thoroughly" | "Press releases aren't research — cross-check with third-party sources" |
+
+### Give Claude Flexibility
+
+Tell Claude WHAT to check and WHY, not exact steps for every situation. Skills are reused across many contexts — being too specific makes them brittle.
+
+| Bad (railroading) | Good (flexible) |
+|---------------------|------------------|
+| "Step 1: Open file X. Step 2: Find line Y. Step 3: Change to Z." | "Check the controller for @ExecuteOn annotation. If missing, add it." |
+
+### Use Examples Over Instructions
+
+A good/bad example teaches more than a paragraph of rules. When possible, show rather than tell.
+
+---
+
+## Config Pattern (for Stateful Skills)
+
+Skills that run repeatedly for the same user should store preferences:
+
+```json
+// content-config.json in the project root
+{
+  "defaultPlatforms": ["x", "linkedin"],
+  "brandVoice": "direct and technical",
+  "audience": "developers"
+}
+```
+
+Read config at skill start. Skip setup questions for configured fields.
+
+---
+
+## Naming
+
+| Type | Convention | Example |
+|------|-----------|---------|
+| Skill directory | `kebab-case` | `ci-cd-patterns/` |
+| Main file | `SKILL.md` (always) | `SKILL.md` |
+| Supporting files | `kebab-case.md` | `code-patterns.md` |
+
+---
+
+## Checklist: Before Shipping a Skill
+
+- [ ] Frontmatter has `name`, `description` (with trigger), and `allowed_tools`
+- [ ] Description says "Use when..." with specific conditions
+- [ ] SKILL.md is under 120 lines (split if longer)
+- [ ] Has a `## Gotchas` section with 3+ items
+- [ ] Code-heavy content is in supporting files, not inline
+- [ ] Examples show good AND bad patterns where applicable
+- [ ] Doesn't restate things Claude already knows
+- [ ] Gives Claude flexibility — principles over exact steps