Conventional Commit

This skill enacts the Algorithms Before Tokens axiom from MANIFESTO.md by encoding commit message conventions as a reusable procedure, eliminating per-session re-prompting overhead. Commit discipline is governed by AGENTS.md § Commit Discipline and CONTRIBUTING.md § Commit Discipline. When this skill and those documents conflict, the primary documents take precedence.

1. Format

<type>(<scope>): <description>

[optional body]

[optional footer(s)]

Rules for the first line:

• Imperative mood: "add", "fix", "update" — not "adds", "fixed", "updating"
• Lowercase throughout (type, scope, description)
• No period at the end of the description
• Maximum 72 characters for the first line
• Scope is in parentheses, not brackets

Valid: docs(guides): add session-management skill reference Invalid: Updated the docs. / DOCS: Updates guides / docs(guides): Added session-management skill reference.

2. Types

Do not use feat for documentation. A new research doc is docs(research), not feat(research). A new guide is docs(guides).

3. Scopes

Scopes are lowercase, single-word identifiers describing the affected area of the codebase:

Scope is optional but strongly encouraged for this repo — it makes git log --oneline readable and enables filtered history queries (e.g., git log --oneline -- scripts/).

4. Multi-Line Body Format

For commits that benefit from explanation (why, not just what), add a body after a blank line:

docs(agents): add session-management skill body section

The session-close procedure previously lacked the issue-comment step.
Added steps 6.2 and 6.3 to encode the gh issue comment + checkbox update
sequence from AGENTS.md § Agent Communication.

Closes #42

Body guidelines:

• Separate from the first line with exactly one blank line
• Wrap at 72 characters
• Explain why the change was made, not what (the diff shows what)
• Issue references on their own line at the end

Issue reference formats:

• Closes #N — closes the issue when the commit lands on main (via PR merge)
• Refs #N — references without closing
• Part of #N — partial progress on a larger issue

5. Breaking Changes

Inline ! suffix

For a breaking change in the first line:

feat(agents)!: rename executive-researcher to research-executive

BREAKING CHANGE footer

For breaking changes with a description:

refactor(scripts): consolidate fetch scripts into single entry point

BREAKING CHANGE: fetch_source.py and fetch_all_sources.py now require
--manifest flag; direct URL argument is removed. Update any scripts
or CI steps that call these with bare URLs.

Both methods are valid. Use ! for simple renames/removals; use the footer when a migration note is needed.

6. Examples Representative of This Repo

# New agent added to the fleet
feat(agents): add executive-docs agent for documentation governance

# Bug fix in a script
fix(scripts): correct branch slug calculation for paths with multiple slashes

# Research synthesis doc added
docs(research): add agent-skills-integration synthesis — status: Final

# ADR committed
docs(decisions): add ADR-006 agent skills adoption

# CI gate added
ci: run validate_skill_files.py on PRs touching .github/skills/

# Workplan created at session start
docs(plans): add 2026-03-07-agent-skills-implementation workplan

# Pre-compact safety commit (no scope needed)
chore: pre-compact checkpoint — session state saved to scratchpad

# Dependency update
chore(deps): bump uv.lock after adding mkdocs-material

# Test coverage for a new script
test(scripts): add tests for scaffold_workplan.py happy path and error exits

# Docs-only correction (no functional change)
docs(guides): fix broken link to session-synthesis source stub

7. What NOT to Do

8. Commit Cadence

Per CONTRIBUTING.md § Commit Discipline: commit frequently as you complete each logical unit of work — not one giant commit at the end of a session.

This repo uses rebase and merge only — squash merge is disabled. Every commit message lands on main individually, so every commit message must be valid and meaningful standing alone.

9. Governing Constraint

This skill is governed by AGENTS.md § Commit Discipline and CONTRIBUTING.md § Commit Discipline. The Conventional Commits specification is at conventionalcommits.org.

The encoding inheritance chain is:

MANIFESTO.md → AGENTS.md → agent files → this skill → session behaviour.

A commit message is not decoration — it is the durable record of a logical change. Low-quality messages degrade the endogenic substrate: future sessions cannot reconstruct intent from history, and CI cannot identify regressions by type. Write commit messages as if a future agent will rely on them to understand the codebase.