AgentRules Compiler

Turn AI agent instruction files into executable repository guardrails.

Prompts tell agents what to do. AgentRules turns the important parts into CI.

Markdown rules are easy to write and easy for agents to ignore. AgentRules Compiler reads files such as AGENTS.md, CLAUDE.md, .cursor/rules/*.md, and .github/copilot-instructions.md, then compiles common instructions into checks that can run locally or in GitHub Actions.

See the live demo PR: R0SS94/agentrules-demo#1.

Why this exists

AI coding agents need repository-specific rules:

• use pnpm, never npm
• do not touch src/payments without approval
• all API route changes need tests
• do not use default exports
• never commit secrets

Today those rules often live as text. This project makes the first useful subset of those rules executable.

When to use this

Use AgentRules when:

• your repository has AGENTS.md, CLAUDE.md, Cursor rules, or Copilot instructions
• AI coding agents open pull requests in your project
• maintainers want CI to enforce the rules they already wrote for agents
• sensitive areas such as auth, payments, CI, or dependencies need human approval
• you want to know which instruction lines are executable and which still need human review

Status

Early MVP. The goal is not to understand every instruction perfectly. The goal is to recognize high-value patterns, explain what was compiled, and fail pull requests when an agent ignores important repository rules.

Try It In GitHub Actions

Create .github/workflows/agentrules.yml:

name: AgentRules

on:
  pull_request:

permissions:
  contents: read
  issues: write
  pull-requests: write

jobs:
  agentrules:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Changed files
        run: git diff --name-only origin/${{ github.base_ref }}...HEAD > changed-files.txt

      - name: Audit agent rules
        uses: R0SS94/agentrules@v0.3.0
        with:
          changed-files: changed-files.txt
          comment: "true"
          github-token: ${{ github.token }}

Then add rules to AGENTS.md:

- Use pnpm, never npm.
- Never use default exports.
- Do not touch src/payments without approval.
- All API routes must have tests.

AgentRules will compile those instructions, annotate matching lines in the pull request, and publish a Markdown report.

Live Demo

The demo repository contains an intentionally failing pull request that shows what AgentRules reports in GitHub:

• Demo repository: R0SS94/agentrules-demo
• Demo pull request: Demo: AgentRules catches risky AI-style changes
• Example report comment: AgentRules check failed

Install

No runtime dependencies. Python 3.10+ is enough.

python -m pip install -e .

Or run directly from the repository:

python -m agentrules --help

Quick Start

Compile rules from repository instruction files:

python -m agentrules compile --root . --output agentrules.json

Measure how much of an instruction file is executable:

python -m agentrules coverage --root . --format markdown

Check changed files and commands:

python -m agentrules check \
  --root . \
  --rules agentrules.json \
  --changed-files examples/changed-files.txt \
  --commands examples/commands.txt

Create a Markdown report for a PR comment:

python -m agentrules check \
  --root . \
  --format markdown \
  --output agentrules-report.md \
  --changed-files examples/changed-files.txt \
  --commands examples/commands.txt

Emit GitHub Actions annotations for findings:

python -m agentrules check \
  --root . \
  --changed-files examples/changed-files.txt \
  --github-annotations

Adopt AgentRules with a baseline:

python -m agentrules check \
  --root . \
  --changed-files examples/changed-files.txt \
  --write-baseline agentrules-baseline.json \
  --no-fail

Then fail only on new findings:

python -m agentrules check \
  --root . \
  --changed-files examples/changed-files.txt \
  --baseline agentrules-baseline.json

Example output:

AgentRules check
Changed files: 3
Commands: 1
Errors: 5
Warnings: 3

- [error] Do not run npm commands. Command: npm test
- [error] src/api/users.ts:1: Default exports are not allowed.
- [error] src/payments/stripe.ts: Changes under src/payments require approval.

Coverage output:

AgentRules coverage
Sources: 1
Instruction lines: 9
Compiled rules: 5
Coverage: 56%

Recognized:
- AGENTS.md:3 Must run tests before opening a PR.
- AGENTS.md:4 Do not edit .github/workflows without approval.

Unrecognized:
- AGENTS.md:8 Keep compiled rules readable and explainable.

Supported Instruction Patterns

The compiler currently recognizes rules like:

• use pnpm, never npm
• never use default exports
• do not touch src/payments without approval
• do not edit .github/workflows without approval
• all API routes must have tests
• must run tests
• no console.log
• do not use any
• do not add dependencies without approval

The checker also includes a built-in lightweight secret scan for changed files.

See docs/rules.md for the current rule catalog.

What It Catches Today

Instruction style	Example finding
Forbidden package managers	npm test when the repo says to use pnpm
Sensitive paths	Changes under src/payments without approval
API route test requirements	src/api/users.ts changed without a matching test
Risky TypeScript patterns	export default, console.log, or any
Dependency changes	package.json changes without approval
Possible secrets	Lightweight scan for committed credentials

GitHub Action

This repository includes a composite action in action.yml.

Example workflow:

name: AgentRules

on:
  pull_request:

jobs:
  agentrules:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Changed files
        run: git diff --name-only origin/${{ github.base_ref }}...HEAD > changed-files.txt

      - name: Audit agent rules
        uses: R0SS94/agentrules@v0.3.0
        with:
          changed-files: changed-files.txt
          format: markdown

To publish a sticky pull request comment:

name: AgentRules

on:
  pull_request:

permissions:
  contents: read
  issues: write
  pull-requests: write

jobs:
  agentrules:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Changed files
        run: git diff --name-only origin/${{ github.base_ref }}...HEAD > changed-files.txt

      - name: Audit agent rules
        uses: R0SS94/agentrules@v0.3.0
        with:
          changed-files: changed-files.txt
          comment: "true"
          github-token: ${{ github.token }}

To adopt AgentRules gradually, commit agentrules-baseline.json and pass it to the action:

      - name: Audit agent rules
        uses: R0SS94/agentrules@v0.3.0
        with:
          changed-files: changed-files.txt
          baseline: agentrules-baseline.json
          comment: "true"
          github-token: ${{ github.token }}

The action emits GitHub annotations by default, so file and line findings appear next to changed code. It can also suppress known findings from a baseline file and writes the report to the GitHub Actions step summary.

This repository dogfoods AgentRules with its own root AGENTS.md and a self-check workflow in .github/workflows/agentrules.yml.

Design

AgentRules Compiler has three parts:

1. discover: find known AI instruction files.
2. compile: turn recognized text rules into a JSON policy.
3. coverage: show which instruction lines became executable rules.
4. check: evaluate changed files, commands, and file content against the policy.

The compiled file is intentionally readable so maintainers can review and adjust what the tool understood.

Roadmap

Near-term roadmap:

• Rule ignores with expiry dates.
• Rule confidence scores and "needs human review" mode.
• More instruction dialects for Cursor, Claude Code, Codex, Copilot, and Windsurf.
• Test coverage heuristics per language/framework.

See ROADMAP.md and docs/marketplace.md.

License

MIT