---
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. 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)
3. For each logical group, stage only the relevant files and commit with a
   properly formatted message.
4. 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.

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