maintaining-vcs-hygiene

name

maintaining-vcs-hygiene

description

AI-native version-control culture for agents in git and jj repositories. Use when committing or describing changes, parking or handing off work, cleaning a repository, coordinating with other agents or humans in one checkout, deciding where scratch output belongs, closing a work session, or reviewing how well agent guardrails are working. Complements repository-specific VCS skills; does not replace their procedures. Not for choosing VCS commands or syntax, resolving merge conflicts, or CI/CD pipeline configuration.

Maintaining VCS hygiene

Agents differ from human committers in three ways, and every rule here compensates one of them: agents lose context (compaction, restarts), they run in parallel with humans and other agents, and they generate volume cheaply.

This skill is the culture layer; it pairs with working-with-jj for the command layer. Each works alone, but in a jj repository load both — culture without safe commands, or commands without culture, each recreates half of the incidents these rules came from.

1. The repository is a shared, addressed space

• Nothing enters the working tree unless a future reader needs it. Scratch output, logs, downloads, analysis scripts, and bundles go to the session scratchpad — never the repository.
• Before the first edit, establish whose work the working copy holds (jj: jj log -r @; git: git status + current branch). Humans and other agent CLIs count as writers; edits in an auto-snapshotting VCS silently join whatever change is checked out.

2. Work is always addressable

• No orphaned work. At any pause, every edit is either landed, or parked on a described change/branch, or explicitly abandoned with a stated reason.
• Commit at milestones and at least every 20 minutes while dirty — an agent can die mid-task, and an uncommitted tree at handoff is a defect, not a style choice.
• At session end, sweep for strays and resolve them: jj jj log -r 'all() & ~::<trunk>'; git git branch --no-merged plus a reflog check for detached work. Sweep the undescribed too, wherever they sit — jj jj log -r 'description(exact:"") & ~root()' — because an unpushed range hides them until it is pushed (§4).
• A working copy is not evidence of unlanded work. A workspace parked on an already-landed commit presents exactly like a large uncommitted change: status lists files, and a diff against its parent shows the whole change. Decide by ancestry, never by appearance — jj jj log -r '<rev> & ::<trunk>', git git merge-base --is-ancestor <rev> <trunk> — and do it before forming any opinion about the work. Comparing its contents against trunk answers a different question and answers it misleadingly: trunk holding a newer version of the same files reads as "superseded duplicate" when the truth may be that trunk was built from this very commit and moved on. The sweep revset above already encodes this; the mistake is reaching a working copy by another route — a workspace listing, a colleague's checkout — and judging it on its diff.

3. Descriptions carry intent

• First line: what changed. Body: why now, alternatives rejected and the reason, invariants preserved, deliberate deferrals, sequencing or deploy constraints, who authorized contract changes, verification evidence. Assume the reviewer sees only the repository, never the chat.
• State what was NOT verified and why, not only what was — partial verification presented as complete is the same defect as a partial tree presented as done.
• Committing on another writer's behalf is legitimate when their work would otherwise be stranded — say so in the body.
• Read before you write: when code looks wrong or oddly deliberate, run annotate/git log -L on those lines and read the description body before "fixing" it — it may be someone's fence. A deliberate trap in code also deserves a comment at the site; the body holds the why.

4. History is a deliverable

• Land honest units: one logical change each; fold "WIP"/"fix"/"next" noise into its parent before integrating. Placeholder descriptions are acceptable only on empty changes.
• An empty change with no description at all is push-blocking litter, and it surfaces late. jj refuses the whole push over one of them (Won't push commit <id> since it has no description), and such a commit is typically an abandoned working copy from an earlier session sitting in the middle of history — invisible in the local log, harmless for weeks, and discovered only when a push finally reaches that far. An empty change that carries a description pushes without complaint, so the distinction is description, not emptiness. Clearing it rebases every descendant: seconds while the range is unpublished, impossible once it is not. Describe or abandon an empty change when you step off it, not when the gate finds it.
• Never rewrite published history or force-push without explicit authorization. When the VCS refuses an abandon, squash or rebase as immutable, that refusal is evidence about the commit, not an obstacle to route around: it says the commit is already published. Stop and re-derive why you thought it was disposable.
• Attribution stays honest — and specific. In a checkout with several writers, "the human's name on every commit" is anonymity, not attribution: the author field should name the executing agent (jj: JJ_USER/JJ_EMAIL in the session environment; git: repo-local user.name/user.email in single-writer clones). Never impersonate another writer or strip co-authorship; when useful, carry the ordering context (session or task id) as a commit trailer so the intent conversation stays findable.
• Agent identities must be real addresses. Hosts verify signatures against the committer's account-registered email, so a synthetic domain in the committer field turns a validly signed commit into "unverified" and a required-signature rule rejects the push. Use real, account-verified agent addresses (e.g. aliases on the org domain); until they are registered, keep the committer human and carry agent identity in the author field and trailers only.
• The model is attribution too, and unlike the CLI it changes mid-session — so it cannot live in static env. Record it where it is known at commit time: interactive agents add a Model: <exact-model-id> trailer when describing; spawned workers, whose model is fixed for life, embed it in the clone identity (user.name "<worker-id> (<model>)").
• Attribution and message shape are checked on the result, not on the command that produced it, because --stdin, an editor, a script, or another agent CLI writes descriptions no command-lint can see. Where the repository ships the check, missing attribution, a subject over 72 characters, or an unwrapped body blocks the push — so fix a description when you are told, not at the gate.

5. Litter is removed at the source

• A stray artifact in status output means a missing ignore rule — fix the rule, but scope it narrowly: over-broad patterns (bin/, *.so) silently swallow real files such as test fixtures and vendored sources, and the loss surfaces only in CI or never.
• Close what you opened: delete merged branches and bookmarks you created, remove finished workspaces and scratch clones, drop stale remotes and bundles.

6. Claims require evidence

• Say "committed", "pushed", or "deployed" only after verifying the ref actually moved; name the commit and the gates that ran.
• Report uncommitted files, conflicts, and skipped checks honestly at handoff. A partial tree presented as done is the same defect as a job that reports success while losing data.

7. Guardrails are reviewed, not accumulated

When guards keep firing, a documented rule keeps being violated, or the instruction set has grown past what an agent actually reads, run a reflection pass: reflection.md. The core doctrine: an instruction that gets violated should become a mechanism, not a louder instruction — and every addition is paired with a removal candidate. Reflection proposes; it never edits its own constraints without review.

Onboarding a project

What belongs in global CLAUDE.md versus a repository's AGENTS.md, and what must never be duplicated out of skills: see working-with-jj onboarding.md (jj-specific parts apply only there; the layering rules apply everywhere).