convention-enforcement · diff
git:20260506.b1f0fef to git:20260909.6778255
16 added, 80 removed. Audit A to A.
---
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)
-
- ```bash
- 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>
+ ## Contract
- [optional body]
+ Iron law: **a commit that violates project conventions is defective regardless of code quality; conventions are not optional.** Invoked by `/flow:commit` Phase 4 (message generation and validation) and by the `convention-checker` agent during `/flow:pr` and `/flow:address` reviews. Reads rules from CLAUDE.md, then `conventions.*` settings, then defaults; infers project-specific patterns from recent history when they differ. Returns a violation table (violation, P2/P3 severity, fix) covering commit messages, branch name, PR format, and issue linkage, or an explicit "no violations". Permitted skips: none — an unconfigured rule is reported as inferred, never treated as absent.
- [optional footer]
- ```
+ ## Convention Sources (priority order)
- ### Rules
+ 1. **CLAUDE.md** — `.claude/CLAUDE.md`, else `CLAUDE.md` (highest priority)
+ 2. **settings.flow.json** — `conventions.commitTypes`, `conventions.branchPatterns`
+ 3. **Defaults** below (lowest priority)
- - **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
+ ## Commit Messages
- ### Validation
+ Format `<type>(<scope>): <subject>`, optional body and footer separated by blank lines. Type must be one of `conventions.commitTypes` (default: feat, fix, docs, style, refactor, test, chore, perf, ci, build, revert, improve); scope optional, parenthesized, lowercase; subject imperative, no trailing period.
```bash
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:
-
- ```bash
- BRANCH=$(git branch --show-current)
- ```
+ Check each subject against `^(feat|fix|docs|style|refactor|test|chore|perf|ci|build|revert|improve)(\(.+\))?: .+$` with the configured types substituted.
- Valid patterns (from `conventions.branchPatterns`):
- - `feature/issue-{N}-{desc}` — alphanumeric + hyphens
- - `fix/issue-{N}-{desc}`
- - `docs/issue-{N}-{desc}`
+ ## Branch Names
- Invalid:
- - Spaces or special characters
- - Missing issue number (unless explicitly configured)
- - Direct commits to default branch
+ `git branch --show-current` must match a `conventions.branchPatterns` entry — defaults `feature/issue-{N}-{desc}`, `fix/issue-{N}-{desc}`, `docs/issue-{N}-{desc}`, alphanumeric plus hyphens. Invalid: spaces or special characters, missing issue number (unless explicitly configured), commits directly on the default branch.
- ## PR Format Validation
+ ## PR Format
- 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
+ Title in conventional-commit format; body with at least a Summary section and a linked issue reference; at least one label; not draft when requesting review.
## Issue Linkage
- Every branch should link to an issue:
-
```bash
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
+ [ -n "$ISSUE_NUM" ] && gh issue view "$ISSUE_NUM" --json state,assignees 2>/dev/null
```
- Warn if:
- - Branch has no issue number
- - Linked issue is closed
- - Linked issue is assigned to someone else
+ Warn when the branch has no issue number, the linked issue is closed, or it is assigned to someone else.
## Project-Specific Detection
- Infer conventions from existing patterns:
-
```bash
- # 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.
+ If the project uses different conventions (e.g. `feat/123-description`), validate against the observed pattern and say so in the output. A configured convention applies to every change type — there is no "doesn't apply to this kind of change". A bad message is fixed now; "later" does not exist in git history.
## 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. |