class-ai-agent 1.2.3 → 1.4.0

package/.claude/skills/supabase-postgres-best-practices/references/schema-lowercase-identifiers.md

@@ -0,0 +1,55 @@
+---
+title: Use Lowercase Identifiers for Compatibility
+impact: MEDIUM
+impactDescription: Avoid case-sensitivity bugs with tools, ORMs, and AI assistants
+tags: naming, identifiers, case-sensitivity, schema, conventions
+---
+
+## Use Lowercase Identifiers for Compatibility
+
+PostgreSQL folds unquoted identifiers to lowercase. Quoted mixed-case identifiers require quotes forever and cause issues with tools, ORMs, and AI assistants that may not recognize them.
+
+**Incorrect (mixed-case identifiers):**
+
+```sql
+-- Quoted identifiers preserve case but require quotes everywhere
+CREATE TABLE "Users" (
+  "userId" bigint PRIMARY KEY,
+  "firstName" text,
+  "lastName" text
+);
+
+-- Must always quote or queries fail
+SELECT "firstName" FROM "Users" WHERE "userId" = 1;
+
+-- This fails - Users becomes users without quotes
+SELECT firstName FROM Users;
+-- ERROR: relation "users" does not exist
+```
+
+**Correct (lowercase snake_case):**
+
+```sql
+-- Unquoted lowercase identifiers are portable and tool-friendly
+CREATE TABLE users (
+  user_id bigint PRIMARY KEY,
+  first_name text,
+  last_name text
+);
+
+-- Works without quotes, recognized by all tools
+SELECT first_name FROM users WHERE user_id = 1;
+```
+
+Common sources of mixed-case identifiers:
+
+```sql
+-- ORMs often generate quoted camelCase - configure them to use snake_case
+-- Migrations from other databases may preserve original casing
+-- Some GUI tools quote identifiers by default - disable this
+
+-- If stuck with mixed-case, create views as a compatibility layer
+CREATE VIEW users AS SELECT "userId" AS user_id, "firstName" AS first_name FROM "Users";
+```
+
+Reference: [Identifiers and Key Words](https://www.postgresql.org/docs/current/sql-syntax-lexical.html#SQL-SYNTAX-IDENTIFIERS)

package/.claude/skills/supabase-postgres-best-practices/references/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/.claude/skills/supabase-postgres-best-practices/references/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/.claude/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/.claude/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/.claude/skills/supabase-postgres-best-practices/references/security-rls-performance.md

@@ -0,0 +1,63 @@
+---
+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:
+
+`SECURITY DEFINER` functions run with the creator's privileges and bypass RLS on any tables they touch — which is what makes them useful for internal lookups, but also what makes them dangerous if misused. Always include an explicit `auth.uid()` check inside the function body, keep them in a non-exposed schema, and revoke `EXECUTE` from any role that shouldn't call them directly.
+
+```sql
+-- Create helper function in a private schema
+create or replace function private.is_team_member(team_id bigint)
+returns boolean
+language sql
+security definer
+set search_path = ''
+as $$
+  select exists (
+    select 1 from public.team_members
+    -- always check the calling user's identity inside the function
+    where team_id = $1 and user_id = (select auth.uid())
+  );
+$$;
+
+-- Revoke direct execution from public roles
+revoke execute on function private.is_team_member(bigint) from PUBLIC, anon, authenticated, service_role;
+
+-- Use in policy (indexed lookup, not per-row check)
+create policy team_orders_policy on orders
+  using ((select private.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/.cursor/CURSOR.md

@@ -2,7 +2,7 @@
 
 ## Overview
 
-This project uses **Cursor** with the same structured workflows, specialized agent personas, and coding standards as the Claude-oriented **`.claude/`** tree. Cursor-specific files live under **`.cursor/`**.
+This project uses **Cursor** with the same structured workflows, specialized agent personas, and coding standards as **`.claude/`** and **`.kiro/`**. Cursor-specific files live under **`.cursor/`**.
 
 ---
 
@@ -30,6 +30,9 @@ Follow this workflow for feature development:
 | `commands/debug.md` | Systematic diagnosis |
 | `commands/simplify.md` | Reduce complexity, same behavior |
 | `commands/fix-issue.md` | Analyze and fix reported issues |
+| `commands/handoff.md` | End session — update `.agent/SESSION.md` for cross-tool continuity |
+| `commands/resume.md` | Start session — load `.agent/SESSION.md` and continue prior work |
+| `commands/publish-npm.md` | **Maintainers:** draft release notes, bump version, update README, publish to npm |
 
 **How to use:** Open the markdown file, copy the section you need, or **@ mention** the file in Chat/Composer so the model loads it.
 
@@ -56,6 +59,24 @@ Project rules are **`.cursor/rules/*.mdc`**. They use YAML frontmatter:
 | Stack, structure, APIs | `tech-stack`, `project-structure`, `api-conventions` |
 | Data & naming | `naming-conventions`, `database` |
 | Ops & quality | `security`, `monitoring`, `testing`, `git-workflow`, `system-design` |
+| Code intelligence | `codegraph` (MCP usage; see below) |
+
+---
+
+## Code intelligence (CodeGraph)
+
+This project includes **[CodeGraph](https://github.com/colbymchenry/codegraph)** for local, structural code search via MCP.
+
+| Item | Location |
+|------|----------|
+| MCP server config | `.cursor/mcp.json` |
+| Usage rules | `.cursor/rules/codegraph.mdc` |
+| Symbol index (generated) | `.codegraph/` (gitignored) |
+| Setup reference | `.cursor/references/codegraph.md` |
+
+After installing scaffolding, **reload the Cursor window** (or restart Cursor) so the CodeGraph MCP server connects. Use `codegraph_*` tools for structural questions (callers, callees, traces, impact); use grep/read for literal text in comments or strings.
+
+If the index is missing, run `npx @colbymchenry/codegraph init -i` in the project root.
 
 ---
 
@@ -82,6 +103,9 @@ Reusable playbooks: **`.cursor/skills/*/SKILL.md`** (and related `.md` files whe
 | `incremental-implementation` | Vertical slices |
 | `deploy` | Deployment pipeline |
 | `security-review` | Security audit |
+| `agent-continuity` | Cross-tool session handoff via `.agent/SESSION.md` |
+| `supabase` | Supabase products, Auth, CLI, MCP, migrations, RLS |
+| `supabase-postgres-best-practices` | Postgres performance, indexes, RLS tuning |
 
 ---
 
@@ -95,18 +119,29 @@ Reusable playbooks: **`.cursor/skills/*/SKILL.md`** (and related `.md` files whe
 | `testing-patterns.md` | Test structure |
 | `performance-checklist.md` | Performance |
 | `accessibility-checklist.md` | WCAG-oriented checks |
+| `codegraph.md` | CodeGraph install and Claude Code setup |
+| `agent-continuity.md` | Session handoff and `/resume` / `/handoff` |
+| `supabase.md` | Supabase skills, MCP OAuth, secrets |
 
 ---
 
 ## Config parity
 
-**`.cursor/settings.json`** lists directories (mirrors `.claude/settings.json` for Claude Code). Cursor natively loads **`.cursor/rules/*.mdc`**; other paths are documentation for humans and for `@` includes.
+**`.cursor/settings.json`** lists directories (mirrors `.claude/settings.json` for Claude Code). Cursor natively loads **`.cursor/rules/*.mdc`** and **`.cursor/mcp.json`** for MCP servers; other paths are documentation for humans and for `@` includes.
+
+---
+
+## Agent continuity
+
+Cross-tool handoff lives in **`.agent/SESSION.md`** (committed). Use **`/resume`** at session start and **`/handoff`** at session end when switching chats or tools (Cursor, Claude Code, Kiro). See **`.cursor/references/agent-continuity.md`** and **`.cursor/rules/agent-continuity.mdc`**.
 
 ---
 
 ## Agent behavior
 
 1. Follow the workflow and use the command prompts when starting a phase.
-2. Apply **`.cursor/rules/`**; treat **`security.mdc`** as non-negotiable.
-3. Prefer tests first and small, buildable changes.
-4. **@ mention** the right **`.cursor/agents/`** file when the task matches that role.
+2. If **`.agent/SESSION.md`** exists, read it before planning or coding; run **`/resume`** when continuing prior work.
+3. Apply **`.cursor/rules/`**; treat **`security.mdc`** as non-negotiable.
+4. Prefer tests first and small, buildable changes.
+5. **@ mention** the right **`.cursor/agents/`** file when the task matches that role.
+6. Update **`.agent/SESSION.md`** (or **`/handoff`**) before ending a session.

package/.cursor/commands/build.md

@@ -23,9 +23,10 @@ Implement tasks one at a time using Test-Driven Development. Each increment leav
 #### Step 1: Load Context
 
 ```
-1. Read the task's acceptance criteria
-2. Identify relevant existing code and patterns
-3. Understand types and interfaces involved
+1. Read `.agent/SESSION.md` if present (or run `/resume` at session start)
+2. Read the task's acceptance criteria from `tasks/todo.md`
+3. Identify relevant existing code and patterns
+4. Understand types and interfaces involved
 ```
 
 #### Step 2: RED — Write Failing Test
@@ -86,7 +87,7 @@ git commit -m "feat(tasks): add createTask function"
 
 #### Step 6: Mark Complete
 
-Update `tasks/todo.md`:
+Update `tasks/todo.md` and `.agent/SESSION.md` (**Done**, **In progress**, **Next**):
 ```markdown
 - [x] Task 1.1: Create task endpoint
 ```

package/.cursor/commands/debug.md

@@ -20,7 +20,7 @@ When unexpected failures occur:
 3. **DIAGNOSE** — Follow the 6-step triage process
 4. **FIX** — Address root cause, not symptoms
 5. **GUARD** — Add tests to prevent recurrence
-6. **RESUME** — Only continue after verification
+6. **RESUME** — Only continue after verification; update `.agent/SESSION.md` with root cause, guard tests, and **Next**
 
 ---
 
@@ -236,6 +236,7 @@ git bisect reset                  # When done
 - Regression test added
 - All tests passing
 - Clear commit message explaining the fix
+- **`.agent/SESSION.md`** updated (Gotchas, Decisions, **Next**)
 
 ## Next Step
 

package/.cursor/commands/handoff.md

@@ -0,0 +1,94 @@
+---
+name: handoff
+description: End-of-session — update .agent/SESSION.md for the next agent or tool
+---
+
+# /handoff — Session handoff
+
+> "Leave the next agent a map, not a maze."
+
+## Purpose
+
+Capture current work in **`.agent/SESSION.md`** so another chat, persona, or tool (Cursor, Claude Code, Kiro) can continue without re-discovering context.
+
+## When to use
+
+- End of a work session (before closing chat)
+- Switching tools (Cursor → Claude Code → Kiro)
+- Switching persona (e.g. architect → backend)
+- After completing a workflow phase (spec, plan, build, test, review)
+- Before opening a PR (document what reviewers should know)
+
+## Prerequisites
+
+- `.agent/SESSION.md` exists (created by `npx class-ai-agent` or copy from `.agent/SESSION.template.md`)
+- You have context on what was done this session
+
+## Workflow
+
+### Phase 1: Gather state
+
+1. **Review git** — branch name, uncommitted files, last commits
+2. **Review tasks** — open `tasks/todo.md`; sync checkboxes with reality
+3. **Review spec** — note linked `SPEC.md` or `docs/specs/...` path
+4. **Scan decisions** — what did we choose that is not obvious from code alone?
+5. **Scan gotchas** — what failed, env quirks, commands that matter
+
+### Phase 2: Update `.agent/SESSION.md`
+
+Refresh every section (use `.agent/SESSION.template.md` as schema):
+
+| Section | Content |
+|---------|---------|
+| **Meta** | `Updated` (today), `Phase`, `Tool` (cursor/claude/kiro), optional `Persona` |
+| **Goal** | One paragraph — still accurate? |
+| **Done** | Bullets with file paths or commit refs |
+| **In progress** | Current task; **Blockers** (none or describe) |
+| **Next** | Numbered steps for the *next* agent |
+| **Decisions** | Non-obvious choices made this session |
+| **Gotchas** | Failed attempts, test commands, env notes |
+| **Pointers** | Spec path, `tasks/todo.md`, branch, key files |
+
+### Phase 3: Sync `tasks/todo.md`
+
+- Mark completed items `[x]`
+- Add new tasks discovered during work
+- Remove or defer items that are out of scope
+
+### Phase 4: Risk note (if applicable)
+
+If work is **not** safe to pick up blindly, add under **Gotchas** or **In progress**:
+
+- Uncommitted changes and why
+- Failing tests or broken build
+- External blockers (API, review, dependency)
+
+### Phase 5: Optional milestone archive
+
+For major milestones, copy `SESSION.md` to:
+
+```
+.agent/history/YYYY-MM-DD-short-slug.md
+```
+
+Commit both `SESSION.md` and the history file when ready.
+
+## Security
+
+**Never** write to `SESSION.md`:
+
+- API keys, passwords, tokens, credentials
+- PII or customer data
+- Full stack traces with secrets
+
+Use issue links or commit SHAs instead.
+
+## Output
+
+- Updated **`.agent/SESSION.md`**
+- Updated **`tasks/todo.md`** (if it exists)
+- Short summary for the user: phase, next steps, blockers
+
+## Next step
+
+Tell the user to run **`/resume`** in the next session or tool, or commit and share the branch.

package/.cursor/commands/plan.md

@@ -100,6 +100,7 @@ Save to `tasks/` directory:
 
 - `tasks/plan.md` — Full planning document with context
 - `tasks/todo.md` — Actionable task checklist
+- **`.agent/SESSION.md`** — Update Meta `phase` to `build`, **Pointers** → `tasks/todo.md` and spec path, **Next** → first `/build` task
 
 ```markdown
 # TODO: [Feature Name]