/publish-branch

name: publish-branch
description: 'Use when asked to publish the checked-out branch: commit and push it on whatever branch it is, the default branch included. Not for creating branches, PRs, force pushes, or pushing any other branch; when the request excludes the default branch, use commit-push-current.'
disable-model-invocation: true

Commit and push the current branch

Contract

| Field | Bound contract | |---|---| | Trigger | User asks to commit and push to the branch currently checked out, including the default branch. | | Authority | Remote: pushes local commits to `origin/<current-branch>`; requires explicit human invocation. Invoking on the checked-out branch (including `main`/`master`) is explicit authorization to push to that branch. Preview the push target and consequence before pushing. | | Side effect | Creates local commits and pushes them to `origin/<current-branch>`. No branch creation, no branch switch, no force push, no PR. | | Done | Current branch is committed and pushed, or detached/diverged/no-origin state is reported without unsafe recovery. |

Inputs

• Working-tree status (`git status`) and diff against HEAD (`git diff HEAD`): required, gathered by the skill.
• Current branch (`git branch --show-current`): required, gathered by the skill; empty output means detached HEAD.
• Recent commit history (`git log --oneline -10`): required, gathered by the skill.
• Push-target divergence: required, gathered by the skill with `git rev-list --left-right --count origin/$(git branch --show-current)...HEAD 2>/dev/null || echo 'NO_REMOTE_BRANCH'` (left count = commits only on origin, right count = commits only on HEAD); `NO_REMOTE_BRANCH` means the branch has no counterpart on origin yet.
• Configured remotes (`git remote`): required, gathered by the skill.
• A commit message supplied by the user: optional; when absent it is derived from the diff and the repo conventions.

Procedure

1. Resolve branch state. Run `git branch --show-current`.

• Detached HEAD (empty output): there is no branch ref to push. Report that this skill pushes only the checked-out branch and stop. Never create or switch a branch.
• Any named branch: continue. The default branch is not special: invocation is consent to push from the current HEAD.

Done when: a named branch is identified and recorded, or detached HEAD is detected and the stop is reported.

2. Check for work against the gathered status and divergence counts.

• Clean tree AND right-side count `0`: report "nothing to commit, already up to date" and stop.
• Clean tree but commits ahead of the push target, or `NO_REMOTE_BRANCH`: skip to step 6.
• Dirty tree: continue to step 3.
• The push target is always `origin/<current-branch>`, regardless of any differently-configured upstream, because step 6 pushes there. `NO_REMOTE_BRANCH` also fires in detached HEAD, where the branch expansion is empty; the detached-HEAD bullet in step 1 runs first and stops, so keep these branches in this order.

Done when: the tree state is classified as clean-and-current (stop), clean-and-ahead (skip to step 6), or dirty (continue to step 3), and the classification is recorded.

3. Determine commit message conventions. Match repo style in this priority: project instructions in context > recent commits > seven-rule style (capitalized imperative subject, 50 chars target and 72 hard, no trailing period; blank line; body wrapped at 72 explaining what and why, not how; footers `Closes #N`, `See also: #N`, `BREAKING CHANGE: <what broke>`). In a repo that uses conventional commits, default to `fix:` over `feat:` when ambiguous: code added to remedy broken or missing behavior is `fix:`; `feat:` is for capabilities the user could not previously do. The user may override. Done when: the commit message convention is identified (project instructions, recent-commit style, or seven-rule default) and the convention source is named, so step 4 and 5 produce messages that match repo style.

4. Group the changes into logical commits. One concern per commit, where a concern is one reason the tree changed. Two changes belong in the same commit only when reverting one without the other leaves the tree broken (the revert test). Split by mechanism, not by file: where one file carries two mechanisms, write the filtered patch out of `git diff -- <file>`, keep only the hunks for one mechanism, and stage it with `git apply --cached <patch>`: the first real split is unverified and must be confirmed with the user before it is applied, because this headless form was not executed this session and `git add -p` needs a TTY the agent lacks. A lint, format, or whitespace sweep is its own commit, never folded into a behavior change. Order commits so each one is independently coherent. Done when: each group is a single concern by the revert test, no group mixes a behavior change with a lint or whitespace sweep, and every group has its files and staging method identified.

5. Commit each group. Run the repo-native verification gate (type-checker and/or linter, whichever the repo defines) once per commit group before staging that group; a failing group is not ready to commit; skip silently if neither is configured. Stage and commit each group in a single call, naming files explicitly: never `git add -A` or `git add .`, which can sweep in sensitive files (`.env`, credentials) or unrelated changes. After committing, run `git status` to verify success and record the commit hash(es) and subject line(s) for the final report. Use a heredoc to preserve message formatting:

git add file1 file2 file3 && git commit -m "$(cat <<'EOF'
Add first-class subject line here

Optional body explaining why this change was made,
not just what changed.
EOF
)"

Done when: every group is committed with its hash and subject recorded, `git status` confirms each commit, and no `git add -A` or `git add .` was used, or a verification gate failure stopped the group and the failing group