cokit-cli 1.0.9 → 1.2.0

package/skills/databases/stacks/sqlite.md

@@ -0,0 +1,244 @@
+# SQLite Rules
+
+Guidelines for designing schemas specific to SQLite.
+
+---
+
+## Data Types
+
+SQLite has **dynamic typing**, with only 5 storage classes:
+
+| Storage Class | Use case | Notes |
+|---------------|----------|-------|
+| `INTEGER` | PK, FK, counts, booleans | |
+| `REAL` | Floats, decimals | |
+| `TEXT` | Strings, dates, JSON, enums | |
+| `BLOB` | Binary data | |
+| `NULL` | Null values | |
+
+### Type affinity
+SQLite does not strictly enforce types. Type declaration is just a "hint":
+```sql
+-- All of these will be stored
+CREATE TABLE test (price REAL);
+INSERT INTO test VALUES (100);      -- Stored as INTEGER
+INSERT INTO test VALUES (99.99);    -- Stored as REAL
+INSERT INTO test VALUES ('free');   -- Stored as TEXT (!)
+```
+
+### Date/Time
+SQLite **does not have** DATE/TIME type. Store as TEXT with ISO format:
+```sql
+created_at TEXT DEFAULT (datetime('now'))
+-- Format: YYYY-MM-DD HH:MM:SS
+```
+
+---
+
+## Metadata Tables (REQUIRED)
+
+SQLite **does not support comments** on tables and columns. Need to create metadata tables:
+
+### Create metadata tables
+
+```sql
+CREATE TABLE IF NOT EXISTS metadata_tables (
+    table_name TEXT PRIMARY KEY,
+    description TEXT NOT NULL,
+    created_at TEXT DEFAULT (datetime('now')),
+    updated_at TEXT DEFAULT (datetime('now'))
+);
+
+CREATE TABLE IF NOT EXISTS metadata_columns (
+    table_name TEXT NOT NULL,
+    column_name TEXT NOT NULL,
+    description TEXT NOT NULL,
+    data_type TEXT,
+    is_nullable INTEGER DEFAULT 1,  -- 0=NOT NULL, 1=NULL
+    default_value TEXT,
+    created_at TEXT DEFAULT (datetime('now')),
+    PRIMARY KEY (table_name, column_name),
+    FOREIGN KEY (table_name) REFERENCES metadata_tables(table_name) ON DELETE CASCADE
+);
+
+CREATE INDEX idx_metadata_columns_table ON metadata_columns(table_name);
+```
+
+### Insert metadata after creating table
+
+```sql
+-- Table metadata
+INSERT INTO metadata_tables (table_name, description)
+VALUES ('orders', 'Table storing customer order information');
+
+-- Column metadata
+INSERT INTO metadata_columns (table_name, column_name, description, data_type, is_nullable)
+VALUES
+    ('orders', 'id', 'Primary key, auto increment', 'INTEGER', 0),
+    ('orders', 'order_number', 'Unique order code', 'TEXT', 0),
+    ('orders', 'user_id', 'FK to users.id', 'INTEGER', 0),
+    ('orders', 'status', 'pending|confirmed|shipped|cancelled', 'TEXT', 0),
+    ('orders', 'total_amount', 'Total value', 'REAL', 0);
+```
+
+### Query metadata
+
+```sql
+-- View schema with descriptions
+SELECT
+    t.table_name,
+    t.description AS table_description,
+    c.column_name,
+    c.description AS column_description,
+    c.data_type
+FROM metadata_tables t
+LEFT JOIN metadata_columns c ON t.table_name = c.table_name
+ORDER BY t.table_name, c.column_name;
+```
+
+---
+
+## Auto Increment
+
+```sql
+-- Option 1: INTEGER PRIMARY KEY (recommended)
+-- SQLite auto-increments INTEGER PRIMARY KEY automatically
+CREATE TABLE users (
+    id INTEGER PRIMARY KEY,
+    name TEXT
+);
+
+-- Option 2: AUTOINCREMENT keyword
+-- Ensures deleted IDs are not reused (slower)
+CREATE TABLE users (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    name TEXT
+);
+```
+
+---
+
+## Foreign Keys
+
+**IMPORTANT**: FK is disabled by default in SQLite!
+
+```sql
+-- Enable FK for each connection
+PRAGMA foreign_keys = ON;
+
+-- Create table with FK
+CREATE TABLE order_items (
+    id INTEGER PRIMARY KEY,
+    order_id INTEGER NOT NULL,
+    product_id INTEGER NOT NULL,
+    FOREIGN KEY (order_id) REFERENCES orders(id) ON DELETE CASCADE,
+    FOREIGN KEY (product_id) REFERENCES products(id) ON DELETE RESTRICT
+);
+
+-- Create index for FK
+CREATE INDEX idx_order_items_order ON order_items(order_id);
+CREATE INDEX idx_order_items_product ON order_items(product_id);
+```
+
+---
+
+## ENUM substitute
+
+SQLite does not have ENUM. Use CHECK constraint:
+
+```sql
+CREATE TABLE orders (
+    status TEXT NOT NULL DEFAULT 'pending'
+        CHECK (status IN ('pending', 'confirmed', 'shipped', 'cancelled'))
+);
+```
+
+---
+
+## Index Types
+
+SQLite only supports B-Tree indexes:
+
+```sql
+-- Standard index
+CREATE INDEX idx_orders_status ON orders(status);
+
+-- Composite index
+CREATE INDEX idx_orders_user_status ON orders(user_id, status);
+
+-- Unique index
+CREATE UNIQUE INDEX idx_orders_number ON orders(order_number);
+
+-- Partial index (SQLite 3.8.0+)
+CREATE INDEX idx_orders_active ON orders(user_id)
+    WHERE deleted_at IS NULL;
+```
+
+---
+
+## Limitations
+
+| Feature | Status | Workaround |
+|---------|--------|------------|
+| `ALTER COLUMN` | ❌ Not supported | Recreate table |
+| `DROP COLUMN` | ✅ SQLite 3.35+ | Recreate table (older) |
+| Comments | ❌ Not supported | Metadata tables |
+| ENUM | ❌ Not supported | CHECK constraint |
+| Stored procedures | ❌ Not supported | App logic |
+| Concurrent writes | ⚠️ Limited | Single writer |
+
+---
+
+## Example DDL
+
+```sql
+-- Enable foreign keys
+PRAGMA foreign_keys = ON;
+
+-- Create table
+CREATE TABLE orders (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    order_number TEXT NOT NULL,
+    user_id INTEGER NOT NULL,
+    status TEXT NOT NULL DEFAULT 'pending'
+        CHECK (status IN ('pending', 'confirmed', 'shipped', 'cancelled')),
+    subtotal REAL NOT NULL DEFAULT 0,
+    discount_amount REAL NOT NULL DEFAULT 0,
+    total_amount REAL NOT NULL DEFAULT 0,
+    created_at TEXT NOT NULL DEFAULT (datetime('now')),
+    updated_at TEXT NOT NULL DEFAULT (datetime('now')),
+    deleted_at TEXT,
+
+    FOREIGN KEY (user_id) REFERENCES users(id) ON DELETE RESTRICT
+);
+
+-- Indexes
+CREATE UNIQUE INDEX idx_orders_number ON orders(order_number);
+CREATE INDEX idx_orders_user ON orders(user_id);
+CREATE INDEX idx_orders_status ON orders(status);
+CREATE INDEX idx_orders_updated ON orders(updated_at);
+
+-- Metadata
+INSERT INTO metadata_tables (table_name, description)
+VALUES ('orders', 'Table storing order information');
+
+INSERT INTO metadata_columns (table_name, column_name, description, data_type, is_nullable)
+VALUES
+    ('orders', 'id', 'Primary key', 'INTEGER', 0),
+    ('orders', 'order_number', 'Unique order code', 'TEXT', 0),
+    ('orders', 'user_id', 'FK to users.id', 'INTEGER', 0),
+    ('orders', 'status', 'pending|confirmed|shipped|cancelled', 'TEXT', 0),
+    ('orders', 'total_amount', 'Total payment', 'REAL', 0);
+```
+
+---
+
+## Checklist
+
+- [ ] `PRAGMA foreign_keys = ON` at start of each connection
+- [ ] Metadata tables created
+- [ ] INSERT metadata after each CREATE TABLE
+- [ ] Use `TEXT` for dates (ISO format: YYYY-MM-DD HH:MM:SS)
+- [ ] CHECK constraint instead of ENUM
+- [ ] Index for FK columns
+- [ ] Update metadata when ALTER/DROP table

package/skills/databases/transactional.md

@@ -0,0 +1,176 @@
+# Transactional (OLTP) Rules
+
+> **Note:** Core naming conventions, workflow, and checklist are in `SKILL.md` or `db-design.md` (always loaded).
+
+Guidelines for designing schemas for day-to-day business operations.
+
+---
+
+## Normalization Principles
+
+### Prefer 3NF (Third Normal Form)
+
+- Each table represents one clear entity/relationship
+- No repeating information that can be referenced (use FK)
+- Clear separation:
+  - `orders` (header) vs `order_items` (line items)
+  - `products` vs `product_variants`, `product_prices`
+
+### Foreign Key Constraints
+
+Use FK with appropriate ON DELETE / ON UPDATE:
+
+```sql
+-- Cascade: delete order → delete order_items
+FOREIGN KEY (order_id) REFERENCES orders(id) ON DELETE CASCADE
+
+-- Restrict: cannot delete user if orders exist
+FOREIGN KEY (user_id) REFERENCES users(id) ON DELETE RESTRICT
+
+-- Set null: delete category → product.category_id = NULL
+FOREIGN KEY (category_id) REFERENCES categories(id) ON DELETE SET NULL
+```
+
+---
+
+## Indexing Rules
+
+### 1. Primary Key
+- Usually `BIGINT` auto-increment or UUID
+- Format: `PRIMARY KEY (id)`
+
+### 2. Foreign Key Indexes
+**IMPORTANT**: Create indexes for ALL foreign keys for efficient JOINs:
+```sql
+CREATE INDEX idx_orders_user_id ON orders(user_id);
+CREATE INDEX idx_order_items_order_id ON order_items(order_id);
+CREATE INDEX idx_order_items_product_id ON order_items(product_id);
+```
+
+### 3. Frequently Filtered Columns
+Index columns commonly used in WHERE:
+- `status`, `created_at`, `updated_at`
+- Code/reference columns: `order_number`, `sku`
+
+### 4. Composite Indexes
+Based on actual query patterns:
+```sql
+-- Query: WHERE user_id = ? AND status = ? ORDER BY created_at DESC
+CREATE INDEX idx_orders_user_status_created ON orders(user_id, status, created_at DESC);
+
+-- Query: WHERE store_id = ? AND created_at BETWEEN ...
+CREATE INDEX idx_orders_store_created ON orders(store_id, created_at);
+```
+
+**Composite index rules:**
+- Put columns with **high selectivity** (fewer duplicate values) first
+- Avoid duplicate/redundant indexes
+- Index should cover WHERE + ORDER BY of query
+
+### 5. Unique Constraints
+```sql
+UNIQUE (order_number)
+UNIQUE (sku)
+UNIQUE (user_id, email)  -- compound unique
+```
+
+---
+
+## Soft Delete Pattern
+
+When you need to keep deleted data instead of permanently deleting:
+
+```sql
+-- Add deleted_at column
+deleted_at TIMESTAMP NULL
+
+-- Partial index for non-deleted records (PostgreSQL)
+CREATE INDEX idx_orders_active ON orders(user_id, status)
+    WHERE deleted_at IS NULL;
+
+-- Query only active records
+SELECT * FROM orders WHERE deleted_at IS NULL;
+```
+
+---
+
+## Anti-patterns to Avoid
+
+### Missing FK Index
+```sql
+-- ❌ BAD: FK without index → slow JOINs
+FOREIGN KEY (user_id) REFERENCES users(id)
+-- Forgot CREATE INDEX
+```
+
+### Over-indexing
+```sql
+-- ❌ BAD: Indexing each column separately
+CREATE INDEX idx_a ON orders(user_id);
+CREATE INDEX idx_b ON orders(status);
+CREATE INDEX idx_c ON orders(created_at);
+
+-- ✅ GOOD: Composite index based on query pattern
+CREATE INDEX idx_orders_user_status_created ON orders(user_id, status, created_at DESC);
+```
+
+### Using TEXT instead of ENUM
+```sql
+-- ❌ BAD: Cannot validate values
+status TEXT
+
+-- ✅ GOOD: Use ENUM or CHECK
+status ENUM('pending', 'confirmed', 'shipped', 'cancelled')
+-- or
+status VARCHAR(32) CHECK (status IN ('pending', 'confirmed', 'shipped'))
+```
+
+### Missing Audit Columns
+```sql
+-- ❌ BAD
+CREATE TABLE products (id INT, name VARCHAR(255));
+
+-- ✅ GOOD
+CREATE TABLE products (
+    id INT,
+    name VARCHAR(255),
+    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP
+);
+```
+
+---
+
+## Example DDL
+
+```sql
+CREATE TABLE orders (
+    id BIGINT PRIMARY KEY AUTO_INCREMENT,
+    order_number VARCHAR(50) NOT NULL,
+    user_id BIGINT NOT NULL,
+    status VARCHAR(32) NOT NULL DEFAULT 'pending',
+    subtotal DECIMAL(18,2) NOT NULL DEFAULT 0,
+    discount_amount DECIMAL(18,2) NOT NULL DEFAULT 0,
+    total_amount DECIMAL(18,2) NOT NULL DEFAULT 0,
+    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
+
+    UNIQUE (order_number),
+    FOREIGN KEY (user_id) REFERENCES users(id) ON DELETE RESTRICT
+);
+
+CREATE INDEX idx_orders_user_id ON orders(user_id);
+CREATE INDEX idx_orders_status ON orders(status);
+CREATE INDEX idx_orders_user_status_created ON orders(user_id, status, created_at DESC);
+```
+
+---
+
+## Checklist
+
+- [ ] Audit columns: `created_at`, `updated_at`
+- [ ] All FKs have indexes
+- [ ] Unique constraints for business keys (`order_number`, `sku`, `email`)
+- [ ] ENUM or CHECK for status/type columns
+- [ ] Composite index based on main query patterns
+- [ ] Soft delete if needed: `deleted_at` + partial index

package/{templates/repo/.github/skills/ck-debugging → skills/debug}/SKILL.md

@@ -1,82 +1,84 @@
----
-name: 'ck-debugging'
-description: 'Systematic debugging framework ensuring root cause investigation before fixes. Includes four-phase debugging process, backward call stack tracing, multi-layer validation, and verification protocols. Use when encountering bugs, test failures, unexpected behavior, performance issues, or before claiming work complete. Prevents random fixes, masks over symptoms, and false completion claims.'
----
-
-# Debugging
-
-Comprehensive debugging framework combining systematic investigation, root cause tracing, defense-in-depth validation, and verification protocols.
-
-## Core Principle
-
-**NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST**
-
-Random fixes waste time and create new bugs. Find the root cause, fix at source, validate at every layer, verify before claiming success.
-
-## When to Use
-
-**Always use for:** Test failures, bugs, unexpected behavior, performance issues, build failures, integration problems, before claiming work complete
-
-**Especially when:** Under time pressure, "quick fix" seems obvious, tried multiple fixes, don't fully understand issue, about to claim success
-
-## The Four Techniques
-
-### 1. Systematic Debugging (`references/systematic-debugging.md`)
-
-Four-phase framework ensuring proper investigation:
-- Phase 1: Root Cause Investigation (read errors, reproduce, check changes, gather evidence)
-- Phase 2: Pattern Analysis (find working examples, compare, identify differences)
-- Phase 3: Hypothesis and Testing (form theory, test minimally, verify)
-- Phase 4: Implementation (create test, fix once, verify)
-
-**Key rule:** Complete each phase before proceeding. No fixes without Phase 1.
-
-**Load when:** Any bug/issue requiring investigation and fix
-
-### 2. Root Cause Tracing (`references/root-cause-tracing.md`)
-
-Trace bugs backward through call stack to find original trigger.
-
-**Technique:** When error appears deep in execution, trace backward level-by-level until finding source where invalid data originated. Fix at source, not at symptom.
-
-**Includes:** `scripts/find-polluter.sh` for bisecting test pollution
-
-**Load when:** Error deep in call stack, unclear where invalid data originated
-
-### 3. Defense-in-Depth (`references/defense-in-depth.md`)
-
-Validate at every layer data passes through. Make bugs impossible.
-
-**Four layers:** Entry validation → Business logic → Environment guards → Debug instrumentation
-
-**Load when:** After finding root cause, need to add comprehensive validation
-
-### 4. Verification (`references/verification.md`)
-
-Run verification commands and confirm output before claiming success.
-
-**Iron law:** NO COMPLETION CLAIMS WITHOUT FRESH VERIFICATION EVIDENCE
-
-Run the command. Read the output. Then claim the result.
-
-**Load when:** About to claim work complete, fixed, or passing
-
-## Quick Reference
-
-```
-Bug → systematic-debugging.md (Phase 1-4)
-  Error deep in stack? → root-cause-tracing.md (trace backward)
-  Found root cause? → defense-in-depth.md (add layers)
-  About to claim success? → verification.md (verify first)
-```
-
-## Red Flags
-
-Stop and follow process if thinking:
-- "Quick fix for now, investigate later"
-- "Just try changing X and see if it works"
-- "It's probably X, let me fix that"
-- "Should work now" / "Seems fixed"
-- "Tests pass, we're done"
-
-**All mean:** Return to systematic process.
+---
+name: debug
+description: Debug systematically with root cause analysis before fixes. Use for bugs, test failures, unexpected behavior, performance issues, call stack tracing, multi-layer validation.
+version: 3.1.0
+languages: all
+---
+
+# Debugging
+
+Comprehensive debugging framework combining systematic investigation, root cause tracing, defense-in-depth validation, and verification protocols.
+
+## Core Principle
+
+**NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST**
+
+Random fixes waste time and create new bugs. Find the root cause, fix at source, validate at every layer, verify before claiming success.
+
+## When to Use
+
+**Always use for:** Test failures, bugs, unexpected behavior, performance issues, build failures, integration problems, before claiming work complete
+
+**Especially when:** Under time pressure, "quick fix" seems obvious, tried multiple fixes, don't fully understand issue, about to claim success
+
+## The Four Techniques
+
+### 1. Systematic Debugging (`references/systematic-debugging.md`)
+
+Four-phase framework ensuring proper investigation:
+- Phase 1: Root Cause Investigation (read errors, reproduce, check changes, gather evidence)
+- Phase 2: Pattern Analysis (find working examples, compare, identify differences)
+- Phase 3: Hypothesis and Testing (form theory, test minimally, verify)
+- Phase 4: Implementation (create test, fix once, verify)
+
+**Key rule:** Complete each phase before proceeding. No fixes without Phase 1.
+
+**Load when:** Any bug/issue requiring investigation and fix
+
+### 2. Root Cause Tracing (`references/root-cause-tracing.md`)
+
+Trace bugs backward through call stack to find original trigger.
+
+**Technique:** When error appears deep in execution, trace backward level-by-level until finding source where invalid data originated. Fix at source, not at symptom.
+
+**Includes:** `scripts/find-polluter.sh` for bisecting test pollution
+
+**Load when:** Error deep in call stack, unclear where invalid data originated
+
+### 3. Defense-in-Depth (`references/defense-in-depth.md`)
+
+Validate at every layer data passes through. Make bugs impossible.
+
+**Four layers:** Entry validation → Business logic → Environment guards → Debug instrumentation
+
+**Load when:** After finding root cause, need to add comprehensive validation
+
+### 4. Verification (`references/verification.md`)
+
+Run verification commands and confirm output before claiming success.
+
+**Iron law:** NO COMPLETION CLAIMS WITHOUT FRESH VERIFICATION EVIDENCE
+
+Run the command. Read the output. Then claim the result.
+
+**Load when:** About to claim work complete, fixed, or passing
+
+## Quick Reference
+
+```
+Bug → systematic-debugging.md (Phase 1-4)
+  Error deep in stack? → root-cause-tracing.md (trace backward)
+  Found root cause? → defense-in-depth.md (add layers)
+  About to claim success? → verification.md (verify first)
+```
+
+## Red Flags
+
+Stop and follow process if thinking:
+- "Quick fix for now, investigate later"
+- "Just try changing X and see if it works"
+- "It's probably X, let me fix that"
+- "Should work now" / "Seems fixed"
+- "Tests pass, we're done"
+
+**All mean:** Return to systematic process.