@softspark/ai-toolkit 1.0.0

package/app/skills/migration-patterns/SKILL.md

@@ -0,0 +1,260 @@
+---
+name: migration-patterns
+description: "Loaded when user asks about database migrations or zero-downtime deploys"
+effort: medium
+user-invocable: false
+---
+
+# Migration Patterns
+
+## Database Migration Tools
+
+### Alembic (Python/SQLAlchemy)
+```bash
+# Initialize
+alembic init migrations
+
+# Create migration
+alembic revision --autogenerate -m "add users table"
+
+# Apply
+alembic upgrade head
+
+# Rollback
+alembic downgrade -1
+```
+
+```python
+# migrations/versions/001_add_users.py
+def upgrade():
+    op.create_table(
+        "users",
+        sa.Column("id", sa.Integer, primary_key=True),
+        sa.Column("email", sa.String(255), unique=True, nullable=False),
+        sa.Column("created_at", sa.DateTime, server_default=sa.func.now()),
+    )
+    op.create_index("idx_users_email", "users", ["email"])
+
+def downgrade():
+    op.drop_index("idx_users_email")
+    op.drop_table("users")
+```
+
+### Prisma (TypeScript)
+```bash
+# Create migration
+npx prisma migrate dev --name add_users
+
+# Apply in production
+npx prisma migrate deploy
+
+# Reset (dev only)
+npx prisma migrate reset
+```
+
+### Laravel (PHP)
+```bash
+# Create migration
+php artisan make:migration create_users_table
+
+# Apply
+php artisan migrate
+
+# Rollback
+php artisan migrate:rollback --step=1
+
+# Dry run
+php artisan migrate --pretend
+```
+
+### Django (Python)
+```bash
+# Create migration from models
+python manage.py makemigrations
+
+# Apply
+python manage.py migrate
+
+# Rollback
+python manage.py migrate app_name 0001
+
+# Show plan
+python manage.py showmigrations
+```
+
+### Flyway (Java/SQL)
+```bash
+flyway migrate
+flyway info
+flyway undo    # Undo last migration (Teams edition)
+flyway repair  # Fix metadata table
+```
+
+## Zero-Downtime Migration Strategies
+
+### 1. Expand-Contract Pattern
+```
+Phase 1 (Expand): Add new column, keep old
+  ALTER TABLE users ADD COLUMN full_name VARCHAR(200);
+
+Phase 2 (Migrate): Copy data
+  UPDATE users SET full_name = first_name || ' ' || last_name;
+
+Phase 3 (Switch): Update code to use new column
+  Deploy new code that reads/writes full_name
+
+Phase 4 (Contract): Remove old columns
+  ALTER TABLE users DROP COLUMN first_name;
+  ALTER TABLE users DROP COLUMN last_name;
+```
+
+### 2. Safe Column Operations
+```sql
+-- Safe: Add nullable column
+ALTER TABLE users ADD COLUMN phone VARCHAR(20);
+
+-- Safe: Add column with default (PostgreSQL 11+, instant)
+ALTER TABLE users ADD COLUMN status VARCHAR(20) DEFAULT 'active';
+
+-- Safe: Create index concurrently (no lock)
+CREATE INDEX CONCURRENTLY idx_users_status ON users(status);
+
+-- UNSAFE: Add NOT NULL without default (locks table)
+-- Instead, do it in 3 steps:
+ALTER TABLE users ADD COLUMN email VARCHAR(255);
+UPDATE users SET email = 'unknown@example.com' WHERE email IS NULL;
+ALTER TABLE users ALTER COLUMN email SET NOT NULL;
+```
+
+### 3. Rename Column Safely
+```
+Step 1: Add new column
+Step 2: Write to both old and new columns (dual-write)
+Step 3: Backfill new column from old
+Step 4: Read from new column
+Step 5: Stop writing to old column
+Step 6: Drop old column (next release)
+```
+
+## Data Backfill Patterns
+
+### Batch Processing
+```python
+BATCH_SIZE = 1000
+
+def backfill_users():
+    last_id = 0
+    while True:
+        batch = db.execute(
+            "SELECT id, first_name, last_name FROM users "
+            "WHERE id > :last_id ORDER BY id LIMIT :limit",
+            {"last_id": last_id, "limit": BATCH_SIZE}
+        ).fetchall()
+
+        if not batch:
+            break
+
+        for row in batch:
+            db.execute(
+                "UPDATE users SET full_name = :name WHERE id = :id",
+                {"name": f"{row.first_name} {row.last_name}", "id": row.id}
+            )
+
+        db.commit()
+        last_id = batch[-1].id
+        logger.info(f"Backfilled up to id={last_id}")
+```
+
+## API Versioning
+
+### URL-Based (Most Common)
+```
+GET /api/v1/users
+GET /api/v2/users
+```
+
+### Header-Based
+```
+GET /api/users
+Accept: application/vnd.myapp.v2+json
+```
+
+### Implementation Pattern
+```python
+# FastAPI
+from fastapi import APIRouter
+
+v1_router = APIRouter(prefix="/api/v1")
+v2_router = APIRouter(prefix="/api/v2")
+
+@v1_router.get("/users")
+def get_users_v1():
+    return [{"name": user.name} for user in users]  # Old format
+
+@v2_router.get("/users")
+def get_users_v2():
+    return [{"full_name": user.name, "id": user.id} for user in users]  # New format
+```
+
+## Feature Flags for Gradual Rollout
+
+```python
+# Simple feature flag
+import os
+
+def is_feature_enabled(feature: str, user_id: str | None = None) -> bool:
+    flag = os.getenv(f"FF_{feature.upper()}", "false")
+    if flag == "true":
+        return True
+    if flag.endswith("%") and user_id:
+        percentage = int(flag[:-1])
+        return hash(user_id) % 100 < percentage
+    return False
+
+# Usage
+if is_feature_enabled("new_search", user_id=request.user.id):
+    return new_search(query)
+else:
+    return old_search(query)
+```
+
+## Rollback Strategies
+
+### Database Rollback
+```bash
+# Always test rollback before deploying
+alembic downgrade -1   # Alembic
+npx prisma migrate resolve --rolled-back 20240101_migration  # Prisma
+php artisan migrate:rollback --step=1  # Laravel
+```
+
+### Application Rollback
+```bash
+# Git-based rollback
+git revert HEAD --no-edit
+git push
+
+# Container rollback
+kubectl rollout undo deployment/api
+docker service rollback api
+```
+
+## Migration Checklist
+
+- [ ] Forward migration tested on staging
+- [ ] Rollback migration tested on staging
+- [ ] No data loss in either direction
+- [ ] Performance impact assessed (large tables?)
+- [ ] Backward compatible with current code
+- [ ] Backfill script tested (if needed)
+- [ ] Feature flag in place (if needed)
+- [ ] Monitoring/alerts configured
+- [ ] Team notified of migration window
+
+## Anti-Patterns
+- Running migrations without rollback plan
+- Locking large tables during peak hours
+- Mixing schema and data migrations
+- Not testing rollback path
+- Deploying code before migration completes
+- Dropping columns before removing code references

package/app/skills/night-watch/SKILL.md

@@ -0,0 +1,28 @@
+---
+name: night-watch
+description: "Run autonomous maintenance and dependency updates"
+effort: medium
+disable-model-invocation: true
+context: fork
+agent: night-watchman
+allowed-tools: Bash, Read, Edit, Grep
+---
+
+# Night Watch Command
+
+Triggers the autonomous maintenance agent.
+
+## Usage
+
+```bash
+/night-watch [scope]
+# Example: /night-watch deps
+# Example: /night-watch cleanup
+# Default: runs full suite
+```
+
+## Protocol
+1. **Checkout**: Create `maintenance/` branch.
+2. **Execute**: Run `night-watchman` agent skills.
+3. **Verify**: Run full test suite.
+4. **Report**: Generate Shift Report.

package/app/skills/observability-patterns/SKILL.md

@@ -0,0 +1,203 @@
+---
+name: observability-patterns
+description: "Loaded when user asks about logging, metrics, or tracing patterns"
+effort: medium
+user-invocable: false
+---
+
+# Observability Patterns
+
+## Structured Logging
+
+### Python (structlog)
+```python
+import structlog
+
+logger = structlog.get_logger()
+
+logger.info("user_created", user_id=user.id, email=user.email, source="api")
+logger.error("payment_failed", order_id=order.id, error=str(e), amount=amount)
+```
+
+### Node.js (Pino)
+```typescript
+import pino from "pino";
+
+const logger = pino({ level: "info", transport: { target: "pino-pretty" } });
+
+logger.info({ userId: user.id, action: "login" }, "User logged in");
+logger.error({ err, orderId: order.id }, "Payment processing failed");
+```
+
+### Log Levels
+| Level | Use For |
+|-------|---------|
+| `error` | Failures requiring attention |
+| `warn` | Unexpected but handled situations |
+| `info` | Business events, state transitions |
+| `debug` | Development diagnostics |
+
+### Rules
+- Always use structured key-value pairs, not string interpolation
+- Include correlation IDs for request tracing
+- Never log sensitive data (passwords, tokens, PII)
+- Log at boundaries: API entry/exit, external calls, state changes
+
+## OpenTelemetry
+
+### Python Setup
+```python
+from opentelemetry import trace, metrics
+from opentelemetry.sdk.trace import TracerProvider
+from opentelemetry.sdk.metrics import MeterProvider
+from opentelemetry.exporter.otlp.proto.grpc.trace_exporter import OTLPSpanExporter
+
+trace.set_tracer_provider(TracerProvider())
+trace.get_tracer_provider().add_span_processor(
+    BatchSpanProcessor(OTLPSpanExporter(endpoint="http://otel-collector:4317"))
+)
+
+tracer = trace.get_tracer(__name__)
+meter = metrics.get_meter(__name__)
+
+request_counter = meter.create_counter("http_requests_total", description="Total HTTP requests")
+request_duration = meter.create_histogram("http_request_duration_seconds")
+
+@tracer.start_as_current_span("process_order")
+def process_order(order_id: str):
+    request_counter.add(1, {"method": "POST", "endpoint": "/orders"})
+    with tracer.start_as_current_span("validate_order"):
+        validate(order_id)
+    with tracer.start_as_current_span("charge_payment"):
+        charge(order_id)
+```
+
+### Node.js Setup
+```typescript
+import { NodeSDK } from "@opentelemetry/sdk-node";
+import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-grpc";
+
+const sdk = new NodeSDK({
+  traceExporter: new OTLPTraceExporter({ url: "http://otel-collector:4317" }),
+  instrumentations: [getNodeAutoInstrumentations()],
+});
+sdk.start();
+```
+
+## Prometheus Metrics
+
+### Metric Types
+```python
+# Counter - monotonically increasing (requests, errors)
+http_requests_total = Counter("http_requests_total", "Total requests", ["method", "status", "path"])
+
+# Histogram - distribution (latency, sizes)
+request_duration = Histogram("request_duration_seconds", "Request latency",
+    buckets=[0.01, 0.05, 0.1, 0.25, 0.5, 1.0, 2.5, 5.0])
+
+# Gauge - current value (connections, queue size)
+active_connections = Gauge("active_connections", "Current active connections")
+```
+
+### Key Metrics (RED Method)
+| Metric | Type | Purpose |
+|--------|------|---------|
+| Request **R**ate | Counter | Traffic volume |
+| Request **E**rrors | Counter | Error rate |
+| Request **D**uration | Histogram | Latency distribution |
+
+### Key Metrics (USE Method - Infrastructure)
+| Metric | Type | Purpose |
+|--------|------|---------|
+| **U**tilization | Gauge | % resource used |
+| **S**aturation | Gauge | Queue depth |
+| **E**rrors | Counter | Error count |
+
+## Health Check Endpoints
+
+```python
+# FastAPI example
+@app.get("/health")
+async def health():
+    checks = {
+        "database": await check_db(),
+        "redis": await check_redis(),
+        "disk": check_disk_space(),
+    }
+    status = "healthy" if all(checks.values()) else "degraded"
+    code = 200 if status == "healthy" else 503
+    return JSONResponse({"status": status, "checks": checks}, status_code=code)
+
+@app.get("/ready")
+async def readiness():
+    """Kubernetes readiness probe - can this instance serve traffic?"""
+    return {"ready": True}
+
+@app.get("/live")
+async def liveness():
+    """Kubernetes liveness probe - is the process alive?"""
+    return {"alive": True}
+```
+
+## Error Tracking (Sentry)
+
+```python
+import sentry_sdk
+
+sentry_sdk.init(
+    dsn="https://key@sentry.io/project",
+    traces_sample_rate=0.1,
+    profiles_sample_rate=0.1,
+    environment="production",
+)
+
+# Automatic exception capture + manual context
+with sentry_sdk.push_scope() as scope:
+    scope.set_tag("order_id", order.id)
+    scope.set_context("payment", {"amount": amount, "currency": "USD"})
+    sentry_sdk.capture_exception(e)
+```
+
+## SLI/SLO Definition
+
+### Example SLOs
+| Service | SLI | SLO | Window |
+|---------|-----|-----|--------|
+| API | Availability (2xx / total) | 99.9% | 30 days |
+| API | Latency p99 | < 500ms | 30 days |
+| Search | Result relevance | > 80% | 7 days |
+| Ingest | Processing success rate | 99.5% | 30 days |
+
+### Error Budget
+```
+Error Budget = 1 - SLO = 1 - 0.999 = 0.1%
+Monthly budget = 30 days * 24h * 60min * 0.001 = 43.2 minutes
+```
+
+## Alerting Rules
+
+### Prometheus Alert Examples
+```yaml
+groups:
+  - name: api-alerts
+    rules:
+      - alert: HighErrorRate
+        expr: rate(http_requests_total{status=~"5.."}[5m]) / rate(http_requests_total[5m]) > 0.05
+        for: 5m
+        labels:
+          severity: critical
+        annotations:
+          summary: "Error rate above 5% for 5 minutes"
+
+      - alert: HighLatency
+        expr: histogram_quantile(0.99, rate(request_duration_seconds_bucket[5m])) > 1
+        for: 10m
+        labels:
+          severity: warning
+```
+
+### Alert Best Practices
+- Alert on symptoms (high latency), not causes (high CPU)
+- Include runbook links in annotations
+- Set appropriate severity: page only for user-impacting issues
+- Use `for` duration to avoid flapping

package/app/skills/onboard/SKILL.md

@@ -0,0 +1,76 @@
+---
+name: onboard
+description: "Generate project onboarding materials"
+effort: medium
+disable-model-invocation: true
+argument-hint: "[project-path]"
+allowed-tools: Bash, Read, Write, Glob
+---
+
+# /onboard - Project Setup Guide
+
+$ARGUMENTS
+
+## What This Command Does
+
+Guide the user through setting up the ai-toolkit in their project, including configuration and customization.
+
+## Setup Steps
+
+### Step 1: Prerequisites Check
+- [ ] Claude Code CLI installed
+- [ ] ai-toolkit repository cloned
+- [ ] Current directory is the target project
+
+### Step 2: Install Toolkit
+```bash
+# Run the installer from the toolkit directory
+/path/to/ai-toolkit/install.sh
+```
+
+This creates symlinks in `.claude/`:
+- `agents/` -> toolkit agents
+- `skills/` -> toolkit skills (slash commands + knowledge skills)
+- `hooks.json` -> quality gates
+- `constitution.md` -> safety rules
+
+### Step 3: Configure CLAUDE.md
+Create a project-specific `CLAUDE.md` from the template:
+```bash
+cp /path/to/ai-toolkit/CLAUDE.md.template ./CLAUDE.md
+```
+
+Customize with:
+- Project description and tech stack
+- Coding standards specific to this project
+- Common development commands
+- Architecture notes
+
+### Step 4: Configure Settings
+Edit `.claude/settings.local.json` for project-specific settings:
+- MCP server connections
+- Permission overrides
+- Environment variables
+
+### Step 5: Verify Installation
+```bash
+/path/to/ai-toolkit/validate.sh
+```
+
+### Step 6: Quick Start Guide
+
+| Command | Purpose |
+|---------|---------|
+| `/explore` | Understand the codebase |
+| `/plan` | Plan a new feature |
+| `/test` | Run tests |
+| `/review` | Code review |
+| `/commit` | Create a structured commit |
+
+## Usage Examples
+
+```
+/onboard              # Full guided setup
+/onboard verify       # Just verify existing installation
+/onboard update       # Update toolkit symlinks
+```

package/app/skills/orchestrate/SKILL.md

@@ -0,0 +1,86 @@
+---
+name: orchestrate
+description: "Coordinate multiple specialized agents in parallel"
+user-invocable: true
+effort: max
+argument-hint: "[task]"
+context: fork
+agent: orchestrator
+model: opus
+allowed-tools: Bash, Read, Write, Edit, Glob, Grep, Agent, TeamCreate, TeamDelete, SendMessage, TaskCreate, TaskList, TaskUpdate
+---
+
+# /orchestrate - Multi-Agent Coordination
+
+$ARGUMENTS
+
+## MANDATORY: You MUST use the Agent tool
+
+**DO NOT analyze or implement this task yourself.** Your only job is to decompose the task and invoke specialized agents via the `Agent` tool. If you attempt to do the work inline, you have failed.
+
+## Step 1 — Decompose
+
+Analyze the task and identify 3–6 sub-domains (e.g. backend, frontend, security, testing, docs). Define clear file ownership per domain so agents don't conflict.
+
+Present the decomposition to the user and wait for approval before Step 2.
+
+## Step 2 — Spawn agents in parallel (REQUIRED)
+
+Call the `Agent` tool **multiple times in a single response** — one call per sub-domain. All independent agents MUST be launched in the same message to run in parallel.
+
+Example for a feature implementation task:
+
+```
+Agent(subagent_type="backend-specialist", prompt="...", ...)
+Agent(subagent_type="frontend-specialist", prompt="...", ...)
+Agent(subagent_type="test-engineer", prompt="...", ...)
+Agent(subagent_type="security-auditor", prompt="...", ...)
+```
+
+Each agent prompt MUST include:
+1. The original user task
+2. The specific sub-task this agent owns
+3. File paths this agent is allowed to modify
+4. Success criteria for this agent's work
+
+## Step 3 — Synthesize
+
+After all agents complete, generate the Orchestration Report combining their findings.
+
+## Available Agents
+
+| Agent | Domain |
+|-------|--------|
+| `backend-specialist` | API, server logic, databases |
+| `frontend-specialist` | React, Vue, UI components |
+| `test-engineer` | Unit, integration, E2E tests |
+| `security-auditor` | OWASP, vulnerabilities, auth |
+| `database-architect` | Schema, migrations, queries |
+| `devops-implementer` | Docker, CI/CD, infra |
+| `performance-optimizer` | Profiling, bottlenecks |
+| `documenter` | KB, architecture notes, runbooks |
+| `code-reviewer` | Code quality, patterns |
+| `tech-lead` | Architecture, standards |
+
+## Output Format
+
+```markdown
+## Orchestration Report
+
+### Task
+[Original task]
+
+### Agents Invoked
+| # | Agent | Sub-task | Files | Status |
+|---|-------|----------|-------|--------|
+| 1 | backend-specialist | API layer | src/api/ | Done |
+| 2 | frontend-specialist | UI components | src/components/ | Done |
+| 3 | test-engineer | Test suite | tests/ | Done |
+
+### Key Findings
+1. **[Agent]**: Finding
+2. **[Agent]**: Finding
+
+### Summary
+[Synthesis]
+```

package/app/skills/panic/SKILL.md

@@ -0,0 +1,30 @@
+---
+name: panic
+description: "Emergency stabilization via system-governor agent"
+effort: low
+disable-model-invocation: true
+agent: system-governor
+context: fork
+allowed-tools: Bash
+---
+
+# Panic Command (The Kill Switch)
+
+Stops the system dead in its tracks.
+
+## Usage
+
+```bash
+/panic [reason]
+# Example: /panic "Agents are looping infinitely"
+```
+
+## Protocol
+1. **Create Lockfile**: `touch .claude/HALT`
+2. **Notify User**: "System Halted. Delete .claude/HALT to resume."
+
+## Resume
+To resume operations:
+```bash
+rm .claude/HALT
+```