codehava-agent-kit 1.0.1 → 3.0.0

package/templates/.agent/skills/subagent-driven-development/SKILL.md

@@ -0,0 +1,242 @@
+---
+name: subagent-driven-development
+description: "Use when executing implementation plans with independent tasks in the current session"
+risk: unknown
+source: community
+date_added: "2026-02-27"
+---
+
+# Subagent-Driven Development
+
+Execute plan by dispatching fresh subagent per task, with two-stage review after each: spec compliance review first, then code quality review.
+
+**Core principle:** Fresh subagent per task + two-stage review (spec then quality) = high quality, fast iteration
+
+## When to Use
+```dot
+digraph when_to_use {
+    "Have implementation plan?" [shape=diamond];
+    "Tasks mostly independent?" [shape=diamond];
+    "Stay in this session?" [shape=diamond];
+    "subagent-driven-development" [shape=box];
+    "executing-plans" [shape=box];
+    "Manual execution or brainstorm first" [shape=box];
+
+    "Have implementation plan?" -> "Tasks mostly independent?" [label="yes"];
+    "Have implementation plan?" -> "Manual execution or brainstorm first" [label="no"];
+    "Tasks mostly independent?" -> "Stay in this session?" [label="yes"];
+    "Tasks mostly independent?" -> "Manual execution or brainstorm first" [label="no - tightly coupled"];
+    "Stay in this session?" -> "subagent-driven-development" [label="yes"];
+    "Stay in this session?" -> "executing-plans" [label="no - parallel session"];
+}
+```
+
+**vs. Executing Plans (parallel session):**
+- Same session (no context switch)
+- Fresh subagent per task (no context pollution)
+- Two-stage review after each task: spec compliance first, then code quality
+- Faster iteration (no human-in-loop between tasks)
+
+## The Process
+
+```dot
+digraph process {
+    rankdir=TB;
+
+    subgraph cluster_per_task {
+        label="Per Task";
+        "Dispatch implementer subagent (./implementer-prompt.md)" [shape=box];
+        "Implementer subagent asks questions?" [shape=diamond];
+        "Answer questions, provide context" [shape=box];
+        "Implementer subagent implements, tests, commits, self-reviews" [shape=box];
+        "Dispatch spec reviewer subagent (./spec-reviewer-prompt.md)" [shape=box];
+        "Spec reviewer subagent confirms code matches spec?" [shape=diamond];
+        "Implementer subagent fixes spec gaps" [shape=box];
+        "Dispatch code quality reviewer subagent (./code-quality-reviewer-prompt.md)" [shape=box];
+        "Code quality reviewer subagent approves?" [shape=diamond];
+        "Implementer subagent fixes quality issues" [shape=box];
+        "Mark task complete in TodoWrite" [shape=box];
+    }
+
+    "Read plan, extract all tasks with full text, note context, create TodoWrite" [shape=box];
+    "More tasks remain?" [shape=diamond];
+    "Dispatch final code reviewer subagent for entire implementation" [shape=box];
+    "Use superpowers:finishing-a-development-branch" [shape=box style=filled fillcolor=lightgreen];
+
+    "Read plan, extract all tasks with full text, note context, create TodoWrite" -> "Dispatch implementer subagent (./implementer-prompt.md)";
+    "Dispatch implementer subagent (./implementer-prompt.md)" -> "Implementer subagent asks questions?";
+    "Implementer subagent asks questions?" -> "Answer questions, provide context" [label="yes"];
+    "Answer questions, provide context" -> "Dispatch implementer subagent (./implementer-prompt.md)";
+    "Implementer subagent asks questions?" -> "Implementer subagent implements, tests, commits, self-reviews" [label="no"];
+    "Implementer subagent implements, tests, commits, self-reviews" -> "Dispatch spec reviewer subagent (./spec-reviewer-prompt.md)";
+    "Dispatch spec reviewer subagent (./spec-reviewer-prompt.md)" -> "Spec reviewer subagent confirms code matches spec?";
+    "Spec reviewer subagent confirms code matches spec?" -> "Implementer subagent fixes spec gaps" [label="no"];
+    "Implementer subagent fixes spec gaps" -> "Dispatch spec reviewer subagent (./spec-reviewer-prompt.md)" [label="re-review"];
+    "Spec reviewer subagent confirms code matches spec?" -> "Dispatch code quality reviewer subagent (./code-quality-reviewer-prompt.md)" [label="yes"];
+    "Dispatch code quality reviewer subagent (./code-quality-reviewer-prompt.md)" -> "Code quality reviewer subagent approves?";
+    "Code quality reviewer subagent approves?" -> "Implementer subagent fixes quality issues" [label="no"];
+    "Implementer subagent fixes quality issues" -> "Dispatch code quality reviewer subagent (./code-quality-reviewer-prompt.md)" [label="re-review"];
+    "Code quality reviewer subagent approves?" -> "Mark task complete in TodoWrite" [label="yes"];
+    "Mark task complete in TodoWrite" -> "More tasks remain?";
+    "More tasks remain?" -> "Dispatch implementer subagent (./implementer-prompt.md)" [label="yes"];
+    "More tasks remain?" -> "Dispatch final code reviewer subagent for entire implementation" [label="no"];
+    "Dispatch final code reviewer subagent for entire implementation" -> "Use superpowers:finishing-a-development-branch";
+}
+```
+
+## Prompt Templates
+
+- `./implementer-prompt.md` - Dispatch implementer subagent
+- `./spec-reviewer-prompt.md` - Dispatch spec compliance reviewer subagent
+- `./code-quality-reviewer-prompt.md` - Dispatch code quality reviewer subagent
+
+## Example Workflow
+
+```
+You: I'm using Subagent-Driven Development to execute this plan.
+
+[Read plan file once: docs/plans/feature-plan.md]
+[Extract all 5 tasks with full text and context]
+[Create TodoWrite with all tasks]
+
+Task 1: Hook installation script
+
+[Get Task 1 text and context (already extracted)]
+[Dispatch implementation subagent with full task text + context]
+
+Implementer: "Before I begin - should the hook be installed at user or system level?"
+
+You: "User level (~/.config/superpowers/hooks/)"
+
+Implementer: "Got it. Implementing now..."
+[Later] Implementer:
+  - Implemented install-hook command
+  - Added tests, 5/5 passing
+  - Self-review: Found I missed --force flag, added it
+  - Committed
+
+[Dispatch spec compliance reviewer]
+Spec reviewer: ✅ Spec compliant - all requirements met, nothing extra
+
+[Get git SHAs, dispatch code quality reviewer]
+Code reviewer: Strengths: Good test coverage, clean. Issues: None. Approved.
+
+[Mark Task 1 complete]
+
+Task 2: Recovery modes
+
+[Get Task 2 text and context (already extracted)]
+[Dispatch implementation subagent with full task text + context]
+
+Implementer: [No questions, proceeds]
+Implementer:
+  - Added verify/repair modes
+  - 8/8 tests passing
+  - Self-review: All good
+  - Committed
+
+[Dispatch spec compliance reviewer]
+Spec reviewer: ❌ Issues:
+  - Missing: Progress reporting (spec says "report every 100 items")
+  - Extra: Added --json flag (not requested)
+
+[Implementer fixes issues]
+Implementer: Removed --json flag, added progress reporting
+
+[Spec reviewer reviews again]
+Spec reviewer: ✅ Spec compliant now
+
+[Dispatch code quality reviewer]
+Code reviewer: Strengths: Solid. Issues (Important): Magic number (100)
+
+[Implementer fixes]
+Implementer: Extracted PROGRESS_INTERVAL constant
+
+[Code reviewer reviews again]
+Code reviewer: ✅ Approved
+
+[Mark Task 2 complete]
+
+...
+
+[After all tasks]
+[Dispatch final code-reviewer]
+Final reviewer: All requirements met, ready to merge
+
+Done!
+```
+
+## Advantages
+
+**vs. Manual execution:**
+- Subagents follow TDD naturally
+- Fresh context per task (no confusion)
+- Parallel-safe (subagents don't interfere)
+- Subagent can ask questions (before AND during work)
+
+**vs. Executing Plans:**
+- Same session (no handoff)
+- Continuous progress (no waiting)
+- Review checkpoints automatic
+
+**Efficiency gains:**
+- No file reading overhead (controller provides full text)
+- Controller curates exactly what context is needed
+- Subagent gets complete information upfront
+- Questions surfaced before work begins (not after)
+
+**Quality gates:**
+- Self-review catches issues before handoff
+- Two-stage review: spec compliance, then code quality
+- Review loops ensure fixes actually work
+- Spec compliance prevents over/under-building
+- Code quality ensures implementation is well-built
+
+**Cost:**
+- More subagent invocations (implementer + 2 reviewers per task)
+- Controller does more prep work (extracting all tasks upfront)
+- Review loops add iterations
+- But catches issues early (cheaper than debugging later)
+
+## Red Flags
+
+**Never:**
+- Skip reviews (spec compliance OR code quality)
+- Proceed with unfixed issues
+- Dispatch multiple implementation subagents in parallel (conflicts)
+- Make subagent read plan file (provide full text instead)
+- Skip scene-setting context (subagent needs to understand where task fits)
+- Ignore subagent questions (answer before letting them proceed)
+- Accept "close enough" on spec compliance (spec reviewer found issues = not done)
+- Skip review loops (reviewer found issues = implementer fixes = review again)
+- Let implementer self-review replace actual review (both are needed)
+- **Start code quality review before spec compliance is ✅** (wrong order)
+- Move to next task while either review has open issues
+
+**If subagent asks questions:**
+- Answer clearly and completely
+- Provide additional context if needed
+- Don't rush them into implementation
+
+**If reviewer finds issues:**
+- Implementer (same subagent) fixes them
+- Reviewer reviews again
+- Repeat until approved
+- Don't skip the re-review
+
+**If subagent fails task:**
+- Dispatch fix subagent with specific instructions
+- Don't try to fix manually (context pollution)
+
+## Integration
+
+**Required workflow skills:**
+- **superpowers:writing-plans** - Creates the plan this skill executes
+- **superpowers:requesting-code-review** - Code review template for reviewer subagents
+- **superpowers:finishing-a-development-branch** - Complete development after all tasks
+
+**Subagents should use:**
+- **superpowers:test-driven-development** - Subagents follow TDD for each task
+
+**Alternative workflow:**
+- **superpowers:executing-plans** - Use for parallel session instead of same-session execution

package/templates/.agent/skills/subagent-driven-development/code-quality-reviewer-prompt.md

@@ -0,0 +1,20 @@
+# Code Quality Reviewer Prompt Template
+
+Use this template when dispatching a code quality reviewer subagent.
+
+**Purpose:** Verify implementation is well-built (clean, tested, maintainable)
+
+**Only dispatch after spec compliance review passes.**
+
+```
+Task tool (superpowers:code-reviewer):
+  Use template at requesting-code-review/code-reviewer.md
+
+  WHAT_WAS_IMPLEMENTED: [from implementer's report]
+  PLAN_OR_REQUIREMENTS: Task N from [plan-file]
+  BASE_SHA: [commit before task]
+  HEAD_SHA: [current commit]
+  DESCRIPTION: [task summary]
+```
+
+**Code reviewer returns:** Strengths, Issues (Critical/Important/Minor), Assessment

package/templates/.agent/skills/subagent-driven-development/implementer-prompt.md

@@ -0,0 +1,78 @@
+# Implementer Subagent Prompt Template
+
+Use this template when dispatching an implementer subagent.
+
+```
+Task tool (general-purpose):
+  description: "Implement Task N: [task name]"
+  prompt: |
+    You are implementing Task N: [task name]
+
+    ## Task Description
+
+    [FULL TEXT of task from plan - paste it here, don't make subagent read file]
+
+    ## Context
+
+    [Scene-setting: where this fits, dependencies, architectural context]
+
+    ## Before You Begin
+
+    If you have questions about:
+    - The requirements or acceptance criteria
+    - The approach or implementation strategy
+    - Dependencies or assumptions
+    - Anything unclear in the task description
+
+    **Ask them now.** Raise any concerns before starting work.
+
+    ## Your Job
+
+    Once you're clear on requirements:
+    1. Implement exactly what the task specifies
+    2. Write tests (following TDD if task says to)
+    3. Verify implementation works
+    4. Commit your work
+    5. Self-review (see below)
+    6. Report back
+
+    Work from: [directory]
+
+    **While you work:** If you encounter something unexpected or unclear, **ask questions**.
+    It's always OK to pause and clarify. Don't guess or make assumptions.
+
+    ## Before Reporting Back: Self-Review
+
+    Review your work with fresh eyes. Ask yourself:
+
+    **Completeness:**
+    - Did I fully implement everything in the spec?
+    - Did I miss any requirements?
+    - Are there edge cases I didn't handle?
+
+    **Quality:**
+    - Is this my best work?
+    - Are names clear and accurate (match what things do, not how they work)?
+    - Is the code clean and maintainable?
+
+    **Discipline:**
+    - Did I avoid overbuilding (YAGNI)?
+    - Did I only build what was requested?
+    - Did I follow existing patterns in the codebase?
+
+    **Testing:**
+    - Do tests actually verify behavior (not just mock behavior)?
+    - Did I follow TDD if required?
+    - Are tests comprehensive?
+
+    If you find issues during self-review, fix them now before reporting.
+
+    ## Report Format
+
+    When done, report:
+    - What you implemented
+    - What you tested and test results
+    - Files changed
+    - Self-review findings (if any)
+    - Any issues or concerns
+```

package/templates/.agent/skills/subagent-driven-development/spec-reviewer-prompt.md

@@ -0,0 +1,61 @@
+# Spec Compliance Reviewer Prompt Template
+
+Use this template when dispatching a spec compliance reviewer subagent.
+
+**Purpose:** Verify implementer built what was requested (nothing more, nothing less)
+
+```
+Task tool (general-purpose):
+  description: "Review spec compliance for Task N"
+  prompt: |
+    You are reviewing whether an implementation matches its specification.
+
+    ## What Was Requested
+
+    [FULL TEXT of task requirements]
+
+    ## What Implementer Claims They Built
+
+    [From implementer's report]
+
+    ## CRITICAL: Do Not Trust the Report
+
+    The implementer finished suspiciously quickly. Their report may be incomplete,
+    inaccurate, or optimistic. You MUST verify everything independently.
+
+    **DO NOT:**
+    - Take their word for what they implemented
+    - Trust their claims about completeness
+    - Accept their interpretation of requirements
+
+    **DO:**
+    - Read the actual code they wrote
+    - Compare actual implementation to requirements line by line
+    - Check for missing pieces they claimed to implement
+    - Look for extra features they didn't mention
+
+    ## Your Job
+
+    Read the implementation code and verify:
+
+    **Missing requirements:**
+    - Did they implement everything that was requested?
+    - Are there requirements they skipped or missed?
+    - Did they claim something works but didn't actually implement it?
+
+    **Extra/unneeded work:**
+    - Did they build things that weren't requested?
+    - Did they over-engineer or add unnecessary features?
+    - Did they add "nice to haves" that weren't in spec?
+
+    **Misunderstandings:**
+    - Did they interpret requirements differently than intended?
+    - Did they solve the wrong problem?
+    - Did they implement the right feature but wrong way?
+
+    **Verify by reading code, not by trusting report.**
+
+    Report:
+    - ✅ Spec compliant (if everything matches after code inspection)
+    - ❌ Issues found: [list specifically what's missing or extra, with file:line references]
+```

package/templates/.agent/skills/supabase-automation/SKILL.md

@@ -0,0 +1,239 @@
+---
+name: supabase-automation
+description: "Automate Supabase database queries, table management, project administration, storage, edge functions, and SQL execution via Rube MCP (Composio). Always search tools first for current schemas."
+risk: unknown
+source: community
+date_added: "2026-02-27"
+---
+
+# Supabase Automation via Rube MCP
+
+Automate Supabase operations including database queries, table schema inspection, SQL execution, project and organization management, storage buckets, edge functions, and service health monitoring through Composio's Supabase toolkit.
+
+## Prerequisites
+
+- Rube MCP must be connected (RUBE_SEARCH_TOOLS available)
+- Active Supabase connection via `RUBE_MANAGE_CONNECTIONS` with toolkit `supabase`
+- Always call `RUBE_SEARCH_TOOLS` first to get current tool schemas
+
+## Setup
+
+**Get Rube MCP**: Add `https://rube.app/mcp` as an MCP server in your client configuration. No API keys needed — just add the endpoint and it works.
+
+1. Verify Rube MCP is available by confirming `RUBE_SEARCH_TOOLS` responds
+2. Call `RUBE_MANAGE_CONNECTIONS` with toolkit `supabase`
+3. If connection is not ACTIVE, follow the returned auth link to complete Supabase authentication
+4. Confirm connection status shows ACTIVE before running any workflows
+
+## Core Workflows
+
+### 1. Query and Manage Database Tables
+
+**When to use**: User wants to read data from tables, inspect schemas, or perform CRUD operations
+
+**Tool sequence**:
+1. `SUPABASE_LIST_ALL_PROJECTS` - List projects to find the target project_ref [Prerequisite]
+2. `SUPABASE_LIST_TABLES` - List all tables and views in the database [Prerequisite]
+3. `SUPABASE_GET_TABLE_SCHEMAS` - Get detailed column types, constraints, and relationships [Prerequisite for writes]
+4. `SUPABASE_SELECT_FROM_TABLE` - Query rows with filtering, sorting, and pagination [Required for reads]
+5. `SUPABASE_BETA_RUN_SQL_QUERY` - Execute arbitrary SQL for complex queries, inserts, updates, or deletes [Required for writes]
+
+**Key parameters for SELECT_FROM_TABLE**:
+- `project_ref`: 20-character lowercase project reference
+- `table`: Table or view name to query
+- `select`: Comma-separated column list (supports nested selections and JSON paths like `profile->avatar_url`)
+- `filters`: Array of filter objects with `column`, `operator`, `value`
+- `order`: Sort expression like `created_at.desc`
+- `limit`: Max rows to return (minimum 1)
+- `offset`: Rows to skip for pagination
+
+**PostgREST filter operators**:
+- `eq`, `neq`: Equal / not equal
+- `gt`, `gte`, `lt`, `lte`: Comparison operators
+- `like`, `ilike`: Pattern matching (case-sensitive / insensitive)
+- `is`: IS check (for null, true, false)
+- `in`: In a list of values
+- `cs`, `cd`: Contains / contained by (arrays)
+- `fts`, `plfts`, `phfts`, `wfts`: Full-text search variants
+
+**Key parameters for RUN_SQL_QUERY**:
+- `ref`: Project reference (20 lowercase letters, pattern `^[a-z]{20}$`)
+- `query`: Valid PostgreSQL SQL statement
+- `read_only`: Boolean to force read-only transaction (safer for SELECTs)
+
+**Pitfalls**:
+- `project_ref` must be exactly 20 lowercase letters (a-z only, no numbers or hyphens)
+- `SELECT_FROM_TABLE` is read-only; use `RUN_SQL_QUERY` for INSERT, UPDATE, DELETE operations
+- For PostgreSQL array columns (text[], integer[]), use `ARRAY['item1', 'item2']` or `'{"item1", "item2"}'` syntax, NOT JSON array syntax `'["item1", "item2"]'`
+- SQL identifiers that are case-sensitive must be double-quoted in queries
+- Complex DDL operations may timeout (~60 second limit); break into smaller queries
+- ERROR 42P01 "relation does not exist" usually means unquoted case-sensitive identifiers
+- ERROR 42883 "function does not exist" means you are calling non-standard helpers; prefer information_schema queries
+
+### 2. Manage Projects and Organizations
+
+**When to use**: User wants to list projects, inspect configurations, or manage organizations
+
+**Tool sequence**:
+1. `SUPABASE_LIST_ALL_ORGANIZATIONS` - List all organizations (IDs and names) [Required]
+2. `SUPABASE_GETS_INFORMATION_ABOUT_THE_ORGANIZATION` - Get detailed org info by slug [Optional]
+3. `SUPABASE_LIST_MEMBERS_OF_AN_ORGANIZATION` - List org members with roles and MFA status [Optional]
+4. `SUPABASE_LIST_ALL_PROJECTS` - List all projects with metadata [Required]
+5. `SUPABASE_GETS_PROJECT_S_POSTGRES_CONFIG` - Get database configuration [Optional]
+6. `SUPABASE_GETS_PROJECT_S_AUTH_CONFIG` - Get authentication configuration [Optional]
+7. `SUPABASE_GET_PROJECT_API_KEYS` - Get API keys (sensitive -- handle carefully) [Optional]
+8. `SUPABASE_GETS_PROJECT_S_SERVICE_HEALTH_STATUS` - Check service health [Optional]
+
+**Key parameters**:
+- `ref`: Project reference for project-specific tools
+- `slug`: Organization slug (URL-friendly identifier) for org tools
+- `services`: Array of services for health check: `auth`, `db`, `db_postgres_user`, `pg_bouncer`, `pooler`, `realtime`, `rest`, `storage`
+
+**Pitfalls**:
+- `LIST_ALL_ORGANIZATIONS` returns both `id` and `slug`; `LIST_MEMBERS_OF_AN_ORGANIZATION` expects `slug`, not `id`
+- `GET_PROJECT_API_KEYS` returns live secrets -- NEVER log, display, or persist full key values
+- `GETS_PROJECT_S_SERVICE_HEALTH_STATUS` requires a non-empty `services` array; empty array causes invalid_request error
+- Config tools may return 401/403 if token lacks required scope; handle gracefully rather than failing the whole workflow
+
+### 3. Inspect Database Schema
+
+**When to use**: User wants to understand table structure, columns, constraints, or generate types
+
+**Tool sequence**:
+1. `SUPABASE_LIST_ALL_PROJECTS` - Find the target project [Prerequisite]
+2. `SUPABASE_LIST_TABLES` - Enumerate all tables and views with metadata [Required]
+3. `SUPABASE_GET_TABLE_SCHEMAS` - Get detailed schema for specific tables [Required]
+4. `SUPABASE_GENERATE_TYPE_SCRIPT_TYPES` - Generate TypeScript types from schema [Optional]
+
+**Key parameters for LIST_TABLES**:
+- `project_ref`: Project reference
+- `schemas`: Array of schema names to search (e.g., `["public"]`); omit for all non-system schemas
+- `include_views`: Include views alongside tables (default true)
+- `include_metadata`: Include row count estimates and sizes (default true)
+- `include_system_schemas`: Include pg_catalog, information_schema, etc. (default false)
+
+**Key parameters for GET_TABLE_SCHEMAS**:
+- `project_ref`: Project reference
+- `table_names`: Array of table names (max 20 per request); supports schema prefix like `public.users`, `auth.users`
+- `include_relationships`: Include foreign key info (default true)
+- `include_indexes`: Include index info (default true)
+- `exclude_null_values`: Cleaner output by hiding null fields (default true)
+
+**Key parameters for GENERATE_TYPE_SCRIPT_TYPES**:
+- `ref`: Project reference
+- `included_schemas`: Comma-separated schema names (default `"public"`)
+
+**Pitfalls**:
+- Table names without schema prefix assume `public` schema
+- `row_count` and `size_bytes` from LIST_TABLES may be null for views or recently created tables; treat as unknown, not zero
+- GET_TABLE_SCHEMAS has a max of 20 tables per request; batch if needed
+- TypeScript types include all tables in specified schemas; cannot filter individual tables
+
+### 4. Manage Edge Functions
+
+**When to use**: User wants to list, inspect, or work with Supabase Edge Functions
+
+**Tool sequence**:
+1. `SUPABASE_LIST_ALL_PROJECTS` - Find the project reference [Prerequisite]
+2. `SUPABASE_LIST_ALL_FUNCTIONS` - List all edge functions with metadata [Required]
+3. `SUPABASE_RETRIEVE_A_FUNCTION` - Get detailed info for a specific function [Optional]
+
+**Key parameters**:
+- `ref`: Project reference
+- Function slug for RETRIEVE_A_FUNCTION
+
+**Pitfalls**:
+- `LIST_ALL_FUNCTIONS` returns metadata only, not function code or logs
+- `created_at` and `updated_at` may be epoch milliseconds; convert to human-readable timestamps
+- These tools cannot create or deploy edge functions; they are read-only inspection tools
+- Permission errors may occur without org/project admin rights
+
+### 5. Manage Storage Buckets
+
+**When to use**: User wants to list storage buckets or manage file storage
+
+**Tool sequence**:
+1. `SUPABASE_LIST_ALL_PROJECTS` - Find the project reference [Prerequisite]
+2. `SUPABASE_LISTS_ALL_BUCKETS` - List all storage buckets [Required]
+
+**Key parameters**:
+- `ref`: Project reference
+
+**Pitfalls**:
+- `LISTS_ALL_BUCKETS` returns bucket list only, not bucket contents or access policies
+- For file uploads, `SUPABASE_RESUMABLE_UPLOAD_SIGN_OPTIONS_WITH_ID` handles CORS preflight for TUS resumable uploads only
+- Direct file operations may require using `proxy_execute` with the Supabase storage API
+
+## Common Patterns
+
+### ID Resolution
+- **Project reference**: `SUPABASE_LIST_ALL_PROJECTS` -- extract `ref` field (20 lowercase letters)
+- **Organization slug**: `SUPABASE_LIST_ALL_ORGANIZATIONS` -- use `slug` (not `id`) for downstream org tools
+- **Table names**: `SUPABASE_LIST_TABLES` -- enumerate available tables before querying
+- **Schema discovery**: `SUPABASE_GET_TABLE_SCHEMAS` -- inspect columns and constraints before writes
+
+### Pagination
+- `SUPABASE_SELECT_FROM_TABLE`: Uses `offset` + `limit` pagination. Increment offset by limit until fewer rows than limit are returned.
+- `SUPABASE_LIST_ALL_PROJECTS`: May paginate for large accounts; follow cursors/pages until exhausted.
+- `SUPABASE_LIST_TABLES`: May paginate for large databases.
+
+### SQL Best Practices
+- Always use `SUPABASE_GET_TABLE_SCHEMAS` or `SUPABASE_LIST_TABLES` before writing SQL
+- Use `read_only: true` for SELECT queries to prevent accidental mutations
+- Quote case-sensitive identifiers: `SELECT * FROM "MyTable"` not `SELECT * FROM MyTable`
+- Use PostgreSQL array syntax for array columns: `ARRAY['a', 'b']` not `['a', 'b']`
+- Break complex DDL into smaller statements to avoid timeouts
+
+## Known Pitfalls
+
+### ID Formats
+- Project references are exactly 20 lowercase letters (a-z): pattern `^[a-z]{20}$`
+- Organization identifiers come as both `id` (UUID) and `slug` (URL-friendly string); tools vary in which they accept
+- `LIST_MEMBERS_OF_AN_ORGANIZATION` requires `slug`, not `id`
+
+### SQL Execution
+- `BETA_RUN_SQL_QUERY` has ~60 second timeout for complex operations
+- PostgreSQL array syntax required: `ARRAY['item']` or `'{"item"}'`, NOT JSON syntax `'["item"]'`
+- Case-sensitive identifiers must be double-quoted in SQL
+- ERROR 42P01: relation does not exist (check quoting and schema prefix)
+- ERROR 42883: function does not exist (use information_schema instead of custom helpers)
+
+### Sensitive Data
+- `GET_PROJECT_API_KEYS` returns service-role keys -- NEVER expose full values
+- Auth config tools exclude secrets but may still contain sensitive configuration
+- Always mask or truncate API keys in output
+
+### Schema Metadata
+- `row_count` and `size_bytes` from `LIST_TABLES` can be null; do not treat as zero
+- System schemas are excluded by default; set `include_system_schemas: true` to see them
+- Views appear alongside tables unless `include_views: false`
+
+### Rate Limits and Permissions
+- Enrichment tools (API keys, configs) may return 401/403 without proper scopes; skip gracefully
+- Large table listings may require pagination
+- `GETS_PROJECT_S_SERVICE_HEALTH_STATUS` fails with empty `services` array -- always specify at least one
+
+## Quick Reference
+
+| Task | Tool Slug | Key Params |
+|------|-----------|------------|
+| List organizations | `SUPABASE_LIST_ALL_ORGANIZATIONS` | (none) |
+| Get org info | `SUPABASE_GETS_INFORMATION_ABOUT_THE_ORGANIZATION` | `slug` |
+| List org members | `SUPABASE_LIST_MEMBERS_OF_AN_ORGANIZATION` | `slug` |
+| List projects | `SUPABASE_LIST_ALL_PROJECTS` | (none) |
+| List tables | `SUPABASE_LIST_TABLES` | `project_ref`, `schemas` |
+| Get table schemas | `SUPABASE_GET_TABLE_SCHEMAS` | `project_ref`, `table_names` |
+| Query table | `SUPABASE_SELECT_FROM_TABLE` | `project_ref`, `table`, `select`, `filters` |
+| Run SQL | `SUPABASE_BETA_RUN_SQL_QUERY` | `ref`, `query`, `read_only` |
+| Generate TS types | `SUPABASE_GENERATE_TYPE_SCRIPT_TYPES` | `ref`, `included_schemas` |
+| Postgres config | `SUPABASE_GETS_PROJECT_S_POSTGRES_CONFIG` | `ref` |
+| Auth config | `SUPABASE_GETS_PROJECT_S_AUTH_CONFIG` | `ref` |
+| Get API keys | `SUPABASE_GET_PROJECT_API_KEYS` | `ref` |
+| Service health | `SUPABASE_GETS_PROJECT_S_SERVICE_HEALTH_STATUS` | `ref`, `services` |
+| List edge functions | `SUPABASE_LIST_ALL_FUNCTIONS` | `ref` |
+| Get edge function | `SUPABASE_RETRIEVE_A_FUNCTION` | `ref`, function slug |
+| List storage buckets | `SUPABASE_LISTS_ALL_BUCKETS` | `ref` |
+| List DB branches | `SUPABASE_LIST_ALL_DATABASE_BRANCHES` | `ref` |
+
+## When to Use
+This skill is applicable to execute the workflow or actions described in the overview.