@rune-kit/rune 2.3.1 → 2.3.3

package/README.md

@@ -32,7 +32,7 @@ Mesh:      A ↔ B ↔ C             (B fails = A reaches C via D→E)
            D ↔ E ↔ F
 ```
 
-## What's New (v2.3.1)
+## What's New (v2.3.3)
 
 - **UI/UX Pro Max Integration** — 161 palettes, 84 styles, 73 font pairings, 161 reasoning rules from [UI/UX Pro Max](https://github.com/nextlevelbuilder/ui-ux-pro-max-skill) (MIT, 42.8k★) meshed into `design` skill + `@rune/ui` pack
 - **11 Core Skill Enrichments** — deviation rules, repair operators, evidence quality gate, decision classification, debug knowledge base, CSO discipline, YAGNI pushback, formal pause/resume

package/docs/index.html

@@ -62,7 +62,7 @@
       <canvas id="mesh-canvas"></canvas>
     </div>
     <div class="hero-content">
-      <p class="hero-badge">v2.3.1 &mdash; 59 skills &bull; 8 platforms &bull; MIT</p>
+      <p class="hero-badge">v2.3.3 &mdash; 59 skills &bull; 8 platforms &bull; MIT</p>
       <h1>Less skills.<br><span class="accent">Deeper connections.</span></h1>
       <p class="hero-sub">A mesh ecosystem for AI coding assistants. Skills call each other bidirectionally, forming resilient workflows that adapt when things go wrong.</p>
       <div class="hero-actions">

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rune-kit/rune",
-  "version": "2.3.1",
+  "version": "2.3.3",
   "description": "59-skill mesh for AI coding assistants — 5-layer architecture, 200+ connections, 8 platforms (Claude Code, Cursor, Windsurf, Antigravity, Codex, OpenCode, OpenClaw, Generic)",
   "type": "module",
   "bin": {

package/skills/db/SKILL.md

@@ -3,7 +3,7 @@ name: db
 description: Database workflow specialist. Generates migration files with rollback scripts, detects breaking schema changes, and validates query parameterization.
 metadata:
   author: runedev
-  version: "0.1.0"
+  version: "0.2.0"
   layer: L2
   model: sonnet
   group: development
@@ -35,6 +35,10 @@ Database workflow specialist. Handles the parts of database work that cause prod
 - `deploy` (L2): pre-deploy migration safety check
 - `audit` (L2): database health dimension
 
+## References
+
+- `references/scaling-reference.md` — Index strategies, query optimization, N+1 prevention, connection pooling, read replicas, partitioning, sharding, denormalization. Load when scaling, performance, or indexing context detected.
+
 ## Executable Steps
 
 ### Step 1 — Discovery

package/skills/db/references/scaling-reference.md

@@ -0,0 +1,271 @@
+# Database Scaling Reference
+
+> Loaded by `db` skill when scaling, indexing, or performance optimization context is detected.
+> Source patterns: production-proven PostgreSQL scaling strategies.
+
+---
+
+## Indexing Strategy
+
+### Index Type Selection
+
+| Type | Use Case | Example |
+|------|----------|---------|
+| **B-tree** (default) | Equality, range, sorting | `WHERE id = 1`, `ORDER BY date` |
+| **GIN** | Arrays, JSONB, full-text search | `WHERE tags @> ARRAY['a']` |
+| **GiST** | Geometric, spatial, nearest-neighbor | PostGIS, `ORDER BY location <->` |
+| **BRIN** | Large tables with natural ordering | Time-series > 100GB |
+
+### Compound Index Rules
+
+Order columns: **equality → range → sort**
+
+```sql
+-- Query: WHERE customer_id = X AND status IN (...) AND created_at > Y ORDER BY id
+CREATE INDEX idx_orders ON orders(customer_id, status, created_at, id);
+```
+
+### Partial Indexes (index what you query)
+
+```sql
+-- Only index active users (90% smaller, 90% faster writes)
+CREATE INDEX idx_active_users ON users(email) WHERE status = 'active';
+
+-- Only index pending orders
+CREATE INDEX idx_pending_orders ON orders(customer_id) WHERE status = 'pending';
+```
+
+### Covering Indexes (avoid heap lookups)
+
+```sql
+-- Query only needs total and date — include them in index
+CREATE INDEX idx_orders_covering ON orders(customer_id)
+INCLUDE (total, created_at);
+
+-- Index-only scan — no heap access needed
+SELECT total, created_at FROM orders WHERE customer_id = 123;
+```
+
+### Index Anti-Patterns
+
+- Indexing every column (slows writes, wastes storage)
+- Indexing low-cardinality columns alone (status with 3 values → useless)
+- Missing indexes on foreign keys (kills JOIN performance)
+- Unused indexes (check `pg_stat_user_indexes` for `idx_scan = 0`)
+
+---
+
+## Query Optimization
+
+### EXPLAIN ANALYZE — Always Profile
+
+```sql
+EXPLAIN (ANALYZE, BUFFERS, TIMING ON)
+SELECT * FROM orders WHERE customer_id = 123 AND created_at > NOW() - INTERVAL '30d';
+```
+
+**Red flags in output:**
+- `Seq Scan` on large table → missing index
+- `Filter` removes most rows → index should be more selective
+- `Sort` with high cost → add index that matches ORDER BY
+- `Nested Loop` with large outer table → consider hash/merge join
+
+### pg_stat_statements — Find Problem Queries
+
+```sql
+-- Top 10 slowest queries by total time
+SELECT query, calls, total_exec_time / 1000 AS total_sec,
+       mean_exec_time AS avg_ms,
+       100.0 * shared_blks_hit / NULLIF(shared_blks_hit + shared_blks_read, 0) AS cache_pct
+FROM pg_stat_statements
+ORDER BY total_exec_time DESC LIMIT 10;
+
+-- N+1 detector: queries called many times with low individual cost
+SELECT query, calls, mean_exec_time AS avg_ms
+FROM pg_stat_statements
+WHERE calls > 1000 AND mean_exec_time < 5
+ORDER BY calls DESC LIMIT 10;
+```
+
+---
+
+## N+1 Query Prevention
+
+### Prisma
+
+```typescript
+// BAD: 1 + N queries
+const users = await prisma.user.findMany();
+for (const u of users) {
+  u.posts = await prisma.post.findMany({ where: { authorId: u.id } });
+}
+
+// GOOD: 2 queries (parallel fetch)
+const users = await prisma.user.findMany({ include: { posts: true } });
+
+// GOOD: Single query (database JOIN)
+const users = await prisma.user.findMany({
+  relationLoadStrategy: 'join',
+  include: { posts: { select: { id: true, title: true } } }
+});
+```
+
+### Drizzle (no N+1 by design)
+
+```typescript
+const results = await db.select().from(users)
+  .leftJoin(posts, eq(users.id, posts.userId));
+```
+
+### Detection
+
+Enable query logging — look for **query count = 1 + N** where N = row count.
+
+```typescript
+// Prisma query logging
+const prisma = new PrismaClient({ log: [{ emit: 'event', level: 'query' }] });
+prisma.$on('query', (e) => {
+  if (e.duration > 100) console.warn(`SLOW: ${e.duration}ms — ${e.query}`);
+});
+```
+
+---
+
+## Connection Pooling
+
+### Sizing Formula
+
+```
+pool_size = (CPU cores × 2) + effective_spindle_count
+
+4-core  → 9 connections
+8-core  → 17 connections
+16-core → 33 connections
+```
+
+### PgBouncer Configuration
+
+```ini
+[pgbouncer]
+pool_mode = transaction          # Release after each transaction
+default_pool_size = 25           # Per database/user pair
+min_pool_size = 10               # Keep warm
+reserve_pool_size = 5            # Overflow buffer
+max_client_connections = 1000    # Total client limit
+server_idle_timeout = 600        # Close idle server connections (10min)
+query_wait_timeout = 120         # Max wait for available connection
+```
+
+**Warning signs:** Pool utilization > 80%, rising wait times, connection timeouts.
+
+---
+
+## Read Replicas
+
+### When to Add
+
+- Read:write ratio exceeds **10:1**
+- Primary CPU consistently > 70% from read queries
+- Analytics queries competing with transactional reads
+
+### Routing Pattern
+
+```typescript
+const primaryPool = new Pool({ host: 'primary.db.com' });
+const replicaPool = new Pool({ host: 'replica.db.com' });
+
+async function query(sql: string, params: unknown[], opts?: { write?: boolean }) {
+  const pool = opts?.write ? primaryPool : replicaPool;
+  return pool.query(sql, params);
+}
+```
+
+### Replication Lag
+
+- Typical: 5-50ms for well-tuned async replication
+- **Read-your-writes consistency**: After a write, read from primary for that user's session
+- **Analytics queries**: Always safe on replicas (stale data acceptable)
+
+---
+
+## Partitioning
+
+### When to Partition
+
+- Table exceeds **100GB** or **100M+ rows**
+- Queries always filter on a specific column (date, tenant)
+- Need fast deletion of old data (`DROP` partition vs `DELETE`)
+
+### Range Partitioning (time-series)
+
+```sql
+CREATE TABLE events (
+  id BIGSERIAL, created_at TIMESTAMPTZ NOT NULL, data JSONB
+) PARTITION BY RANGE (created_at);
+
+CREATE TABLE events_2025_01 PARTITION OF events
+  FOR VALUES FROM ('2025-01-01') TO ('2025-02-01');
+
+-- Delete old data instantly
+DROP TABLE events_2024_01; -- 0.01s vs DELETE minutes
+```
+
+### Hash Partitioning (even distribution)
+
+```sql
+CREATE TABLE orders (id BIGSERIAL, customer_id INT, data JSONB)
+PARTITION BY HASH (customer_id);
+
+CREATE TABLE orders_0 PARTITION OF orders FOR VALUES WITH (MODULUS 4, REMAINDER 0);
+CREATE TABLE orders_1 PARTITION OF orders FOR VALUES WITH (MODULUS 4, REMAINDER 1);
+```
+
+**Rule:** Keep partition count under 500 — query planning overhead grows with partition count.
+
+---
+
+## Sharding Decision Matrix
+
+### When to Shard (Last Resort)
+
+| Strategy | Pros | Cons |
+|----------|------|------|
+| **Hash-based** | Even distribution | No range queries on shard key |
+| **Range-based** | Range queries work | Hot shards if distribution skewed |
+| **Tenant-based** | Strong isolation | Uneven if tenants vary in size |
+
+### Before Sharding, Try These First
+
+1. Add proper indexes
+2. Fix N+1 queries
+3. Add read replicas
+4. Add caching layer
+5. Partition large tables
+6. Vertical scaling (bigger instance)
+7. Archive old data
+8. Optimize queries with EXPLAIN ANALYZE
+
+---
+
+## Denormalization Decision Matrix
+
+| Scenario | Keep Normalized | Denormalize |
+|----------|----------------|-------------|
+| High write volume | Yes | No |
+| High read volume, slow joins | No | Yes |
+| Data consistency critical | Yes | No |
+| Analytics / reporting | No | Yes (materialized views) |
+
+### Materialized Views
+
+```sql
+CREATE MATERIALIZED VIEW order_stats AS
+SELECT customer_id, COUNT(*) AS order_count, SUM(total) AS total_spent
+FROM orders GROUP BY customer_id;
+
+-- Refresh periodically (CONCURRENTLY allows reads during refresh)
+REFRESH MATERIALIZED VIEW CONCURRENTLY order_stats;
+CREATE UNIQUE INDEX ON order_stats(customer_id);
+```
+
+**Rule:** Start normalized. Denormalize specific queries only when EXPLAIN shows expensive joins that caching can't solve.

package/skills/perf/SKILL.md

@@ -3,7 +3,7 @@ name: perf
 description: Performance regression gate. Detects N+1 queries, sync-in-async, missing indexes, memory leaks, and bundle bloat before they reach production.
 metadata:
   author: runedev
-  version: "0.1.0"
+  version: "0.2.0"
   layer: L2
   model: sonnet
   group: quality
@@ -38,6 +38,11 @@ Performance regression gate. Analyzes code changes for patterns that cause measu
 - `review` (L2): performance patterns detected in diff
 - `deploy` (L2): pre-deploy perf regression check
 
+## References
+
+- `references/cost-reference.md` — Cost priority hierarchy, quick wins checklist, instance right-sizing, data transfer traps, serverless optimization, observability cost control, managed vs self-hosted matrix, unit economics tracking. Load when cost analysis or FinOps context detected.
+- `references/scalability-reference.md` — Bottleneck identification flow, performance thresholds, API patterns (cursor pagination, rate limiting, circuit breaker, graceful shutdown), caching strategies, queue-based load leveling, concurrency patterns, K8s HPA, CDN headers, load testing. Load when scaling or infrastructure optimization context detected.
+
 ## Executable Steps
 
 ### Step 1 — Scope

package/skills/perf/references/cost-reference.md

@@ -0,0 +1,205 @@
+# Cost Optimization Reference
+
+> Loaded by `perf` skill when cost analysis, cloud spending, or FinOps context is detected.
+> Patterns: production-proven cost reduction strategies with dollar-impact estimates.
+
+---
+
+## Cost Priority Hierarchy
+
+Optimize in this order — higher tiers save 10x more than lower:
+
+```
+1. Architecture choices     (10x impact — monolith vs micro, serverless vs containers)
+2. Data transfer            (NAT Gateway, cross-region, CDN vs origin)
+3. Compute right-sizing     (instance types, spot/reserved, autoscaling)
+4. Database optimization    (query tuning, connection pooling, read replicas)
+5. Caching layer            (Redis, CDN, in-memory — ROI depends on hit rate)
+6. Storage tiering          (S3 lifecycle, cold storage, cleanup)
+7. Bundle/asset size        (tree-shaking, image optimization, compression)
+8. Observability costs      (log sampling, trace sampling, retention)
+```
+
+---
+
+## Quick Wins Checklist
+
+| Fix | Typical Savings | Effort |
+|-----|----------------|--------|
+| S3 Intelligent-Tiering on infrequent buckets | 40-70% storage | 5 min |
+| Fix N+1 queries (Prisma `include`) | 10-100x query reduction | 30 min |
+| WebP/AVIF images (Sharp pipeline) | 25-80% bandwidth | 1 hr |
+| Add CDN for static assets | 50-90% origin traffic | 1 hr |
+| NAT Gateway → VPC endpoints for AWS services | $30-100/mo per service | 30 min |
+| Log sampling (10% INFO, 100% ERROR) | 50-80% observability bill | 30 min |
+| Gzip/Brotli response compression | 70-90% transfer size | 15 min |
+| Lambda memory right-sizing (power tuning) | 10-40% Lambda cost | 1 hr |
+
+---
+
+## Instance Right-Sizing
+
+### AWS EC2 Strategy
+
+| Strategy | Savings | Commitment |
+|----------|---------|-----------|
+| On-Demand | Baseline | None |
+| Spot Instances | 60-90% | Can be interrupted |
+| Reserved (1-yr) | ~40% | 1 year |
+| Reserved (3-yr) | ~60% | 3 years |
+| Savings Plans | ~30-40% | Flexible commitment |
+
+### Kubernetes Right-Sizing
+
+```yaml
+# Set requests = actual P95 usage, limits = 2x requests
+resources:
+  requests:
+    cpu: "250m"      # Based on actual P95 CPU usage
+    memory: "256Mi"  # Based on actual P95 memory
+  limits:
+    cpu: "500m"
+    memory: "512Mi"
+```
+
+Check actual usage: `kubectl top pods --sort-by=cpu`
+
+---
+
+## Data Transfer Cost Traps
+
+### NAT Gateway Problem
+
+NAT Gateway: **$0.045/GB + $0.045/hr** — one of the most expensive AWS surprises.
+
+**Fix:** Replace with VPC endpoints for AWS services:
+```
+S3 Gateway Endpoint         → Free (gateway type)
+DynamoDB Gateway Endpoint   → Free (gateway type)
+SQS/SNS Interface Endpoint → $0.01/hr (still 4x cheaper than NAT)
+```
+
+### Cross-Region Transfer
+
+- Same region, same AZ: **Free**
+- Same region, different AZ: **$0.01/GB**
+- Cross-region: **$0.02/GB**
+- Internet egress: **$0.09/GB** (first 10TB)
+
+**Rule:** Keep services in the same AZ when possible. Use CloudFront for global distribution.
+
+---
+
+## Serverless Optimization
+
+### Lambda Memory Tuning
+
+Lambda CPU scales linearly with memory. Sometimes MORE memory = CHEAPER (faster execution):
+
+```
+128MB, 3000ms  = 375,000 GB-ms = $0.00000625
+512MB, 800ms   = 400,000 GB-ms = $0.00000667  (similar cost, 4x faster)
+1024MB, 400ms  = 400,000 GB-ms = $0.00000667  (same cost, 7.5x faster)
+```
+
+Use [AWS Lambda Power Tuning](https://github.com/alexcasalboni/aws-lambda-power-tuning) to find optimal memory.
+
+### Cold Start Reduction
+
+| Technique | Impact |
+|-----------|--------|
+| Smaller deployment package | -100-500ms |
+| Use Graviton (arm64) | -200ms + 20% cheaper |
+| Provisioned concurrency | Eliminates cold starts |
+| Lazy-load heavy SDKs | -200-1000ms |
+| Use ESM instead of CJS | -100-300ms (Node.js) |
+
+---
+
+## Observability Cost Control
+
+### Log Sampling
+
+```typescript
+// Sample 10% of INFO logs, keep 100% of errors
+const shouldLog = (level: string): boolean => {
+  if (level === 'error' || level === 'warn') return true;
+  return Math.random() < 0.1; // 10% sampling
+};
+```
+
+### Trace Sampling
+
+```typescript
+// 100% errors and slow requests, 10% normal
+const shouldTrace = (duration: number, isError: boolean): boolean => {
+  if (isError) return true;
+  if (duration > 1000) return true; // Slow requests
+  return Math.random() < 0.1;
+};
+```
+
+### High-Cardinality Metrics — NEVER DO
+
+```typescript
+// BAD: Creates millions of unique time series
+metrics.counter('requests', { userId: req.userId }); // ← kills Datadog bill
+
+// GOOD: Low-cardinality labels only
+metrics.counter('requests', { endpoint: '/api/users', method: 'GET', status: '200' });
+```
+
+### Retention Policies
+
+| Data Type | Recommended Retention |
+|-----------|----------------------|
+| Raw logs | 7-14 days |
+| Aggregated metrics | 90 days |
+| Error logs | 30-90 days |
+| Traces | 7 days |
+| Audit logs | 1-7 years (compliance) |
+
+---
+
+## Managed vs Self-Hosted Decision Matrix
+
+| Service | Self-Host When | Stay Managed When |
+|---------|---------------|-------------------|
+| Auth | >200K MAU ($4K+/mo managed) | <200K MAU or need compliance |
+| Search | >500K records or >$500/mo | <500K records, need instant setup |
+| Database | >$500/mo RDS bill | Need HA, backups, patching handled |
+| Email | Almost never | Always (deliverability is hard) |
+| Monitoring | >$1K/mo Datadog | Need APM + distributed tracing |
+
+---
+
+## Unit Economics Tracking
+
+```typescript
+// Track cost per unit to detect inefficiency trends
+interface UnitEconomics {
+  costPerRequest: number;   // Total infra / total requests
+  costPerUser: number;      // Total infra / MAU
+  costPerTransaction: number; // Total infra / transactions
+}
+
+// Alert if unit cost increases >20% month-over-month
+function checkCostTrend(current: number, previous: number): void {
+  const increase = (current - previous) / previous;
+  if (increase > 0.2) {
+    alert(`Unit cost increased ${(increase * 100).toFixed(0)}% — investigate`);
+  }
+}
+```
+
+---
+
+## Cost Optimization Priority Matrix
+
+| Effort | Low Savings (<$100/mo) | Med Savings ($100-500) | High Savings (>$500) |
+|--------|----------------------|----------------------|---------------------|
+| **Low** | Log retention | Image optimization | S3 tiering |
+| **Medium** | Bundle analysis | Caching layer | Instance right-sizing |
+| **High** | — | Query optimization | Architecture redesign |
+
+**Rule:** Start top-right (high savings, low effort), work diagonally down-left.

package/skills/perf/references/scalability-reference.md

@@ -0,0 +1,378 @@
+# Scalability Reference
+
+> Loaded by `perf` skill when scaling, load handling, or infrastructure optimization context is detected.
+> Patterns: production-proven scalability strategies for Node.js/TypeScript applications.
+
+---
+
+## Bottleneck Identification Flow
+
+Profile BEFORE optimizing. Follow this decision tree:
+
+```
+Is database the bottleneck (>50% of response time)?
+├── YES → Index optimization, connection pooling, read replicas, query caching
+│         See db/references/scaling-reference.md
+└── NO
+    Is external API the bottleneck?
+    ├── YES → Circuit breaker, caching, parallel requests, queue background
+    └── NO
+        Is it CPU-bound?
+        ├── YES → Worker threads, horizontal scaling, algorithm optimization
+        └── NO
+            Is it memory pressure?
+            ├── YES → Leak detection, streaming, pagination, bounded caches
+            └── NO → Measure again with better instrumentation
+```
+
+## Performance Thresholds
+
+| Metric | Healthy | Warning | Critical |
+|--------|---------|---------|----------|
+| p99 latency | <200ms | 200-500ms | >500ms |
+| DB cache hit ratio | >95% | 90-95% | <90% |
+| Connection pool utilization | <70% | 70-85% | >85% |
+| CPU utilization | <60% | 60-80% | >80% |
+| Memory utilization | <70% | 70-85% | >85% |
+| Error rate | <0.1% | 0.1-1% | >1% |
+| Queue depth | <100 | 100-1000 | >1000 |
+| Queue wait time | <1s | 1-10s | >10s |
+
+---
+
+## API Scalability Patterns
+
+### Cursor-Based Pagination
+
+Offset pagination breaks at scale (`OFFSET 100000` = scan 100K rows). Use cursor-based:
+
+```typescript
+// Cursor-based — consistent performance at any depth
+async function listOrders(cursor?: string, limit = 20) {
+  const where = cursor ? { id: { gt: cursor } } : {};
+  const items = await prisma.order.findMany({
+    where,
+    take: limit + 1, // Fetch one extra to detect hasMore
+    orderBy: { id: 'asc' },
+  });
+
+  const hasMore = items.length > limit;
+  const data = hasMore ? items.slice(0, -1) : items;
+
+  return {
+    data,
+    cursor: data.at(-1)?.id ?? null,
+    hasMore,
+  };
+}
+```
+
+### Rate Limiting (Tiered)
+
+```typescript
+const rateLimits = {
+  free:       { requests: 100,  window: '15m' },
+  pro:        { requests: 1000, window: '15m' },
+  enterprise: { requests: 10000, window: '15m' },
+};
+
+// Response headers (always include)
+// X-RateLimit-Limit: 1000
+// X-RateLimit-Remaining: 847
+// X-RateLimit-Reset: 1699234567
+// Retry-After: 30  (only on 429)
+```
+
+### Circuit Breaker
+
+```typescript
+import CircuitBreaker from 'opossum';
+
+const breaker = new CircuitBreaker(callExternalAPI, {
+  timeout: 3000,          // Fail if function takes > 3s
+  errorThresholdPercentage: 50,  // Open if 50% fail
+  resetTimeout: 30000,    // Try again after 30s
+  volumeThreshold: 10,    // Min calls before tripping
+});
+
+breaker.fallback(() => cachedResponse);
+breaker.on('open', () => logger.warn('Circuit breaker OPEN'));
+```
+
+### Graceful Shutdown
+
+```typescript
+async function shutdown(signal: string) {
+  logger.info(`${signal} received — starting graceful shutdown`);
+
+  // 1. Stop accepting new connections
+  server.close();
+
+  // 2. Finish in-flight requests (with timeout)
+  await Promise.race([
+    finishInflightRequests(),
+    new Promise(resolve => setTimeout(resolve, 30000)),
+  ]);
+
+  // 3. Close DB connections
+  await prisma.$disconnect();
+  await redis.quit();
+
+  process.exit(0);
+}
+
+process.on('SIGTERM', () => shutdown('SIGTERM'));
+process.on('SIGINT', () => shutdown('SIGINT'));
+```
+
+---
+
+## Caching Strategies
+
+### Strategy Selection
+
+| Strategy | When to Use | Trade-off |
+|----------|-------------|-----------|
+| **Cache-aside** | Most common. App checks cache, falls back to DB | May serve stale data |
+| **Write-through** | Cache updated on every write | Higher write latency |
+| **Write-behind** | Cache updated async after write | Risk of data loss |
+| **Read-through** | Cache auto-fetches on miss | Cache library dependency |
+
+### TTL Guidelines
+
+| Data Type | TTL | Rationale |
+|-----------|-----|-----------|
+| Static config | 1 hour | Rarely changes |
+| User profile | 5 min | Changes occasionally |
+| Product catalog | 15 min | Balance freshness vs load |
+| Session data | 30 min sliding | Security + UX |
+| Rate limit counters | Match window | Exact timing matters |
+| Search results | 60s | High-read, low-freshness need |
+
+### Cache Invalidation Patterns
+
+```typescript
+// 1. TTL-based (simplest, eventual consistency)
+await redis.setex(`user:${id}`, 300, JSON.stringify(user));
+
+// 2. Explicit invalidation (strongest consistency)
+await prisma.user.update({ where: { id }, data });
+await redis.del(`user:${id}`);
+
+// 3. Tag-based (invalidate groups)
+await redis.sadd('tag:users', `user:${id}`, `user:${id}:posts`);
+// On invalidate:
+const keys = await redis.smembers('tag:users');
+await redis.del(...keys);
+
+// 4. Versioned keys (zero-downtime cache migration)
+const version = 'v2';
+await redis.setex(`user:${version}:${id}`, 300, data);
+```
+
+---
+
+## Queue-Based Load Leveling
+
+### When to Use Queues
+
+- Request takes > 500ms to process
+- External API with rate limits
+- Spiky traffic patterns
+- Fire-and-forget operations (email, webhooks, analytics)
+
+### BullMQ Pattern
+
+```typescript
+import { Queue, Worker } from 'bullmq';
+
+const emailQueue = new Queue('emails', { connection: redis });
+
+// Producer — returns immediately
+await emailQueue.add('welcome', { userId, email }, {
+  attempts: 3,
+  backoff: { type: 'exponential', delay: 1000 },
+  removeOnComplete: 1000,  // Keep last 1000 completed
+  removeOnFail: 5000,      // Keep last 5000 failed
+});
+
+// Consumer — processes in background
+const worker = new Worker('emails', async (job) => {
+  await sendEmail(job.data.email, 'Welcome!');
+}, {
+  connection: redis,
+  concurrency: 5,          // Process 5 emails in parallel
+  limiter: { max: 10, duration: 1000 }, // Rate limit: 10/sec
+});
+```
+
+---
+
+## Concurrency Patterns
+
+### Worker Threads (CPU-intensive)
+
+```typescript
+import { Worker, isMainThread, parentPort, workerData } from 'worker_threads';
+
+if (isMainThread) {
+  const worker = new Worker(__filename, { workerData: { input } });
+  worker.on('message', (result) => resolve(result));
+  worker.on('error', reject);
+} else {
+  const result = heavyComputation(workerData.input);
+  parentPort?.postMessage(result);
+}
+```
+
+### Backpressure (prevent OOM)
+
+```typescript
+// Bounded queue — reject when full instead of consuming infinite memory
+class BoundedQueue<T> {
+  private queue: T[] = [];
+  constructor(private maxSize: number) {}
+
+  enqueue(item: T): boolean {
+    if (this.queue.length >= this.maxSize) return false; // Apply backpressure
+    this.queue.push(item);
+    return true;
+  }
+}
+```
+
+### Semaphore (limit concurrent operations)
+
+```typescript
+class Semaphore {
+  private current = 0;
+  private queue: (() => void)[] = [];
+
+  constructor(private max: number) {}
+
+  async acquire(): Promise<void> {
+    if (this.current < this.max) {
+      this.current++;
+      return;
+    }
+    return new Promise((resolve) => this.queue.push(resolve));
+  }
+
+  release(): void {
+    this.current--;
+    const next = this.queue.shift();
+    if (next) { this.current++; next(); }
+  }
+}
+
+// Usage: limit to 10 concurrent DB connections
+const sem = new Semaphore(10);
+await sem.acquire();
+try { await db.query(sql); }
+finally { sem.release(); }
+```
+
+---
+
+## Deployment Scalability
+
+### Kubernetes HPA
+
+```yaml
+apiVersion: autoscaling/v2
+kind: HorizontalPodAutoscaler
+metadata:
+  name: api-hpa
+spec:
+  scaleTargetRef:
+    apiVersion: apps/v1
+    kind: Deployment
+    name: api
+  minReplicas: 2
+  maxReplicas: 20
+  metrics:
+    - type: Resource
+      resource:
+        name: cpu
+        target:
+          type: Utilization
+          averageUtilization: 70
+  behavior:
+    scaleUp:
+      stabilizationWindowSeconds: 60
+    scaleDown:
+      stabilizationWindowSeconds: 300  # Slow scale-down prevents flapping
+```
+
+### CDN Cache-Control Headers
+
+```
+# Immutable assets (hashed filenames)
+Cache-Control: public, max-age=31536000, immutable
+
+# API responses (short cache + revalidation)
+Cache-Control: public, max-age=60, stale-while-revalidate=30
+
+# Private user data
+Cache-Control: private, no-store
+
+# HTML pages (revalidate every time)
+Cache-Control: no-cache
+```
+
+### Zero-Downtime Database Migrations
+
+3-phase safe migration pattern:
+
+```
+Phase 1: ADD new column (nullable) → deploy
+Phase 2: Deploy code that writes to BOTH old + new columns → backfill
+Phase 3: Drop old column → deploy
+
+NEVER in one step:
+- Rename column (breaks running code)
+- Change type (data loss risk)
+- Add NOT NULL without default (fails on existing rows)
+```
+
+---
+
+## Load Testing
+
+### k6 Quick Start
+
+```javascript
+import http from 'k6/http';
+import { check, sleep } from 'k6';
+
+export const options = {
+  stages: [
+    { duration: '1m', target: 50 },   // Ramp up
+    { duration: '3m', target: 50 },   // Steady state
+    { duration: '1m', target: 0 },    // Ramp down
+  ],
+  thresholds: {
+    http_req_duration: ['p(99)<500'],  // 99th percentile < 500ms
+    http_req_failed: ['rate<0.01'],    // Error rate < 1%
+  },
+};
+
+export default function () {
+  const res = http.get('https://api.example.com/orders');
+  check(res, { 'status 200': (r) => r.status === 200 });
+  sleep(1);
+}
+```
+
+### What to Measure
+
+| Metric | Target | Why |
+|--------|--------|-----|
+| p50 latency | <100ms | Typical user experience |
+| p99 latency | <500ms | Worst-case user experience |
+| Throughput (RPS) | >baseline | Capacity headroom |
+| Error rate | <0.1% | Reliability |
+| CPU during load | <80% | Scaling headroom |
+| Memory during load | <70% | Leak detection |
+
+**Rule:** Always observe p99, not p50. Median latency hides tail latency that kills user experience.

package/skills/skill-forge/SKILL.md

@@ -3,7 +3,7 @@ name: skill-forge
 description: Use when creating new Rune skills, editing existing skills, or verifying skill quality before deployment. Applies TDD discipline to skill authoring — test before write, verify before ship.
 metadata:
   author: runedev
-  version: "1.5.0"
+  version: "1.6.0"
   layer: L2
   model: opus
   group: creation
@@ -34,6 +34,10 @@ The skill that builds skills. Applies Test-Driven Development to skill authoring
 
 - `cook` (L1): when the feature being built IS a new skill
 
+## References
+
+- `references/claude-skill-reference.md` — Claude Code skill system: frontmatter fields, variables, shell injection, invocation control matrix, skill type patterns (task/research/knowledge/dynamic), file structure, and quality checklist. Load when creating or editing any skill.
+
 ## Workflow
 
 ### Phase 1 — DISCOVER

package/skills/skill-forge/references/claude-skill-reference.md

@@ -0,0 +1,182 @@
+# Claude Code Skill System Reference
+
+> Loaded by `skill-forge` when creating or editing skills. Covers frontmatter fields, variables, shell injection, invocation control, and skill type patterns.
+
+---
+
+## Frontmatter Fields
+
+### Required
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `name` | string | Kebab-case identifier. Becomes the `/slash-command`. Must match directory name. |
+| `description` | string | What the skill does. Claude uses this for auto-activation matching. Include action verbs and trigger phrases. |
+
+### Optional
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `argument-hint` | string | — | Shown in autocomplete after command name. Use `[brackets]`. |
+| `user-invocable` | boolean | `true` | If `false`, no slash command — auto-activate only. |
+| `auto-activate` | boolean | `true` | If `false`, slash command only — never auto-activates. |
+| `allowed-tools` | string[] | all | Whitelist of tools the skill can use. |
+| `disallowed-tools` | string[] | none | Blacklist of tools. |
+
+### Invocation Control Matrix
+
+| `user-invocable` | `auto-activate` | Behavior |
+|-------------------|-----------------|----------|
+| `true` (default) | `true` (default) | Full access: slash command + auto-activates |
+| `true` | `false` | Slash command only, never auto-activates |
+| `false` | `true` | Auto-activate only, no slash command |
+| `false` | `false` | Never runs — avoid this combination |
+
+---
+
+## Variables
+
+Replaced at invocation time before Claude sees the content.
+
+| Variable | Description |
+|----------|-------------|
+| `$ARGUMENTS` | Everything after `/command`. Empty if no arguments. |
+| `$0` | Alias for `$ARGUMENTS` |
+| `${CLAUDE_SKILL_DIR}` | Absolute path to skill directory. Use for referencing supporting files. |
+| `${CLAUDE_SESSION_ID}` | Unique ID for current Claude Code session. |
+
+**Usage in SKILL.md:**
+```markdown
+The user wants: $ARGUMENTS
+Read `${CLAUDE_SKILL_DIR}/reference.md` for details.
+```
+
+---
+
+## Shell Injection
+
+Embed live command output using `` !`command` `` syntax:
+
+```markdown
+Current branch: !`git branch --show-current`
+Node version: !`node --version`
+Changed files: !`git diff main --name-only`
+```
+
+**How it works:**
+- Commands execute when skill activates (not at definition time)
+- Output replaces the `` !`command` `` inline
+- Commands run in current working directory
+- Keep commands fast — slow commands delay skill activation
+- Don't use for side effects — skill content is for context, not execution
+
+---
+
+## Skill Type Patterns
+
+### Task Skill (side effects)
+
+Performs actions — deploy, commit, publish. Use `auto-activate: false` for destructive operations.
+
+```yaml
+---
+name: deploy
+description: Deploy application to production or staging. Use when user wants to deploy, ship, release.
+argument-hint: [environment: staging|production]
+auto-activate: false
+---
+```
+
+### Research Skill (information gathering)
+
+Gathers and synthesizes information. Uses Agent subagents for parallel research.
+
+```yaml
+---
+name: deep-research
+description: Perform deep research on a topic using web search and analysis.
+argument-hint: [topic or question to research]
+---
+```
+
+### Knowledge Skill (pure reference)
+
+Provides reference context. Auto-activates when relevant, no slash command needed.
+
+```yaml
+---
+name: api-conventions
+description: API design conventions for this project. Use when writing API endpoints or reviewing API code.
+user-invocable: false
+---
+```
+
+### Dynamic Context Skill (live state)
+
+Uses shell injection to inject current project state.
+
+```markdown
+Branch: !`git branch --show-current`
+Changed files: !`git diff main --name-only`
+```
+
+---
+
+## File Structure & Loading
+
+```
+skills/my-skill/
+├── SKILL.md          # Required — loaded on activation
+├── reference.md      # Optional — read on-demand via ${CLAUDE_SKILL_DIR}
+├── examples.md       # Optional — read on-demand
+└── scripts/          # Optional — bundled scripts, never auto-loaded
+```
+
+**Loading behavior:**
+- **SKILL.md**: Always loaded when skill activates
+- **Supporting `.md` files**: NOT auto-loaded. Only read when SKILL.md references them via `${CLAUDE_SKILL_DIR}`
+- **Scripts**: Available on disk, never auto-loaded
+
+This means: keep SKILL.md focused (under 300 lines), put detailed references in separate files that load lazily.
+
+---
+
+## Skill Quality Checklist
+
+1. **Name**: kebab-case, matches directory name
+2. **Description**: includes trigger phrases Claude can match against
+3. **SKILL.md under 300 lines**: move details to reference files
+4. **Supporting files referenced via `${CLAUDE_SKILL_DIR}`**: never hardcode paths
+5. **`$ARGUMENTS` used for user input**: contains everything after slash command
+6. **One skill per concern**: don't bundle unrelated functionality
+7. **Templates are minimal**: show patterns, not complete applications
+8. **Tool restrictions only when safety-critical**: don't over-constrain
+
+---
+
+## Anti-Patterns
+
+| Don't | Do Instead |
+|-------|-----------|
+| Giant monolith SKILL.md (>300 lines) | Split into supporting reference files |
+| Vague description ("Helps with stuff") | Action-oriented with trigger phrases |
+| Hardcoded paths to supporting files | Use `${CLAUDE_SKILL_DIR}` |
+| Over-engineering frontmatter | Most skills only need name + description |
+| Duplicating built-in Claude behavior | Only create skills for project-specific patterns |
+| Missing argument-hint | Users won't know what to type after `/command` |
+
+---
+
+## Rune-Specific Conventions
+
+When creating Rune skills (vs generic Claude Code skills):
+
+| Field | Rune Convention |
+|-------|----------------|
+| Frontmatter | Add `metadata:` block with author, version, layer, model, group, tools |
+| Layer | L0 (router), L1 (orchestrator), L2 (workflow), L3 (utility), L4 (extension pack) |
+| Connections | Document `Calls` (outbound) and `Called By` (inbound) sections |
+| Model | haiku (scan), sonnet (code), opus (architecture) |
+| Version | semver — bump on enrichment |
+| References | Store in `references/` subdirectory |
+| Cross-references | Use `rune:skill-name` syntax |