Stop colliding before you start.

preflight-lane

We've been building in your codebase, and we kept seeing the same thing: with a lot of agents committing fast, they quietly step on each other. Same migration version, same files, same fix, twice. So we read across the whole repo to see how it actually happens, and built a small skill that does the 30 seconds of bookkeeping that catches it up front. Read-only, git + gh only. Copy it, paste it to your agent, and it runs before the next PR.

What we found (the honest read)

⚠

A single migration version claimed by two different files. Supabase keys on that 14-digit version, so only one can ever apply. One had to be quietly retimestamped off it to survive. PR #3853

↻

6 retimestamp fixes in 13 days, plus an 11-deep stack on one minute-base. The version numbers are hand-picked, so collisions are constant and manual.

The migration linter only sees one branch at a time, so two branches picking the same version both pass, and collide only at merge. There's no CODEOWNERS and no branch protection to catch it either. verified live

◫

app.module.ts is a conflict magnet: 100+ commits, 6+ hands, and an afternoon of feat then revert then reship when two module registrations raced.

⇉

Two lanes worked the same KPI-hierarchy area in parallel and only converged because someone happened to notice. #3940 / #4065

What it does, every run

A safe migration version deterministic

Reads the versions on main AND every open PR, and hands you the next one that's free across all of it. Closes the gap the single-branch linter can't see. Unique against everything in flight at scan time.

Who's already in your files advisory

Lists the open PRs and recent merges touching your files or subsystem, so you see a neighbor before you collide or duplicate. A heads-up, not a blocker. Always flags app.module.ts.

An enforced backstop

A ~30-line CI check that rejects any PR whose migration version is already taken across main and open PRs. Zero adoption needed, and it closes the one gap the scan can't: two agents racing in the same few seconds.

Try it, no setup

Paste this to your agent runs before your next PR

Run this before you start a work unit in this repo. It is read-only bookkeeping, do it first, then paste the result into your PR.

1) MIGRATION VERSION (only if you are adding a Supabase migration)
Use a version that is free across main AND every open PR, then take the next one up in the same timestamp style the touched files already use. Do not hand-pick a version.
  git fetch origin main -q
  # highest version already on main:
  git ls-tree -r --name-only origin/main supabase/migrations | grep -oE '[0-9]{14}' | sort | tail -1
  # highest version across all open PRs:
  for b in $(gh pr list --state open -L 100 --json headRefName -q '.[].headRefName'); do gh pr diff "$b" --name-only 2>/dev/null; done | grep 'supabase/migrations/' | grep -oE '[0-9]{14}' | sort | tail -1
  # use max(of those two) + 1

2) IN-FLIGHT OVERLAP (always)
See who else is in your files or subsystem before you start.
  gh pr list --state open -L 100 --json number,author,title,headRefName
  # for any PR near your area: gh pr diff  --name-only
  gh pr list --state merged -L 40 --json number,author,title,mergedAt
If someone else is touching your files or subsystem, coordinate before you duplicate or collide. Treat apps/backend/src/app.module.ts as a conflict magnet: append your registration to the current tail, do not merge-race it.

3) Paste into your PR body: the version you allocated, and who else is in-flight in your area. Then start.

The enforced backstop (drop into CI)

Reject a taken migration version ~30 lines, no adoption needed

# Run on every PR. Fails if the PR's new migration version is already taken
# across main + open PRs. Needs: gh (with repo read) on PATH.
set -euo pipefail
BASE=origin/main
git fetch origin main -q
NEW=$(git diff --name-only "$BASE"...HEAD | grep 'supabase/migrations/' | grep -oE '[0-9]{14}' | sort | tail -1 || true)
[ -z "${NEW:-}" ] && { echo "no migration in this PR"; exit 0; }
MAIN_MAX=$(git ls-tree -r --name-only "$BASE" supabase/migrations | grep -oE '[0-9]{14}' | sort | tail -1)
PR_MAX=$(for b in $(gh pr list --state open -L 100 --json headRefName -q '.[].headRefName'); do
           gh pr diff "$b" --name-only 2>/dev/null; done | grep 'supabase/migrations/' | grep -oE '[0-9]{14}' | sort | tail -1 || true)
MAX=$(printf '%s\n%s\n' "$MAIN_MAX" "${PR_MAX:-0}" | sort | tail -1)
if [ ! "$NEW" \> "$MAX" ]; then
  echo "Migration version $NEW is <= max in-flight $MAX. Rebase to a higher version."; exit 1
fi
echo "migration version $NEW is clear (max in-flight $MAX)"

Honest about what it is

✓The version check is deterministic arithmetic. The overlap heads-up is a best-effort heuristic that warns, never blocks. Don't treat the heads-up as a guarantee.
✓A true same-second version race is closed by the CI backstop, not the scan alone. Run both.
✓It reduces collisions and surfaces neighbors. It does not review your code or prove your change is correct. That's a different job.

Give it a try on your next PR. Tweak it to fit how your lane works. If it's not useful, no harm, no foul. If it saves one silent collision, it paid for itself.