halfline/git-stage-batch/commit-unstaged-changes

Commit Unstaged Changes

Use this skill to turn the current unstaged working tree into one or more atomic commits with messages that match project conventions.

Adopt a meticulous, completion-oriented stance toward history curation: once the correct split is clear, keep executing it until the series is finished or a listed blocker is reached. Be tenacious, resiliant, and autonomous.

This skill is autonomous and non-interactive. Inspect the working tree, use git-stage-batch to stage related changes, create one or more commits as needed, and then stop without asking the user to review each message first.

git-stage-batch is not just the preferred staging mechanism here. It is the core execution workflow for carrying out the split. When the history requires temporarily setting work aside, put that work into named batches with discard --to BATCH or include --to BATCH instead of moving it aside by hand. When a commit needs an earlier coherent version of a changed region or file, use include --line --as, include --line --as-stdin, include --file --as, or include --file --as-stdin to stage that earlier state rather than editing unrelated files outside the git-stage-batch flow.

Do not broaden or collapse the commit plan merely because the staging work looks tedious, mixed files require line-level selection, or the analysis is taking longer than expected. "To keep this tractable", "to reduce tool calls", "to avoid backtracking", or any similar rollout-efficiency rationale is explicitly invalid in this skill. If the right split is clear, keep following it. If the right split is not clear enough to execute safely, stop and report the ambiguity or blocker instead of inventing a coarser history.

If the remaining split is clear but the next staging step is more intricate, do not stop merely because it involves repeated show --file inspection, line-level staging, --as replacements, batch peeling, temporary restaging of the index, or other careful execution work. Those are normal costs of this skill, not blockers. Before stopping, identify one concrete blocker:

• a git-stage-batch bug or incorrect staged result
• an intended history that is genuinely ambiguous in a way that risks the

wrong split

• a repository policy conflict that cannot be resolved from local context
• a missing capability where the desired split cannot be expressed safely with

the available staging tools

If none of those apply, continue staging. If you can name the exact next git-stage-batch, git diff --cached, or git show :path command you would run to keep splitting the current commit, you should usually run it rather than stopping.

Do not stop merely because a substantial amount of correctly split work still remains. "This is still a lot of work", "the rest of the series is substantial", "I have already made enough commits for now", or similar reasoning is not a blocker under this skill. If the next split is still clear and stageable, continue until the intended series is finished or one of the explicit blockers above is reached.

If git-stage-batch is available directly in PATH, use it. If it is not, fall back to pipx run git-stage-batch.

This skill does not control Codex sandbox or approval mode. If a required git or git-stage-batch command fails because .git is read-only or because the sandbox blocks writes needed for staging, committing, or batch metadata, rerun that command with an escalation request instead of assuming the repository is misconfigured or abandoning the workflow.

Installed resources and project guidance

Set ASSET_ROOT to the absolute .agents directory containing this installed skill, two levels above its skill directory. Resolve it from the loaded SKILL.md path, whether installed in the repository or the user's home. Resolve references/ and scripts/ paths relative to this skill directory. Keep the working directory in the target repository, quote helper paths in shell commands, and pass ASSET_ROOT to workers that use companion resources.

Before drafting, search the project tree for CONTRIBUTING.md, excluding installed assistant assets. Check the repository root, .github/, docs/, and guidance scoped to the changed paths. Read the applicable project guide. Only if the project has no contribution guide of its own, read $ASSET_ROOT/internal/CONTRIBUTING.md. Other project instructions and commit hooks still take precedence over bundled defaults. Pass the selected guide's path and applicable rules to any drafting worker.

Repository-Agnostic Split Policy

Apply the same split logic in every repository. Do not anchor the decision to project-specific nouns such as assistant names, package names, subsystem names, or filenames. First normalize the diff into generic behavior axes, then split on those axes.

Use these generic axes:

• groundwork: helper logic, shared data structures, remapping, translation,

persistence plumbing, ownership machinery, or refactors that can land without changing a user-facing operation on their own

• adopter: one command, subcommand, workflow, persistence path, replay path,

recording path, install path, or other externally invocable operation that starts using groundwork

• selection semantics: how an existing operation chooses targets, files,

entries, matches, filters, or scope

• surface expansion: a new target, group, mode, assistant, package, asset

family, install destination, packaging surface, or externally visible capability

• validation: tests, fixtures, docs, examples, manpages, or packaging checks

Every code change must be assigned to exactly one of those axes before staging begins. If a planned commit still contains code from more than one non- validation axis, split it by default.

Examples are evidence, not scope. If the skill says to split stale-source adopters or filter-vs-surface work in one repository, apply the same abstract rule to analogous diffs in every other repository even when the nouns differ.

Distinguish abstract capability families from concrete implementations.

Do not treat one high-level category such as "database support", "authentication support", "assistant support", "cloud support", or "storage backends" as a single concern by default. Adding one concrete implementation under that category is a separate concern from adding a second implementation under the same category.

Examples of concrete implementations include:

• one backend versus another backend
• one provider versus another provider
• one target platform versus another target platform
• one install destination versus another install destination
• one protocol adapter versus another protocol adapter
• one asset group versus another asset group
• one bundled entry versus another bundled entry inside the same asset group
• one template or manifest entry versus another sibling entry in the same directory

These distinctions apply equally to data-only additions such as skill definitions, agent configurations, templates, and bundled manifests. Files organized under platform-specific sibling directories or targeting different tool families are separate asset groups even when they provide the same logical capability or share identical internal structure. Platform boundary is an asset-group boundary by default.

Sibling entry boundary is also a split boundary by default. If one directory, manifest, or bundled asset group contains two or more entries that are separately installable, selectable, invocable, or independently meaningful to review, treat each entry as its own concrete implementation even when the entries share identical boilerplate, live under one installer command, or are marketed as one bundle.

If a diff adds or changes two or more concrete implementations, assume the correct split is:

1. shared groundwork, if any
2. one commit per implementation
3. validation for that implementation as required by repository rules
4. docs for that implementation when they belong in the same series

Shared purpose at the category level is not enough to combine them. "database support", "authentication support", "assistant assets", or similar umbrella wording is too broad when the diff contains separate implementation-specific paths.

When a rule below says a broader commit is allowed only if separating it would leave an "intermediate commit" broken, apply that phrase narrowly. A broken intermediate commit is one where the repository would fail in a concrete, immediate way after the narrower commit lands, such as a missing import, missing symbol reference, broken parser dispatch, necessarily failing test in that commit, invalid persisted shape, or missing packaged/install-time asset.

The following do not count as a broken intermediate commit:

• the two changes live in the same command, subcommand, module, package, file,

YAML document, or documentation section

• the changes share helper code, ownership machinery, source refresh logic, or

another dependency that can land on its own

• the broader commit feels easier to explain, review, or stage
• the narrower split would require more line-level staging, more passes, or

more temporary batches

• the broader split still "feels coherent", "seems defensible", or preserves a

high-level story

Before keeping any commit that touches more than one plausible axis or more than one independently testable behavior, run this mandatory falsification test in your working notes:

1. Name the narrowest plausible split in generic terms.
2. Name the exact command, test, import, parser path, runtime path, or

packaged/install-time asset that would be broken immediately after that narrower commit.

1. Explain why that failure would happen in the intermediate history.

If you cannot answer step 2 concretely, the broader commit is forbidden. The fact that two implementations satisfy the same abstract feature goal does not count as coupling.

Core Workflow