clikit-plugin 0.1.0

package/skill/source-code-research/SKILL.md

@@ -0,0 +1,138 @@
+---
+name: source-code-research
+description: Use when API documentation is insufficient. Research library implementation details by fetching package source.
+---
+
+# Source Code Research Skill
+
+You are running the **source-code-research** skill. Go beyond API docs to understand internals.
+
+## When to Use
+
+- API docs don't explain behavior
+- Need to understand edge cases
+- Debugging library interactions
+- Learning implementation patterns
+- Verifying documented behavior
+
+## Research Protocol
+
+### 1. Identify Package
+```bash
+# Find package location
+which <package>
+npm list <package>
+
+# Find source location
+ls -la node_modules/<package>/
+```
+
+### 2. Locate Source
+```
+Check for:
+- src/ directory
+- lib/ directory
+- dist/ with sourcemaps
+- TypeScript .ts files
+- Index entry point
+```
+
+### 3. Read Key Files
+Focus on:
+- Entry point (index.js/ts)
+- Main export file
+- Types/interfaces
+- Core implementation
+- Tests (for behavior)
+
+### 4. Trace Execution
+- Follow function calls
+- Map data flow
+- Identify decision points
+- Note error handling
+
+## Key Questions to Answer
+
+| Question | Why |
+|----------|-----|
+| How is this implemented? | Understand behavior |
+| What edge cases exist? | Avoid surprises |
+| How are errors handled? | Proper error handling |
+| What are the types? | TypeScript integration |
+| What are the defaults? | Implicit behavior |
+
+## Finding Patterns
+
+### Constructor Pattern
+```javascript
+// Look for initialization logic
+class Example {
+  constructor(options) {
+    this.options = { ...defaults, ...options };
+  }
+}
+```
+
+### Error Handling Pattern
+```javascript
+// Identify what throws vs returns
+if (!valid) {
+  throw new Error('...');
+  // or
+  return { error: '...' };
+}
+```
+
+### Async Pattern
+```javascript
+// Understand async behavior
+async function process() {
+  // Is this parallel or sequential?
+  await Promise.all([...]);
+}
+```
+
+## Output Format
+
+Save to `.opencode/memory/research/[package]-internals.md`:
+
+```markdown
+# [Package] Internals
+
+## Entry Points
+- Main: [file]
+- Types: [file]
+
+## Key Findings
+
+### [Feature Name]
+- **Location**: file:line
+- **Behavior**: [description]
+- **Edge Cases**: [list]
+
+## Implementation Notes
+[Key patterns discovered]
+
+## Gotchas
+[Surprising behaviors]
+```
+
+## Anti-Patterns
+
+- Relying only on TypeScript definitions
+- Not reading tests
+- Assuming behavior from name
+- Ignoring error paths
+
+## Quick Reference
+
+```bash
+# Find main entry
+cat node_modules/pkg/package.json | grep main
+
+# Find types
+cat node_modules/pkg/package.json | grep types
+
+# Check for source
+ls node_modules/pkg/src/
+```

package/skill/subagent-driven-development/SKILL.md

@@ -0,0 +1,69 @@
+---
+name: subagent-driven-development
+description: Use when working on multi-task development cycles. Fresh subagent per task for fast iteration with code review between tasks via @review.
+---
+
+# Subagent-Driven Development Skill
+
+You are running the **subagent-driven-development** skill. Work autonomously for hours with quality gates between tasks.
+
+## Core Principle
+
+Fresh subagent per task. Each task is a clean slate with clear objectives. Code review between tasks via @review agent ensures quality accumulation.
+
+## Workflow
+
+### 1. Task Breakdown
+- Split work into discrete, completable tasks
+- Each task should be 15-30 minutes of work
+- Tasks should have clear success criteria
+- Order tasks by dependency
+
+### 2. Task Execution Cycle
+```
+For each task:
+  1. Spawn fresh subagent for task
+  2. Subagent completes task autonomously
+  3. Run @review for code quality check
+  4. Fix issues from review
+  5. Commit or stage changes
+  6. Move to next task
+```
+
+### 3. Quality Gates
+Between each task:
+- Run @review agent on changed files
+- Address all critical and high-priority issues
+- Verify tests pass
+- Confirm task completion criteria met
+
+## Agent Autonomy
+
+The subagent works autonomously:
+- No mid-task questions to user
+- Make reasonable assumptions
+- Document decisions in code
+- Flag blockers only when truly stuck
+
+## Benefits
+
+| Benefit | Why |
+|---------|-----|
+| Fresh context | No accumulated confusion |
+| Fast iteration | Quick task completion |
+| Quality accumulation | Review catches issues early |
+| Autonomous work | Hours of productive work |
+
+## Anti-Patterns
+
+- Tasks too large (lose the benefit of fresh context)
+- Skipping review between tasks
+- Asking user for every decision
+- No clear success criteria per task
+
+## When to Use
+
+- Multi-hour development sessions
+- Features with multiple components
+- Refactoring with clear steps
+- Bug fix chains with review gates

package/skill/supabase/SKILL.md

@@ -0,0 +1,80 @@
+---
+name: supabase
+description: Use when working with Supabase databases, edge functions, authentication, real-time subscriptions, or managing Supabase projects.
+---
+
+# Supabase Skill
+
+Comprehensive Supabase platform MCP covering database operations, edge functions, authentication, real-time features, development tools, debugging, and project management.
+
+## Capabilities
+
+- **Database Operations**: Query, migrate, manage PostgreSQL
+- **Edge Functions**: Deploy, manage, debug serverless functions
+- **Authentication**: User management, auth providers, JWT handling
+- **Real-time**: Subscribe to database changes
+- **Storage**: File upload, management, signed URLs
+- **Development Tools**: Local development, type generation
+- **Debugging**: Logs, metrics, query analysis
+
+## When to Use
+
+- Querying or modifying Supabase databases
+- Deploying and managing edge functions
+- Setting up authentication flows
+- Generating TypeScript types from schema
+- Debugging database queries and functions
+- Managing Supabase projects
+
+## Key Tools
+
+- `query`: Execute SQL queries
+- `migrate`: Run database migrations
+- `deploy_function`: Deploy edge function
+- `generate_types`: Generate TypeScript types
+- `list_logs`: View function/database logs
+- `manage_auth`: User operations
+
+## Example Usage
+
+```
+// Query database
+query({
+  sql: "SELECT * FROM users WHERE active = true LIMIT 10"
+})
+
+// Deploy edge function
+deploy_function({
+  name: "send-notification",
+  entrypoint: "./functions/send-notification/index.ts"
+})
+
+// Generate types
+generate_types({
+  output: "./src/types/supabase.ts"
+})
+
+// Auth operations
+manage_auth({
+  action: "create_user",
+  email: "user@example.com",
+  password: "secure123"
+})
+```
+
+## Development Workflow
+
+```bash
+# Local development
+supabase start          # Start local stack
+supabase db reset       # Reset with migrations
+supabase functions serve # Local function dev
+supabase types gen      # Generate types
+```
+
+## Notes
+
+- Requires Supabase project credentials
+- Supports both local and remote projects
+- Row Level Security policies respected
+- Connection pooling for serverless

package/skill/supabase-postgres-best-practices/SKILL.md

@@ -0,0 +1,168 @@
+---
+name: supabase-postgres-best-practices
+description: Use when writing, reviewing, or optimizing Postgres queries, schema designs, or database configurations from Supabase.
+---
+
+# Supabase Postgres Best Practices Skill
+
+You are running the **supabase-postgres-best-practices** skill. Postgres optimization from Supabase.
+
+## Core Principles
+
+Production-hardened patterns from Supabase's managed Postgres experience.
+
+## Query Optimization
+
+### 1. Index Strategy
+```sql
+-- Index for common query patterns
+CREATE INDEX idx_users_email ON users(email);
+CREATE INDEX idx_posts_user_created ON posts(user_id, created_at DESC);
+
+-- Partial index for filtered queries
+CREATE INDEX idx_active_users ON users(email) WHERE active = true;
+
+-- GIN for JSONB and arrays
+CREATE INDEX idx_metadata ON items USING GIN(metadata);
+```
+
+### 2. Query Patterns
+```sql
+-- Good: Sargable query
+SELECT * FROM users WHERE email = 'user@example.com';
+
+-- Avoid: Function on column prevents index usage
+SELECT * FROM users WHERE LOWER(email) = 'user@example.com';
+
+-- Fix: Use functional index or normalize data
+CREATE INDEX idx_users_email_lower ON users(LOWER(email));
+```
+
+### 3. EXPLAIN ANALYZE
+```sql
+-- Always analyze slow queries
+EXPLAIN ANALYZE SELECT * FROM posts WHERE user_id = 123;
+
+-- Look for:
+-- - Seq Scan (should be Index Scan)
+-- - High cost values
+-- - Large row estimates vs actual
+```
+
+## Schema Design
+
+### 1. Appropriate Types
+```sql
+-- Use appropriate types
+CREATE TABLE events (
+  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  created_at TIMESTAMPTZ DEFAULT NOW(), -- Not TIMESTAMP
+  status TEXT,                          -- Not VARCHAR(n)
+  metadata JSONB DEFAULT '{}'           -- Not JSON
+);
+```
+
+### 2. Foreign Keys
+```sql
+-- Always index foreign keys
+CREATE TABLE posts (
+  id UUID PRIMARY KEY,
+  user_id UUID REFERENCES users(id)
+);
+CREATE INDEX idx_posts_user_id ON posts(user_id);
+```
+
+### 3. Partitioning
+```sql
+-- Partition large tables by time
+CREATE TABLE events (
+  id UUID,
+  created_at TIMESTAMPTZ
+) PARTITION BY RANGE (created_at);
+
+CREATE TABLE events_2024_01 PARTITION OF events
+  FOR VALUES FROM ('2024-01-01') TO ('2024-02-01');
+```
+
+## Connection Management
+
+### 1. Connection Pooling
+```javascript
+// Use Supavisor or PgBouncer
+// Transaction mode for serverless
+const pool = new Pool({
+  connectionString: process.env.DATABASE_URL,
+  max: 10,                    // Limit connections
+  idleTimeoutMillis: 30000,
+  connectionTimeoutMillis: 2000
+});
+```
+
+### 2. Prepared Statements
+```sql
+-- Use prepared statements for repeated queries
+PREPARE get_user(UUID) AS
+  SELECT * FROM users WHERE id = $1;
+
+EXECUTE get_user('uuid-here');
+```
+
+## Performance Checklist
+
+| Check | Why |
+|-------|-----|
+| Index foreign keys | Join performance |
+| Use TIMESTAMPTZ | Timezone handling |
+| Use JSONB not JSON | Binary format, indexing |
+| Analyze slow queries | EXPLAIN ANALYZE |
+| Limit connections | Prevent exhaustion |
+
+## Common Anti-Patterns
+
+| Anti-Pattern | Fix |
+|--------------|-----|
+| SELECT * | Select only needed columns |
+| N+1 queries | Use JOINs or batch fetch |
+| Missing indexes | Add appropriate indexes |
+| VARCHAR(n) | Use TEXT with CHECK constraint |
+| TIMESTAMP | Use TIMESTAMPTZ |
+| Unindexed JSON queries | Use GIN index |
+
+## RLS (Row Level Security)
+
+```sql
+-- Enable RLS
+ALTER TABLE posts ENABLE ROW LEVEL SECURITY;
+
+-- Policy for user's own posts
+CREATE POLICY "Users can manage own posts"
+  ON posts FOR ALL
+  USING (auth.uid() = user_id)
+  WITH CHECK (auth.uid() = user_id);
+```
+
+## Monitoring Queries
+
+```sql
+-- Find slow queries
+SELECT query, mean_exec_time, calls
+FROM pg_stat_statements
+ORDER BY mean_exec_time DESC
+LIMIT 10;
+
+-- Check table bloat
+SELECT schemaname, tablename,
+       pg_size_pretty(pg_total_relation_size(schemaname||'.'||tablename)) as size
+FROM pg_tables
+ORDER BY pg_total_relation_size(schemaname||'.'||tablename) DESC;
+```
+
+## Quick Reference
+
+| Scenario | Solution |
+|----------|----------|
+| Slow reads | Add index, check EXPLAIN |
+| Slow writes | Reduce indexes, batch inserts |
+| Connection limits | Use pooling |
+| Large tables | Partition by time |
+| JSON queries | GIN index on JSONB |

package/skill/swarm-coordination/SKILL.md

@@ -0,0 +1,54 @@
+---
+name: swarm-coordination
+description: Use for implementing plans with multiple independent tasks in parallel using Kimi K2.5 PARL patterns.
+---
+
+# Swarm Coordination Skill
+
+You are running the **swarm-coordination** skill. Parallel multi-task execution.
+
+## PARL Pattern (Parallel Agent Runtime Loop)
+
+Kimi K2.5 patterns for coordinating multiple agents:
+
+| Phase | Action |
+|-------|--------|
+| Plan | Decompose into independent tasks |
+| Assign | Route tasks to available agents |
+| Run | Execute tasks in parallel |
+| Learn | Aggregate results, iterate |
+
+## Task Classification
+
+```
+Independent → Parallel execution
+Dependent   → Sequential with dependency tracking
+Blocked     → Wait for blocker completion
+```
+
+## Anti-Serial-Collapse Detection
+
+Warning signs of serial execution:
+- All tasks waiting on one agent
+- Sequential claims despite no dependencies
+- Long queue with no parallelism
+
+Mitigations:
+- Rebalance task assignments
+- Split blocking tasks
+- Add more agents to bottleneck role
+
+## Graceful Shutdown
+
+1. Complete in-progress tasks
+2. Checkpoint state to Beads
+3. Release all file reservations
+4. Sync to git
+5. Broadcast session end
+
+## Best Practices
+
+- Claim only ready (unblocked) tasks
+- Reserve files early, release promptly
+- Use `beads-village_broadcast` for coordination
+- Check `beads-village_discover` for active agents

package/skill/systematic-debugging/SKILL.md

@@ -0,0 +1,58 @@
+---
+name: systematic-debugging
+description: Use when encountering a bug. Enforces evidence-based 4-phase debugging process.
+---
+
+# Systematic Debugging Skill
+
+You are running the **systematic-debugging** skill. No guessing. No random changes.
+
+## 4-Phase Process
+
+### Phase 1: Reproduce
+- Create a minimal reproduction case
+- Document exact steps to trigger
+- Verify it's reproducible (not intermittent)
+
+### Phase 2: Isolate
+- Binary search: Comment out half the code
+- Which half contains the bug?
+- Repeat until isolated to smallest possible unit
+
+### Phase 3: Identify
+- Read the isolated code carefully
+- Trace variable values
+- Add instrumentation (console.log, debugger)
+- Understand WHY it fails, not just WHERE
+
+### Phase 4: Verify
+- Fix the root cause
+- Run tests to confirm fix
+- Check for similar issues elsewhere
+- Add regression test
+
+## Rules
+
+| Rule | Why |
+|------|-----|
+| No random changes | Masks symptoms, doesn't fix cause |
+| After 3+ failed fixes | Question architectural assumptions |
+| Always reproduce first | Can't fix what you can't trigger |
+| Add regression test | Prevent recurrence |
+
+## Instrumentation
+
+```javascript
+// Stack trace
+console.error('Debug:', new Error().stack);
+
+// Variable dump
+console.error('Context:', JSON.stringify({ var1, var2 }, null, 2));
+```
+
+## Red Flags
+
+- Changing code without understanding why
+- "Let me try this" without hypothesis
+- Fixing symptoms instead of root cause
+- No reproduction steps

package/skill/test-driven-development/SKILL.md

@@ -0,0 +1,53 @@
+---
+name: test-driven-development
+description: Use when implementing any feature. Enforces strict RED-GREEN-REFACTOR cycle.
+---
+
+# Test-Driven Development Skill
+
+You are running the **test-driven-development** skill. No code without tests. No exceptions.
+
+## RED-GREEN-REFACTOR
+
+### Phase 1: RED
+1. Write a failing test
+2. Run the test — it MUST fail
+3. If it passes, the test is wrong — delete and rewrite
+
+### Phase 2: GREEN
+1. Write the MINIMUM code to make the test pass
+2. Run the test — it MUST pass
+3. If it fails, fix the code (not the test)
+
+### Phase 3: REFACTOR
+1. Clean up code while keeping tests green
+2. Run tests after each change
+3. Commit when satisfied
+
+## Rules
+
+| Rule | Enforcement |
+|------|-------------|
+| Write code before test? | DELETE the code. Don't keep as reference. |
+| Test passes unexpectedly? | DELETE the test. It's testing nothing. |
+| Skip RED phase? | Not allowed. Always start with failing test. |
+| "Just this once"? | No. No exceptions. |
+
+## Workflow
+
+```
+1. Think → What should this do?
+2. RED → Write failing test
+3. Run → Watch it fail
+4. GREEN → Write minimal code
+5. Run → Watch it pass
+6. REFACTOR → Clean up
+7. Commit
+```
+
+## Red Flags
+
+- Writing implementation before test
+- Keeping "reference code" while writing test
+- Skipping "watch it fail" step
+- Test that can never fail