---
name: commit-msg
description: >
  Generate piker-style git commit messages from staged
  changes or prompt input. Use when the user asks for a
  commit message or invokes a commit-message command.
compatibility: >
  Requires git and a coding harness able to read and
  write files in the active checkout.
metadata:
  author: goodboy
  version: "1.0"
---

# Piker Git Commit Message Generator

Generate a commit message from the staged diff following
the piker project's conventions, learned from 500 repo
commits.

For the full style guide with verb frequencies,
section markers, abbreviations, piker-specific terms,
and examples, see
[style-guide-reference.md](./style-guide-reference.md).

## Safety

- Never run `git commit`, amend, rebase, merge, or push
  unless the user explicitly requests that operation.
- Do not stage or unstage files for a single-message run.
- Never change issue, plan, or checklist state merely
  because the related implementation is complete.
- Preserve unrelated worktree changes.

## Working Context

1. Run `git rev-parse --show-toplevel`,
   `git rev-parse --git-dir`, and
   `git rev-parse --git-common-dir`.
2. If the git dir differs from the common dir, report the
   active worktree before generating the message.
3. Inspect `git status --short`, the complete staged diff,
   `git diff --staged --check`, and recent commit history.
4. If nothing is staged, stop and tell the user. Prompt
   text may clarify intent but does not replace a staged
   patch unless the user explicitly asks for a draft with
   no staged changes.

## Message Style

- **Subject**: ~50 chars, present tense verb, use
  backticks for code refs; hard maximum 67 columns
- **Body**: only for complex/multi-file changes,
  filled close to a 67-column maximum
- **Section markers**: Also, / Deats, / Other,
- **Bullets**: use `-` style
- **Tone**: technical but casual (piker style)

Use any user-supplied scope or description as context,
but verify it against the staged patch. The message must
describe the complete staged boundary, not only the most
obvious file.

## Provenance

If staged paths include prompt-I/O log entries under
`ai/prompt-io/`, add one trailer per non-raw log file:

```
Prompt-IO: ai/prompt-io/<service>/<entry>.md
```

When the patch has substantive AI-authored changes but no
prompt-I/O entry is staged, remind the user that repository
policy may require one. Do not block message generation.

Always identify the active harness and model from runtime
context rather than hardcoding Claude Code or OpenCode.

When the harness assisted with the patch, append:

```
(this patch was generated in some part by `<harness>` using `<model>` (`<provider>`))
```

When it generated only the message, append:

```
(this commit msg was generated in some part by `<harness>` using `<model>` (`<provider>`))
```

## Output Files

Write the final message to both of these paths relative to
the active checkout returned by `git rev-parse
--show-toplevel`:

- `.claude/skills/commit-msg/msgs/<timestamp>_<hash>_commit_msg.md`
- `.claude/git_commit_msg_LATEST.md`

Use UTC `<timestamp>` format `YYYYMMDDTHHMMSSZ` and the
first seven characters of the current `HEAD` hash. Create
the archive directory when needed. The `.claude` path is a
legacy repository artifact location shared by all coding
harnesses; it does not imply which harness generated the
message.

Finish by reporting both paths and this review-first
command without running it:

```
git commit --edit --file .claude/git_commit_msg_LATEST.md
```

---

**Analysis date:** 2026-01-27
**Commits analyzed:** 500 from piker repository
**Maintained by:** Tyler Goodlet