git-authoring AGENTS.md

Git authoring conventions

Commit-message and pull-request conventions for this repository. Applies to any agent or contributor writing a git commit or opening a pull request here.

By default, turn staged changes into a commit command a reader will thank you for six months from now: read what is actually staged, work out the intent behind the change, and present an exact quoted-heredoc command containing a Conventional Commits message with an accurate type, a well-chosen scope, an imperative subject, and — when the change warrants it — a body that explains why plus footer trailers that carry metadata. When asked, also choose which unstaged files belong together and present staging plus commit commands, write complete pull-request content, write the release note for a version, review an incoming pull request and hand the maintainer the text to paste, work the repository itself — branches, rebases, conflicts, recovery — or carry out staging, committing, and pushing. Getting the shape right (type(scope): subject) is table stakes. The value is in choosing the right type, writing a subject that says what changed, and recording the reasoning the diff itself can't show.

Usage modes

Choose exactly one mode from the user's request.

1. Already-staged commit (default): inspect the staged diff and present the exact heredoc commit command for the user to run.
2. Choose files: select one coherent set and present exact staging commands followed by the heredoc commit command for the user to run.
3. Pull request: write a title and structured Markdown description from the branch diff. Do not open it.
4. Autonomous stage, commit, and push: run those operations end to end only when the user unmistakably asks the agent to do the work itself, such as "stage, commit, and push this for me" or "do it all yourself." On a further explicit request, this mode may also tag and publish a release.
5. Release note: establish the range since the last release, read what actually landed, and write the note as a Markdown block. Do not tag, publish, or write a file.
6. Review an incoming pull request: read someone else's PR through gh, work the decision through with the user, and write the review comment or the merge-commit message as a Markdown block for them to paste. Do not approve, request changes, comment, or merge.
7. Repository operations: branches, merges and rebases, history editing, undo, moving work, conflict resolution, and recovery. Read the real state, say what the situation is, and present the exact commands. Execute only under the mode 4 request.