Skip to main content
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 installs the package-owned enforcement bundle by default. The raw files also ship under node_modules/supaschema/agent-bundle/ so agents can audit or repair files that init reported as skipped and read the complete public MDX documentation offline.

​
Installed surfaces

The downloadable consumer agent bundle is intentionally narrow. Init installs only these package-owned surfaces and hook registrations; it does not copy maintainer-only tooling or write AGENTS.md / CLAUDE.md.

​
Install and repair

Run supaschema init after package install. It reads the packaged manifest, recursively copies missing Agent and Claude skill files, merges package-manager-specific .claude/settings.json and .codex/hooks.json, preserves and reports existing non-identical files, and reports skipped non-mergeable hook config. It never creates .codex/skills/**. Read node_modules/supaschema/agent-bundle/INSTALL.md when auditing the installed files or repairing skipped surfaces. For offline product documentation, open node_modules/supaschema/agent-bundle/docs/index.md. Its entries are sorted package paths linked to their canonical https://supaschema.com/docs/... URLs. The MDX files are byte-for-byte projections of the hosted-doc sources; images, docs.json, and non-MDX files do not ship, and init does not scaffold the corpus. The default scaffold does not run npx skills; npm package init is the activation path for project enforcement. Supabase projects that already carry a _bootstrap schema inventory or a supabase/AGENTS.md owner brief marking supabase/schemas/** as non-generator inventory still receive supaschema.config.json from the detected Supabase paths. In that profile, workflow.schema_diff and workflow.migration_sync are set to manual, Supabase-managed schemas are added to schemas.exclude, and schema-source readers skip _bootstrap directories. When path ownership is genuinely ambiguous, .supaschema/install.json records detected candidates plus agentInstructions, and zero-source diff / zero-arg check stay blocked until supaschema.config.json names the real schemaPaths and migrationsDir. If the consumer repo has AGENTS.md or CLAUDE.md, those files remain consumer-owned. Point them at .agents/prompts/supaschema-install.md only when the project wants that root routing.

​
npx skills lane

The public npx skills source is intentionally narrower than the npm setup surface. Install the single curated directory:
Do not use the repository root as the Skills source. The Skills CLI scans standard agent skill directories; the public source contains only that one curated directory. The skill mirrors the canonical .claude/skills/supaschema tree, including its references/ workflow guides for setup, migration, maintenance, and diagnostics. It installs Agent Skill context only into the location selected by the Skills CLI. It does not install rule files, hook scripts, hook registration, config, or schema directories. Rules and hooks are included in the package bundle and activated by supaschema init.

​
Hook behavior

The installed hooks are limited to Supaschema schema and migration behavior: The bundle does not publish or register this repository’s general Bash, Git, secret, branch, worktree, or deletion policy. Those guards are maintainer tooling for developing Supaschema itself. 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 exactly one selected sync.targets entry is mode: "auto", its database URL reference resolves when its runner needs one, and any remote target has its configured approval variable set. Only then does it call supaschema sync, which owns the ordered source, diff, target-selection, history, check, generated-contract, schema-closure staging, source safety, runner, and reconciliation workflow. 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.

​
Repo-local tooling

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 July 28, 2026