agentic-rule-enforcer

Inspiration

As developers increasingly collaborate with autonomous AI coding agents (such as Claude Code, Cursor, and Antigravity), a recurring frustration arises: AI assistants frequently repeat mistakes, leak hardcoded API secrets into source files, leave debug log dumps, or violate local repository conventions.

Traditional linters only verify syntax and language idioms; they do not enforce conversational or team-specific rules. We built Agentic Rule Enforcer to act as a lightweight, deterministic gatekeeper that holds AI agents accountable to project rules before any code is committed.

What It Does

Agentic Rule Enforcer is a standalone developer CLI that translates human-readable Markdown guidelines (agent_rules.md) into executable pre-commit guardrails:

• Deterministic Scanning (scan): Inspects code line-by-line and reports violations with 1-indexed line numbers, surrounding context, and severity badges in a high-contrast ANSI terminal table.
• Interactive Safe Remediation (fix): Generates colored unified diffs showing exact proposed replacements (e.g., replacing hardcoded keys with os.environ.get), requiring explicit user confirmation (Y/n).
• Safety Snapshots & Rollback (rollback): Automatically creates timestamped file backups in .agentic-enforcer/backups/ before modifying any files, allowing instant byte-for-byte rollbacks.
• Custom Extensibility (rules): Any developer can add custom rules directly in Markdown without touching Python code.
• Zero External Dependencies: Implemented in pure Python 3.10+ standard library for instant portability across Windows, macOS, and Linux without installation hurdles.

How We Built It

We strictly followed the Devpost Learn Skill Pack plan-first methodology:

1. 1-start & 2-scope: Formulated the problem, defined the unique kernel, and bounded the PoC to an essential, demonstrable workflow.
2. 3-prd: Outlined explicit user acceptance criteria, interactive review flows, and safety boundaries.
3. 4-spec: Architected a modular zero-dependency Python structure (parser, scanner, remediator, backup, ui).
4. 5-build: Implemented the system in incremental, verifiable slices with automated test suites (unittest).
5. 6-ship: Packaged the public repository, documentation, and demo.

All planning artifacts (scope.md, prd.md, spec.md, checklist.md, app-map.html) are preserved directly in the repository's devpost/ directory.

Challenges We Faced

• Windows Terminal Encodings: Initial Unicode box glyphs caused encoding exceptions on Windows consoles using CP1250. We resolved this by implementing an ASCII-safe fallback renderer in ui.py.
• Multi-Line Diff Application: Applying multiple fixes to a single file can alter line offsets. We resolved this by sorting violations in reverse line order before patching.

What We Learned

The greatest takeaway was the efficiency of the plan-first workflow. By defining observable acceptance criteria, verification commands, and safety rollback mechanisms before writing any source code, we avoided architectural rework and delivered a robust, crash-free PoC in record time.

What's Next

• Pre-commit git hook automated installer (install-hook).
• GitHub Action companion for automated PR review comments.
• Language-specific preset packs for Solidity, TypeScript, and Python.

Built With

• ai-agents
• cli
• code-quality
• devops
• devpost-learn
• git
• pre-commit
• python
• security