Git Wrapup

When to use

Working-tree or staged changes are ready to ship as a new version. This skill lands them as a stack of logical commits — the work grouped by concern, topped by a release commit (version + changelog + tree). It does NOT tag, push to main, or publish — release-and-publish does all three.

Common triggers:

• Feature work, bug fixes, or dependency updates are done and tested
• A maintenance or polish pass left changes in the working tree
• An orchestrator says "wrapup this project"

Release PR mode

A project can route every release through a pull request — one PR per version, for the audit trail and a stable review target. The mode is declared in the project's CLAUDE.md/AGENTS.md or in the caller's brief; when neither says anything, there is no release PR and the stack lands on main directly.

The branch is created at wrapup time, never before — its name carries the version, so it cannot exist until step 2 has settled one. The moment that number is known, the uncommitted tree moves to release/<version> (end of step 2), and every commit in the run lands there. No commit in these two modes ever reaches main, including the first one: a stack committed on main and then branched is a rewrite to undo, and once it is pushed there is no undo, because force-push is banned. The commit stack, the release commit, and the tag format are identical in every mode — the PR adds an artifact around them, it does not change them.

Pre-wrapup gate checklist

Every item must be true before starting wrapup. Committing means releasing — a commit only happens when the work is ready to ship, not just "the edits are done." Each item is a goal to verify.

• Changes exist — uncommitted files or commits since the last tag
• Work is complete — no half-finished features, no "I'll add the test later," no TODO placeholders. The diff represents a shippable unit.
• Code simplified — if the diff spans more than ~50 changed lines or touches 3+ source files, the code-simplifier skill has been run across the changes
• bun run devcheck is clean — exit-0 AND zero warnings. Biome/lint warnings exit 0 (non-blocking to the tool) but are a HARD BLOCK to shipping — pre-existing warnings in untouched code included: fix them behavior-preserving, or get the maintainer's explicit waiver in the maintainer's own words — never your own adjudication. A documented alternative remedy in a skill (lint:mcp's "or verify by hand that format() renders it") is a way to UNDERSTAND a warning, never a licence to ship it; hand-verifying it and filing a follow-up issue is still shipping dirty. Nor is a pinned version a reason to defer the real fix: when the correct fix crosses the minor floor, the VERSION yields, not the gate — take the minor and say so. Two things that look dirty but aren't: (1) info is not warning — Biome's unsafe-fix suggestions ("Skipped N suggested fixes", useLiteralKeys and friends) print at info severity with the step still ✅; not the block. (2) The Security Audit step's transitive warn — a DIRECT-dep advisory is a hard failure, an all-transitive one is ⚠️ WARNING with the run still ✅; confirm from the bun audit dependency path (pkg › child = transitive), then ship it. Never force a gate green with a resolutions/overrides hack, and never run audit:refresh to silence it (it re-resolves the ^-ranged framework pin off its hold). The exception is a deliberate, maintainer-directed overrides block as its own dependency-hygiene pass — mcp-ts-core carries one as of 0.11.0: leave it in place, pre-authorize it by name in implement/release briefs (or agents burn a phase chasing it), pin entries to the lowest patched version inside the consumer's existing major, and verify the installed tree rather than assuming a pin applied (bun skips resolutions its range can't satisfy). Read the severity label and the failing step before calling a green run dirty — filtering devcheck's output strips exactly the context that separates the tiers.
• bun run rebuild succeeds — full clean build from scratch
• All tests pass — bun run test:all (or bun run test), plus bun run test:package where the project defines one: it guards the public-export manifest and is not part of test:all. New tests and regression tests added as needed for the changes being shipped.
• Fixes verified — bug fixes validated, generally via bun run rebuild and field-testing. Not just written — confirmed to resolve the described behavior.
• No known regressions — the changes don't break existing functionality
• GH issues updated — issues addressed by this work commented with what landed and any follow-ups needed. Concise. Backlinked as needed.
• Docs updated — surgical updates to existing docs as needed. New docs for new features. No large rewrites for documentation that's still accurate.

If any gate is red, fix it before proceeding. This skill re-verifies build + tests in step 7, but the work is committed by then — starting wrapup on a broken tree wastes the version number and turns the fix into an extra commit on a stack that should have been green.

Steps

1. Review the diff

Understand what's about to ship before touching version numbers:

git status
git log v<latest-tag>..HEAD --oneline    # commits since last release
git diff HEAD --stat                      # every uncommitted change, staged or not
git diff HEAD                             # review the actual content

Diff against HEAD, not the index: plain git diff omits staged changes entirely, so a group already staged before wrap-up began — a git mv from a migration step, a hook's output — shows up in git status as a line to scroll past and nowhere in the diff review. Whatever is staged is part of what ships and gets grouped in step 3 like everything else.

If the working tree is clean AND there are no commits since the last tag, halt — nothing to wrap up.

2. Determine the new version — and, in release PR mode, create its branch

Read the current version from package.json. Apply the intended bump:

Default to patch unless the diff clearly warrants minor or major.

In gated or straight-through mode, create the branch now, before going on to step 3 — the version you just settled is its name, and step 3 opens by committing:

git branch --show-current                 # must be main
git switch -c release/<version>           # uncommitted work rides along

Do not defer this to "just before the first commit". Step 3 is where committing starts, so a branch not created here is a branch created too late. If git branch --no-merged main --list 'release/*' prints a branch, a prior release PR was never merged — halt and report it rather than stacking a second release on top. A release/* branch already merged into main is a leftover from a finished release, not a blocker: delete it with git branch -d and continue.

3. Commit the work — one commit per concern

Release PR mode: git branch --show-current must print release/<version> before you run the first git commit. If it prints main, step 2's branch step was skipped — go back and do it. The uncommitted tree moves with you, so nothing is lost by branching late, but a commit already on main has to be unwound.

The work is committed before the version is bumped. Work concerns routinely share a file with the version — a dependency refresh edits package.json, a doc edit lands in a CLAUDE.md/AGENTS.md that pins a version string — and the file is the atomic boundary, so whichever commit comes first takes the file whole. Committing the work first leaves the version hunk (step 4) as the only thing those files carry into the release commit.

Do NOT git add -A into one commit. Group the working tree into a handful of logical commits — never one blob. A feature spanning multiple layers splits by layer: runtime/logic, linter/tooling, docs/skills. Unrelated changes (two separate fixes, an incidental doc tweak) are their own commits. A dependency refresh is its own commit — chore(deps): … carrying package.json, the lockfile, and any pins it moved elsewhere. Work commits do not carry the version.

Stage each group explicitly, commit it by pathspec, then move to the next:

git add <paths-for-this-concern>
git commit --only <paths-for-this-concern> -m "<subject>" -m "<body>"
# repeat per concern

Commit by pathspec, never the bare index. A bare git commit commits everything staged, not the paths just added, so anything staged before wrap-up began — a git mv left by a migration step, a concurrent stage from a second session or a hook — rides into the first concern's commit. --only takes the named paths' working-tree content and disregards the rest of the index, so a pre-staged group never rides along; it stays staged, to be committed as its own concern (chore(skills): move the skill tree to framework-skills/) or reported. Anything still staged when the release commit lands then fails step 10's clean-tree check instead of shipping silently.

The file is the atomic boundary: NEVER split a single file's working-tree changes across commits, regardless of mechanism — not git add -p, not an index-only patch (git apply --cached), not editing the file between commits to remove-then-re-add a hunk. When one file serves two concerns, it ships whole in the commit of its dominant concern; a later commit may touch the file again only for changes made AFTER the first commit (the version bump applied in step 4).

Every commit builds and passes its tests on its own. When a concern changes an exported contract — a service method's return type, a shared helper's signature, a renamed export, a changed query or behavior a consumer's tests assert — the files that consume it AND their tests ride in the same commit, even when they also carry other concerns. Grouping the contract change into one commit and each consumer into its own later commit leaves pushed commits that fail typecheck or the suite alone, and pushed history is never rewritten to repair them. A snapshot can typecheck and still be red: before pushing, check out each work commit's tree (git stash is not the tool — extract it with git archive <sha> | tar -x -C <scratch>, symlink the project's node_modules into it) and run the test script there; merge groups whose snapshot fails.

A dependency bump lands before the commits that use it. When any later commit in the stack uses something the new versions introduce — a new framework export, a new tool() option, a changed signature — chore(deps) is the first work commit. It builds on its own: package.json, the lockfile, and any source change the upgrade itself forces (a renamed import, a removed option) ride in it, so the commits above it compile against the versions they were written for. Ordered the other way, the adopting commit and every commit up to the bump fail typecheck at their own SHA.

Subject format: Conventional Commits, no version in the subject — feat: hosted server endpoint, fix: handle empty SPARQL result sets, feat(linter): enrichment contract rules, docs: document the enrichment block, chore(deps): refresh dev dependencies.

Body: every commit has one, and it is one or two lines. Uniform across the stack — no commit ships subject-only, none ships a paragraph. One sentence stating the why or the load-bearing constraint, a second only if the first genuinely cannot carry it. Two lines is the hard ceiling.

fix: handle empty SPARQL result sets

Upstream returns 200 with an empty bindings array rather than 404.

Never put a closing keyword in a commit body. Fixes #N, Closes #N, Resolves #N and friends close the issue the moment the commit is pushed — before the close-out comment recording what shipped, so the issue closes with no account of the fix. Reference issues as bare (#N) backlinks in the subject or body; closing is a deliberate later step.

A body is too long the moment it:

• enumerates the files, subsystems, or symbols touched — that is git show --stat
• walks through how the implementation works — that is the code
• narrates a fix's mechanism across multiple sentences — that is the changelog entry
• runs to a second paragraph, ever

The changelog carries the depth, the tag carries the headline, the commit carries one line of why. When the body wants to grow, that pressure is telling you the content belongs in the changelog entry.

Rules:

• Plain -m flag only — no heredoc, no command substitution
• No Co-authored-by or Generated with trailers
• No marketing adjectives ("comprehensive", "robust", "enhanced", "seamless", "improved")
• Each commit message stands alone for someone reading git log — no chat context, option numbers, or "as discussed"

Right-size it. "Group by concern" is not "always split." A genuinely single-concern change — one fix, a dependency bump, a small doc edit — is one work commit, with step 8's release commit on top of it. Only when the version bump is the whole change — a republish, a metadata-only patch with nothing else in the tree — is there no work commit to make, and step 8's release commit becomes the entire stack. The failure mode to prevent is the inverse: a large, multi-layer feature crammed into one commit alongside the release artifacts.

When every concern is committed, git status is clean. That clean tree is what makes everything steps 4–6 touch a release artifact and nothing else — confirm it before moving on.

4. Bump version everywhere

Every file that declares a version must be updated. Skip any file that doesn't exist in the project. For @cyanheads/mcp-ts-core projects:

• package.json — version
• server.json — top-level version AND every packages[].version entry. lint:mcp flags a mismatch at either level
• manifest.json (if present) — version. Packaging validation fails on a mismatch, and on a scoped name (use bls-mcp-server, not @cyanheads/bls-mcp-server)
• .claude-plugin/plugin.json and .codex-plugin/plugin.json (if present) — version. Packaging validation fails on a mismatch; .codex-plugin/mcp.json is connection config and carries none
• README.md — version badge. Packaging validation fails on a mismatch with package.json; a literal - in a prerelease is escaped as -- (Version-0.14.0--rc.1-)
• CLAUDE.md / AGENTS.md — if they pin a version string
• Dockerfile — OCI labels if they pin the version

Catch stragglers (replace the placeholder with the actual current version string, e.g. 0.9.7):

grep -rn "0.9.7" . --exclude-dir=node_modules --exclude-dir=.git --exclude-dir=changelog

Resolve hits case by case — historical changelog entries are correct as-is; everything else should match the new version.