align

name

align

description

Run a convention alignment check across the codebase to measure adherence to documented standards. Use when you want to check health of the codebase, verify convention compliance, get a scored report, find violations, check alignment before a release, or run periodic quality scans. Triggers on: "check conventions", "alignment scan", "codebase health", "are we following our standards", "convention violations", "quality check", "how aligned are we".

Convention Alignment Check

Measure codebase adherence to documented conventions. Produces a scored report across 5 categories with ~34 checks.

Usage

/align                # Full codebase scan
/align backend        # Backend checks only
/align frontend       # Frontend checks only
/align operator       # Operator checks only
/align runner         # Runner checks only
/align security       # Security checks only

User Input

$ARGUMENTS

How It Works

1. Parse scope from $ARGUMENTS (default: full scan)
2. Dispatch the convention-eval agent with the scope
   • The agent runs in its own context window
   • It loads component-level convention docs
   • It runs all checks via grep/glob/bash
   • It produces a scored report
3. Display the report to the user

Dispatching the Agent

Use the Agent tool to dispatch the convention-eval agent:

Agent({
  description: "Convention alignment check",
  prompt: "You are the convention-eval agent. Read your definition at .claude/agents/convention-eval.md, then run a ${scope} convention alignment check. Scope: ${scope} (one of: full, backend, frontend, operator, runner, security). Load all context files listed in your definition, run the checks, and report findings in the standard output format with scores."
})

If no scope is specified, run all categories.

Report Format

The agent produces a markdown report with:

• Overall weighted score (0-100%)
• Per-category scores (Backend, Frontend, Operator, Runner, Security)
• Pass/fail per check with file:line references
• Failures grouped by severity (Blocker > Critical > Major > Minor)
• Top 3 recommendations for improvement

Categories and Weights

Category	Checks	Weight	Key concerns
Backend	8	25%	panic, service account misuse, error handling
Frontend	8	25%	any types, raw HTML, manual fetch
Operator	7	20%	OwnerReferences, SecurityContext, reconciliation
Runner	4	10%	async patterns, credential handling
Security	7	20%	RBAC, token redaction, input validation

Interpreting Results

• 90-100%: Excellent alignment. Ship with confidence.
• 70-89%: Good alignment. Address blockers before merge.
• 50-69%: Moderate alignment. Technical debt accumulating.
• Below 50%: Significant drift. Prioritize convention adherence.

Any Blocker failures should be addressed immediately regardless of overall score.