codexkit 1.0.0

package/.codex/skills/supabase-postgres-best-practices/rules/schema-partitioning.md

@@ -0,0 +1,55 @@
+---
+title: Partition Large Tables for Better Performance
+impact: MEDIUM-HIGH
+impactDescription: 5-20x faster queries and maintenance on large tables
+tags: partitioning, large-tables, time-series, performance
+---
+
+## Partition Large Tables for Better Performance
+
+Partitioning splits a large table into smaller pieces, improving query performance and maintenance operations.
+
+**Incorrect (single large table):**
+
+```sql
+create table events (
+  id bigint generated always as identity,
+  created_at timestamptz,
+  data jsonb
+);
+
+-- 500M rows, queries scan everything
+select * from events where created_at > '2024-01-01';  -- Slow
+vacuum events;  -- Takes hours, locks table
+```
+
+**Correct (partitioned by time range):**
+
+```sql
+create table events (
+  id bigint generated always as identity,
+  created_at timestamptz not null,
+  data jsonb
+) partition by range (created_at);
+
+-- Create partitions for each month
+create table events_2024_01 partition of events
+  for values from ('2024-01-01') to ('2024-02-01');
+
+create table events_2024_02 partition of events
+  for values from ('2024-02-01') to ('2024-03-01');
+
+-- Queries only scan relevant partitions
+select * from events where created_at > '2024-01-15';  -- Only scans events_2024_01+
+
+-- Drop old data instantly
+drop table events_2023_01;  -- Instant vs DELETE taking hours
+```
+
+When to partition:
+
+- Tables > 100M rows
+- Time-series data with date-based queries
+- Need to efficiently drop old data
+
+Reference: [Table Partitioning](https://www.postgresql.org/docs/current/ddl-partitioning.html)

package/.codex/skills/supabase-postgres-best-practices/rules/schema-primary-keys.md

@@ -0,0 +1,61 @@
+---
+title: Select Optimal Primary Key Strategy
+impact: HIGH
+impactDescription: Better index locality, reduced fragmentation
+tags: primary-key, identity, uuid, serial, schema
+---
+
+## Select Optimal Primary Key Strategy
+
+Primary key choice affects insert performance, index size, and replication
+efficiency.
+
+**Incorrect (problematic PK choices):**
+
+```sql
+-- identity is the SQL-standard approach
+create table users (
+  id serial primary key  -- Works, but IDENTITY is recommended
+);
+
+-- Random UUIDs (v4) cause index fragmentation
+create table orders (
+  id uuid default gen_random_uuid() primary key  -- UUIDv4 = random = scattered inserts
+);
+```
+
+**Correct (optimal PK strategies):**
+
+```sql
+-- Use IDENTITY for sequential IDs (SQL-standard, best for most cases)
+create table users (
+  id bigint generated always as identity primary key
+);
+
+-- For distributed systems needing UUIDs, use UUIDv7 (time-ordered)
+-- Requires pg_uuidv7 extension: create extension pg_uuidv7;
+create table orders (
+  id uuid default uuid_generate_v7() primary key  -- Time-ordered, no fragmentation
+);
+
+-- Alternative: time-prefixed IDs for sortable, distributed IDs (no extension needed)
+create table events (
+  id text default concat(
+    to_char(now() at time zone 'utc', 'YYYYMMDDHH24MISSMS'),
+    gen_random_uuid()::text
+  ) primary key
+);
+```
+
+Guidelines:
+
+- Single database: `bigint identity` (sequential, 8 bytes, SQL-standard)
+- Distributed/exposed IDs: UUIDv7 (requires pg_uuidv7) or ULID (time-ordered, no
+  fragmentation)
+- `serial` works but `identity` is SQL-standard and preferred for new
+  applications
+- Avoid random UUIDs (v4) as primary keys on large tables (causes index
+  fragmentation)
+
+Reference:
+[Identity Columns](https://www.postgresql.org/docs/current/sql-createtable.html#SQL-CREATETABLE-PARMS-GENERATED-IDENTITY)

package/.codex/skills/supabase-postgres-best-practices/rules/security-privileges.md

@@ -0,0 +1,54 @@
+---
+title: Apply Principle of Least Privilege
+impact: MEDIUM
+impactDescription: Reduced attack surface, better audit trail
+tags: privileges, security, roles, permissions
+---
+
+## Apply Principle of Least Privilege
+
+Grant only the minimum permissions required. Never use superuser for application queries.
+
+**Incorrect (overly broad permissions):**
+
+```sql
+-- Application uses superuser connection
+-- Or grants ALL to application role
+grant all privileges on all tables in schema public to app_user;
+grant all privileges on all sequences in schema public to app_user;
+
+-- Any SQL injection becomes catastrophic
+-- drop table users; cascades to everything
+```
+
+**Correct (minimal, specific grants):**
+
+```sql
+-- Create role with no default privileges
+create role app_readonly nologin;
+
+-- Grant only SELECT on specific tables
+grant usage on schema public to app_readonly;
+grant select on public.products, public.categories to app_readonly;
+
+-- Create role for writes with limited scope
+create role app_writer nologin;
+grant usage on schema public to app_writer;
+grant select, insert, update on public.orders to app_writer;
+grant usage on sequence orders_id_seq to app_writer;
+-- No DELETE permission
+
+-- Login role inherits from these
+create role app_user login password 'xxx';
+grant app_writer to app_user;
+```
+
+Revoke public defaults:
+
+```sql
+-- Revoke default public access
+revoke all on schema public from public;
+revoke all on all tables in schema public from public;
+```
+
+Reference: [Roles and Privileges](https://supabase.com/blog/postgres-roles-and-privileges)

package/.codex/skills/supabase-postgres-best-practices/rules/security-rls-basics.md

@@ -0,0 +1,50 @@
+---
+title: Enable Row Level Security for Multi-Tenant Data
+impact: CRITICAL
+impactDescription: Database-enforced tenant isolation, prevent data leaks
+tags: rls, row-level-security, multi-tenant, security
+---
+
+## Enable Row Level Security for Multi-Tenant Data
+
+Row Level Security (RLS) enforces data access at the database level, ensuring users only see their own data.
+
+**Incorrect (application-level filtering only):**
+
+```sql
+-- Relying only on application to filter
+select * from orders where user_id = $current_user_id;
+
+-- Bug or bypass means all data is exposed!
+select * from orders;  -- Returns ALL orders
+```
+
+**Correct (database-enforced RLS):**
+
+```sql
+-- Enable RLS on the table
+alter table orders enable row level security;
+
+-- Create policy for users to see only their orders
+create policy orders_user_policy on orders
+  for all
+  using (user_id = current_setting('app.current_user_id')::bigint);
+
+-- Force RLS even for table owners
+alter table orders force row level security;
+
+-- Set user context and query
+set app.current_user_id = '123';
+select * from orders;  -- Only returns orders for user 123
+```
+
+Policy for authenticated role:
+
+```sql
+create policy orders_user_policy on orders
+  for all
+  to authenticated
+  using (user_id = auth.uid());
+```
+
+Reference: [Row Level Security](https://supabase.com/docs/guides/database/postgres/row-level-security)

package/.codex/skills/supabase-postgres-best-practices/rules/security-rls-performance.md

@@ -0,0 +1,57 @@
+---
+title: Optimize RLS Policies for Performance
+impact: HIGH
+impactDescription: 5-10x faster RLS queries with proper patterns
+tags: rls, performance, security, optimization
+---
+
+## Optimize RLS Policies for Performance
+
+Poorly written RLS policies can cause severe performance issues. Use subqueries and indexes strategically.
+
+**Incorrect (function called for every row):**
+
+```sql
+create policy orders_policy on orders
+  using (auth.uid() = user_id);  -- auth.uid() called per row!
+
+-- With 1M rows, auth.uid() is called 1M times
+```
+
+**Correct (wrap functions in SELECT):**
+
+```sql
+create policy orders_policy on orders
+  using ((select auth.uid()) = user_id);  -- Called once, cached
+
+-- 100x+ faster on large tables
+```
+
+Use security definer functions for complex checks:
+
+```sql
+-- Create helper function (runs as definer, bypasses RLS)
+create or replace function is_team_member(team_id bigint)
+returns boolean
+language sql
+security definer
+set search_path = ''
+as $$
+  select exists (
+    select 1 from public.team_members
+    where team_id = $1 and user_id = (select auth.uid())
+  );
+$$;
+
+-- Use in policy (indexed lookup, not per-row check)
+create policy team_orders_policy on orders
+  using ((select is_team_member(team_id)));
+```
+
+Always add indexes on columns used in RLS policies:
+
+```sql
+create index orders_user_id_idx on orders (user_id);
+```
+
+Reference: [RLS Performance](https://supabase.com/docs/guides/database/postgres/row-level-security#rls-performance-recommendations)

package/.codex/skills/swarm-coordination/SKILL.md

@@ -0,0 +1,179 @@
+---
+name: swarm-coordination
+description: >
+  Use when implementing plans with multiple independent tasks that can run in parallel.
+  Enables leader agents to spawn, coordinate, and monitor worker swarms using Kimi K2.5 PARL patterns.
+  Covers task classification, anti-serial-collapse detection, delegation packets, progress tracking,
+  and graceful shutdown patterns.
+version: "2.1.0"
+license: MIT
+tags: [agent-coordination, workflow]
+dependencies: [beads-bridge]
+---
+
+# Swarm Coordination - Kimi K2.5 PARL Multi-Agent Execution
+
+> **Replaces** manual task-by-task execution of large plans — sequential bottleneck when tasks have no dependencies
+
+## When to Use
+
+- Implementing plans with 3+ independent tasks that can run in parallel
+- You need structured coordination, monitoring, and delegation across many agents
+
+## When NOT to Use
+
+- Single-task or tightly sequential work without parallelizable groups
+- Simple 1–2 file changes better handled by a single agent
+
+## Overview
+
+**Swarm = Leader + Workers + Reconciler + Progress Tracking + Todo Persistence**
+
+- **Leader (build agent)**: Orchestrates the swarm - analyzes tasks, spawns workers, monitors progress, synthesizes results
+- **Workers (general/explore/review/plan agents)**: Execute independent tasks - read delegation, make changes, report progress
+- **Reconciler**: Watches for CI failures, detects broken builds, auto-spawns fix tasks - this is the self-healing mechanism
+- **Progress Tracker (swarm-progress.jsonl)**: Real-time progress updates with TUI visualization
+- **Todo Persistence (swarm-todos.json)**: Cross-session recovery for interrupted swarms
+
+**Key Tools**:
+
+| Tool    | Purpose                    | When to Use          |
+| ------- | -------------------------- | -------------------- |
+| `swarm` | Unified swarm coordination | All swarm operations |
+
+**swarm operations:**
+
+- `plan`: Task classification & dependency graph (before spawning workers)
+- `delegate`: Create delegation packets (assigning work to workers)
+- `monitor`: Progress tracking + TUI visualization (during swarm execution)
+- `sync`: Sync Beads ↔ Codex todos (session start, cross-session)
+
+**Key Distinction**:
+
+- **Swarm**: Parallel execution of independent tasks with dynamic allocation
+- **Beads**: Task tracking and dependency management across sessions
+- **Task tool**: Spawning individual subagents for research/execution
+- **swarm tool**: Unified operations for planning, monitoring, delegation, and sync
+
+**When to Use Swarm Coordination**:
+
+- "Does this plan have 3+ independent tasks?" → **YES** = Swarm
+- "Can multiple tasks run in parallel without conflicts?" → **YES** = Swarm
+- "Do I need to coordinate multiple agents?" → **YES** = Swarm
+- "Is this a single task or sequential dependency chain?" → **NO** = Single agent
+
+**Kimi K2.5 PARL Patterns**:
+
+- **Task Classification**: Auto-detect parallelization potential
+- **Anti-Serial-Collapse**: Prevent forced sequential execution
+- **Dynamic Allocation**: Conservative start, scale based on bottlenecks
+- **Progress Visualization**: Real-time TUI with beautiful markdown blocks
+- **Dependency Graphs**: DAG-based task scheduling with critical path analysis
+
+## When to Use Swarm vs Single Agent
+
+| Scenario                      | Approach     |
+| ----------------------------- | ------------ |
+| 1-2 file changes              | Single agent |
+| Sequential dependencies       | Single agent |
+| 3+ independent parallel tasks | Swarm        |
+| Cross-domain work (FE/BE/DB)  | Swarm        |
+| Time-sensitive parallel work  | Swarm        |
+
+## Quick Reference - Kimi K2.5 PARL Pattern
+
+```
+SWARM LAUNCH (PARL):
+  0. SETUP: swarm({ operation: "sync", action: "push" })
+     → Make Beads visible to subagents
+  1. ANALYZE: swarm({ operation: "plan", action: "analyze", task: userRequest, files: detectedFiles })
+     → Get classification, phases, dependency_graph
+  2. CHECK: swarm({ operation: "plan", action: "check", ... })
+     → Detect/prevent serial collapse
+  3. DELEGATE: swarm({ operation: "delegate", ... })
+     → Create packets for each worker
+  4. SPAWN: Task({ subagent_type: "general" })
+     → Launch workers using parallelizable_groups order
+  5. MONITOR: swarm({ operation: "monitor", action: "render_block" })
+     → Real-time TUI progress
+  6. VERIFY: npm run typecheck && npm run lint && npm test
+  7. CLOSE: swarm({ operation: "sync", action: "pull" }) && br close <bead>
+
+WORKER EXECUTION:
+  1. Read delegation packet
+  2. Report START: swarm({ operation: "monitor", action: "progress_update", progress: 0, status: "working" })
+  3. Execute with constraints
+  4. Report PROGRESS (every 25%): swarm({ operation: "monitor", action: "progress_update", progress: 25/50/75 })
+  5. Run acceptance checks
+  6. Report DONE: swarm({ operation: "monitor", action: "progress_update", progress: 100, status: "completed" })
+
+COORDINATION:
+  - Progress: .beads/swarm-progress.jsonl (via swarm monitor)
+  - Delegation: .beads/artifacts/<id>/delegation.md (via swarm delegate)
+  - Analysis: swarm tool for classification + dependency graphs
+
+RECOVERY:
+  - Check: swarm({ operation: "monitor", action: "status" })
+  - Use shared task lists: swarm({ operation: "sync", action: "create_shared" })
+  - Continue with remaining workers
+
+SHUTDOWN:
+  - All workers done → swarm({ operation: "monitor", action: "clear" })
+  - Run full test suite
+  - swarm({ operation: "sync", action: "pull" })
+  - Close parent bead
+```
+
+## Tools Reference
+
+| Tool      | Purpose                    | Key Operations                        |
+| --------- | -------------------------- | ------------------------------------- |
+| **swarm** | Unified swarm coordination | `plan`, `monitor`, `delegate`, `sync` |
+
+**swarm operations:**
+
+- `plan`: Task analysis + dependency DAG (actions: analyze, classify, check, allocate)
+- `delegate`: Create delegation packets
+- `monitor`: Progress tracking + visualization (actions: progress_update, render_block, status, clear)
+- `sync`: Beads ↔ Codex todos (actions: push, pull, create_shared, get_shared, update_shared, list_shared)
+
+## Rules
+
+1. **Leader spawns, workers execute** - Clear role separation
+2. **Delegation packets are contracts** - Workers follow them strictly
+3. **Progress tracking for coordination** - All status via swarm monitor progress updates
+4. **Non-overlapping assignments** - Ensure workers edit different files
+5. **Acceptance checks required** - Workers verify before reporting done
+6. **Persist periodically** - Enable cross-session recovery
+7. **Use dependency graph** - Spawn workers in parallelizable_groups order
+8. **Graceful shutdown** - Leader waits for all workers, syncs back to Beads
+9. **Use tmux for visibility** - Enable visual monitoring when available
+10. **Use reconciler at scale** - Required for 50+ agents, recommended for 10+
+11. **Reconciler watches continuously** - Spawns fix tasks on detected failures
+
+## Anti-Patterns
+
+| Anti-Pattern                                            | Why It Fails                                               | Instead                                                           |
+| ------------------------------------------------------- | ---------------------------------------------------------- | ----------------------------------------------------------------- |
+| Spawning agents for tasks with shared file dependencies | Workers block or overwrite each other, causing merge churn | Partition work by non-overlapping files/modules first             |
+| Not tracking agent completion status                    | Leader loses visibility; work appears done when it is not  | Require `monitor.progress_update` lifecycle (start/progress/done) |
+| Dispatching without pre-computed dependency graph       | Tasks run out of order, causing rework and serial fallback | Run `swarm plan` first and dispatch by `parallelizable_groups`    |
+| Using swarm for < 3 tasks (overhead not worth it)       | Coordination overhead exceeds execution savings            | Use a single agent or 2 direct `Task()` calls                     |
+
+## References
+
+- `references/architecture.md` - Swarm architecture diagram
+- `references/reconciler.md` - Reconciler pattern, error analysis, and fix task spawning
+- `references/drift-check.md` - Drift checks after each wave and recovery protocol
+- `references/launch-flow.md` - PARL swarm launch flow with step-by-step code
+- `references/dependency-graph.md` - Dependency graph structures and usage
+- `references/delegation-worker-protocol.md` - Delegation packet structure, worker protocol, and error handling
+- `references/integration-beads.md` - Swarm integration workflow with Beads
+- `references/tmux-integration.md` - Tmux monitoring setup and commands
+- `references/tier-enforcement.md` - Tier enforcement (Longshot pattern)
+
+## See Also
+
+- `agent-teams` — for coordinated multi-role collaboration beyond large plan execution
+- `dispatching-parallel-agents` — for lightweight parallel debugging of independent failures
+- `executing-plans` — for plan-driven execution when parallelism is moderate or bounded

package/.codex/skills/swarm-coordination/references/architecture.md

@@ -0,0 +1,39 @@
+# Swarm Architecture
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                         BUILD AGENT (Leader)                     │
+│  - Parses plan into tasks                                        │
+│  - Creates delegation packets                                    │
+│  - Spawns worker agents via Task tool                            │
+│  - Monitors progress via swarm tool                             │
+│  - Synthesizes final results                                     │
+└─────────────────────────────────────────────────────────────────┘
+          │                    │                    │
+          ▼                    ▼                    ▼
+┌─────────────┐      ┌─────────────┐      ┌─────────────┐
+│  WORKER-1   │      │  WORKER-2   │      │  WORKER-3   │
+│  (general)  │      │  (general)  │      │  (general)  │
+│             │      │             │      │             │
+│ - Read      │      │ - Read      │      │ - Read      │
+│   delegation│      │   delegation│      │   delegation│
+│ - Execute   │      │ - Execute   │      │ - Execute   │
+│ - Report    │      │ - Report    │      │ - Report    │
+└─────────────┘      └─────────────┘      └─────────────┘
+          │                    │                    │
+          └────────────────────┼────────────────────┘
+                               ▼
+                     ┌─────────────────┐
+                     │   RECONCILER    │
+                     │                 │
+                     │ - Watch CI      │
+                     │ - Detect broken │
+                     │ - Spawn fixes   │
+                     └─────────────────┘
+                               │
+                               ▼
+                     ┌─────────────────┐
+                     │  PROGRESS +     │
+                     │  TODO PERSIST   │
+                     └─────────────────┘
+```

package/.codex/skills/swarm-coordination/references/delegation-worker-protocol.md

@@ -0,0 +1,145 @@
+# Delegation Packet Structure and Worker Protocol
+
+## Delegation Packet Structure
+
+```markdown
+# Delegation Packet
+
+- TASK: task-1 - Implement auth service
+- EXPECTED OUTCOME: Auth service with JWT tokens, tests pass
+- REQUIRED TOOLS:
+  - read
+  - grep
+  - lsp
+  - edit
+  - bash
+- MUST DO:
+  - LSP before edits
+  - Run npm test after changes
+  - Follow existing code patterns
+- MUST NOT DO:
+  - No new dependencies
+  - Don't edit config files
+  - Don't modify shared utilities
+- ACCEPTANCE CHECKS:
+  - typecheck: npm run typecheck
+  - lint: npm run lint
+  - test: npm test
+- CONTEXT:
+  See .beads/artifacts/task-1/spec.md for requirements
+```
+
+## Worker Protocol (Updated with Progress Tracking)
+
+Workers follow this execution pattern:
+
+### 1. Read Delegation
+
+```typescript
+// First action: read the delegation packet
+read({ filePath: ".beads/artifacts/<task-id>/delegation.md" });
+```
+
+### 2. Announce Start with Progress
+
+```typescript
+await swarm({
+  operation: "monitor",
+  operation: "progress_update",
+  team_name: "plan-implementation",
+  worker_id: "worker-1",
+  phase: "explore", // or "generate", "reflect", etc.
+  progress: 0,
+  status: "working",
+  file: "src/api/users.ts", // current file being worked on
+});
+```
+
+### 3. Execute Task with Progress Updates
+
+Follow the MUST DO constraints. Avoid MUST NOT DO items. Use required tools only.
+
+Report progress every 25%:
+
+```typescript
+// At 25%, 50%, 75% completion
+await swarm({
+  operation: "monitor",
+  operation: "progress_update",
+  team_name: "plan-implementation",
+  worker_id: "worker-1",
+  phase: "explore",
+  progress: 25, // or 50, 75
+  status: "working",
+  file: "src/api/users.ts",
+});
+```
+
+### 4. Run Acceptance Checks
+
+```bash
+# Run each check from the delegation packet
+npm run typecheck
+npm run lint
+npm test
+```
+
+### 5. Report Completion
+
+```typescript
+// Mark as completed
+await swarm({
+  operation: "monitor",
+  operation: "progress_update",
+  team_name: "plan-implementation",
+  worker_id: "worker-1",
+  phase: "explore",
+  progress: 100,
+  status: "completed",
+  file: "src/api/users.ts",
+});
+```
+
+## Error Handling
+
+### Worker Fails Acceptance Checks
+
+Workers report failures via progress updates with error status:
+
+```typescript
+// Worker reports error via progress update
+await swarm({
+  operation: "monitor",
+  operation: "progress_update",
+  team_name: "plan-implementation",
+  worker_id: "worker-1",
+  phase: "explore",
+  progress: 75,
+  status: "error",
+  message: "typecheck failed: missing type for AuthToken",
+});
+```
+
+### Leader Response
+
+1. Check worker status via `swarm({ operation: "monitor", operation: "status" })`
+2. Review error details in progress entries
+3. Decide: fix locally or reassign to new worker
+
+### Worker Gets Blocked
+
+Workers should report blockers via progress updates:
+
+```typescript
+// Worker reports blocker via progress update
+await swarm({
+  operation: "monitor",
+  operation: "progress_update",
+  team_name: "plan-implementation",
+  worker_id: "worker-2",
+  phase: "explore",
+  progress: 50,
+  status: "blocked",
+  message: "Need auth service types from worker-1",
+});
+```

package/.codex/skills/swarm-coordination/references/dependency-graph.md

@@ -0,0 +1,50 @@
+# Dependency Graph Features
+
+The `swarm` tool's plan operation includes full dependency graph analysis:
+
+## Structure
+
+```typescript
+interface DependencyGraph {
+  nodes: TaskNode[]; // Individual tasks
+  edges: Edge[]; // Dependencies between tasks
+  critical_path: string[]; // Longest dependency chain
+  parallelizable_groups: string[][]; // Tasks that can run in parallel
+}
+
+interface TaskNode {
+  id: string;
+  content: string;
+  phase: string;
+  worker: string;
+  status: "pending" | "in_progress" | "completed";
+  priority: "high" | "medium" | "low";
+  blockedBy: string[]; // Tasks this depends on
+  blocks: string[]; // Tasks that depend on this
+  assignedFiles: string[]; // Files assigned to this task
+}
+```
+
+## Usage
+
+```typescript
+const analysis = await swarm({
+  operation: "plan",
+  operation: "analyze",
+  task: "Refactor API layer",
+  files: "src/api/users.ts,src/api/posts.ts,src/api/auth.ts",
+});
+
+const plan = JSON.parse(analysis);
+
+// Critical path shows the longest dependency chain
+// Focus attention here for optimal completion time
+console.log(`Critical path: ${plan.dependency_graph.critical_path.join(" → ")}`);
+
+// Parallelizable groups show which tasks can run simultaneously
+// Each group must complete before starting the next
+for (let i = 0; i < plan.dependency_graph.parallelizable_groups.length; i++) {
+  const group = plan.dependency_graph.parallelizable_groups[i];
+  console.log(`Wave ${i + 1}: ${group.join(", ")} (${group.length} parallel tasks)`);
+}
+```