| name | plan-commits |
| description | Investigate the working tree, group changes into atomic commits with Conventional Commits messages, and emit a paste-ready bash script. Inspects only; never runs `git add`/`commit`/`push` itself. Triggers: 'plan commits', 'commit my changes', 'stage and commit', 'split these changes', 'group into commits', running `git status` on a working tree with multiple unrelated edits, or any request to turn the current diff into more than one commit. Skip when: the task is general git history, rebasing, or branch management. |
| license | AGPL-3.0-only |
| metadata | {"author":"marcodsl","tags":"git, commits, workflow, planning","version":3} |
Plan Commits
Investigate the working tree, group changes into atomic commits, write Conventional Commits messages, and emit a paste-ready shell script. Do not run any mutating git commands.
- The user asks to commit, stage, or plan commits from uncommitted changes.
- The user wants a commit script or batch-commit plan for the current working tree.
- The user asks for help grouping or splitting changes into logical commits.
<do_not_use_when>
- The user is asking about git history, rebasing, merging, or branch management unrelated to commit planning.
</do_not_use_when>
<governing_rule>
Only inspect; never mutate. Do not run git add, git commit, git push, or any other write command. Reference only paths reported by git status / git diff; never invent files.
</governing_rule>
<working_method>
- Survey changes with read-only git inspection.
- Group changes into atomic commits.
- Write Conventional Commits messages.
- Optionally draft PR metadata.
- Emit the Plan + Commands script in the required format.
</working_method>
Run read-only inspection only:
- `git status --porcelain=v1 -uall`
- `git diff --stat` and `git diff` (unstaged)
- `git diff --staged` if anything is staged
- For untracked files, read their contents directly.
Each group must satisfy all three:
- Single scope of work: one feature, fix, refactor, docs change, config update, or chore. Split mixed intents.
- Coupling: files that must land together stay together (implementation + tests, schema + migration, code + lockfile, type definition + call-site updates).
- Atomicity: the commit compiles and passes tests on its own and is independently revertable.
Additional rules:
- Split unrelated drive-by edits in the same file via
git add -p hunks. Flag this in the plan when needed.
- Prefer fewer, well-scoped commits over many trivial ones. One commit per logical concern, not per file.
- If a change breaks an existing contract (API, config key, CLI flag), isolate it for independent revert.
- Group infrastructure or tooling changes (CI, lint rules, dep updates) separately from feature/fix code.
Follow Conventional Commits 1.0.0. The full decision guide is `references/conventional-commits.md`.
Format:
<type>[optional scope][optional !]: <description>
[optional body]
[optional footer(s)]
- Type: narrowest truthful.
feat for new user-facing features, fix for bug or regression fixes. docs, refactor, perf, test, build, ci, chore, style, revert when more accurate.
- Scope: short noun in parentheses (
(auth), (parser), (api)) only when it clarifies the subject. Omit for repo-wide changes.
- Breaking:
! before the colon, a BREAKING CHANGE: footer, or both, whenever existing callers, configs, or consumers must change behavior.
- Description: imperative mood, describe the result not the process, ≤72 chars. Good:
fix(parser): reject invalid UTF-8 sequences. Weak: fix(parser): fixed parser bug.
- Body: add only when the subject alone does not explain the why, tradeoff, or operational effect. Wrap at 72 chars.
- Footers:
BREAKING CHANGE:, Refs: #123, Closes: #456, Reviewed-by:.
If the change set spans more than one commit or is non-trivial, draft a PR title and description:
- Title mirrors the dominant commit's subject.
- Description states what changed, why, and follow-ups. Facts only.
- Apply `natural-tone` rules: direct, concrete, no filler, no marketing voice, no emoji, no hedging.
Reply in this exact structure, nothing else:
Plan
2-6 line summary of grouping and rationale.
Commands
A single fenced bash block, paste-ready:
git add -- <file1> <file2> ...
git commit -m "type(scope): subject" -m "optional body"
Use git add -p -- <file> with a comment for hunk-split files. Quote paths with spaces.
PR (only if drafted)
Title: <title>
<description>
- Working tree clean: respond with exactly `Working tree is clean - nothing to commit.` Do not emit the Plan/Commands structure.
- Uncertain how to split: ask one focused question; do not emit the structure yet.
- Never claim a commit ran unless `git commit` actually executed.
<review_checklist>
- Every file from
git status appears in exactly one commit group (none omitted, none duplicated unless split via -p).
- Each commit message type matches the actual change.
- Breaking changes are marked with
! or a BREAKING CHANGE: footer.
- The script, if pasted verbatim, would produce a clean working tree.
</review_checklist>
<bundled_resources>
references/conventional-commits.md — full type decision guide, scope rules, breaking-change forms, common mistakes.
</bundled_resources>
