Commit message specification

Commit format for a2c-workflow, aligned with LibESys repository policy. Enforced locally via gitlint and pre-commit (commit-msg hook).

Goals

• Readable history (git log --oneline)
• Consistent intent via type and optional scope
• Visible architectural decisions via adr commits
• Explicit AI assistance and breaking changes

Message structure

<title line>

<optional body>

<optional footers>

• Blank line between title and body
• Blank line between body and footers
• Title ≤ 72 characters
• Body/footer lines ≤ 100 characters

Title line

[WIP: ]<type>[<scope>][!]: <subject>

Allowed types

Type	Use for
adr	Architectural decision records — one ADR per commit
build	Build or toolchain policy docs
chore	Repo hygiene, hooks, version bumps
ci	GitLab CI or automation
docs	Documentation, rules, templates, prompts
feat	New workflow capability
fix	Corrections to policy, adapters, or docs
perf	Performance-related policy (rare)
refactor	Restructure without semantic policy change
revert	Revert a prior commit
style	Formatting only
test	Tests only (rare in this repo)

ADR commits

adr(<category>): <short summary>

Examples:

adr(workflow): Establish a2c-workflow as the canonical A2C repository
adr(workflow): Adopt A2C workflow v1.0
adr(build): Use CMake and Conan as core toolchain
adr(layout): Keep public headers under include
adr(docs): Use Markdown docs-as-code

The first example applies to a2c-workflow only. The adoption example applies to downstream A2C-based projects.

ADR commits must contain only the ADR file, index updates, and supersession links. See pathname:///a2c-assets/rules/03-adr-commits.md.

Non-semantic maintenance on Accepted ADRs (typos, broken links) uses docs(adr): or fix(adr): — not adr(...). See pathname:///a2c-assets/rules/08-adr-editing-evolution.md.

Recommended scopes

docs, cursor, templates, rules, prompts, profiles, hooks, workflow

Rules: lowercase; characters a-z, 0-9, ., _, /, -.

Subject style

• Imperative mood: Add ADR structure, not Added…
• Start with uppercase after :
• No trailing period

Examples:

docs: Add ADR structure and A2C core workflow docs
chore: Bootstrap a2c-workflow repository skeleton
feat(prompts): Add implementation batch prompt family

Footers

AI: (optional)

Value	Meaning
yes	AI-assisted
no	No AI assistance
mixed	Multiple tools or substantial human edit

At most one AI: footer per commit.

BREAKING CHANGE:

Required when the title includes ! after type/scope.

WIP commits

WIP: prefix allowed on topic branches only — not on develop, master, release/*, or hotfix/*.

Git author

Commits must list the human operator as author, even when AI helped.

Validation

Rule	Value
Title max length	72
Body line max length	100
Title regex	See .gitlint (includes adr type)

Setup

./scripts/setup-dev.sh

See development-workflow.md and commit-checklist.md.