atomic-git-discipline

Files (1)

• SKILL.md

SKILL.md (first lines)

> Adapted from [Atomic Claude](https://github.com/damusix/atomic-claude) at `b4ca195cae6022464b0cc5c07273b3fa9602da17`. Invoke in Codex CLI as `$atomic-git-discipline`. Commands beginning with `atomic` require the Atomic CLI; Atomic Claude slash commands and hooks are specific to Claude Code.



<trigger>

- "write a commit", "commit message", "generate commit"
- "open a PR", "PR description", "PR body", writing `gh pr create --body`
- Staging changes for commit
- Ship verbs delegating message format
- Read directly by subagents briefed to create a commit or open a PR (per `CLAUDE.md` Commits & PRs — subagents can't auto-fire skills)

</trigger>

Write commit messages terse and exact. Conventional Commits. No fluff. Why over what.

## Rules

**Subject line:**

- `<type>(<scope>): <imperative summary>` — `<scope>` optional
- Types: `feat`, `fix`, `refactor`, `perf`, `docs`, `test`, `chore`, `build`, `ci`, `style`, `revert`
- Imperative mood: "add", "fix", "remove" — not "added", "adds", "adding"
- ≤50 chars when possible, hard cap 72
- No trailing period
- Match project convention for capitalization after the colon

**Body (only if needed):**

- Skip entirely when subject is self-explanatory
- Add body only for: non-obvious *why*, breaking changes, migration notes, linked issues
- Hard cap: 4 lines / 2 bullets. One why-sentence beats a paragraph.
- Never restate what the diff shows — file lists, renamed symbols, mechanical changes
- Wrap at 72 chars
- Bullets with `-`, not `*`
- Reference issues/PRs at end: `Closes #42`, `Refs #17`

**Omit from commit messages:**

- "This commit does X", "I", "we", "now", "currently" — the diff says what
- "As requested by..." — use `Co-authored-by:` trailer instead
- AI-generation attribution or co-author trailers, including `Co-Authored-By: Claude`, unless the user or repository explicitly requires them
- Emoji (unless project convention requires)
- Restating the file name when scope already says it

## Examples

<examples>

<example>
Diff: new endpoint for user profile with body explaining the why

- Bad: `feat: add a new endpoint to get user profile information from the database`
- Good:

    ```
    feat(api): add GET /users/:id/profile

    Mobile client needs slim profile payload to cut LTE bandwidth on
    cold-launch screens.

    Closes #128
    ```
</example>

<example>
Diff: breaking API change

- Good:

    ```
    feat(api)!: rename /v1/orders to /v1/checkout

    BREAKING CHANGE: clients on /v1/orders must migrate to /v1/checkout
    before 2026-06-01. Old route returns 410 after that date.
    ```
</example>

</examples>

## Auto-Clarity

Always include body for: breaking changes, security fixes, data migrations, anything reverting a prior commit. Never compress these into subject-only — future debuggers need the context. The body cap still applies: 2-3 lines stating the break/risk and the migration path, not a narrative.

## PR titles and bodies

Same discipline, higher stakes. A PR body is read by people who weren't in the session — often maintainers with no context — so its length is a cost every reviewer pays, and a long body buries the two sentences they actually needed.

**Title:** imperative, ≤70 chars, no trailing period.

The `<type>:` prefix is not cosmetic — on a squash merge the title *becomes* the commit subject on the base branch, and it is the only line a changelog generator reads. A prose title on a squash-merged PR ships the work invisibly: the branch's own conventional commits survive only as body bullets, which release-please and its siblings do not parse for a type. Nothing fails; the release just comes out empty.

So the prefix is required whenever the project uses Conventional Commits and the PR may be squash-merged — which is any project whose merge button you do not control. Pick the type by the same user-visible-impact rule as a commit subject, and apply it to the whole PR: highest impact wins, `feat:` for new behavior, `fix!:` for anything removed or renamed. Only when the project does not use Conventional Commits at all does the title go bare.

A merge-commit merge is the exception that hides this: it keeps every commit on the branch, so release-please reads them directly and the title never matters. Do not let a repo's merge-commit history convince you the title is free — the next merge may be a squash.

**Body — state only what the diff can't show:**

- Hard cap ~120 words / 3 short paragraphs. Over that means investigation notes leaked in.
- Include only: why the change was necessary, why this approach over the obvious alternative, and any decision a reviewer would otherwise flag as a mistake.
- Cut anything a reviewer learns by opening the Files tab — which files changed, dependency bumps, tooling swaps, version pins, new exports, added tests, coverage numbers.
- Evidence that convinced *you* is not reviewer-facing: mutation tests, resolution traces, package listings, install probes, benchmark output. State the decision and its one-line reason. The trail belongs in the project's own docs (`docs/design/`, `docs/spec/`, roadmap, wiki) or nowhere — never both.
- Local and process detail does not exist for the reader. Branch and worktree names, rebases, squashes, force-pushes, iteration or checkpoint counts, regenerated build outputs, scratchpad paths, "as discussed earlier" — none of it is visible in the repo a reviewer opens, and none of it changes their judgment. They see a diff and a body, not the session that produced them.
- Every cross-reference must resolve for a stranger. Link it or cut it: `#123`, a full URL, or a repo-relative path that exists on the default branch once merged. A bare mention ("see the design doc", "per the spec", "as the other session found") is a dead end for anyone who wasn't there. A pointer to a local path, a scratchpad file, or an unmerged branch is worse — it reads as actionable and isn't.

**Screenshots, when the change has a rendered surface:**

- A change a reviewer would otherwise have to run to see — a UI, a docs-site page, terminal output — carries a screenshot of the new state; a fix carries a before and after pair. A change with no rendered surface carries none.
- One line per image, after the prose, referencing the local file with a caption: `![Plans on the realm root](tmp/shots/plans-root.png)`. The caption says what the reader is looking at, not what changed.
- The invoking ship verb uploads each file with `gh pr create --attach '<path>#<caption>'` (GitHub CLI 2.99.0 or newer) and rewrites the path into a hosted `user-attachments` URL. This skill names the files and writes the captions; it never uploads.

**Omit from PR bodies:**

- Test plans, "How to verify", reproduction steps — CI runs the tests, reviewers read them in the diff
- Enumerated file lists and per-file summaries
- Section headings on a body under 120 words — scaffolding pretending to be structure
- Restating the title in the opening line
- AI attribution, in any form

From Shamanbenny/agent-tools, MIT.

More from Shamanbenny/agent-tools