@c0x12c/ai-toolkit 1.15.0

package/skills/investor-outreach/examples.md

@@ -0,0 +1,76 @@
+# Investor Outreach — Email Examples
+
+> Read these examples to calibrate your email style. Short, specific, and with a clear ask.
+
+## Cold Email
+
+### Bad
+> Subject: Exciting Opportunity in the AI Space
+>
+> Dear [Investor Name],
+>
+> I hope this email finds you well. My name is [Name] and I'm the CEO of [Company]. We are building a revolutionary AI-powered platform that leverages cutting-edge machine learning technology to transform the way businesses handle customer support.
+>
+> We have a comprehensive product roadmap and a talented team of engineers from top universities. Our platform utilizes state-of-the-art natural language processing to deliver seamless customer experiences.
+>
+> I would love to schedule a 30-minute call to discuss how we can work together. Please let me know your availability.
+>
+> Best regards,
+> [Name]
+
+**Problems:** Generic subject, "I hope this email finds you well", buzzword soup, no proof point, no personalization, too long, asks for 30 minutes from a stranger.
+
+### Good
+> Subject: AI support tool — 40 paying customers, raising seed
+>
+> Hi Sarah,
+>
+> Your investment in Intercom caught my eye — we're solving a related problem for smaller teams.
+>
+> We built an AI tool that handles L1 support tickets automatically. 40 companies paying us, $18K MRR, growing 25% monthly. B2B SaaS teams with 2-5 support agents.
+>
+> Would you be open to a 15-min intro call next week?
+>
+> [Name]
+> CEO, [Company]
+
+**Why this works:** Specific subject with proof point, personalized to their portfolio, concrete numbers, short ask.
+
+---
+
+## Warm Intro Request
+
+### The Ask (to the connector)
+> Hey [Connector],
+>
+> Would you be open to introducing me to Sarah at [Fund]? She led their Intercom investment and we're in a similar space (AI for support teams).
+>
+> Here's a forwardable blurb if you're up for it:
+
+### Forwardable Blurb
+> [Name] is building [Company] — an AI tool that auto-resolves L1 support tickets. 40 paying customers, $18K MRR, 25% monthly growth. Raising a $2M seed. Thought it might be up your alley given the Intercom investment.
+
+---
+
+## Follow-Up (Day 5)
+
+### Bad
+> Hi Sarah,
+>
+> Just following up on my previous email. I wanted to make sure it didn't get lost in your inbox. Would love to connect when you have a chance.
+>
+> Best,
+> [Name]
+
+**Problems:** No new information, apologetic tone, "didn't get lost in your inbox" is cliche.
+
+### Good
+> Hi Sarah,
+>
+> Quick update since last week — we crossed $20K MRR and signed our first enterprise pilot (200-seat team).
+>
+> Still raising our seed if the timing works on your end.
+>
+> [Name]
+
+**Why this works:** New information (MRR growth + enterprise pilot), short, no begging, leaves door open.

package/skills/kotlin-best-practices/SKILL.md

@@ -0,0 +1,58 @@
+---
+name: kotlin-best-practices
+description: Kotlin coding standards including null safety, Either error handling, coroutines, and Exposed ORM patterns. Use when writing Kotlin code, reviewing code quality, or learning project patterns.
+allowed_tools:
+  - Read
+  - Write
+  - Edit
+  - Glob
+  - Grep
+---
+
+# Kotlin Best Practices — Quick Reference
+
+## Null Safety
+
+`!!` is banned. Use `?.`, `?:`, or null check for smart cast.
+
+> See code-patterns.md for all null safety examples.
+
+## Either Error Handling
+
+Managers return `Either<ClientException, T>` -- never throw. Controllers unwrap with `.throwOrValue()`.
+
+> See code-patterns.md for manager + controller examples.
+
+## Enum Usage
+
+Never hardcode strings when an enum exists. Use `EnumName.VALUE.value` everywhere.
+
+> See code-patterns.md for enum definition and usage patterns.
+
+## Exposed ORM Patterns
+
+Extend `UUIDTable`, use `text()` not `varchar()`. Always filter `deletedAt.isNull()`. Soft delete via timestamp update, never hard delete.
+
+> See code-patterns.md for table, query, and soft delete examples.
+
+## Transaction Rules
+
+Reads use `db.replica`, writes use `db.primary`. Multi-table writes go in one transaction block -- all succeed or all rollback.
+
+> See code-patterns.md for transaction examples.
+
+## Conversion Pattern
+
+Put `companion object { fun from(entity) }` inside Response DTOs. Never create separate mapper files.
+
+> See code-patterns.md for the full pattern.
+
+## What to Avoid
+
+- `!!` -- always use `?.`, `?:`, or null check
+- `@Suppress` -- fix the root cause
+- Throwing exceptions -- return `Either.left()` instead
+- `VARCHAR` in SQL -- use `TEXT`
+- Hardcoded strings for enum values
+- `Table` base class -- use `UUIDTable`
+- Field injection -- use constructor injection

package/skills/kotlin-best-practices/code-patterns.md

@@ -0,0 +1,132 @@
+# Kotlin Best Practices — Code Patterns
+
+> This file is referenced by SKILL.md. Read it when writing Kotlin code and you need the exact syntax.
+
+## Null Safety Patterns
+
+```kotlin
+// NEVER — banned, pre-commit hook rejects it
+val x = foo!!.bar
+
+// GOOD — safe call + elvis
+val x = foo?.bar ?: defaultValue
+
+// GOOD — explicit null check (smart cast after)
+if (foo == null) return error.left()
+foo.bar  // smart cast, no ?. needed
+
+// GOOD — let for null-safe chains
+user?.let { generateTokens(it, provider) }
+  ?: return AuthError.AUTHENTICATION_FAILED.asException().left()
+```
+
+## Either Error Handling
+
+```kotlin
+// Managers return Either — never throw
+suspend fun findById(id: UUID): Either<ClientException, UserResponse> {
+  val entity = userRepository.byId(id)
+    ?: return ClientError.USER_NOT_FOUND.asException().left()
+  return UserResponse.from(entity).right()
+}
+
+// Controllers unwrap with .throwOrValue()
+@Get("/user")
+suspend fun getUser(@QueryValue id: UUID): UserResponse {
+  return userManager.findById(id).throwOrValue()
+}
+```
+
+## Enum Usage
+
+```kotlin
+// NEVER hardcode strings when an enum exists
+val status = "critical"              // WRONG
+val status = HealthStatus.CRITICAL.value  // RIGHT
+
+// Define enums with .value
+enum class HealthStatus(val value: String) {
+  HEALTHY("healthy"),
+  AT_RISK("at_risk"),
+  CRITICAL("critical");
+
+  companion object {
+    fun fromValue(v: String) = entries.find { it.value == v }
+  }
+}
+```
+
+## Exposed ORM Patterns
+
+```kotlin
+// Table — extend UUIDTable, use text() not varchar()
+object UsersTable : UUIDTable("users") {
+  val email = text("email")
+  val displayName = text("display_name").nullable()
+  val createdAt = timestamp("created_at")
+  val updatedAt = timestamp("updated_at").nullable()
+  val deletedAt = timestamp("deleted_at").nullable()
+}
+
+// Query — ALWAYS check deletedAt.isNull()
+fun byId(id: UUID): UserEntity? {
+  return transaction(db.replica) {
+    UsersTable
+      .selectAll()
+      .where { (UsersTable.id eq id) and UsersTable.deletedAt.isNull() }
+      .singleOrNull()
+      ?.let { convert(it) }
+  }
+}
+
+// Soft delete — NEVER hard delete
+fun deleteById(id: UUID): UserEntity? {
+  return transaction(db.primary) {
+    UsersTable.update(
+      where = { (UsersTable.id eq id) and UsersTable.deletedAt.isNull() }
+    ) {
+      it[deletedAt] = Instant.now()
+      it[updatedAt] = Instant.now()
+    }
+    UsersTable.selectAll()
+      .where { UsersTable.id eq id }
+      .singleOrNull()
+      ?.let { convert(it) }
+  }
+}
+```
+
+## Transaction Rules
+
+```kotlin
+// Reads use replica, writes use primary
+val user = transaction(db.replica) { userRepository.byId(id) }
+val saved = transaction(db.primary) { userRepository.insert(entity) }
+
+// Multiple writes in one transaction
+transaction(db.primary) {
+  val user = userRepository.insert(userEntity)
+  profileRepository.insert(profileEntity)
+  // all succeed or all rollback
+}
+```
+
+## Conversion Pattern
+
+```kotlin
+// Companion object from() on Response DTOs
+data class UserResponse(
+  val id: UUID,
+  val email: String
+) {
+  companion object {
+    fun from(entity: UserEntity) = UserResponse(
+      id = entity.id,
+      email = entity.email
+    )
+  }
+}
+
+// Use in manager
+return UserResponse.from(entity).right()
+```

package/skills/market-research/SKILL.md

@@ -0,0 +1,99 @@
+---
+name: market-research
+description: Run market research, competitive analysis, investor due diligence, and industry scans. Use when the user wants market sizing, competitor comparisons, fund research, or tech scans.
+allowed_tools:
+  - WebSearch
+  - WebFetch
+  - Read
+---
+
+# Market Research
+
+Make research that helps decisions, not research for show.
+
+## When to Use
+
+- Researching a market, company, investor, or tech trend
+- Building TAM/SAM/SOM numbers
+- Comparing competitors
+- Checking investor fit before outreach
+- Testing a thesis before building
+
+## Process
+
+### 1. Pick the Research Type
+
+Figure out which kind of research the user needs:
+- Investor / Fund Check
+- Competitor Check
+- Market Size
+- Tech / Tool Research
+
+### 2. Run Investor / Fund Check
+
+Get:
+- Fund size, stage, check size
+- Portfolio companies that matter
+- Public thesis and recent deals
+- Why they fit or don't fit
+- Red flags
+
+### 3. Run Competitor Check
+
+Get:
+- What the product really does (not marketing fluff)
+- Funding and investors
+- Traction if public
+- How they get users and what they charge
+- Strengths, weaknesses, gaps
+
+### 4. Run Market Size
+
+Use:
+- Top-down from reports
+- Bottom-up from real customer numbers
+- Show your math. Every guess should be clear.
+
+### 5. Run Tech / Tool Research
+
+Get:
+- How it works
+- Trade-offs and who's using it
+- How hard to set up
+- Lock-in, security, and risk
+
+### 6. Write It Up
+
+Structure every deliverable as:
+1. Quick summary (2-3 sentences)
+2. Key findings
+3. What this means
+4. Risks and caveats
+5. What to do next
+6. Sources
+
+## Rules
+
+- Every big claim needs a source.
+- Use recent data. Flag old data.
+- Include the bad news too. Show risks.
+- End with a decision, not just a summary.
+- Keep facts, guesses, and suggestions separate.
+- All numbers have sources or are marked as guesses.
+- Old data is flagged.
+- The suggestion follows from the facts.
+- Someone can make a decision from this.
+
+## Gotchas
+
+- **Top-down TAM is lazy and always wrong.** "10% of the $X billion market" is not analysis. Bottom-up from real customer numbers or go home.
+- **Analyst reports have built-in bias.** Reports from vendors (like AWS sizing the cloud market) overstate their own segment. Use independent sources.
+- **Revenue proxies are unreliable.** SimilarWeb traffic estimates can be off by 5x. Combine multiple signals: hiring, social, Crunchbase, app store rankings.
+- **Don't confuse market size with addressable market.** The CRM market is $80B, but if you're building for freelancers, your market is a fraction of that.
+- **Recency matters.** A market growing 40% in 2024 might be flat in 2026. Always check the latest data points, not just the headline number.
+
+## Output
+
+Save to the project's `02-research/` folder.
+
+Format each deliverable with: quick summary, key findings, what this means, risks and caveats, next steps, and sources.

package/skills/security-checklist/SKILL.md

@@ -0,0 +1,65 @@
+---
+name: security-checklist
+description: Security best practices for Micronaut/Kotlin backend including authentication, authorization, input validation, and OWASP prevention. Use when implementing auth, validating inputs, or reviewing security.
+allowed_tools:
+  - Read
+  - Glob
+  - Grep
+---
+
+# Security Checklist
+
+Run a security audit against Micronaut/Kotlin backend code.
+
+## When to Use
+
+- Adding authentication or authorization to endpoints
+- Validating user inputs on new or changed endpoints
+- Reviewing code for security issues before merge
+- Checking for common vulnerabilities (SQL injection, XSS, IDOR)
+- Setting up secrets management
+
+## Process
+
+> See audit-reference.md for code examples, vulnerability table, and SAFE/DANGEROUS patterns.
+
+1. **Check Authentication** — every controller has @Secured, current user comes from security context
+2. **Check Authorization** — verify user has access to the resource before returning it
+3. **Check Input Validation** — @Valid on controller params, Jakarta annotations on request DTOs
+4. **Check SQL Injection Prevention** — use Exposed ORM (auto-parameterized), never raw SQL with string concat
+5. **Check Common Vulnerabilities** — SQL injection, XSS, CSRF, auth bypass, IDOR, mass assignment, data exposure, rate limiting
+6. **Check Secrets Management** — no hardcoded secrets, use env vars, never log tokens/passwords/PII, never commit .env
+7. **Check Response Sanitization** — response DTOs control what's exposed, never return raw entities
+
+## Interaction Style
+
+- Always checks all categories, doesn't skip any section
+- Flags the most dangerous issues first
+- Shows code examples for every fix, not just descriptions
+- Tells you what's wrong AND how to fix it
+
+## Rules
+
+- Every endpoint must have a @Secured annotation
+- Admin endpoints use OAuthSecurityRule.ADMIN
+- Users can only access their own resources (or admin can access all)
+- Input validated with @Valid and Jakarta annotations
+- No raw SQL queries with string concatenation
+- Sensitive fields excluded from response DTOs
+- Tokens/passwords never logged
+- Error messages don't leak internal details
+- Rate limiting on auth endpoints
+
+## Output
+
+Produces a checklist report with pass/fail for each category:
+
+- [ ] All endpoints have @Secured annotation
+- [ ] Admin endpoints use OAuthSecurityRule.ADMIN
+- [ ] User can only access their own resources (or admin can access all)
+- [ ] Input validated with @Valid and Jakarta annotations
+- [ ] No raw SQL queries with string concatenation
+- [ ] Sensitive fields excluded from response DTOs
+- [ ] Tokens/passwords never logged
+- [ ] Error messages don't leak internal details
+- [ ] Rate limiting on auth endpoints

package/skills/security-checklist/audit-reference.md

@@ -0,0 +1,95 @@
+# Security Checklist — Audit Reference
+
+> This file is referenced by SKILL.md. Read it when running a security audit and you need code examples.
+
+## Authentication Patterns
+
+```kotlin
+// Always use @Secured on controllers
+@Secured(SecurityRule.IS_AUTHENTICATED)   // Any logged-in user
+@Secured(OAuthSecurityRule.ADMIN)         // Admin only
+@Secured(SecurityRule.IS_ANONYMOUS)       // Public endpoint
+
+// Get current user from security context
+val principal = SecurityUtils.currentPrincipal()
+  ?: return AuthError.UNAUTHORIZED.asException().left()
+```
+
+## Authorization Patterns
+
+```kotlin
+// Verify user has access to the resource
+suspend fun getEmployee(id: UUID, requesterId: UUID): Either<ClientException, EmployeeResponse> {
+  val employee = employeeRepository.byId(id)
+    ?: return ClientError.NOT_FOUND.asException().left()
+
+  // Check: can this user see this employee?
+  if (!hasAccess(requesterId, employee)) {
+    return ClientError.FORBIDDEN.asException().left()
+  }
+
+  return EmployeeResponse.from(employee).right()
+}
+```
+
+## Input Validation Patterns
+
+```kotlin
+// Validate at controller boundary
+@Post("/employee")
+suspend fun create(@Valid @Body request: CreateEmployeeRequest): EmployeeResponse {
+  // @Valid triggers Jakarta validation annotations
+  return employeeManager.create(request).throwOrValue()
+}
+
+// Request with validation
+data class CreateEmployeeRequest(
+  @field:NotBlank val name: String,
+  @field:Email val email: String,
+  @field:Size(max = 1000) val description: String?
+)
+```
+
+## SQL Injection Prevention
+
+```kotlin
+// SAFE — Exposed ORM parameterizes automatically
+UsersTable.selectAll()
+  .where { UsersTable.email eq userInput }  // parameterized
+
+// DANGEROUS — raw SQL with string concat
+exec("SELECT * FROM users WHERE email = '$userInput'")  // NEVER DO THIS
+```
+
+## Common Vulnerabilities Table
+
+| Vulnerability | Prevention |
+|--------------|-----------|
+| SQL Injection | Use Exposed ORM (auto-parameterized) |
+| XSS | Don't render user input as HTML |
+| CSRF | Micronaut handles via token validation |
+| Auth bypass | @Secured on every controller |
+| IDOR | Check resource ownership in manager |
+| Mass assignment | Use explicit request DTOs, not entity directly |
+| Sensitive data exposure | Never return passwords, tokens in responses |
+| Missing rate limiting | Add @RateLimiter for auth endpoints |
+
+## Response Sanitization
+
+```kotlin
+// Response DTO controls what's exposed — don't return raw entities
+data class UserResponse(
+  val id: UUID,
+  val email: String,
+  val displayName: String
+  // NO password field, NO internal fields
+) {
+  companion object {
+    fun from(entity: UserEntity) = UserResponse(
+      id = entity.id,
+      email = entity.email,
+      displayName = entity.displayName ?: entity.email
+    )
+  }
+}
+```

package/skills/service-debugging/SKILL.md

@@ -0,0 +1,116 @@
+---
+name: service-debugging
+description: "Structured debugging runbook for backend services. Use when investigating production issues, API errors, performance problems, or when something broke and you need to find why."
+allowed_tools:
+  - Read
+  - Glob
+  - Grep
+  - Bash
+---
+
+# Service Debugging
+
+Structured approach to investigating and fixing service issues. Symptoms in, root cause out.
+
+## When to Use
+
+- API endpoint returning errors (4xx, 5xx)
+- Performance degradation or slow queries
+- Service not starting or crashing
+- Data inconsistency between services
+- After a deploy when something broke
+- User reports "something is broken"
+
+## Process
+
+### 1. Gather Symptoms
+
+Before touching code, collect:
+- **What's broken?** (specific endpoint, feature, or behavior)
+- **When did it start?** (after a deploy? gradually? suddenly?)
+- **Who's affected?** (all users, specific users, specific data?)
+- **Error messages?** (logs, HTTP responses, stack traces)
+
+### 2. Check the Obvious
+
+Run these first — they catch 80% of issues:
+
+```bash
+# Recent deploys (did someone push something?)
+git log --oneline -10
+
+# Service health
+curl -s http://localhost:8080/health | jq .
+
+# Recent errors in logs
+grep -i "error\|exception\|fatal" logs/app.log | tail -20
+
+# Database connectivity
+psql -h $DB_HOST -U $DB_USER -d $DB_NAME -c "SELECT 1"
+
+# Environment variables (missing or wrong?)
+env | grep -i "DB_\|API_\|SECRET_" | sort
+```
+
+### 3. Narrow Down
+
+| Symptom | Check First |
+|---------|-------------|
+| 500 errors | Stack trace in logs → find the throwing line |
+| 404 errors | Route registration → is the controller loaded? |
+| 401/403 errors | Auth config → is @Secured correct? Token valid? |
+| Slow response | Database → run EXPLAIN on the slow query |
+| Timeout | External service → is the downstream API responding? |
+| Data missing | Soft delete → is `deleted_at` set? Wrong query filter? |
+| Service won't start | Bean creation → check @Factory and @Singleton wiring |
+
+### 4. Reproduce
+
+- Can you trigger the bug locally?
+- What's the minimal request that fails?
+- Does it fail consistently or intermittently?
+
+### 5. Find Root Cause
+
+Use git bisect if it's a regression:
+```bash
+git bisect start
+git bisect bad HEAD
+git bisect good <last-known-good-commit>
+# Test each commit until you find the one that broke it
+```
+
+Use grep to find related code:
+```bash
+# Find where the error message comes from
+grep -r "error message text" --include="*.kt" src/
+
+# Find all callers of a broken function
+grep -r "functionName" --include="*.kt" src/
+```
+
+### 6. Fix and Verify
+
+1. Write a test that reproduces the bug (red)
+2. Fix the code (green)
+3. Run full test suite
+4. Test manually if it's a user-facing issue
+
+> See `common-issues.md` for a catalog of frequently seen bugs and their fixes.
+
+## Gotchas
+
+- **Don't fix the symptom, fix the cause.** Adding a null check that hides a data issue means the data issue will bite you later.
+- **Check the deploy log before blaming the code.** Config changes, environment variable updates, and infra changes cause more outages than code bugs.
+- **"It works on my machine" usually means environment difference.** Compare local env vars, database state, and service versions with the target environment.
+- **Intermittent failures are usually race conditions.** If it fails 1 in 10 times, look for concurrent access, shared mutable state, or connection pool exhaustion.
+- **Don't restart the service as your first debugging step.** You'll lose the state that helps you diagnose. Read logs first, then restart if needed.
+- **Soft-deleted records are the #1 "data missing" cause.** Always check `deleted_at IS NULL` in your queries.
+
+## Rules
+
+- Always gather symptoms before changing code
+- Write a failing test before fixing
+- Check recent git history — most bugs are regressions
+- Don't deploy a fix without understanding the root cause
+- Document the incident if it affected users