RLS-on-every-table
Flags any migration that touches a table without a corresponding RLS policy. The most common Supabase production disaster, by a large margin.
Triggers on supabase/migrations/*.sql and migrations/*.sql
Features · Guardrails
Guardrails
Rules and hooks that prevent the named Next.js + Supabase disasters. Rules are markdown read by Claude when matching files are touched. Hooks are deterministic shell commands run by Claude Code on tool-use events.
The five rules
Stack-specific. Named after what they block.
Service-role key scan
Blocks staged diffs that contain known credential shapes — Supabase service role JWT, Stripe live key, AWS access ID. Stops the commit and names the file and line.
Triggers on Pre-commit hook on every git commit
Auth.js session revalidation
Flags Server Actions that read a session without revalidatePath or revalidateTag after a write. Stale session data after a mutation is a silent bug.
Triggers on app/**/actions.ts
Server Action return-type guard
Blocks Server Actions that return non-serializable values — functions, class instances, Date objects without .toISOString(). These fail at runtime with cryptic messages.
Triggers on app/**/actions.ts
OAuth callback list audit
Flags hardcoded localhost:3000 redirect URIs in OAuth provider configs. Ships to production, breaks on the first login.
Triggers on lib/auth.ts and app/api/auth/**
Rule pattern catalog
Six pattern types. Write your own using any of them.
Rules in .claude/rules/ follow a small set of patterns. The kit ships one or more of each type; you can add more by dropping a new markdown file in the same directory.
Config-file rule
e.g. globs: package.json — flag dependency additions
Pipeline-contract rule
e.g. fingerprint table writes must include created_at
DB-access rule
e.g. any new query must use the project's connection helper
AI-prompt rule
e.g. any prompt change requires a regression test
Schema-registry rule
e.g. new event types must be added to the registry
Self-maintenance rule
e.g. CLAUDE.md edits must update the version footer
The hooks
Deterministic shell. Not LLM-driven.
Hooks run before or after specific Claude Code tool calls. They execute a shell command directly — no model involved. Fast and reliable.
PreToolUse: Bash
Deterministic shell check before every Bash tool call
Blocks git push --force on protected branches, rm -rf on tracked directories, DROP TABLE outside of migration files.
SessionStart
Shell script on session open
Echoes git status headline plus open-issues count. Claude opens with current state rather than assuming a clean tree.
PostToolUse: Edit/Write
Shell script after every file write
Reminds Claude to run tests before marking a task done. Prevents the silent skip from edit straight to commit.
All 12 hook events
Every event Claude Code exposes.
PreToolUse
Before a tool call
Block dangerous commands before they execute.
PostToolUse
After a successful tool call
Run tests after a file write. Log the action.
PostToolUseFailure
After a tool call that failed
Surface a cleaner error message than Claude Code's default.
SessionStart
When a session opens
Echo git status, open-issues count, active task name.
Stop
When Claude finishes a response
Save session state before context compresses.
SubagentStart
When a subagent is invoked
Log which agent was dispatched and why.
SubagentStop
When a subagent completes
Record the subagent's verdict in the audit log.
FileChanged
When a file on disk changes
Detect unexpected out-of-band writes.
PreCompact
Before context compression
Save current task status so the compressed session doesn't lose it.
PostCompact
After context compression
Reload saved state so the session continues coherently.
WorktreeCreate
When a new git worktree is created
Copy .env and local config into the new worktree.
WorktreeRemove
When a worktree is cleaned up
Log what the worktree agent produced or discarded.
Hook handler types
Four ways to respond to an event.
command
A shell command. Exit code is interpreted: 0 passes, 2 blocks and surfaces stderr, any other non-zero is a warning. The most common handler type.
prompt
Injects text into Claude's context. Use when you need Claude to see a message rather than have the action blocked.
agent
Invokes a subagent. The subagent receives the hook context and can act on it — read files, write a log entry, send a report.
http
POSTs to a URL. The response is interpreted. Use for integrations with external systems — Slack alerts, webhooks, audit services.
Exit-code semantics
Three outcomes. Only exit 2 blocks.
exit 0Pass. The action proceeds.
exit 2Block. Claude Code halts the action and surfaces stderr to Claude.
Any other non-zeroWarning. The action proceeds, but Claude sees the message.
Destructive-command block
Five categories of commands that exit 2 by default.
Shipped as a PreToolUse hook keyed to Bash tool calls. The hook matches the command string before any shell execution. Exit 2 means Claude Code halts and shows the reason to Claude.
git push --forceOn protected branches
rm -rfOn tracked directories
DROP TABLEOutside migration files
kubectl deleteWithout --dry-run first
Force-push to main / masterAlways
Opt-out
Each rule and hook is individually removable.
Rules live as individual files in .claude/rules/. Delete a file, the rule stops firing. Hooks are listed in .claude/settings.json. Remove a hook entry, it stops running.
The kit does not reinstall on update unless you explicitly ask it to. Your deletions survive kit updates.