Sync Convex Auth

Sync Convex Auth

Handle $ARGUMENTS.

Goal: compare https://github.com/zbeyens/convex-better-auth with its upstream fork, sync that fork to upstream when it can be done without losing fork-only work, extract every upstream change that matters to kitcn, then delegate one coherent implementation slice to $task so it opens the PR.

Goal Template

When this sync needs durable goal state, use the project-owned sync template instead of the generic task template:

node .agents/skills/autogoal/scripts/create-goal-scratchpad.mjs \
  --template sync-convex-auth \
  --title "sync convex auth"

This plan owns the upstream audit, classification ledger, ambiguity decisions, fork-sync result, and delegated task prompt. The delegated implementation still uses task; do not duplicate implementation PR machinery inside the sync plan.

Rules

• Use evidence, not vibes. Read commits, changed files, and patches.
• Treat the fork being behind upstream as signal, not proof. Pull only relevant work into kitcn.
• Syncing the fork is required. Snapshot the pre-sync range first, then update zbeyens/convex-better-auth by fast-forward push or fork PR. Never force push the fork.
• Ignore genuinely irrelevant upstream changes when deciding KitCN work. Do not mirror upstream into KitCN just to feel caught up.
• Pull all clearly relevant, non-conflicting fixes in the same slice when they share the same kitcn auth surface.
• Stop and ask the user before importing optional additions where the tradeoff is unclear, especially slow e2e suites, broad fixture rewrites, examples, release plumbing, or dev-only test infrastructure.
• Prefer deleting kitcn glue over adding more glue when upstream fixed the real problem.
• If no actionable opportunity exists, stop with the evidence. Do not open a vanity PR.

1. Establish Fork, Upstream, And Refs

Use GitHub metadata to discover the upstream parent instead of guessing:

gh repo view zbeyens/convex-better-auth \
  --json nameWithOwner,parent,defaultBranchRef \
  --jq '{fork: .nameWithOwner, parent: .parent.nameWithOwner, branch: .defaultBranchRef.name}'

If parent is missing or ambiguous, stop and ask for the upstream repo.

Before asking, try these fallbacks in order:

npm view @convex-dev/better-auth repository homepage --json
test -d ../convex-better-auth/.git && git -C ../convex-better-auth remote -v
gh repo view get-convex/better-auth --json nameWithOwner,defaultBranchRef,url

If npm metadata or the local clone clearly point to one upstream repo, use that repo and continue instead of stopping.

Use a local clone for navigation, creating it only if missing. Identify the remote that points at the fork and the remote that points at upstream by URL; do not assume origin is the fork:

test -d ../convex-better-auth/.git || \
  gh repo clone zbeyens/convex-better-auth ../convex-better-auth
git -C ../convex-better-auth remote -v
git -C ../convex-better-auth remote get-url <upstream-remote> >/dev/null 2>&1 || \
  git -C ../convex-better-auth remote add <upstream-remote> https://github.com/<upstream-owner>/<repo-name>.git
git -C ../convex-better-auth fetch <fork-remote> --tags
git -C ../convex-better-auth fetch <upstream-remote> --tags

Record:

• fork owner/name and default branch
• upstream owner/name and default branch
• fork remote name and upstream remote name
• fork ref and upstream ref being compared
• behind count
• ahead count, if any
• exact commit range

Commands:

git -C ../convex-better-auth rev-list --count <fork-remote>/<fork-branch>..<upstream-remote>/<upstream-branch>
git -C ../convex-better-auth rev-list --count <upstream-remote>/<upstream-branch>..<fork-remote>/<fork-branch>
git -C ../convex-better-auth log --oneline --decorate <fork-remote>/<fork-branch>..<upstream-remote>/<upstream-branch>

If $ARGUMENTS names a base or target ref, use it as the bound after proving it exists.

2. Sync The Fork

The sync audit must update zbeyens/convex-better-auth itself, not only KitCN. Do this after recording the pre-sync range above, so the KitCN audit still knows which upstream commits were imported.

If the fork is already at the upstream ref, record fork sync: already synced.

If the fork is behind and not ahead, fast-forward the fork default branch to the upstream ref and push:

git -C ../convex-better-auth merge-base --is-ancestor \
  <fork-remote>/<fork-branch> <upstream-remote>/<upstream-branch>
git -C ../convex-better-auth push <fork-remote> \
  refs/remotes/<upstream-remote>/<upstream-branch>:refs/heads/<fork-branch>
git -C ../convex-better-auth fetch <fork-remote> --tags
git -C ../convex-better-auth rev-parse <fork-remote>/<fork-branch>

If the fast-forward push is rejected because the fork default branch is protected or direct push is not allowed, open a PR in the fork instead:

git -C ../convex-better-auth switch -C sync-upstream-<date> \
  <upstream-remote>/<upstream-branch>
git -C ../convex-better-auth push <fork-remote> \
  HEAD:refs/heads/sync-upstream-<date>
gh pr create \
  --repo zbeyens/convex-better-auth \
  --base <fork-branch> \
  --head zbeyens:sync-upstream-<date> \
  --title "Sync upstream convex-better-auth" \
  --body "Fast-forward fork to <upstream-owner>/<repo-name>@<upstream-ref>."

If the fork is ahead of upstream or has diverged, stop and ask before merging, rebasing, or overwriting anything. Do not force push. Record:

• fork sync status: already synced, fast-forward pushed, fork PR opened, blocked: diverged, or blocked: push rejected
• post-sync fork ref or PR URL
• whether KitCN audit continues from the pre-sync range

3. Read The Upstream Diff

Start with a file summary:

git -C ../convex-better-auth diff --name-status \
  <pre-sync-fork-ref>..<pre-sync-upstream-ref>

Then read patches for relevant-looking files:

git -C ../convex-better-auth diff \
  <pre-sync-fork-ref>..<pre-sync-upstream-ref> -- \
  src package.json bun.lock tsconfig.json '*.md' \
  ':!**/dist/**' ':!**/build/**' ':!**/node_modules/**'

Use gh compare when it gives cleaner commit/file metadata:

gh api \
  repos/<upstream-owner>/<repo-name>/compare/<fork-owner>:<fork-branch>...<upstream-branch> \
  --jq '.commits[] | {sha: .sha, message: .commit.message}'

gh api \
  repos/<upstream-owner>/<repo-name>/compare/<fork-owner>:<fork-branch>...<upstream-branch> \
  --jq '.files[] | {filename,status,patch}'

If the compare is too large, group by subsystem first, then inspect the patches for likely auth-runtime impact.

4. Search Kitcn For Affected Auth Surfaces

Search local kitcn integration points:

rg -n "@convex-dev/better-auth|convexBetterAuth|getToken|convexClient|convex\\(|BetterAuth|better-auth|auth" \
  packages www .agents docs tooling fixtures example

Search institutional notes before proposing work:

rg -i --files-with-matches \
  "convex-better-auth|@convex-dev/better-auth|better-auth|auth|react-start|nextjs|jwt|jwks|session|cookie|schema|plugin|getToken" \
  docs/solutions docs/plans

Read relevant hits, especially notes about:

• @convex-dev/better-auth reexports and wrappers
• kitcn/auth, kitcn/auth-client, kitcn/auth-nextjs, and kitcn/auth-start
• Better Auth and Convex version compatibility
• token, JWT, JWKS, cookie, and session handling
• schema generation, plugin reconciliation, and generated auth contracts
• React, Solid, Next.js, and TanStack Start provider behavior
• scaffold templates, docs, and packages/kitcn/skills/kitcn/**
• local hacks that might be obsolete after upstream changes