settled-reach/.claude/skills/git-commit/SKILL.md

name, description, user-invocable, allowed-tools

name	description	user-invocable	allowed-tools
git-commit	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.	true	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 —
   • 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 governance/, 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:

# 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.