jpmschweitzerandClaude Opus 4.7
bf3659d1a5
The per-commit clerk had three flaws, exposed by a 20-commit push where 6 of 7
rejections were false (incl. a CHANGELOG-only commit):
1. No-verdict / max-turns / timeout defaulted to REJECTED — an unfinished review
read as 'hard contradiction found'. Now a third outcome, INCOMPLETE, which is
non-blocking (the push proceeds with a warning); only a real REJECTED blocks.
2. Turn/time budget too tight (6 turns / 150s) for decision-heavy commits. Raised
defaults to 15 turns / 300s, and the prompt now biases to APPROVED when no
concrete contradiction is found ('unsure' means APPROVED, never REJECTED).
3. The skip valve matched its own feature commit because it scanned for the token
anywhere in the message. Moved to a trailer-line match so prose/subject mentions
no longer trip it.
Pre-push hook updated to treat INCOMPLETE as a non-blocking warning. The git-commit
skill documents the trailer form.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
174 lines
5.7 KiB
Markdown
174 lines
5.7 KiB
Markdown
---
|
|
name: git-commit
|
|
description: >
|
|
Commit changes with clean, structured messages. Use when the user says
|
|
"commit", "save my work", "commit changes", or invokes /git-commit. Enforces
|
|
conventional commit format, groups changes into logical commits, and maintains
|
|
CHANGELOG.md. Never squash unrelated changes into one commit.
|
|
user-invocable: true
|
|
allowed-tools: Bash, Read, Grep, Glob, Write, Edit
|
|
---
|
|
|
|
# Commit Skill
|
|
|
|
## Workflow
|
|
|
|
1. Run `git status` and `git diff --stat` to assess all pending changes.
|
|
2. **Triage: session vs pre-existing.** Separate changes you made in this
|
|
session from changes that were already dirty when the session started.
|
|
Check the conversation history — if you didn't touch a file, it's
|
|
pre-existing. After grouping your own commits, surface any remaining
|
|
modified or untracked files to the user:
|
|
|
|
> These files are also modified/untracked but weren't part of this
|
|
> session's work:
|
|
> - `path/to/file` — <brief description of the diff>
|
|
> - `path/to/other` — <untracked, N files>
|
|
>
|
|
> Should any of these be included in a commit?
|
|
|
|
Wait for the user's answer before staging them. Never silently skip
|
|
or silently include pre-existing changes.
|
|
3. Group changes into **logical commits** — each commit should represent one
|
|
coherent change. Common groupings:
|
|
- A bug fix (all files touched to fix one issue)
|
|
- A new feature or system (e.g., new trait files + localization + events)
|
|
- Refactoring / cleanup (encoding fixes, comment fixes, renaming)
|
|
- Config / meta changes (CLAUDE.md, .claude/ skills, mod descriptor)
|
|
- Data corrections (province remapping, missing fields)
|
|
4. For each logical group, stage only the relevant files and commit with a
|
|
properly formatted message.
|
|
5. After all commits, update CHANGELOG.md.
|
|
|
|
## Commit Message Format
|
|
|
|
```
|
|
<type>(<scope>): <short summary>
|
|
|
|
<optional body — what and why, not how>
|
|
|
|
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
|
|
```
|
|
|
|
### Types
|
|
|
|
| Type | Use for |
|
|
|------|---------|
|
|
| `feat` | New game system, mechanic, or feature |
|
|
| `fix` | Bug fix — crashes, logic errors, broken references |
|
|
| `refactor` | Code restructuring without behavior change |
|
|
| `chore` | Build, config, tooling, skills, CLAUDE.md, infrastructure |
|
|
| `docs` | Documentation, design docs, discussion logs, briefings |
|
|
| `data` | Game data changes — entity definitions, map templates, balance values |
|
|
| `loc` | Localization additions or corrections |
|
|
|
|
### Scope
|
|
|
|
Use the project subsystem as scope. Examples:
|
|
- `agents` — agent personality files (.claude/agents/)
|
|
- `skills` — skill definitions (.claude/skills/)
|
|
- `docs` — design documents, architecture docs
|
|
- `briefings` — agent briefing files (docs/briefings/)
|
|
- `discussions` — discussion round archives
|
|
- `schema` — database schema changes
|
|
- `db` — database operations, connector scripts
|
|
- `config` — project configuration, endpoints
|
|
- `simulation` — game simulation server-side code
|
|
- `client` — game client code, rendering
|
|
- `engine` — engine-level systems (ECS, chunk loading, etc.)
|
|
- `ui` — user interface, HUD, insert/minimap
|
|
- `audio` — sound system, audio propagation
|
|
- `assets` — visual assets, sprites, art
|
|
- `meta` — project config, CLAUDE.md, team roster
|
|
|
|
### Rules
|
|
|
|
- Summary line: imperative mood, lowercase, no period, max 72 chars.
|
|
- Body: wrap at 72 chars. Explain *why* the change was made.
|
|
- Never combine unrelated changes (e.g., don't mix a crash fix with new features).
|
|
- When in doubt, prefer more smaller commits over fewer large ones.
|
|
|
|
### Clerk safety valve (`Clerk-Skip:` trailer)
|
|
|
|
The pre-push clerk reviews each commit for D-record consistency. For a pure bulk
|
|
content commit — e.g. shipping thousands of generated planetary description files
|
|
— that review is moot and just burns agents on noise. Add a `Clerk-Skip:` **trailer
|
|
line** to the commit message and `tooling/clerk-review` auto-approves that commit
|
|
without spawning an agent. Use it only for content/data dumps, never for commits
|
|
that touch `decisions/`, code, or ticket-bearing work.
|
|
|
|
It must be a trailer (a line starting with `Clerk-Skip:`), not inline prose — that
|
|
way a commit that merely *mentions* the token in its subject or body isn't skipped.
|
|
|
|
```
|
|
data(content): generate 5000 planetary description files
|
|
|
|
Clerk-Skip: bulk generated content, no D-record surface
|
|
```
|
|
|
|
### Examples
|
|
|
|
```
|
|
feat(simulation): add LOS shadowcasting for vision cone
|
|
|
|
Implements 2D shadowcasting per z-level with forward/peripheral/
|
|
blind spot zones per D-011 and D-015 specifications.
|
|
```
|
|
|
|
```
|
|
docs(discussions): archive round 13 engine selection debate
|
|
|
|
Split completed round from DISCUSSION.md into per-round archive.
|
|
Updated briefings for Tyre and Troblum with new requirements.
|
|
```
|
|
|
|
```
|
|
chore(agents): add Stig UI developer agent
|
|
|
|
Standby agent for UI implementation phase. Configured with
|
|
briefing reference and Settled Reach-themed personality.
|
|
```
|
|
|
|
## CHANGELOG.md Format
|
|
|
|
Maintain `CHANGELOG.md` in the project root. Use Keep a Changelog format:
|
|
|
|
```markdown
|
|
# Changelog
|
|
|
|
## [Unreleased]
|
|
|
|
### Added
|
|
- New feature descriptions
|
|
|
|
### Fixed
|
|
- Bug fix descriptions
|
|
|
|
### Changed
|
|
- Change descriptions
|
|
```
|
|
|
|
Group entries under: Added, Fixed, Changed, Removed. Write entries from the
|
|
player/modder perspective, not implementation details.
|
|
|
|
After committing, read the existing CHANGELOG.md (create if missing), prepend
|
|
new entries under `[Unreleased]`, and commit the changelog update separately as:
|
|
|
|
```
|
|
chore(meta): update changelog
|
|
```
|
|
|
|
## Version Tracking
|
|
|
|
Version is tracked in CHANGELOG.md. When the user bumps the version,
|
|
move `[Unreleased]` entries under a new version heading and commit as:
|
|
|
|
```
|
|
chore(meta): release v0.1.0
|
|
```
|
|
|
|
## Staging Rules
|
|
|
|
See `.claude/rules/git-safety.md` for staging rules (always-loaded).
|
|
These apply to ALL git operations, not just this skill.
|