genesis-agent-instruction-linter

genesis-agent-instruction-linter

Deterministic policy conflict detector and broken reference auditor for multi-agent repositories.

---

The Problem

Modern AI development stacks often maintain multiple instruction files across different tools:

• AGENTS.md (OpenAI / generic agent conventions)
• CLAUDE.md (Anthropic Claude Code conventions)
• GEMINI.md (Google Antigravity / Gemini guidelines)
• .cursorrules / .clinerules (IDE assistants)

As rules evolve, conflicting directives emerge silently: one file specifies Never git push to main directly, while another says Always automatically git push on completion. Autonomous agents get stuck in policy loops, crash CI, or execute dangerous operations due to contradictory instructions.

The Solution

genesis-agent-instruction-linter statically parses all agent instruction files in a repository, extracts operational directives, tags polarities (FORBIDDEN vs PERMITTED), and flags semantic topic collisions (e.g. git_push, git_commit, destructive_clean, dep_install, secrets). It also detects dead file references in markdown links.

---

Key Features

• Zero Third-Party Dependencies: Pure Python 3 standard library (pathlib, re, argparse, json).
• Semantic Topic Collision Detection: Pinpoints contradictory instructions between files with line numbers and exact rule quotes.
• Dead Link & Missing Doc Auditor: Identifies broken markdown documentation links cited in agent instructions.
• Machine-Readable JSON Mode: Integrates into pre-commit hooks and CI pipelines (--json).
• Instant Execution: Audits standard multi-agent repos in under 10ms.

---

Quickstart

# Clone the repository
git clone git@github.com:genesiscode2026/genesis-agent-instruction-linter.git
cd genesis-agent-instruction-linter

# Run against current repository or any workspace
./bin/genesis-instruction-linter /path/to/project

# Or output structured JSON for CI
./bin/genesis-instruction-linter --json /path/to/project

---

Example Output

==================================================================
  GENESIS AGENT INSTRUCTION CONFLICT LINTER — AUDIT REPORT
==================================================================
Workspace Scanned : /path/to/project
Files Inspected   : 2 (AGENTS.md, CLAUDE.md)
Overall Status    : [ FAIL ]
Summary           : 1 Critical, 0 High, 1 Broken Links
------------------------------------------------------------------
[CRITICAL] Topic Conflict: 'git_push'
  • Rule A: AGENTS.md:4 (FORBIDDEN) -> "- Strictly prohibited: never git push to main directly."
  • Rule B: CLAUDE.md:4 (PERMITTED) -> "- Always automatically git push to main when work is finished."
  • Reason: Polarity contradiction on 'git_push': AGENTS.md:4 (FORBIDDEN) vs CLAUDE.md:4 (PERMITTED)

[WARN] Broken Path Reference in CLAUDE.md: 'docs/non_existent.md' does not exist.
==================================================================

---

Commercial Distribution

• Product Name: genesis-agent-instruction-linter
• Catalog ID: P05
• Price: $19
• Seller: genesiscode2026
• Authorized Payout Rail: USDC on Base (0xC6F86e170411182114FcCdb28793dC76B5e8D144)
• License: MIT