The agent bundle gives coding agents the same migration workflow that humans use: edit declarative SQL, generate with diff, check replay safety, and never hand-edit generated migration files.
supaschema init does not install this bundle by default. The raw files ship under node_modules/supaschema/agent-bundle/ for review and opt-in installation.
Raw surfaces
The downloadable consumer agent bundle is intentionally narrow and inactive until installed on demand.
| Surface | Files |
|---|
| Shared install prompt | agent-bundle/agents/prompts/supaschema-install.md |
| Shared skill | agent-bundle/agents/skills/supaschema |
| Claude skill and rule | agent-bundle/claude/skills/supaschema, agent-bundle/claude/rules/supaschema.md |
| Claude hooks and settings | agent-bundle/claude/settings.<manager>.json, agent-bundle/claude/hooks/guards/bash-policy-checks.mjs, agent-bundle/claude/hooks/sync-llm-on-claude-surface-change.mjs |
| Codex rule mirror | agent-bundle/codex/rules/supaschema.rules |
| Codex hooks and settings | agent-bundle/codex/hooks.<manager>.json, agent-bundle/codex/hooks/general-guard.mjs, agent-bundle/codex/hooks/guards/bash-policy-checks.mjs, agent-bundle/codex/hooks/sync-llm-on-claude-surface-change.mjs |
Install on demand
Read node_modules/supaschema/agent-bundle/INSTALL.md before installing the bundle. Install only when the user asks for AI-agent enforcement or approves the bundle:
supaschema init --agent-bundle
PreToolUse or PostToolUse through .codex/hooks/tool-gate.mjs, or Stop through .codex/hooks/stop.mjs, the installer keeps the dispatcher and removes package-owned direct hooks for that event instead of duplicating them.
The default scaffold does not run npx skills and does not copy the packaged supaschema skill directories into active consumer paths.
Supabase projects that already carry a _bootstrap schema inventory or a supabase/AGENTS.md owner brief marking supabase/schemas/** as non-generator inventory are left in path-confirmation state. In that state .supaschema/install.json records the detected candidates and zero-source diff / zero-arg check stay blocked until supaschema.config.json names the real generator-owned schemaPaths, sources.to, and migrationsDir.
When the bundle is installed on demand, the managed AGENTS.md addendum points agents to .agents/prompts/supaschema-install.md before setup or schema work. CLAUDE.md stays a pointer-style entrypoint (@AGENTS.md) when the consumer uses AGENTS.md as the canonical brief.
npx skills lane
The public npx skills source is intentionally narrower than the npm setup surface:
npx skills add https://github.com/jmclaughlin724/supaschema/tree/main/skills/supaschema
skills/supaschema.
That source mirrors .claude/skills/supaschema/SKILL.md into skills/supaschema/SKILL.md. It installs Agent Skill context only into the location selected by the Skills CLI. It does not install passive rule files, hook scripts, hook registration, config, or schema directories.
Rules and hooks are included only in the raw package bundle unless supaschema init --agent-bundle or a manual reviewed install copies them into active consumer paths.
Hook behavior
The installed hooks enforce supaschema migration policy and a small Bash safety policy:
| Hook | Event | Purpose |
|---|
supaschema hook generated-migration-edit | PreToolUse | Blocks edits to generated migration SQL when the lineage marker is present. |
bash-policy-checks.mjs / general-guard.mjs | PreToolUse for Bash | Blocks secret argv and secret env-file reads, raw SQL DDL through Bash, destructive git shortcuts, and rm -rf equivalents. Plain recursive rm -r is not blocked by this generic policy. |
supaschema hook schema-write | PostToolUse | Watches schema-tree SQL writes. By default it runs supaschema diff then checks the generated migration files; when config enables automatic sync and every selected target is resolved and approved, it delegates to supaschema sync. |
sync-llm-on-claude-surface-change.mjs | Claude PostToolBatch, Codex Stop | Keeps the installed .agents skill and Codex rule/hook mirrors aligned when the consumer edits the shipped .claude supaschema rule or skill. |
supaschema hook schema-write triggers the default migration workflow after configured schema files are edited. It writes the migration when workflow.schema_diff is "on_schema_write" and runs the replay-safety check on those generated migration paths when workflow.migration_check is "after_schema_diff". If workflow.migration_sync allows automatic sync, the hook first confirms the selected sync.targets are mode: "auto", database URL references resolve, and any remote target has its configured approval variable set. Only then does it call supaschema sync, which owns diff, generated outputs, type/RLS safety gates, apply, and target history reconciliation.
If config or approval does not permit automatic sync, the hook stays on the non-mutating diff/check lane. If check or sync fails, the hook emits continuation feedback so Claude or Codex investigates the root source, searches for correlated migration failures, fixes the canonical owner, and reruns the failing command.
Maintainer Claude/Codex optimization infrastructure is not part of the public repository, npm package, or install scaffold by default.
Keep these private unless the consumer contract explicitly changes:
.claude/hooks/context-*.codex/hooks/context-*- optimizer skills
- internal rules
.claude/agents/**.codex/agents/**.codex/config.toml- MCP config
- advisor plans
- operator services
If one of these surfaces becomes part of the consumer contract, update the package allowlist, scaffold, package tests, and Package Boundary in the same change. Last modified on June 19, 2026
