@kolbo/kolbo-code-linux-arm64-musl 1.1.73 → 2.0.0

package/skills/supabase-postgres-best-practices/references/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/skills/supabase-postgres-best-practices/references/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/skills/supabase-postgres-best-practices/references/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/skills/supabase-quickstart/SKILL.md

@@ -0,0 +1,400 @@
+---
+name: supabase-quickstart
+description: "Use when a user wants to build a fullstack app with Supabase, set up a new Supabase project, connect Supabase to a frontend framework, or says anything like 'build me an app', 'I need a database', 'set up auth', 'create a backend'. Guides non-technical users step-by-step through project creation, MCP server setup, auth, database schema, and generates project-level AGENTS.md rules."
+---
+
+# Supabase Fullstack Quickstart
+
+You are guiding a user — who may have zero backend experience — through building a fullstack app powered by Supabase. Your job is to automate everything possible, explain only what the user needs to decide, and leave behind project rules so future sessions stay consistent.
+
+## Phase 0: Understand What They Want
+
+Before touching any tool, ask the user THREE things (skip any they already answered):
+
+1. **What does the app do?** (e.g., "a todo app", "a SaaS dashboard", "a booking system")
+2. **Do they already have a Supabase project?** (yes → get project URL + anon key; no → guide creation)
+3. **What frontend?** (Next.js / React + Vite / SvelteKit / Astro / other — default to Next.js if unsure)
+
+## Phase 1: Supabase Project Setup
+
+### If user has NO Supabase project
+
+Walk them through this — they'll do the clicking, you tell them exactly what to click:
+
+```
+1. Go to https://supabase.com/dashboard → Sign up or log in
+2. Click "New Project"
+3. Pick an organization (or create one — any name is fine)
+4. Set:
+   - Project name: [suggest based on their app idea]
+   - Database password: [tell them to save it somewhere safe]
+   - Region: [suggest closest to their location]
+5. Click "Create new project" — wait ~2 minutes for provisioning
+6. Once ready, go to Project Settings → API
+7. Copy these two values:
+   - Project URL (looks like https://xxxxx.supabase.co)
+   - anon/public key (starts with eyJ...)
+```
+
+### If user HAS a Supabase project
+
+Ask for:
+- Project URL
+- Anon key (public, safe for frontend)
+- Service role key (only if they'll need admin operations — warn them this is sensitive)
+
+## Phase 2: Supabase CLI & MCP Server
+
+### Install Supabase CLI
+
+```bash
+# Check if already installed
+supabase --version
+
+# If not installed:
+# macOS/Linux
+brew install supabase/tap/supabase
+# or npx (works everywhere)
+npx supabase --version
+```
+
+### Configure MCP Server (so YOU can interact with their database directly)
+
+Add to the project's `opencode.json` (create if it doesn't exist):
+
+```json
+{
+  "mcp": {
+    "supabase": {
+      "type": "remote",
+      "url": "https://mcp.supabase.com/mcp",
+      "oauth": true
+    }
+  }
+}
+```
+
+Then tell the user:
+```
+I've configured the Supabase MCP server. You need to authenticate it:
+1. Restart this session (or reload the editor)
+2. When prompted, complete the OAuth flow in your browser
+3. Once authenticated, I'll be able to create tables, run queries,
+   and manage your database directly — no copy-pasting SQL needed.
+```
+
+If MCP auth fails, fall back to the CLI: `supabase db query "SELECT 1"` to verify connectivity.
+
+### Link to their project (for local dev)
+
+```bash
+supabase login
+supabase link --project-ref <project-ref>
+# project-ref is the xxxxx part of https://xxxxx.supabase.co
+```
+
+## Phase 3: Frontend Scaffolding
+
+### Create the project (if starting fresh)
+
+Based on their framework choice:
+
+**Next.js (recommended for beginners):**
+```bash
+npx create-next-app@latest my-app --typescript --tailwind --app --eslint
+cd my-app
+npm install @supabase/supabase-js @supabase/ssr
+```
+
+**React + Vite:**
+```bash
+npm create vite@latest my-app -- --template react-ts
+cd my-app
+npm install @supabase/supabase-js
+```
+
+**SvelteKit:**
+```bash
+npx sv create my-app
+cd my-app
+npm install @supabase/supabase-js @supabase/ssr
+```
+
+### Environment variables
+
+Create `.env.local` (Next.js) or `.env` (Vite/Svelte):
+```
+NEXT_PUBLIC_SUPABASE_URL=https://xxxxx.supabase.co
+NEXT_PUBLIC_SUPABASE_ANON_KEY=eyJ...
+```
+
+IMPORTANT: Never put the service_role key in a `NEXT_PUBLIC_` or `VITE_` variable — it gets shipped to the browser.
+
+### Create the Supabase client
+
+**Next.js (App Router) — create `src/lib/supabase/`:**
+
+`client.ts` (browser):
+```typescript
+import { createBrowserClient } from "@supabase/ssr"
+
+export function createClient() {
+  return createBrowserClient(
+    process.env.NEXT_PUBLIC_SUPABASE_URL!,
+    process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!,
+  )
+}
+```
+
+`server.ts` (server components/actions):
+```typescript
+import { createServerClient } from "@supabase/ssr"
+import { cookies } from "next/headers"
+
+export async function createClient() {
+  const cookieStore = await cookies()
+  return createServerClient(
+    process.env.NEXT_PUBLIC_SUPABASE_URL!,
+    process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!,
+    {
+      cookies: {
+        getAll() { return cookieStore.getAll() },
+        setAll(cookiesToSet) {
+          try {
+            cookiesToSet.forEach(({ name, value, options }) =>
+              cookieStore.set(name, value, options))
+          } catch {}
+        },
+      },
+    },
+  )
+}
+```
+
+`middleware.ts` (in project root):
+```typescript
+import { createServerClient } from "@supabase/ssr"
+import { NextResponse, type NextRequest } from "next/server"
+
+export async function middleware(request: NextRequest) {
+  let response = NextResponse.next({ request })
+  const supabase = createServerClient(
+    process.env.NEXT_PUBLIC_SUPABASE_URL!,
+    process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!,
+    {
+      cookies: {
+        getAll() { return request.cookies.getAll() },
+        setAll(cookiesToSet) {
+          cookiesToSet.forEach(({ name, value }) =>
+            request.cookies.set(name, value))
+          response = NextResponse.next({ request })
+          cookiesToSet.forEach(({ name, value, options }) =>
+            response.cookies.set(name, value, options))
+        },
+      },
+    },
+  )
+  await supabase.auth.getUser()
+  return response
+}
+
+export const config = {
+  matcher: ["/((?!_next/static|_next/image|favicon.ico|.*\\.(?:svg|png|jpg|jpeg|gif|webp)$).*)"],
+}
+```
+
+**React + Vite:**
+```typescript
+import { createClient } from "@supabase/supabase-js"
+
+export const supabase = createClient(
+  import.meta.env.VITE_SUPABASE_URL,
+  import.meta.env.VITE_SUPABASE_ANON_KEY,
+)
+```
+
+## Phase 4: Auth Setup
+
+Ask the user: "Do you need user login? (email/password, Google, GitHub, magic link?)"
+
+### Email/Password (simplest)
+
+Enable in Supabase Dashboard → Auth → Providers → Email.
+
+Create signup/login pages with forms. Example (Next.js):
+
+```typescript
+// app/auth/login/page.tsx
+"use client"
+import { createClient } from "@/lib/supabase/client"
+import { useRouter } from "next/navigation"
+import { useState } from "react"
+
+export default function Login() {
+  const [email, setEmail] = useState("")
+  const [password, setPassword] = useState("")
+  const [error, setError] = useState("")
+  const router = useRouter()
+  const supabase = createClient()
+
+  const handleLogin = async (e: React.FormEvent) => {
+    e.preventDefault()
+    const { error } = await supabase.auth.signInWithPassword({ email, password })
+    if (error) setError(error.message)
+    else router.push("/dashboard")
+  }
+
+  return (
+    <form onSubmit={handleLogin}>
+      <input type="email" value={email} onChange={e => setEmail(e.target.value)} placeholder="Email" required />
+      <input type="password" value={password} onChange={e => setPassword(e.target.value)} placeholder="Password" required />
+      {error && <p style={{color:"red"}}>{error}</p>}
+      <button type="submit">Log in</button>
+    </form>
+  )
+}
+```
+
+### OAuth (Google, GitHub, etc.)
+
+Guide the user through the dashboard:
+```
+1. Supabase Dashboard → Auth → Providers
+2. Enable Google/GitHub/etc.
+3. For Google: Create OAuth credentials at console.cloud.google.com
+   - Authorized redirect: https://xxxxx.supabase.co/auth/v1/callback
+4. Paste Client ID + Client Secret into Supabase
+```
+
+Then add OAuth login button:
+```typescript
+const { data, error } = await supabase.auth.signInWithOAuth({
+  provider: "google",
+  options: { redirectTo: `${window.location.origin}/auth/callback` }
+})
+```
+
+## Phase 5: Database Schema
+
+Based on what the user described in Phase 0, design the schema. Use MCP `execute_sql` if available, otherwise generate migration files.
+
+### Example flow
+
+1. Design tables based on app requirements
+2. Create them:
+   ```sql
+   CREATE TABLE public.todos (
+     id UUID DEFAULT gen_random_uuid() PRIMARY KEY,
+     user_id UUID REFERENCES auth.users(id) ON DELETE CASCADE NOT NULL,
+     title TEXT NOT NULL,
+     completed BOOLEAN DEFAULT false,
+     created_at TIMESTAMPTZ DEFAULT now()
+   );
+   ```
+3. ALWAYS enable RLS:
+   ```sql
+   ALTER TABLE public.todos ENABLE ROW LEVEL SECURITY;
+
+   CREATE POLICY "Users can read own todos"
+     ON public.todos FOR SELECT
+     USING (auth.uid() = user_id);
+
+   CREATE POLICY "Users can insert own todos"
+     ON public.todos FOR INSERT
+     WITH CHECK (auth.uid() = user_id);
+
+   CREATE POLICY "Users can update own todos"
+     ON public.todos FOR UPDATE
+     USING (auth.uid() = user_id);
+
+   CREATE POLICY "Users can delete own todos"
+     ON public.todos FOR DELETE
+     USING (auth.uid() = user_id);
+   ```
+4. Generate migration: `supabase db pull --local --yes`
+
+## Phase 6: Generate Project Rules (AGENTS.md)
+
+**CRITICAL: After setup is complete, ALWAYS generate an `AGENTS.md` file in the project root.** This ensures all future agent sessions know how the project is configured.
+
+Template — adapt based on actual setup:
+
+```markdown
+# [App Name] — Agent Rules
+
+## Stack
+- Frontend: [Next.js 15 / React + Vite / SvelteKit] + TypeScript + Tailwind CSS
+- Backend: Supabase (Database, Auth, RLS, Edge Functions)
+- Database: PostgreSQL via Supabase
+
+## Supabase Configuration
+- Project URL: stored in `NEXT_PUBLIC_SUPABASE_URL` env var
+- Anon Key: stored in `NEXT_PUBLIC_SUPABASE_ANON_KEY` env var
+- MCP server configured in `opencode.json` — use MCP tools to query/modify the database directly
+
+## Auth
+- Provider: [Email/Password | Google OAuth | GitHub OAuth | Magic Link]
+- Client setup: `src/lib/supabase/client.ts` (browser) and `src/lib/supabase/server.ts` (server)
+- Middleware at `middleware.ts` refreshes auth tokens on every request
+- Protected routes: [list or pattern, e.g., "/dashboard/*"]
+
+## Database Rules
+- **RLS is ON for all tables** — every new table MUST have RLS enabled with appropriate policies
+- **user_id pattern**: All user-owned tables have a `user_id UUID REFERENCES auth.users(id)` column
+- **Never use `user_metadata`** for authorization — it's user-editable
+- **Migrations**: Use `supabase db pull --local --yes` to generate, never create migration files manually
+
+## Schema
+[List tables and their purpose, e.g.:]
+- `todos` — User tasks (CRUD by owner only)
+- `profiles` — Extended user info (read by anyone, write by owner)
+
+## Development
+- Local dev: `npm run dev` (frontend) + Supabase cloud (no local Supabase instance)
+- Environment: `.env.local` for secrets (gitignored)
+- Never expose `service_role` key in frontend code
+
+## Security Checklist (run before any PR)
+- [ ] All new tables have RLS enabled
+- [ ] No `service_role` key in client-side code
+- [ ] No `user_metadata` used for authorization
+- [ ] Views use `security_invoker = true`
+- [ ] Functions in private schema if `security definer`
+```
+
+## Phase 7: Verify Everything Works
+
+Run through this checklist before telling the user "you're ready":
+
+1. `npm run dev` starts without errors
+2. Can sign up a test user
+3. Can log in with that user
+4. Can create/read data (confirms RLS works)
+5. `AGENTS.md` exists in project root
+6. `.env.local` is in `.gitignore`
+7. MCP server is connected (if applicable)
+
+Tell the user:
+```
+Your app is set up and running. Here's what I've configured:
+- [Framework] project with Supabase connected
+- User authentication with [provider]
+- Database with [N] tables, all with Row Level Security
+- Project rules in AGENTS.md so I'll remember this setup next time
+- MCP server so I can query your database directly
+
+You can now ask me to add features, and I'll build on this foundation.
+```
+
+## Adapting to Existing Projects
+
+If the user already has a frontend project and wants to ADD Supabase:
+
+1. Install packages: `npm install @supabase/supabase-js @supabase/ssr`
+2. Create env vars
+3. Create Supabase client files (Phase 3)
+4. Add middleware (if Next.js/SvelteKit)
+5. Set up MCP (Phase 2)
+6. Generate/update AGENTS.md (Phase 6)
+
+Do NOT restructure their existing project — add Supabase to their existing patterns.

package/skills/systematic-debugging/CREATION-LOG.md

@@ -0,0 +1,119 @@
+# Creation Log: Systematic Debugging Skill
+
+Reference example of extracting, structuring, and bulletproofing a critical skill.
+
+## Source Material
+
+Extracted debugging framework from `/Users/jesse/.claude/CLAUDE.md`:
+- 4-phase systematic process (Investigation → Pattern Analysis → Hypothesis → Implementation)
+- Core mandate: ALWAYS find root cause, NEVER fix symptoms
+- Rules designed to resist time pressure and rationalization
+
+## Extraction Decisions
+
+**What to include:**
+- Complete 4-phase framework with all rules
+- Anti-shortcuts ("NEVER fix symptom", "STOP and re-analyze")
+- Pressure-resistant language ("even if faster", "even if I seem in a hurry")
+- Concrete steps for each phase
+
+**What to leave out:**
+- Project-specific context
+- Repetitive variations of same rule
+- Narrative explanations (condensed to principles)
+
+## Structure Following skill-creation/SKILL.md
+
+1. **Rich when_to_use** - Included symptoms and anti-patterns
+2. **Type: technique** - Concrete process with steps
+3. **Keywords** - "root cause", "symptom", "workaround", "debugging", "investigation"
+4. **Flowchart** - Decision point for "fix failed" → re-analyze vs add more fixes
+5. **Phase-by-phase breakdown** - Scannable checklist format
+6. **Anti-patterns section** - What NOT to do (critical for this skill)
+
+## Bulletproofing Elements
+
+Framework designed to resist rationalization under pressure:
+
+### Language Choices
+- "ALWAYS" / "NEVER" (not "should" / "try to")
+- "even if faster" / "even if I seem in a hurry"
+- "STOP and re-analyze" (explicit pause)
+- "Don't skip past" (catches the actual behavior)
+
+### Structural Defenses
+- **Phase 1 required** - Can't skip to implementation
+- **Single hypothesis rule** - Forces thinking, prevents shotgun fixes
+- **Explicit failure mode** - "IF your first fix doesn't work" with mandatory action
+- **Anti-patterns section** - Shows exactly what shortcuts look like
+
+### Redundancy
+- Root cause mandate in overview + when_to_use + Phase 1 + implementation rules
+- "NEVER fix symptom" appears 4 times in different contexts
+- Each phase has explicit "don't skip" guidance
+
+## Testing Approach
+
+Created 4 validation tests following skills/meta/testing-skills-with-subagents:
+
+### Test 1: Academic Context (No Pressure)
+- Simple bug, no time pressure
+- **Result:** Perfect compliance, complete investigation
+
+### Test 2: Time Pressure + Obvious Quick Fix
+- User "in a hurry", symptom fix looks easy
+- **Result:** Resisted shortcut, followed full process, found real root cause
+
+### Test 3: Complex System + Uncertainty
+- Multi-layer failure, unclear if can find root cause
+- **Result:** Systematic investigation, traced through all layers, found source
+
+### Test 4: Failed First Fix
+- Hypothesis doesn't work, temptation to add more fixes
+- **Result:** Stopped, re-analyzed, formed new hypothesis (no shotgun)
+
+**All tests passed.** No rationalizations found.
+
+## Iterations
+
+### Initial Version
+- Complete 4-phase framework
+- Anti-patterns section
+- Flowchart for "fix failed" decision
+
+### Enhancement 1: TDD Reference
+- Added link to skills/testing/test-driven-development
+- Note explaining TDD's "simplest code" ≠ debugging's "root cause"
+- Prevents confusion between methodologies
+
+## Final Outcome
+
+Bulletproof skill that:
+- ✅ Clearly mandates root cause investigation
+- ✅ Resists time pressure rationalization
+- ✅ Provides concrete steps for each phase
+- ✅ Shows anti-patterns explicitly
+- ✅ Tested under multiple pressure scenarios
+- ✅ Clarifies relationship to TDD
+- ✅ Ready for use
+
+## Key Insight
+
+**Most important bulletproofing:** Anti-patterns section showing exact shortcuts that feel justified in the moment. When Claude thinks "I'll just add this one quick fix", seeing that exact pattern listed as wrong creates cognitive friction.
+
+## Usage Example
+
+When encountering a bug:
+1. Load skill: skills/debugging/systematic-debugging
+2. Read overview (10 sec) - reminded of mandate
+3. Follow Phase 1 checklist - forced investigation
+4. If tempted to skip - see anti-pattern, stop
+5. Complete all phases - root cause found
+
+**Time investment:** 5-10 minutes
+**Time saved:** Hours of symptom-whack-a-mole
+
+---
+
+*Created: 2025-10-03*
+*Purpose: Reference example for skill extraction and bulletproofing*