convention-enforcement

name	convention-enforcement
description	Validate git conventions (commit messages, branch naming, PR format, issue linkage) by detecting project-specific rules from CLAUDE.md and settings, inferring patterns from recent history. Use when creating commits, preparing PRs, or reviewing for convention compliance. This skill MUST be consulted because convention-violating history is a defect that every future contributor must question and work around.
allowed-tools	Bash, Read
context	fork
agent	Explore

Convention Enforcement

Domain skill for validating git conventions across the development workflow.

Iron Law

CONVENTIONS ARE NOT OPTIONAL. A commit that violates project conventions is a defective commit, regardless of code quality.

History that violates conventions is history that every future contributor must question and work around.

Convention Sources (Priority Order)

1. CLAUDE.md — Project-specific overrides (highest priority)
2. settings.flow.json — Plugin configuration
3. Defaults — Built-in conventions (lowest priority)

CLAUDE_MD=""
[ -f ".claude/CLAUDE.md" ] && CLAUDE_MD=".claude/CLAUDE.md"
[ -z "$CLAUDE_MD" ] && [ -f "CLAUDE.md" ] && CLAUDE_MD="CLAUDE.md"

Commit Message Validation

Format

<type>(<scope>): <subject>

[optional body]

[optional footer]

Rules

• Type: Must be one of configured conventions.commitTypes (default: feat, fix, docs, style, refactor, test, chore, perf, ci, build, revert, improve)
• Scope: Optional, parenthesized, lowercase
• Subject: Imperative mood, no period
• Body: Separated by blank line

Validation

DEFAULT_BRANCH=$(gh repo view --json defaultBranchRef --jq '.defaultBranchRef.name' 2>/dev/null || echo "main")
git log --format="%s" "$DEFAULT_BRANCH"..HEAD

Check each commit subject against the format regex: ^(feat|fix|docs|style|refactor|test|chore|perf|ci|build|revert|improve)(\(.+\))?: .+$

Branch Naming Validation

Check current branch against configured patterns:

BRANCH=$(git branch --show-current)

Valid patterns (from conventions.branchPatterns):

• feature/issue-{N}-{desc} — alphanumeric + hyphens
• fix/issue-{N}-{desc}
• docs/issue-{N}-{desc}

Invalid:

• Spaces or special characters
• Missing issue number (unless explicitly configured)
• Direct commits to default branch

PR Format Validation

A valid PR must have:

• Title matching conventional commit format
• Body with at least: Summary section, linked issue reference
• Labels (at least one)
• No draft status when requesting review

Issue Linkage

Every branch should link to an issue:

ISSUE_NUM=$(echo "$BRANCH" | grep -oE 'issue-[0-9]+' | grep -oE '[0-9]+')
[ -n "$ISSUE_NUM" ] && gh issue view "$ISSUE_NUM" --json state --jq '.state' 2>/dev/null

Warn if:

• Branch has no issue number
• Linked issue is closed
• Linked issue is assigned to someone else

Project-Specific Detection

Infer conventions from existing patterns:

# Infer from recent commits
git log --oneline -20 --format="%s"
# Infer from existing branches
git for-each-ref --sort=-committerdate --format='%(refname:short)' refs/remotes/origin/ | head -10

If project uses different conventions (e.g., feat/123-description instead of feature/issue-123-description), adapt validation accordingly and note in output.

Output

Report all violations with severity:

Violation	Severity	Fix
Non-conventional commit message	P2	Amend or reword
Wrong branch naming	P3	Note only (too late to rename)
Missing issue linkage	P2	Add Closes #N to PR body
Missing PR labels	P3	Add during PR creation

Rationalization Prevention

Excuse	Response
"The convention doesn't apply to this type of change"	Check the config. If the convention is configured, it applies.
"I'll fix the commit message later"	Later doesn't exist in git history. Fix it now.