Problem context
Your repo already writes events into Supabase. Inserts and upserts are scattered across the source tree.
Coding agents (Cursor, Claude Code) are now writing meaningful chunks of new code in the same repo.
You want PRs that touch event-writing files to get checked automatically.
What breaks if this is not solved
- An agent rewrites a function and the `supabase.from('events').insert` inside it disappears.
- An agent renames a column in a payload and the table column it filled stops getting set.
- A property gets dropped from a payload and a breakdown over that column returns empty.
When this playbook applies
- Your repo writes events through `supabase-js` (browser or server), server-side inserts, or Postgres functions.
- You have at least one dashboard or query over your Supabase event tables you actually trust today.
- You can install a CLI and add a GitHub Action to your repo.
System approach
Run the audit before the CI integration. You want a clean baseline before PRs start getting checked against it.
Get the MCP path working in your own editor first. Future contributors can opt in to MCP over time; the GitHub Action is the universal guard.
Treat the Skene manifest like a lockfile: commit it, review changes to it on every merge, never silently regenerate.
Execution steps
- Install the CLI: `npm install -g @skene/cli`.
- Run `npx @skene/cli audit` and inspect `skene-manifest.json`. Confirm every event write you expect is present.
- Resolve discrepancies (events you thought existed but do not; events you did not know about).
- Commit `skene-manifest.json` to the repo.
- Install the MCP into your coding agent. For Cursor: add `{ "mcpServers": { "skene": { "command": "skene-mcp" } } }` to `~/.cursor/mcp.json`.
- Add the GitHub Action to `.github/workflows/skene.yml` (see the install docs for the snippet). Set the `SKENE_API_KEY` secret.
- Open a test PR that intentionally drops an event insert. Confirm Skene posts a comment naming the file, line, and event.
- Communicate to the team: which events are tracked, what intent acceptance looks like, who owns the manifest.
Metrics to watch
PRs with Skene findings, per week
Expect 1-3 per active week. Zero means Skene is not running; double-digit means something upstream is generating noise.
Findings marked accepted vs. fixed
Roughly even is healthy. If everything is accepted, the validation is not catching real bugs.
Failure modes
- Skipping the audit and turning on the Action first - the first PR will be drowned in noise from already-drifted state.
- Adding the manifest to .gitignore. It needs to live in the repo so PRs can diff against it.
- Treating every Skene finding as a real bug. Many will be intentional changes; the workflow has to allow accepting them.
