opencodekit 0.15.9 → 0.15.11

package/dist/template/.opencode/skill/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/dist/template/.opencode/skill/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/dist/template/.opencode/skill/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/dist/template/.opencode/skill/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/dist/template/.opencode/skill/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/dist/template/.opencode/skill/swarm-coordination/SKILL.md

@@ -0,0 +1,405 @@
+---
+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. Covers delegation
+  packets, mailbox communication, task assignment, and graceful shutdown patterns.
+version: "1.0.0"
+license: MIT
+---
+
+# Swarm Coordination - Multi-Agent Parallel Execution
+
+Coordinate multiple agents working on independent tasks in parallel. Leader orchestrates, workers execute, mailbox communicates.
+
+## Overview
+
+**Swarm = Leader + Workers + Mailbox**
+
+- **Leader (build agent)**: Orchestrates the swarm - spawns workers, monitors progress, synthesizes results
+- **Workers (general agents)**: Execute independent tasks - read delegation, make changes, report back
+- **Mailbox (swarm-mail.jsonl)**: Append-only log for coordination messages
+
+**Key Distinction**:
+
+- **Swarm**: Parallel execution of independent tasks from a plan
+- **Beads**: Task tracking and dependency management across sessions
+- **Task tool**: Spawning individual subagents for research/execution
+
+**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
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                         BUILD AGENT (Leader)                     │
+│  - Parses plan into tasks                                        │
+│  - Creates delegation packets                                    │
+│  - Spawns worker agents via Task tool                            │
+│  - Monitors mailbox for progress                                 │
+│  - Synthesizes final results                                     │
+└─────────────────────────────────────────────────────────────────┘
+         │                    │                    │
+         ▼                    ▼                    ▼
+┌─────────────┐      ┌─────────────┐      ┌─────────────┐
+│  WORKER-1   │      │  WORKER-2   │      │  WORKER-3   │
+│  (general)  │      │  (general)  │      │  (general)  │
+│             │      │             │      │             │
+│ - Read      │      │ - Read      │      │ - Read      │
+│   delegation│      │   delegation│      │   delegation│
+│ - Execute   │      │ - Execute   │      │ - Execute   │
+│ - Report    │      │ - Report    │      │ - Report    │
+└─────────────┘      └─────────────┘      └─────────────┘
+         │                    │                    │
+         └────────────────────┼────────────────────┘
+                              ▼
+                    ┌─────────────────┐
+                    │  SWARM MAILBOX  │
+                    │  (swarm-mail    │
+                    │   .jsonl)       │
+                    └─────────────────┘
+```
+
+## Swarm Launch Flow (5 Steps)
+
+### Step 1: Parse Plan into Tasks
+
+Extract independent tasks from the approved plan:
+
+```typescript
+// Read the plan
+const plan = read({ filePath: ".beads/artifacts/<bead-id>/plan.md" });
+
+// Identify parallelizable tasks
+// Tasks are parallel if they:
+// - Don't modify the same files
+// - Don't have sequential dependencies
+// - Can verify independently
+```
+
+### Step 2: Create Delegation Packets
+
+For each task, create a delegation packet:
+
+```typescript
+swarm_delegate({
+  bead_id: "task-1",
+  title: "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",
+  must_not_do: "No new dependencies, don't edit config files",
+  acceptance_checks: "typecheck: npm run typecheck, lint: npm run lint, test: npm test",
+  context: "See .beads/artifacts/task-1/spec.md for requirements",
+  write: true,
+});
+```
+
+### Step 3: Spawn Worker Agents
+
+Use Task tool to spawn workers in parallel:
+
+```typescript
+// Multiple Task calls in one message run simultaneously
+Task({
+  subagent_type: "general",
+  description: "Execute task-1",
+  prompt: `Execute bead task-1: Implement auth service
+
+Read delegation packet at: .beads/artifacts/task-1/delegation.md
+
+Requirements:
+1. Follow all MUST DO constraints
+2. Avoid all MUST NOT DO items
+3. Run acceptance checks before claiming done
+4. Report completion via swarm-helper sendTeamMessage
+
+Team: plan-implementation
+Worker: worker-1`,
+});
+
+Task({
+  subagent_type: "general",
+  description: "Execute task-2",
+  prompt: `Execute bead task-2: Add user routes
+...same pattern...`,
+});
+
+Task({
+  subagent_type: "general",
+  description: "Execute task-3",
+  prompt: `Execute bead task-3: Create frontend forms
+...same pattern...`,
+});
+// All three run in parallel
+```
+
+### Step 4: Monitor Progress
+
+Check mailbox for worker reports:
+
+```typescript
+swarm_helper({
+  operation: "getTeamStatus",
+  team_name: "plan-implementation",
+  limit: 20,
+});
+// Returns messages from workers about progress
+```
+
+### Step 5: Synthesize Results
+
+When all workers complete:
+
+1. Read their completion messages from mailbox
+2. Verify all acceptance checks passed
+3. Run full test suite
+4. Summarize what was accomplished
+5. Close the parent bead
+
+## 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
+
+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
+
+```typescript
+swarm_helper({
+  operation: "sendTeamMessage",
+  team_name: "plan-implementation",
+  from_worker: "worker-1",
+  to_worker: "leader",
+  message: "Starting: <task-title>",
+});
+```
+
+### 3. Execute Task
+
+Follow the MUST DO constraints. Avoid MUST NOT DO items. Use required tools only.
+
+### 4. Run Acceptance Checks
+
+```bash
+# Run each check from the delegation packet
+npm run typecheck
+npm run lint
+npm test
+```
+
+### 5. Report Completion
+
+```typescript
+swarm_helper({
+  operation: "sendTeamMessage",
+  team_name: "plan-implementation",
+  from_worker: "worker-1",
+  to_worker: "leader",
+  message: "DONE: <task-title>. All checks passed. Changes: <summary>",
+});
+```
+
+## Mailbox Message Format
+
+Messages in `.beads/swarm-mail.jsonl`:
+
+```json
+{
+  "timestamp": "2025-01-27T10:30:00.000Z",
+  "team_name": "plan-implementation",
+  "from_worker": "worker-1",
+  "to_worker": "leader",
+  "message": "DONE: Implement auth service. All checks passed.",
+  "status": "unread"
+}
+```
+
+### Message Types
+
+| Type     | From   | To       | Purpose                     |
+| -------- | ------ | -------- | --------------------------- |
+| START    | worker | leader   | Worker beginning task       |
+| PROGRESS | worker | leader   | Intermediate update         |
+| BLOCKED  | worker | leader   | Worker needs help           |
+| DONE     | worker | leader   | Task completed successfully |
+| ERROR    | worker | leader   | Task failed                 |
+| HELP     | worker | worker-N | Request assistance          |
+| ASSIGN   | leader | worker   | New task assignment         |
+| SHUTDOWN | leader | all      | Graceful shutdown signal    |
+
+## Conflict Prevention
+
+### File Reservation
+
+Before workers start, leader reserves files:
+
+```typescript
+// Reserve files for each worker
+bd_reserve({
+  paths: ["src/auth/service.ts", "src/auth/types.ts"],
+  reason: "worker-1: auth service implementation",
+});
+```
+
+### Non-Overlapping Assignments
+
+Ensure workers don't edit same files:
+
+| Worker   | Assigned Files          |
+| -------- | ----------------------- |
+| worker-1 | src/auth/\*             |
+| worker-2 | src/routes/user/\*      |
+| worker-3 | src/components/forms/\* |
+
+## Error Handling
+
+### Worker Fails Acceptance Checks
+
+```typescript
+// Worker sends error message
+swarm_helper({
+  operation: "sendTeamMessage",
+  team_name: "plan-implementation",
+  from_worker: "worker-1",
+  to_worker: "leader",
+  message: "ERROR: typecheck failed. Issue: missing type for AuthToken",
+});
+```
+
+### Leader Response
+
+1. Read error from mailbox
+2. Decide: fix locally or reassign
+3. Either spawn fix-agent or adjust task
+
+### Worker Gets Blocked
+
+```typescript
+// Worker asks for help
+swarm_helper({
+  operation: "sendTeamMessage",
+  team_name: "plan-implementation",
+  from_worker: "worker-2",
+  to_worker: "leader",
+  message: "BLOCKED: Need auth service types. Waiting on worker-1.",
+});
+```
+
+## Graceful Shutdown
+
+Leader signals completion:
+
+```typescript
+// After all workers done
+swarm_helper({
+  operation: "sendTeamMessage",
+  team_name: "plan-implementation",
+  from_worker: "leader",
+  to_worker: "all",
+  message: "SHUTDOWN: All tasks complete. Final verification passed.",
+});
+```
+
+## 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        |
+
+## Integration with Beads
+
+Swarm works on top of Beads:
+
+1. **Plan creates beads** for each task
+2. **Leader claims parent** bead
+3. **Workers claim child** beads
+4. **Completion closes** beads via `bd_done()`
+
+```typescript
+// Leader workflow
+bd_claim(); // Gets parent task
+// ... spawn swarm ...
+// ... monitor completion ...
+bd_done({ id: "parent-task", msg: "Swarm completed all subtasks" });
+```
+
+## Quick Reference
+
+```
+SWARM LAUNCH:
+  1. Parse plan → identify parallel tasks
+  2. Create delegation packets (swarm-delegate)
+  3. Spawn workers (Task tool, multiple in one message)
+  4. Monitor mailbox (swarm-helper getTeamStatus)
+  5. Synthesize results
+
+WORKER EXECUTION:
+  1. Read delegation packet
+  2. Announce start via mailbox
+  3. Execute with constraints
+  4. Run acceptance checks
+  5. Report completion via mailbox
+
+COORDINATION:
+  - Mailbox: .beads/swarm-mail.jsonl
+  - Delegation: .beads/artifacts/<id>/delegation.md
+  - File locks: bd_reserve() before spawning
+
+SHUTDOWN:
+  - All workers done → leader sends SHUTDOWN
+  - Run full test suite
+  - Close parent bead
+```
+
+## Rules
+
+1. **Leader spawns, workers execute** - Clear role separation
+2. **Delegation packets are contracts** - Workers follow them strictly
+3. **Mailbox for coordination** - All communication through swarm-mail
+4. **No file conflicts** - Reserve before spawning workers
+5. **Acceptance checks required** - Workers verify before reporting done
+6. **Graceful shutdown** - Leader waits for all workers, then shuts down