/spec-commit

name: spec-commit
description: Internal commit helper for public workflows that already hold explicit commit authorization; creates scoped, value-communicating commits without owning push or PR landing.
user-invocable: false

Git Commit

Create a single, well-crafted git commit from the current working tree changes.

Invocation And Authorization Boundary

This is an internal-only helper. A public workflow may delegate here only after the current user or a visible upstream handoff has established `commit_authorization: authorized` for the intended run-owned paths. Record branch authority separately:

commit_authorization: authorized | missing
branch_mutation_authorization: authorized | missing

`workflow invocation does not authorize commit`; tool permission, a dirty tree, a branch name, or successful verification are execution facts, not authority. Explicit commit authorization does not imply branch mutation authorization. When any commit intent is expressed while commit authorization is missing, stop before branch mutation, staging, or commit and return `commit_authorization_missing`. When a checkout or new branch is needed but branch authority is missing, stop before that Git mutation and return `branch_mutation_authorization_missing` or obtain approval for the exact branch action. A pure status question about uncommitted changes (no commit intent expressed) does not trigger this gate: answer the query directly, mutate nothing, and do not stage or commit.

This helper owns commit composition and the authorized commit checkpoint only. It does not own push, PR creation/update, plan lifecycle, or unrelated dirty paths. If branch creation would be required, obtain explicit approval for that concrete branch mutation before creating it.

Context

Gather Git context by running each command as its own argv-style shell tool call. Do not join commands with shell separators, pipes, substitutions, or redirects; those forms are host-shell-specific and can hide the real exit status.

| Command | Purpose | Non-zero or empty result | | --- | --- | --- | | `git status` | Working-tree state | Not a Git repository: stop | | `git diff HEAD` | Uncommitted changes | An unborn repo may have no `HEAD`; inspect tracked changes directly | | `git branch --show-current` | Current branch | Empty output means detached HEAD | | `git log --oneline -10` | Commit-message convention | An unborn repo has no history | | `git rev-parse --abbrev-ref origin/HEAD` | Remote default branch | Resolve it using the fallback in Step 1 |

These facts are a snapshot. Re-read the branch and staged paths immediately before committing because the working tree may change after intake.

---

Workflow

Step 1: Gather context

Run every command in the Context section as a separate shell tool call.

The remote default branch value returns something like `origin/main`. Strip the `origin/` prefix to get the branch name. If the command exited non-zero or returned a bare `HEAD`, try:

gh repo view --json defaultBranchRef --jq '.defaultBranchRef.name'

If both fail, fall back to `main`.

If the git status from the context above shows a clean working tree (no staged, modified, or untracked files), report that there is nothing to commit and stop.

If the current branch from the context above is empty, the repository is in detached HEAD state. Explain that a branch is required if the user wants this work attached to a branch. When `branch_mutation_authorization: missing`, ask whether to create the exact proposed feature branch now and do not run checkout first. Use the platform's blocking question tool: `AskUserQuestion` in Claude Code (call `ToolSearch` with `select:AskUserQuestion` first if its schema isn't loaded) or `request_user_input` in Codex. Fall back to presenting options in chat only when no blocking tool exists in the harness or the call errors (e.g., Codex edit modes) — not because a schema load is required. Never silently skip the question.

• If the user authorizes the displayed branch creation, set `branch_mutation_authorization: authorized`, derive the name from the change content, create it with `git checkout -b <branch-name>`, then run `git branch --show-current` again and use that result as the current branch name for the rest of the workflow.
• If the user declines, continue with the detached HEAD commit.

Step 2: Determine commit message convention

Follow this priority order:

1. **Repo conventions already in context** -- If project instructions (AGENTS.md, CLAUDE.md, or similar) are already loaded and specify commit message conventions, follow those. Do not re-read these files; they are loaded at session start. 2. **Recent commit history** -- If no explicit convention is documented, examine the 10 most recent commits from Step 1. If a clear pattern emerges (e.g., conventional commits, ticket prefixes, emoji prefixes), match that pattern. 3. **Default: conventional commits** -- If neither source provides a pattern, use conventional commit format: `type(scope): description` where type is one of `feat`, `fix`, `docs`, `refactor`, `test`, `chore`, `perf`, `ci`, `style`, `build`.

When using conventional commits, choose the type that most precisely describes the change (the type list above). Where `fix:` and `feat:` both seem to fit, default to `fix:`: a change that remedies broken or missing behavior is `fix:` even when implemented by adding code. Reserve `feat:` for capabilities the user could not previously accomplish. Other types remain primary when they fit better. The user may override for a specific change.

Step 3: Consider logical commits

Before staging everything together, scan the changed files for naturally distinct concerns. If modified files clearly group into separate logical changes (e.g., a refactor in one directory and a new feature in another, or test files for a different change than source files), create separate commits for each group.

Keep this lightwe