feat: add git-history-cleanup skill for rewriting feature branch history

[rlorenzo]

Summary

Adds a new manually invoked /git-history-cleanup command that rewrites a work branch's git history into focused, logical commits — folding review-response, fixup, WIP, and lint-fix noise into the substantive commits they amend — so the history is easy for reviewers to follow and git blame points at commits that explain why a line exists.

What the skill does

• Guards: refuses to run on the default branch (resolved from origin/HEAD), develop, staging, production, or release/*/hotfix/* branches; requires a clean worktree; stops when there is nothing past the merge base or the branch is already merged; warns before rewriting history containing other authors' commits.
• Survey & plan: classifies each commit past the merge base as substantive vs. journey noise, groups the net change into one reviewable commit per feature/fix/concern, keeps mechanical churn separate from behavior changes, and shows the old → new commit mapping before rewriting.
• Execute: creates a <branch>-pre-cleanup backup branch first, then rewrites via a non-interactive rebase (GIT_SEQUENCE_EDITOR) for simple folds or a soft-reset rebuild for regrouping across commits.
• Verify: the rewritten tree must diff empty against the backup; any difference rolls back.
• Push & clean up: after verification, force-pushes with --force-with-lease (plain push if the branch is not on the remote) and deletes the backup branch. On a rejected lease or failed push, it stops and keeps the backup so the original history is never lost.

Changes

• .claude/commands/git-history-cleanup.md — canonical command source
• tools/generate — register git-history-cleanup in SKILL_COMMANDS
• .codex/, .copilot/, .antigravity/, .kimi-code/ skills/git-history-cleanup/SKILL.md — generated per-tool copies
• README.md — document the new command with per-tool usage

Testing

• All 53 bats tests pass, including the generate-sync suite
• tools/generate --check reports generated files in sync
• markdownlint-cli2 clean on the new/changed markdown

🤖 Generated with Claude Code

https://claude.ai/code/session_01CXfFwcsLw7CDauvJVkVYMy

---

Generated by Claude Code

[greptile-apps]

Greptile Summary

Adds a generated, cross-tool git-history-cleanup skill that plans and rewrites feature-branch commits, verifies tree equivalence, and pushes the rewritten history.

• Registers the canonical Claude command with the skill generator and emits copies for Codex, Copilot, Antigravity, and Kimi.
• Documents branch guards, backup and rewrite strategies, verification, lease-protected pushing, and user-facing invocation syntax.

Confidence Score: 4/5

The PR should not merge until the workflow consistently targets the requested branch, preserves default-branch ancestry during rebuilds, and pushes to an explicit verified remote ref.

The new destructive command can rewrite the current checkout instead of the requested branch, reattribute merged default-branch changes during soft-reset rebuilding, and send a force push to an unintended configured destination.

Files Needing Attention: .claude/commands/git-history-cleanup.md and its generated skill copies

Important Files Changed

Filename	Overview
.claude/commands/git-history-cleanup.md	Defines the destructive workflow, but the branch argument is not bound to the checkout, merge-containing rebuilds use the wrong ancestry target, and existing-branch pushes have no explicit destination.
tools/generate	Correctly registers the new canonical command for generation across the supported skill directories.
README.md	Documents the new command consistently, although its safety guarantees depend on correcting the canonical workflow.
.codex/skills/git-history-cleanup/SKILL.md	Generated copy faithfully propagates the canonical workflow and its branch-targeting, ancestry, and push issues.
.copilot/skills/git-history-cleanup/SKILL.md	Generated copy faithfully propagates the canonical workflow and its branch-targeting, ancestry, and push issues.
.antigravity/skills/git-history-cleanup/SKILL.md	Generated copy faithfully propagates the canonical workflow and its branch-targeting, ancestry, and push issues.
.kimi-code/skills/git-history-cleanup/SKILL.md	Generated copy faithfully propagates the canonical workflow and its branch-targeting, ancestry, and push issues.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
  A[Resolve requested branch and default branch] --> B{Guards pass?}
  B -- No --> C[Stop without rewriting]
  B -- Yes --> D[Survey commits and show rewrite plan]
  D --> E[Create pre-cleanup backup]
  E --> F{Rewrite strategy}
  F -- Fold or reorder --> G[Non-interactive rebase]
  F -- Regroup changes --> H[Soft-reset and rebuild commits]
  G --> I{Tree equals backup?}
  H --> I
  I -- No --> J[Restore backup and stop]
  I -- Yes --> K[Push rewritten branch with lease]
  K --> L{Push succeeds?}
  L -- No --> M[Keep backup and report failure]
  L -- Yes --> N[Delete backup and report result]

Loading

_{Reviews (1): Last reviewed commit: "feat(git-history-cleanup): auto force-pu..." | Re-trigger Greptile}

[Copilot]

Pull request overview

Adds a new manually invoked git-history-cleanup Agent Skill to help rewrite a feature branch’s history into clean, review-friendly commits, and wires it into the repo’s skill-generation pipeline and documentation.

Changes:

• Register git-history-cleanup in the generator so it’s emitted for each supported harness.
• Add canonical skill source at .claude/commands/git-history-cleanup.md and generated per-tool copies under .codex/, .copilot/, .antigravity/, .kimi-code/.
• Document the new command and usage variants in README.md.

Reviewed changes

Copilot reviewed 7 out of 7 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
tools/generate	Adds git-history-cleanup to the generated skill set.
README.md	Documents /git-history-cleanup purpose and per-tool invocation syntax.
.claude/commands/git-history-cleanup.md	Canonical skill definition and workflow for rewriting branch history safely.
.codex/skills/git-history-cleanup/SKILL.md	Generated Codex skill copy of the canonical command.
.copilot/skills/git-history-cleanup/SKILL.md	Generated Copilot skill copy of the canonical command.
.antigravity/skills/git-history-cleanup/SKILL.md	Generated Antigravity skill copy of the canonical command.
.kimi-code/skills/git-history-cleanup/SKILL.md	Generated Kimi Code skill copy of the canonical command.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 7 out of 7 changed files in this pull request and generated no new comments.

Suppressed comments (3)

.claude/commands/git-history-cleanup.md:44

• Creating a fixed-name backup branch (<branch>-pre-cleanup) can fail on re-runs (or after a previous failed cleanup) because the backup branch is explicitly kept on failure. Add an explicit instruction to stop rather than overwrite an existing backup branch name.

1. **Safety net first:** `git branch <branch>-pre-cleanup` on the current tip. It stays until the rewrite is verified and pushed — never delete it before then.

README.md:144

• This section says the command refuses to run on main, but the actual guard logic (in the skill text) resolves the repo’s default branch from origin/HEAD (and falls back to main/master). Updating this wording avoids incorrect docs in repos whose default branch isn’t main.

Rewrite a feature branch's git history into focused, logical commits before review or merge. It surveys the branch's commits past the merge base, folds review-response, fixup, WIP, and lint-fix noise into the substantive commits they amend, and reorders the result so each commit is reviewable on its own and `git blame` stays meaningful. Refuses to run on `main` or other long-lived branches, creates a backup branch before rewriting, and verifies the final tree is byte-identical to the original tip. Once verified it force-pushes with `--force-with-lease` (never bare `--force`) and deletes the backup branch; on any failure the backup is kept so the original history is never lost.

.claude/commands/git-history-cleanup.md:2

• The frontmatter description says the command refuses to run on "main", but the guards below resolve and protect the repository’s default branch via origin/HEAD (and fall back to main/master). This description should align with the actual guard behavior so it’s accurate in repos whose default branch is not main.

This issue also appears on line 44 of the same file.

description: "Rewrite a feature branch's git history into focused, logical commits by folding review-response, fixup, and WIP noise into the changes they belong to. Use when asked to clean up, squash, or tidy a branch's commits before review or merge. Refuses to run on main or other long-lived branches, works on a backup branch, verifies the final tree is identical, then force-pushes with lease and removes the backup."