@rune-kit/rune 2.3.1 → 2.3.2

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.2)
 
 - **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.2 &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.2",
   "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/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 |