@c0x12c/ai-toolkit 1.15.0

package/skills/service-debugging/common-issues.md

@@ -0,0 +1,65 @@
+# Common Service Issues — Quick Reference
+
+> This file is referenced by SKILL.md. Skim it when investigating a bug to see if it matches a known pattern.
+
+## Database Issues
+
+### "Connection pool exhausted"
+**Cause:** Tests or code not returning connections, or pool too small for load.
+**Fix:** Increase `maxPoolSize` in config. Check for leaked connections (queries without proper transaction blocks).
+
+### "Column X does not exist"
+**Cause:** Migration not applied, or table definition doesn't match the Kotlin code.
+**Fix:** Run `./gradlew flywayMigrate`. Compare SQL column names with Kotlin Table object.
+
+### "Unique constraint violation"
+**Cause:** Trying to insert a duplicate value on a unique index.
+**Fix:** Check if the record exists first, or use upsert pattern. Remember: soft-deleted records might not violate the constraint if the unique index has `WHERE deleted_at IS NULL`.
+
+### Query returns no results but data exists
+**Cause:** Missing `deletedAt.isNull()` filter, wrong join condition, or querying the wrong database (replica lag).
+**Fix:** Check the query for soft-delete filter. If using replica, check if the write has propagated.
+
+---
+
+## API Issues
+
+### 401 on every request
+**Cause:** Token expired, wrong auth header format, or @Secured misconfiguration.
+**Fix:** Check token expiry. Verify header is `Authorization: Bearer <token>`. Check controller has correct @Secured annotation.
+
+### 400 with no helpful message
+**Cause:** Jackson deserialization failure — field name mismatch between JSON and Kotlin DTO.
+**Fix:** Check if frontend sends `snake_case` but Kotlin expects `camelCase` (or vice versa). Verify Jackson SNAKE_CASE naming strategy is configured.
+
+### Endpoint returns empty list but data exists
+**Cause:** Query filter too strict, wrong field comparison, or soft-delete filtering out results.
+**Fix:** Check the manager query logic. Run the equivalent SQL directly to see what comes back.
+
+---
+
+## Build Issues
+
+### "error.NonExistentClass" in kapt
+**Cause:** Retrofit client interface in a module with kapt enabled.
+**Fix:** Move Retrofit interfaces to `module-client` (no kapt). See RETROFIT_PLACEMENT rule.
+
+### Tests pass locally but fail in CI
+**Cause:** Different database state, missing env vars, or timezone differences.
+**Fix:** Check CI environment variables match local `.env`. Ensure tests clean up after themselves (`truncateAllTables` in @BeforeEach).
+
+### Flyway migration fails
+**Cause:** Migration number conflicts, or trying to modify an already-applied migration.
+**Fix:** Never edit deployed migrations. Create a new migration with the next sequence number. Check `flyway_schema_history` table for applied migrations.
+
+---
+
+## Performance Issues
+
+### Endpoint suddenly slow (>1s)
+**Cause:** Missing database index, N+1 query, or full table scan.
+**Fix:** Run `EXPLAIN ANALYZE` on the slow query. Add indexes for columns in WHERE/JOIN clauses. Check for loops that query the database per item.
+
+### Memory growing over time
+**Cause:** Leaked connections, growing caches without eviction, or large result sets loaded into memory.
+**Fix:** Check connection pool metrics. Review cache configurations. Use pagination for large queries (never `findAll()` without limit).

package/skills/startup-pipeline/SKILL.md

@@ -0,0 +1,152 @@
+---
+name: startup-pipeline
+description: "Coordinates the full startup idea pipeline from brainstorm to investor outreach. Use when the user starts a new idea project, asks for the 'full pipeline', or references stages/gates."
+allowed_tools:
+  - WebSearch
+  - Read
+---
+
+# Startup Pipeline
+
+The full flow for taking an idea from zero to investor-ready.
+
+## The Pipeline
+
+```
+STAGE 1: DISCOVER          STAGE 2: FILTER           STAGE 3: DIG              STAGE 4: BUILD
+─────────────────          ───────────────           ─────────────             ──────────────
+/brainstorm                /validate                 /research                 /pitch
+                                                     /teardown                 /outreach
+                                                                               /content
+
+   Generate ideas  ──►  Kill bad ones fast  ──►  Go deep on survivors  ──►  Make materials
+   8-15 ideas             GO / TEST / PASS         Market + competitors      Deck, memo, emails
+   Pick top 3             Need data? Move on       Real numbers              Ready to send
+
+   📁 01-brainstorm/      📁 03-validation/        📁 02-research/           📁 04-build/
+```
+
+## Setup
+
+On first run, check for a `config.json` in the project root. If it doesn't exist, ask the user and create one:
+
+```json
+{
+  "projectName": "my-idea",
+  "outputDir": "projects/my-idea",
+  "defaultAudience": "B2B SaaS founders",
+  "fundingGoal": "bootstrap",
+  "currentStage": 1
+}
+```
+
+Update `currentStage` as the user progresses through gates. This lets the pipeline resume across sessions.
+
+## Stage Gates
+
+Each stage has a gate. Don't move forward unless you pass.
+
+### Gate 1: Worth Testing?
+After brainstorm, you need at least 1 idea where:
+- The problem is real (people feel pain)
+- You can build a v1 in 2 weeks
+- You know who the user is
+
+If none pass → brainstorm again or pick a new space.
+
+### Gate 2: Worth Researching?
+After validation, you need:
+- Verdict: **GO** or **TEST MORE**
+- At least some demand signal (people search for it, pay for alternatives, complain online)
+- No obvious killer (market too small, already dominated, illegal)
+
+If PASS → stop here. Move to next idea.
+If TEST MORE → do one cheap test first, then re-validate.
+
+### Gate 3: Worth Building?
+After deep research, you need:
+- Market big enough (>$100M TAM for VC, >$1M for bootstrap)
+- Clear gap in competitors (something nobody does well)
+- Realistic distribution path (you can get first 100 users)
+- You understand the customer better than before
+
+If no → archive the project. Save the research for later.
+
+### Gate 4: Ready to Send?
+After pitch materials, check:
+- All numbers match across docs
+- Claims are backed by your research
+- You can answer tough questions about each slide
+- The ask is clear
+
+## File Naming
+
+Each stage saves files with a prefix so they stay sorted:
+
+```
+projects/my-idea/
+├── 01-brainstorm/
+│   └── brainstorm-session-2026-03-02.md
+├── 02-research/
+│   ├── market-research-2026-03-03.md
+│   ├── teardown-competitor-a-2026-03-03.md
+│   └── teardown-competitor-b-2026-03-03.md
+├── 03-validation/
+│   └── validation-report-2026-03-02.md
+├── 04-build/
+│   ├── pitch-deck-outline-2026-03-04.md
+│   ├── one-pager-2026-03-04.md
+│   └── investor-emails-2026-03-04.md
+└── README.md
+```
+
+## How Combo Commands Map
+
+| Combo | Stages | What happens |
+|-------|--------|-------------|
+| `/kickoff [theme]` | 1 → 2 | Brainstorm + validate top ideas |
+| `/deep-dive [project]` | 3 | Research + teardown competitors |
+| `/fundraise [project]` | 4 | Pitch materials + outreach drafts |
+| `/startup [theme]` | 1 → 2 → 3 → 4 | Everything, with pauses at each gate |
+
+## 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 an idea should die at the gate
+- I don't let you skip ahead just because you're excited
+
+**Never:**
+- Ask a question without giving options
+- Let a weak idea pass a gate to be nice
+- Say "it depends" without picking a side
+- Skip the gate check
+- Pretend every idea deserves Stage 4
+
+## Gotchas
+
+- **Don't let excitement skip gates.** Users will want to jump from brainstorm to pitch deck. The gates exist to kill bad ideas early -- enforce them.
+- **"TEST MORE" is the most common verdict, not GO.** Most ideas need cheap validation before deep research. Don't treat the pipeline as a straight path.
+- **Stage 3 kills are normal and healthy.** Finding out a market is too small during research is a success, not a failure. You saved weeks of building.
+- **Pipeline files get stale.** If the user comes back after a week, re-read all prior stage files before continuing. Context drifts fast.
+- **One idea at a time through stages 3-4.** Brainstorm many, validate a few, but only deep-dive one at a time. Parallel research = shallow research.
+
+## Rules
+
+- Always pause at gates. Don't skip ahead.
+- Each stage builds on the last. Read prior work first.
+- If you're at Stage 3 and find a killer, be honest. Move to archive.
+- The pipeline saves time by killing bad ideas early.
+- Not every idea reaches Stage 4. That's the point.

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

@@ -0,0 +1,244 @@
+---
+name: terraform-best-practices
+description: Quick reference for Terraform conventions including file organization, naming, modules, state, security, and anti-patterns. Use when writing or reviewing Terraform code.
+---
+
+# Terraform Best Practices — Quick Reference
+
+## File Organization
+
+```
+terraform/
+  live/                    # Orchestration — providers, backend, module calls
+    terraform.tf           # backend + provider (ONLY place for providers)
+    variables.tf           # all input variables
+    locals.tf              # computed values, remote state refs
+    outputs.tf             # exported values
+    {resource-group}.tf    # module invocations grouped by concern
+  modules/{name}/          # Reusable — no providers, no hardcoded values
+    main.tf                # locals, data sources
+    variables.tf           # inputs with descriptions + types
+    outputs.tf             # consumed values only
+    versions.tf            # required_providers
+    {resource}.tf          # one file per resource type
+  envs/{env}/              # Per-environment config
+    state.config           # backend partial config
+    terraform.tfvars       # non-sensitive values
+    secrets.tfvars         # sensitive values (gitignored)
+```
+
+## Naming
+
+| Thing | Convention | Example |
+|-------|-----------|---------|
+| Resource prefix | `{project}-{service}-{env}` | `acme-payments-prod` |
+| Variables | `snake_case` | `instance_class` |
+| Locals | `snake_case` | `name_prefix` |
+| Outputs | `snake_case` | `repository_url` |
+| Resources | `this` (primary) or descriptive | `aws_db_instance.this` |
+| Security groups | `name_prefix` (not `name`) | `"${local.name_prefix}-app-"` |
+| Files | `{resource-type}.tf` | `rds.tf`, `sg.tf`, `ecr.tf` |
+| Modules | `kebab-case` directory | `modules/ecs-service/` |
+| Tags | PascalCase keys | `Project`, `Environment`, `ManagedBy` |
+
+## Module Patterns
+
+Use modules from the [c0x12c Terraform Registry](https://registry.terraform.io/namespaces/c0x12c).
+Each module source follows `c0x12c/{name}/aws` — see the registry for available modules and versions.
+
+```hcl
+# Calling a registry module — always version-pin
+module "database" {
+  source  = "c0x12c/rds/aws"
+  version = "~> 0.6.6"
+
+  name       = "${local.name_prefix}-db"
+  vpc_id     = local.vpc_id
+  subnet_ids = local.private_subnet_ids
+  tags       = local.common_tags
+}
+
+# Inside a module — no provider, explicit interface
+# versions.tf
+terraform {
+  required_version = ">= 1.5.0"
+  required_providers {
+    aws = {
+      source  = "hashicorp/aws"
+      version = ">= 5.0"
+    }
+  }
+}
+
+# variables.tf — every var has description + type
+variable "name" {
+  description = "Resource name prefix"
+  type        = string
+}
+
+# outputs.tf — only what consumers need
+output "endpoint" {
+  description = "Connection endpoint"
+  value       = aws_db_instance.this.endpoint
+}
+```
+
+## State Management
+
+```hcl
+# Backend config — S3 + DynamoDB locking
+terraform {
+  backend "s3" {}
+}
+
+# envs/dev/state.config
+bucket         = "{project}-terraform-state"
+key            = "{service}/dev/terraform.tfstate"
+region         = "us-east-1"
+dynamodb_table = "{project}-terraform-locks"
+encrypt        = true
+
+# Init with partial config
+# terraform init -backend-config=../envs/dev/state.config
+```
+
+```hcl
+# Remote state for cross-stack references
+data "terraform_remote_state" "infra" {
+  backend = "s3"
+  config = {
+    bucket = "{project}-terraform-state"
+    key    = "infra/terraform.tfstate"
+    region = var.region
+  }
+}
+
+locals {
+  vpc_id = data.terraform_remote_state.infra.outputs.vpc_id
+}
+```
+
+## Security Checklist
+
+```hcl
+# Sensitive variables
+variable "db_password" {
+  type      = string
+  sensitive = true
+}
+
+# S3 — block public, encrypt, version
+module "s3" {
+  versioning              = true
+  server_side_encryption  = { sse_algorithm = "aws:kms" }
+  block_public_access     = {
+    block_public_acls       = true
+    block_public_policy     = true
+    ignore_public_acls      = true
+    restrict_public_buckets = true
+  }
+}
+
+# RDS — encrypt, private subnet, protect
+resource "aws_db_instance" "this" {
+  storage_encrypted   = true
+  deletion_protection = var.env == "prod"
+  publicly_accessible = false  # ALWAYS false
+}
+
+# Security groups — source SG, not CIDR
+resource "aws_security_group_rule" "app_to_db" {
+  source_security_group_id = aws_security_group.app.id  # not cidr_blocks
+  from_port                = 5432
+  to_port                  = 5432
+}
+
+# Default tags at provider level
+provider "aws" {
+  default_tags {
+    tags = {
+      Project     = var.project
+      Service     = var.service
+      Environment = var.env
+      ManagedBy   = "terraform"
+    }
+  }
+}
+```
+
+## Common Anti-Patterns
+
+```hcl
+# WRONG — provider in module
+# modules/rds/main.tf
+provider "aws" { region = "us-east-1" }  # NEVER in a module
+
+# WRONG — no version pin
+module "rds" {
+  source = "git::https://github.com/{project}/terraform-modules.git//rds"
+  # missing ?ref=vX.Y.Z
+}
+
+# WRONG — hardcoded values
+resource "aws_s3_bucket" "assets" {
+  bucket = "acme-prod-assets"  # use ${local.name_prefix}-assets
+}
+
+# WRONG — secrets in code
+resource "aws_db_instance" "main" {
+  password = "hunter2"  # use var.db_password (sensitive)
+}
+
+# WRONG — wildcard IAM
+resource "aws_iam_policy" "app" {
+  policy = jsonencode({
+    Statement = [{ Action = "*", Resource = "*", Effect = "Allow" }]
+  })
+}
+
+# WRONG — public database
+resource "aws_db_instance" "main" {
+  publicly_accessible = true  # NEVER for databases
+}
+
+# WRONG — no state locking
+terraform {
+  backend "s3" {
+    # missing dynamodb_table for locking
+  }
+}
+
+# WRONG — all resources in one file
+# main.tf with 500+ lines of mixed RDS, S3, SQS, IAM...
+# Split into rds.tf, s3.tf, sqs.tf, iam.tf
+```
+
+## CI/CD Patterns
+
+```yaml
+# Standard workflow
+# PR: fmt check → validate → plan (comment on PR)
+# Merge to main: init → plan → apply
+
+# Key rules:
+# - Never auto-apply on PR
+# - Always post plan output as PR comment
+# - Lock state during apply (DynamoDB)
+# - Inject secrets via CI environment variables
+# - Pin Terraform version in CI to match team
+```
+
+## What to Avoid
+
+- Provider blocks in modules
+- Unpinned module versions
+- Hardcoded names, IDs, or account numbers
+- Secrets in `.tf` files or committed `.tfvars`
+- Wildcard IAM policies (`*` on `*`)
+- Public databases or caches
+- Missing encryption on storage
+- Monolithic files (split by resource type)
+- `terraform import` in automation (use `import` blocks)
+- Missing `description` on variables and outputs
+- Nested locals maps (keep flat)
+- `count` for conditional resources (use `for_each` with a set)