Enforcement Agent

Enforcement Agent Skill

Create an agent that automatically checks code changes against documented standards in real-time.

Context

An enforcement agent runs automatically before/after code edits to verify compliance. Unlike ceremonies (which are human-driven reviews), enforcement agents provide instant feedback while you're writing code.

Domain Context

The Standards Enforcer Agent checks code against standards and reports violations with specific fixes. It reads:

1. Changed files (from git diff or provided list)
2. Applies a file-to-standards mapping
3. Reads applicable standards
4. Checks code against each rule
5. Reports violations with severity and fixes

Reference: levels/L3-enforcement/agents/standards-enforcer.md

Instructions

1. Define file-to-standards mapping — Which files trigger which standards?

   • Create a mapping table: File Pattern → Applicable Standards
   • Example:

     *.ts, *.tsx → docs/standards/engineering/typescript.md
     src/api/** → docs/standards/engineering/api-design.md
     *.md → docs/standards/quality/documentation.md
     

   • Be specific about patterns (use glob format)
   • One file pattern can map to multiple standards
   • Deliverable: Complete file-to-standards mapping

2. Set severity levels — Categorize violations by impact

   • ERROR — Blocks merge, violates security or core principles
   • WARN — Should be fixed, degrades maintainability/accessibility
   • INFO — Nice to fix, style/preference
   • For each standard rule, determine its severity
   • Document why: "ERROR because of security implication"
   • Deliverable: Standards with severity levels assigned

3. Write output format — How should violations be reported?

   • Standard format (see reference):

     [SEVERITY] file:line
     Rule: standard#section
     Expected: [what rule requires]
     Found: [what code does]
     Fix: [concrete code example]
     

   • Deliverable: Output format template

4. Integrate with PR workflow — Where does enforcement happen?

   • Option A: Pre-hook (before tool use) — Catches obvious violations early
   • Option B: Post-hook (after tool use) — Catches complex violations after code written
   • Option C: As explicit command — User runs /enforce to check
   • Choose based on team preferences (balance between helpfulness and interruption)
   • Deliverable: Decision on integration point

5. Test with examples — Verify agent works correctly

   • Create 3-5 test scenarios: compliant code, code with WARNING, code with ERROR
   • Run agent on test scenarios
   • Verify: Correct violations detected, severity assigned correctly, fixes are actionable
   • Deliverable: Test results showing agent works as expected

6. Document [CUSTOMIZE] markers — Make agent reusable across projects

   • Standard names that will change between projects: [CUSTOMIZE]
   • File paths that are project-specific: [CUSTOMIZE]
   • Severity levels that might differ: [CUSTOMIZE]
   • Deliverable: Agent definition with [CUSTOMIZE] markers for portability

Anti-Patterns

1. Hardcoding rules instead of reading standards — Fragile enforcement

   • Wrong: Agent has rule logic embedded in code: if (hasAnyType) { error() }
   • Right: Agent reads standard file and extracts rules dynamically
   • Impact: When standard updates, agent is out of sync
   • Guard: Agent should always reference standard files, not embed rules

2. Overly strict enforcement blocking productivity — Team disables agent

   • Wrong: Agent blocks on style issues (indentation, comment length)
   • Right: Agent blocks on substantive issues (security, architecture violations)
   • Impact: Team disables agent because it's too noisy
   • Guard: Discuss with team: which violations should ERROR vs WARN vs INFO?

3. False positives from ambiguous standards — Creates noise

   • Happens when: Standard rule is vague and can be interpreted multiple ways
   • Example: "Code should be clean" → no clear violation
   • Guard: Only enforce standards with specific, measurable rules
   • If you can't code it as a check, it's too vague to enforce

4. Agent doesn't cite the standard — User can't understand violation

   • Wrong: "Remove any type" (no citation)
   • Right: "Remove any type (see docs/standards/engineering/typescript.md#Type Safety)"
   • Impact: User doesn't know why violation matters
   • Guard: Every violation message must include standard file + section name

Further Reading

• levels/L3-enforcement/agents/standards-enforcer.md — Reference agent definition
• levels/L1-context/library/ — Reference standards to enforce
• levels/L3-enforcement/hooks/ — Hook configurations for integration