Awesome Git Commit Plan

Commit Plan

Read a codebase, map how its parts depend on each other, and split it into a commit series where every commit builds and its tests pass. The output is one file: the commits, numbered #1 to #N, each with its message and its exact file set. Nothing is committed, nothing is pushed, and the repository under analysis is never written to.

Why the plan is a separate artifact: a split is a claim about a codebase — that these files form a unit, that this module compiles without the one landing three commits later, that this test has a subject to test. Claims are cheap to write and expensive to discover wrong at commit 14 of 40. A plan file is reviewable before any of that, re-splittable on one word from the user, and executable later by hand or by awesome-git-history-rebuild.

Core principle

BISECTABLE IS A MEASURED PROPERTY, NOT A DESIGN GOAL. A plan that says every commit builds has claimed something; a plan whose ladder was replayed in a scratch clone with the repository's own build and test commands run at every step has proven it. Phase 5 does the replay. A commit that fails its gate is regrouped and the ladder re-run — never shipped with a note that it "should" work.

Four invariants hold throughout:

• Read-only against the user's code. All work happens in a scratch clone or a temporary worktree. The user's checkout is never staged, committed, cleaned or checked out. If the run dies halfway, nothing of theirs moved.
• Every tracked path lands in exactly one commit. Coverage is proven by set arithmetic against git ls-files, not by inspection. An unassigned path is a stop.
• Never invent work that did not happen. Split along seams that exist in the final tree. A fix: commit is honest only when the tree carries the fix; a fabricated bug-and-repair arc is a lie that reaches the changelog.
• The repository's own rules outrank this skill's defaults. A commitlint config, a hook, CONTRIBUTING.md or the existing log decides the message format, always, including where this skill's default is nicer.

Invocation

/awesome-git-commit-plan <repository-url-or-path> [--out <file>] [--commits N] [--granularity coarse|default|fine]
                     [--verify full|build|off] [--strategy layered|vertical|manual] [--slice on|off]

• <repository-url-or-path> — required. A remote URL (https://…, git@…), a local git repository, or a plain directory of source with no git at all. If it is missing, ask for it before doing anything else and do not guess from the working directory.
• --out <file> — plan file path. Default <repo-name>-commits.txt next to the repository.
• --commits N — target commit count. Otherwise proposed from repository size (Phase 4).
• --granularity — coarse (subsystem per commit), default, or fine (module per commit, sliced files).
• --verify — full (default: build and test at every commit), build (compile or typecheck only), off (no replay; the plan then says so in the report and the word bisectable is not used).
• --strategy — layered (default), vertical (one commit per user-visible capability), or manual (the user supplies the grouping; this skill validates coverage, order and messages only).
• --slice on|off — whether a single large file may be introduced across several commits as partial content. Default on for fine, off otherwise.

Tooling check (run first)

• git --version — required.
• The repository's own toolchain — needed for --verify full and build. Detect it from the manifests; never assume it. Missing toolchain is not a silent downgrade: report it and ask whether to continue at --verify off.
• A host CLI (gh, glab) — not needed. This skill reads code, not a remote.

Shell. Detect the platform before running anything (uname -s, or $IsWindows in PowerShell) and pick the shell from that check rather than from habit. The bash blocks below are POSIX shell — they lean on awk, sort, uniq, head, and 2>/dev/null, none of which PowerShell parses. On Windows run them in Git Bash, which ships with Git for Windows and carries all of them. The plain git commands run the same everywhere.

Phase 0 — Target, scope and workspace

1. Resolve the target. A URL is cloned into scratch. A local path is copied or cloned into scratch — the user's directory is the source, never the workspace. A directory with no .git is initialized in scratch so path inventory and the verification ladder have something to run against.

2. Establish the file universe. What the plan may assign, and what it must not:

   git ls-files                                  # tracked: the authoritative list
   git status --porcelain                        # uncommitted work — ask before including
   git ls-files --others --exclude-standard      # untracked but not ignored
   git ls-files --others --ignored --exclude-standard | head   # ignored: never planned
   

   For a non-git directory, the universe is every file except what a present .gitignore excludes, and the run says so.

   Uncommitted or untracked work is a question, not a default. Including it changes what the plan covers; excluding it silently produces a plan that does not reproduce the tree the user is looking at. Ask, quote the count, and record the answer.

3. Exclude what must not be planned as source: generated output and build directories, vendored trees, lockfiles' own caches, binary artifacts that are not assets, anything matched by an existing .gitignore. Lockfiles themselves are not excluded — they are tracked and they land with their manifest (Phase 4).

4. Detect the gates. The commands the verification ladder will run, read from the repository rather than assumed:

   • build or compile: package.json scripts, cargo build, go build ./..., tsc --noEmit, mvn -q compile, dotnet build, a Makefile target
   • test: the runner the repository actually configures
   • lint and format: only when the repository enforces them in CI or a hook Record each gate's exact command and whether it is available on this machine. A gate that cannot run is unavailable, and unavailable is reported, never counted as passed.

5. Size the work. Tracked path count, total lines, largest files, language mix. Above ~1500 paths or ~200k lines, switch to directory-level analysis, say so explicitly, and default to --granularity coarse.

Phase 1 — Load the rules into memory

Read both, in this order, before a single message is drafted:

1. references/commit-message-rules.md — the subject and body ruleset this skill writes to. It is not advisory: every message in the plan file is checked against its section 9 checklist in Phase 6.
2. The repository's own rules, which override it on any conflict:

   ls commitlint.config.* .commitlintrc* .husky/ .pre-commit-config.yaml lefthook.yml .gitmessage 2>/dev/null
   git config core.hooksPath
   git log --format='%s' -200 | sort | uniq -c | sort -rn      # what the repo actually does
   

   Extract: the convention (conventional, [Area] …, sentence case, ticket prefix), the allowed type list, the scope vocabulary already in use, subject length limits, whether bodies and trailers appear, and any server-side message pattern.

Present a one-screen rules card — convention, types, known scopes, hooks that will run, sign-off — and carry it into Phase 6. Reuse the existing scope vocabulary; never invent a parallel one (auth, not authentication).

Phase 2 — Build the navigation map

This is the phase the split is derived from, and it is worth reading the code for. A map assembled from filenames alone produces an alphabetical dump wearing commit messages.

1. Inventory by area:

   git ls-files | awk -F/ '{print $1"/"$2}' | sort | uniq -c | sort -rn
   

2. Classify every path into: entry and bootstrap · dependency manifests and lockfiles · build and tooling config · core domain modules · adapters and integrations · UI · assets, i18n and media · tests · CI/CD · docs · legal and community files · generated or vendored.

3. Read the dependency direction. For every source file, extract what it imports from inside the repository, and build the edge list. This is the map's spine:

   # JS/TS
   git grep -nE "^\s*(import|export) .*from '\.|require\('\." -- '*.ts' '*.tsx' '*.js'
   # Rust
   git grep -nE '^\s*(use crate::|mod )' -- '*.rs'
   # Go
   git grep -nE '^\s*"<module-path>/' -- '*.go'
   # Python
   git grep -nE '^\s*(from|import) (\.|<package>)' -- '*.py'
   

   Then derive, and report:

   • leaves — files that import nothing internal. These can land first.
   • depth — longest path from a leaf to each file. Depth is the commit order.
   • cycles — mutually importing files. A cycle cannot be split; its members land in one commit, and the map names them so the split does not try.
   • fan-in hotspots — a file many others import. It lands early, and it defines a commit boundary.

4. Find the entry points and the wiring. The main, the app bootstrap, the plugin registration, the route table, the command registry. These are usually the last code commit, because they reference everything.

5. Find the honest seams for anything that is not a plain feat: a guard clause with its own test, a workaround with a comment naming a platform bug, an index or cache over an existing path, a formatting-only file. Those are honest fix, perf, refactor and style commits because the artifact is in the tree. Nothing else earns those types.

6. Map the test files to their subjects. A test that lands before the module it imports fails the suite at that commit and breaks the ladder. Every test path is bound to the path set it covers.

Report the map in one screen: layers, module count, leaves, max depth, cycles, hotspots, generated paths excluded, gates detected. This map is what the user reviews before the split, and it is what makes the split arguable rather than arbitrary.

Phase 3 — The bisectability rules

A commit is bisectable-safe when the cumulative tree at that commit satisfies all of these. They are listed with the failure each one prevents, because each was learned by a ladder breaking at exactly that point.

The gate ladder is stated, not pretended. Not every gate is green from commit #1: a test runner exits non-zero with no test files, a linter flags an unused module, a web build needs an entry point. So each gate has a first commit from which it passes, that number is measured in Phase 5, and a commit is required to pass only the gates that are applicable and available at its point in the ladder. A plan that claims "green from #1" for a gate that cannot be is not bisectable, it is unverified.

Phase 4 — Split

Build the plan from the map. Defaults, in order of preference:

Layered (default): manifests and workspace config → build and lint tooling → data model and types → leaf modules by ascending depth → adapters and integrations → UI primitives → screens → wiring and entry points → tests that were not bound to earlier commits → CI → docs → community files.

Vertical (--strategy vertical): one commit per user-visible capability, full stack each. Honest only when the modules genuinely partition that way; a shared core forces a first commit that is a layer anyway.

Granularity, proposed from size and overridable:

Two shaping rules:

• No commit is a wall and none is an orphan. A 4000-line commit hides its own review; a one-line commit that could have joined its neighbour is noise. Report lines per commit and flag both tails.
• Slicing a file is allowed but never free. In --slice on, a large file may be introduced across several commits (a crate root that grows a module line per commit, a command surface that grows an entry per command). Each slice must still satisfy Phase 3. Record the slice note in the plan file; the executor has to cut it by hand.

Coverage proof, before anything else is shown:

tracked paths <T> · assigned <T> · unassigned 0 · assigned twice 0

Unassigned is a stop. Assigned twice is a stop. Neither is a rounding error.

Then present the table and let the user approve, adjust, or re-split at a different granularity or strategy. Never proceed on silence or "looks fine" — the approval names the table.

Phase 5 — Verify the ladder

This is what separates a plan from a guess. Skipped only at --verify off, and then the report says the plan is unverified and drops the word bisectable.

In the scratch clone, on an orphan branch, replay the approved plan and run the gates:

git checkout --orphan plan-verify
git rm -r --cached . -q                 # index emptied, working tree untouched

# per commit N of the plan
git add -- <paths of commit N>
git diff --cached --name-only           # must equal the planned path set exactly
git commit -q -m "#N"                   # placeholder message; real messages come in Phase 6
<build gate>                            # e.g. pnpm exec tsc --noEmit
<test gate>                             # e.g. cargo test

Record per commit: which gates ran, which passed, which were not applicable yet. Then:

• A gate that fails at commit N is a split defect, not a gate defect. Regroup — usually by moving one file earlier or merging two commits — and re-run from N. Never reorder blindly; go back to the map and find the edge that was missed.
• A gate that fails at every commit including the last is a pre-existing failure in the source, not something the split caused. Report it as such and continue; the plan cannot fix a broken build.
• Slow gates: for a full test suite over many commits, offer --verify build for the whole ladder plus the full suite at the last commit, and state exactly that in the report.

Then delete the scratch branch. The verification produced knowledge, not artifacts.

Output of this phase is the gate ladder:

gate                     first green   verified at commits
typecheck                #1            1-24 pass
cargo test               #4            4-24 pass
lint (warnings as errors) #12          12-24 pass
web build                #21           21-24 pass
full test suite          #24           24 pass

Phase 6 — Write the messages

Draft every subject and body against references/commit-message-rules.md, with the repository's own convention overriding it on conflict. The rules in one line each:

• subject type(scope): imperative lowercase, 70 characters or fewer, no trailing period, scope from the repository's own vocabulary
• no body by default — write one only where the reasoning is not visible in the diff. Expect a body on well under half the commits
• at most four paragraphs, wrapped under 80, ordered problem, mechanism, decision
• plain ASCII, no backticks; identifiers bare
• no enumerations, no explanatory colon, no contrast frame, no invented past, no consequence half, no count that can be recounted, no reference to another commit in the plan, no flourish
• what must survive the cut: incident provenance, hard-won behaviour of a third party, a deliberate refusal, a constant with its reason, a wire-format note, a security boundary

Then run the section 9 checklist over every drafted message, and validate against the repository's own linter where one exists:

echo "<subject>" | npx --no-install commitlint       # or the repo's validator

A message that fails the repository's hook is a defect found now, in a text file, instead of at commit 14 of the execution.

Phase 7 — Write the plan file

Exact format, the template and a worked example: references/plan-file-format.md. In short:

• The file starts with commit #1. No title, no summary, no how-to-execute section, no legend.
• Commits are numbered #1 to #N, plain, no prefix letter.
• No dates and no timestamps anywhere. Pacing belongs to whatever executes the plan.
• Each commit carries its subject, its optional body, and its file list with a count.
• A sliced file carries its slice note on the same line.
• Nothing else. No gate columns, no rationale for the split, no alternatives section, no closing notes.

Everything the file does not carry — the map, the coverage proof, the gate ladder, the granularity choice, what could not be verified — goes in the chat report, which is where a reviewer reads it once and a file does not have to carry it forever.

Phase 8 — Report

Lead with the verdict, then the evidence:

plan: <N> commits over <T> tracked paths, written to <path>
coverage: <T> assigned, 0 unassigned, 0 duplicated
verification: <full|build|off> — <N>/<N> commits pass every applicable gate
gate ladder: <the table from Phase 5>
messages: <N> validated against <commitlint|the repo's log convention>, <N> carry a body
map: <L> layers, <M> modules, <C> import cycles collapsed into one commit each
not verified: <gates unavailable on this machine, and why>

Then state plainly, without being asked:

• every gate that could not run, and what that leaves unproven
• any pre-existing failure the ladder inherited from the source
• any file whose placement was a judgement call rather than a dependency fact
• what executing the plan still requires — this skill produced a document, and nothing in git has changed

Do not offer to execute the plan. Rewriting history is awesome-git-history-rebuild, which has the backup, the permission preflight and the confirmation gates that this skill deliberately does not carry.

What this skill does not do