From 7df745420b8178df0101a35b75f1af07fea2d558 Mon Sep 17 00:00:00 2001 From: BigSimmo <87357024+BigSimmo@users.noreply.github.com> Date: Mon, 13 Jul 2026 22:24:33 +0800 Subject: [PATCH 1/2] feat(dx): repo-local session skills (newtask, handoff, prlanded) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Wave 3a. Establishes the .claude/skills/ convention for this repo, encoding the session rituals that are currently prose in AGENTS.md / memory: - newtask: fresh worktree off latest origin/main + npm ci + base-freshness check + route warm — kills the stale-base, cold-worktree, and reserved-port traps. - handoff: safe commit → verify:pr-local → push → PR → ledger, with the protected- branch / provider confirmations spelled out. - prlanded: post-merge content-diff verification (squash rewrites ancestry), the orphaned-late-commit check for the auto-merge race, and ledger/memory update. Markdown only — no runtime surface. Prettier-clean (.claude/ is format-checked). Co-Authored-By: Claude Fable 5 --- .claude/skills/handoff/SKILL.md | 44 ++++++++++++++++++++++++++++++++ .claude/skills/newtask/SKILL.md | 38 +++++++++++++++++++++++++++ .claude/skills/prlanded/SKILL.md | 36 ++++++++++++++++++++++++++ 3 files changed, 118 insertions(+) create mode 100644 .claude/skills/handoff/SKILL.md create mode 100644 .claude/skills/newtask/SKILL.md create mode 100644 .claude/skills/prlanded/SKILL.md diff --git a/.claude/skills/handoff/SKILL.md b/.claude/skills/handoff/SKILL.md new file mode 100644 index 000000000..8ddd5a6b3 --- /dev/null +++ b/.claude/skills/handoff/SKILL.md @@ -0,0 +1,44 @@ +--- +name: handoff +description: Safely commit, verify, and push completed work on a feature branch in this repo, then open a PR and record the review in the ledger. Use when work is finished and you want to hand it off — it runs the repo's verification gate, preserves unrelated work, and never touches protected branches without the required confirmation. +--- + +# handoff — commit, verify, push, PR + +Encodes this repo's safe Git handoff. The goal is to leave completed work committed and +pushed on a `claude/*` feature branch with a PR; NOT to merge into a protected branch, +force-push, or discard work. + +## Preconditions + +- You are on a `claude/*` (or other non-protected) feature branch, not `main`/`master`/ + `develop`/`release/*`. If on a protected branch, create a feature branch first. +- Only your own paths are staged (this worktree may hold other sessions' WIP). + +## Steps + +1. **Inspect first (read-only):** `git status --short --branch`, `git diff`, and the + ahead/behind from `node scripts/check-base-freshness.mjs`. +2. **Stage coherent, completed changes only.** Stage explicit paths — never `git add -A` + blindly. Do not stage `.env*`, secrets, build output, logs, or unrelated WIP; if you + see a possible secret, report the path (never the value) and stop. +3. **Verify** with the smallest sufficient gate: + - Default: `npm run verify:pr-local` (format + cheap gate, plus build/RAG when the + scope needs them). + - Touched UI/routing/styling: add `npm run verify:ui`. + - Touched Supabase env/config: `npm run check:supabase-project` (provider — confirm first). + Do not claim a gate passed unless it actually ran. +4. **Commit** with a clear message. End the message with: + `Co-Authored-By: Claude Fable 5 `. +5. **Push** the feature branch: `git push -u origin `. The pre-push guards run + (auto-merge sentinel, format, drift) — heed a block rather than overriding blindly. +6. **Open a PR** with `gh pr create --base main`, body ending with the Claude Code + attribution line. Enabling squash-auto-merge (`gh pr merge --squash --auto`) is the + repo norm; the PR lands on green. +7. **Record** the review in `docs/branch-review-ledger.md` (Date | Branch/ref | Reviewed + HEAD | Scope | Outcome | Checks). + +## Requires explicit confirmation (do not do automatically) + +Merging into a protected branch, force-push, rebasing a shared branch, deleting/renaming +branches, `git reset --hard`, `git clean -fd`, or any provider-touching verification. diff --git a/.claude/skills/newtask/SKILL.md b/.claude/skills/newtask/SKILL.md new file mode 100644 index 000000000..c5f81958a --- /dev/null +++ b/.claude/skills/newtask/SKILL.md @@ -0,0 +1,38 @@ +--- +name: newtask +description: Bootstrap a clean session for new work in this repo — create a fresh git worktree off the latest origin/main, install deps, warm routes, and confirm the base is current. Use at the start of a task when you want an isolated, up-to-date working copy and want to avoid the stale-base, cold-worktree, and reserved-port traps this repo is prone to. +--- + +# newtask — start a clean, current working copy + +This repo moves fast (`claude/*` branches auto-merge on green) and shares ~40 worktrees +and one stash stack, so starting work on a stale base or a cold worktree is the default +failure. This skill sets up an isolated, current worktree so new work starts clean. + +## Steps + +1. **Sync main.** `git fetch --quiet origin main`. +2. **Create an isolated worktree** off the latest main (never reuse another session's + checkout, and never switch the main checkout's branch): + ```bash + git worktree add -b claude/ ../wt- origin/main + ``` + Use a short, descriptive ``. +3. **Install deps in the new worktree** (worktrees do NOT share `node_modules`; a cold + worktree fails `vitest`/`tsc`). `npm ci` keeps the lockfile untouched: + ```bash + cd ../wt- && npm ci --no-audit --no-fund + ``` + `postinstall` installs the pre-push guards automatically. +4. **Confirm the base is current:** `node scripts/check-base-freshness.mjs` — expect + `behind 0`. If it reports behind, the fetch/worktree base is stale; recreate. +5. **Warm routes before any browser/UI work** (fresh worktrees can hash onto a + Next-reserved port and 404 all routes until warmed): `npm run ensure`, then hit + `/` and `/applications` once. + +## Notes + +- Never `git stash` here — the stash stack is global across all worktrees. Use a + throwaway worktree or a patch file instead. +- Do the work on the `claude/` branch; commit only your own paths. +- When done, hand off with the `handoff` skill. diff --git a/.claude/skills/prlanded/SKILL.md b/.claude/skills/prlanded/SKILL.md new file mode 100644 index 000000000..55c48c70c --- /dev/null +++ b/.claude/skills/prlanded/SKILL.md @@ -0,0 +1,36 @@ +--- +name: prlanded +description: Verify a merged PR actually landed correctly in this repo and clean up after it. Use right after a PR merges (especially squash + auto-merge) to confirm the squashed commit matches your branch by content, catch late commits that were orphaned by the auto-merge race, and update the ledger and memory. +--- + +# prlanded — confirm a merge landed and tidy up + +This repo squash-merges and auto-merges `claude/*` on green, which has twice orphaned a +late follow-up commit and once needed a fix-forward. Run this after a merge to confirm the +work actually landed and to clean up. + +## Steps + +1. **Confirm the merge:** `gh pr view --json state,mergeCommit,mergedAt` → `MERGED`. +2. **Verify by content, not ancestry** (squash rewrites history, so `git branch --merged` + is misleading). Diff your branch tip against merged `main`: + ```bash + git fetch --quiet origin main + git diff --stat origin/main... + ``` + An empty diff means everything landed. Any remaining lines are work that did NOT make + it — the classic auto-merge race. Investigate before deleting the branch. +3. **Check for orphaned late commits:** if you pushed after enabling auto-merge, confirm + those commits are in the squashed result (search the merge commit / `git log origin/main` + for their content). If missing, fix-forward with a new PR — do not force-push. +4. **Clean up the branch** only once the content diff is empty: the PR's + `--delete-branch` handles the remote; prune locally with `git worktree remove` + + `git branch -d ` (never `-D`/force unless you have confirmed it is fully landed). +5. **Update the ledger** (`docs/branch-review-ledger.md`) and any relevant memory note with + the merged HEAD SHA and outcome. + +## Notes + +- Do not re-review a branch/HEAD already recorded in the ledger for the same scope. +- If the content diff is non-empty and you are unsure why, stop and report rather than + deleting anything. From 269aa543e732bbe3b83837712247b562e3e34dc8 Mon Sep 17 00:00:00 2001 From: "coderabbitai[bot]" <136622811+coderabbitai[bot]@users.noreply.github.com> Date: Mon, 13 Jul 2026 15:21:15 +0000 Subject: [PATCH 2/2] fix: apply CodeRabbit auto-fixes Fixed 3 file(s) based on 3 unresolved review comments. Co-authored-by: CodeRabbit --- .claude/skills/handoff/SKILL.md | 13 ++++++++----- .claude/skills/prlanded/SKILL.md | 10 ++++++++-- 2 files changed, 16 insertions(+), 7 deletions(-) diff --git a/.claude/skills/handoff/SKILL.md b/.claude/skills/handoff/SKILL.md index 8ddd5a6b3..534895776 100644 --- a/.claude/skills/handoff/SKILL.md +++ b/.claude/skills/handoff/SKILL.md @@ -17,8 +17,10 @@ force-push, or discard work. ## Steps -1. **Inspect first (read-only):** `git status --short --branch`, `git diff`, and the - ahead/behind from `node scripts/check-base-freshness.mjs`. +1. **Inspect first (read-only):** `git status --short --branch`, `git diff`, `git diff --cached`, + and the ahead/behind from `node scripts/check-base-freshness.mjs`. If staged paths are found + that aren't part of the current session's own work (leftover from other sessions' WIP), + unstage them with `git restore --staged ` before proceeding. 2. **Stage coherent, completed changes only.** Stage explicit paths — never `git add -A` blindly. Do not stage `.env*`, secrets, build output, logs, or unrelated WIP; if you see a possible secret, report the path (never the value) and stop. @@ -34,11 +36,12 @@ force-push, or discard work. (auto-merge sentinel, format, drift) — heed a block rather than overriding blindly. 6. **Open a PR** with `gh pr create --base main`, body ending with the Claude Code attribution line. Enabling squash-auto-merge (`gh pr merge --squash --auto`) is the - repo norm; the PR lands on green. + repo norm but requires explicit user confirmation before enabling; the PR lands on green. 7. **Record** the review in `docs/branch-review-ledger.md` (Date | Branch/ref | Reviewed HEAD | Scope | Outcome | Checks). ## Requires explicit confirmation (do not do automatically) -Merging into a protected branch, force-push, rebasing a shared branch, deleting/renaming -branches, `git reset --hard`, `git clean -fd`, or any provider-touching verification. +Merging into a protected branch, enabling auto-merge (`gh pr merge --squash --auto`), +force-push, rebasing a shared branch, deleting/renaming branches, `git reset --hard`, +`git clean -fd`, or any provider-touching verification. diff --git a/.claude/skills/prlanded/SKILL.md b/.claude/skills/prlanded/SKILL.md index 55c48c70c..7e3464b35 100644 --- a/.claude/skills/prlanded/SKILL.md +++ b/.claude/skills/prlanded/SKILL.md @@ -11,6 +11,9 @@ work actually landed and to clean up. ## Steps +Note: Step 1 is a read-only, non-mutating query exempt from the explicit-confirmation +requirement that applies to mutating provider operations (merging, closing PRs, etc.). + 1. **Confirm the merge:** `gh pr view --json state,mergeCommit,mergedAt` → `MERGED`. 2. **Verify by content, not ancestry** (squash rewrites history, so `git branch --merged` is misleading). Diff your branch tip against merged `main`: @@ -24,8 +27,11 @@ work actually landed and to clean up. those commits are in the squashed result (search the merge commit / `git log origin/main` for their content). If missing, fix-forward with a new PR — do not force-push. 4. **Clean up the branch** only once the content diff is empty: the PR's - `--delete-branch` handles the remote; prune locally with `git worktree remove` + - `git branch -d ` (never `-D`/force unless you have confirmed it is fully landed). + `--delete-branch` handles the remote; prune locally by running `git worktree remove ` + from a different worktree (not the one being removed), then use `git branch -D ` + only after confirming the content diff is empty. For squash-merged branches, `-d` will + refuse (no ancestry merge) even though the content landed, so `-D` is required once + the empty diff confirms the work is fully landed. Do not force-delete before verification. 5. **Update the ledger** (`docs/branch-review-ledger.md`) and any relevant memory note with the merged HEAD SHA and outcome.