Commit

Read the staged diff, gate on green tests, draft a Conventional Commits message, confirm via dropdown, commit. Each commit is atomic: one concern.

0. Stage

git status --short
git diff --cached --stat
git diff --cached

Stage by explicit path only — git add -A / git add . sweeps in .env and credentials.

If nothing is staged but unstaged changes exist, ask via AskUserQuestion:

question: "Nothing staged. Stage specific files, stage all, or abort?"
header: "Staging"
options:
  - label: "Stage specific files"
  - label: "Stage all (by explicit paths)"
  - label: "Abort"

If the staged diff spans unrelated concerns, split into atomic commits: unstage the others with git restore --staged <paths> (not git reset), then stage and commit one concern at a time. Ask when the split is unclear:

question: "These changes span <N> concerns. Split?"
header: "Split"
options:
  - label: "Yes, split (Recommended)"
  - label: "One commit"
  - label: "Show me the diff first"

Done when exactly one concern is staged.

1. Test gate

Run the project's checks and test suite (uv run pytest, npm test — whatever the project defines) and read the summary, not just the exit code. When the repo has a turbo.json, run them through Turborepo: turbo run <tasks> with the check and test task names that turbo.json defines. Unchanged tasks replay from the cache, so the gate stays fast. Follow the repo's instructions for how to call the installed turbo; its flags differ between versions.

The gate is binary: green proceeds; red stops here — the pre-commit hook fails on the same issues, so catching them now saves a wasted commit:

question: "Tests red — commit blocked. How to proceed?"
header: "Test gate"
options:
  - label: "Investigate via /diagnosing-bugs (Recommended)"
  - label: "Abort commit"
  - label: "Show me the failing tests"

2. Draft the message

Load write-simply and write the subject and body in its register. Draft from the why of the staged diff: what motivated the change, where a line-by-line list would only restate git diff.

Changelog projects. When the repo keeps a hand-written CHANGELOG.md (a release tool such as release-please or git-cliff does not generate it from commits), a commit with a user-facing change carries its changelog entry, so git log --grep finds the commit that added a feature:

• The staged diff adds the entry under ## [Unreleased], written by the project's changelog rules (AGENTS.md, CONTRIBUTING.md). If it is missing, write it and stage it before you draft the message.
• The subject names the change from the user's side, as the entry does.
• The body starts with the entry, word for word, under its section name (Added:, Fixed:, ...). The why and internal details follow.
• A commit with no user-facing change (refactor, test, CI) adds no entry.

Conventional Commits format:

<type>(<optional-scope>): <summary>

<optional body>

Types: feat, fix, docs, refactor, test, chore, perf, ci. chore covers build, config, and deps.

Subject: 20–72 chars after the prefix · lowercase after the colon (feat: add X) · imperative ("add") · ends on the object, no punctuation · concrete verb + object.

Body (only when the subject can't carry it, or a changelog entry opens it): blank line after the subject, then one terse bullet per entry, imperative voice, grouped under short headings that match the kind of change — Added, Changed, Fixed, Removed, Breaking. Skip headings when there's only one bullet.

feat(installer): add gateway runtime extraction

Added:
- core/gateway_runtime/ with Protocol-based registry
Changed:
- opencode_runtime now delegates to gateway_runtime

Reference the issue or ticket when the project tracks them. Session context, PR/MR numbers, and future work stay out.

The message ends at the last body line. The human is the sole author: the author field carries their name and the message carries no trailer, footer, or link naming a tool or session. This also holds for everything written downstream of a commit (PR/MR titles and descriptions, release notes) and outranks any harness default that asks for a footer.

Done when every rule above holds and each word in the message names something in the diff.

3. Confirm via dropdown

question: "Commit with this message?"
header: "Commit"
options:
  - label: "Commit (Recommended)"
    preview: |
      <full message>
  - label: "Edit message"
  - label: "Abort"

4. Commit

git commit -m "$(cat <<'EOF'
<type>(<scope>): <summary>

<body>
EOF
)"

If the project wires a pre-commit hook, it runs now:

• Pass → git log -1 shows the new commit
• Autofixes → hook stages them; the commit captures them
• Unfixable → hook blocks; go to step 5

5. On hook failure

The hook is the messenger; fix the cause in the code:

• lint → fix the code
• types → fix the types
• tests → /diagnosing-bugs; three failed fix attempts = stop and report
• complexity / architecture gates → refactor, or ask before accepting a borderline score

Then re-stage and go back to step 3 for a new commit: the failed commit never happened, and --amend would rewrite the one before it.

Hard guardrails

• The hook's verdict stands. Bypass flags (--no-verify, --no-gpg-sign) and suppression comments (# noqa, # type: ignore, eslint-disable) stay unused; the fix goes in the code.
• Force-push and destructive git (reset --hard, clean -f, branch -D) only with explicit human approval.