How caveman-commit Manages Breaking Changes and Migration Notes in Commit Messages

caveman-commit enforces a mandatory commit body whenever a change introduces breaking modifications or data migrations, ensuring that impact details and migration steps are never omitted from the message history.

The caveman-commit tool in the JuliusBrussee/caveman repository automates commit message generation with strict rules for breaking changes and migration notes. Unlike conventional tools that allow terse subject lines, caveman-commit requires descriptive bodies for any change that alters public APIs or transforms data schemas. This approach ensures that critical context survives in the git history and remains accessible to automated tooling.

Rule Definition and Body Inclusion Policy

The foundational logic for commit composition resides in skills/caveman-commit/SKILL.md. According to lines 22-25, the tool adds a commit body only when the rationale isn't obvious from the subject line, or when the change qualifies as a breaking change, migration note, or linked issue. This conditional logic prevents unnecessary verbosity while guaranteeing that high-impact changes receive proper documentation.

Auto-Clarity Enforcement for Critical Changes

The same skill file contains an "Auto-Clarity" clause that removes ambiguity for dangerous modifications. For breaking changes, security fixes, data migrations, and reverts, the body must be present and must never be compressed into the subject line (lines 61-62). This hard requirement prevents developers from burying critical impact details in terse headers, ensuring that migration steps and breaking impacts remain discoverable.

Detection Logic in the Commit Generation Flow

When invoked via the Opencode plugin, the caveman-commit command parses the staged diff to identify specific tokens. It detects keywords such as "BREAKING CHANGE" or migration-related wording, then forces the inclusion of a body section that explains the impact and required migration steps (src/plugins/opencode/commands/caveman-commit.md, lines 4-9). This automated detection ensures that developers cannot accidentally commit breaking changes without documentation, as the system intercepts the commit flow before finalization.

Conventional Commits Syntax and Examples

The generated messages follow the Conventional Commits specification, appending a BREAKING CHANGE: trailer or explicit migration notes to the body. This standardization allows CI/CD pipelines and changelog generators to parse the commit history programmatically and trigger appropriate versioning or notification workflows.

Breaking API Change Example

Consider a route rename that affects public clients:

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.

The exclamation mark (!) in the subject line and the BREAKING CHANGE trailer signal a breaking modification, triggering the mandatory body requirement (skills/caveman-commit/SKILL.md, lines 50-56).

Data Migration Example

For database schema changes, the tool requires migration details even when the subject appears self-explanatory:

refactor(db): rename user_status column to account_state

Migration note: existing rows will be transformed by:
  UPDATE users SET account_state = CASE user_status
    WHEN 'active' THEN 'enabled'
    WHEN 'inactive' THEN 'disabled'
    END;

Even though the subject describes the action, the migration note forces body inclusion per the migration rules (lines 22-25).

Summary

• caveman-commit requires a commit body for breaking changes, security fixes, data migrations, and reverts.
• The rules are defined in skills/caveman-commit/SKILL.md, specifically lines 22-25 and 61-62.
• The Opencode plugin command (src/plugins/opencode/commands/caveman-commit.md) parses diffs to detect breaking change tokens automatically.
• Generated messages use Conventional Commits syntax with BREAKING CHANGE: trailers or explicit migration notes.
• Critical changes cannot be compressed into the subject line alone.

Frequently Asked Questions

When does caveman-commit require a commit body?

caveman-commit mandates a body when the change constitutes a breaking change, security fix, data migration, revert, or linked issue, as defined in skills/caveman-commit/SKILL.md (lines 22-25). Additionally, any change where the motivation isn't obvious from the subject line requires explanatory text.

How does caveman-commit detect breaking changes?

The tool analyzes staged diffs during the commit generation flow in src/plugins/opencode/commands/caveman-commit.md (lines 4-9), scanning for tokens like "BREAKING CHANGE" or migration-related terminology. When detected, the system forces the inclusion of a descriptive body regardless of subject line length.

What format does caveman-commit use for breaking changes?

Breaking changes follow the Conventional Commits specification, utilizing an exclamation mark (!) in the type scope and appending a BREAKING CHANGE: trailer to the body. This format ensures compatibility with automated changelog generators and semantic versioning tools.

Where are the commit rules defined in the repository?

The primary rule definitions reside in skills/caveman-commit/SKILL.md, which specifies body inclusion policies and the Auto-Clarity clause (lines 61-62). The implementation logic that enforces these rules during commit generation is located in src/plugins/opencode/commands/caveman-commit.md.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}