Local read-only Python CLI for diagnosing AGENTS.md, CLAUDE.md, GEMINI.md, Cursor rules, GitHub Copilot instructions, and other AI agent instruction files in repositories.

Screenshots · Overview · Installation · Release and PyPI · Commands · Governance Findings · Safety Boundary · Quality Gates · Development Status · Maintainer Workflow · Support

agent-rules-kit is a local, read-only diagnostic CLI for repositories that use AI coding agents or assistant-specific instruction files.

It helps developers inspect AGENTS.md, CLAUDE.md, GEMINI.md, Cursor rules, GitHub Copilot instructions, and GitHub instruction files without network calls, LLM calls, or repository command execution.

It focuses on files such as:

• AGENTS.md
• CLAUDE.md
• .claude/CLAUDE.md
• GEMINI.md
• .cursor/rules/*.mdc
• .github/copilot-instructions.md
• .github/instructions/*

The project is positioned as a doctor/lint tool for agent instruction files.

It is not:

• a universal instruction generator;
• a security scanner;
• an LLM agent;
• a repository automation bot;
• a CI/CD security auditor;
• a dependency vulnerability scanner.

The default behavior is read-only.

v0.4.0 is the current published GitHub Release and PyPI package for agent-rules-kit.

v0.3.0 remains the previous published GitHub Release and PyPI package baseline.

Current main may include post-v0.4.0 changes that are not part of the published PyPI package until a later release is cut and verified.

The current main behavior includes:

• discovers supported AI agent instruction files;
• reports repository-relative paths;
• supports console, JSON, and Markdown output;
• provides init --dry-run for planning baseline instruction files;
• provides explicit init --write behavior for creating or replacing root AGENTS.md;
• backs up existing root AGENTS.md before replacement;
• provides read-only doctor repository diagnosis output in the published v0.4.0 package and current main;
• provides read-only budget local size and context-pressure approximation output in the published v0.4.0 package and current main;
• provides read-only explain output for known governance rule IDs in the published v0.4.0 package and current main;
• provides read-only dedupe duplicate instruction-line detection in the published v0.4.0 package and current main;
• provides read-only conflicts contradictory-guidance detection in the published v0.4.0 package and current main;
• redacts supported secret-like values in supported output, including finding messages, paths, and evidence payloads;
• avoids network calls;
• avoids LLM calls;
• avoids executing commands from analyzed repositories.

Governance diagnostics were introduced in v0.2.0 and hardened through the published v0.2.1 release. v0.2.2 and v0.2.3 are documentation-only public-truth patches.

These diagnostics are heuristic findings for instruction-file governance. They are meant to flag review-worthy instruction patterns, not to prove that a repository is safe.

Current main evaluates the following governance finding rules, in stable evaluation order:

Governance findings are intentionally conservative and pattern-based. They may produce false positives or false negatives, and they are not a substitute for maintainer review.

The v0.2.0 GitHub Release introduced this governance rule set. The published v0.2.1 release includes subsequent governance hardening and coverage expansion without moving the v0.2.0 tag. The published v0.2.2 release syncs public release, PyPI, and security documentation without runtime behavior changes. The published v0.2.3 release syncs support policy documentation and package metadata without runtime behavior changes.

For detailed rule purpose, evidence, limits, and false-positive notes, see docs/RULES.md.

For CLI output examples in console, JSON, and Markdown formats, see docs/OUTPUTS.md. For the CLI exit-code contract, see docs/EXIT-CODES.md.

agent-rules-kit does not claim to make a repository secure.

It does not:

• prove that a repository is safe;
• scan dependencies for vulnerabilities;
• execute repository commands;
• inspect private infrastructure;
• call external APIs;
• call an LLM;
• modify files during check;
• modify files during init --dry-run;
• provide complete secret scanning;
• replace human review.

A clean report means only that the implemented checks did not find a supported issue. It is not proof of safety, completeness, or production readiness.

v0.4.0 is the current published GitHub Release and PyPI package.

The published package can be installed from PyPI. Release publication uses PyPI Trusted Publishing from the GitHub Release workflow.

Requirements for using a published CLI release:

• Python 3.12 or newer;
• a Python virtual environment;
• a published PyPI release of agent-rules-kit.

Install v0.4.0 in a virtual environment:

python -m venv .venv
.venv/bin/python -m pip install agent-rules-kit==0.4.0
.venv/bin/agent-rules-kit --version
.venv/bin/agent-rules-kit check /path/to/repository --format console

Normal CLI use does not require Ruff or any development dependency.

Requirements for working on the repository and running local checks:

• Python 3.12 or newer;
• a Python virtual environment;
• editable install with development dependencies.

Set up a local development environment from the source tree:

python -m venv .venv
.venv/bin/python -m pip install -e '.[dev]'
PATH="$PWD/.venv/bin:$PATH" ./scripts/check.sh

The development dependency group installs tools used by local checks, including Ruff. Installing only a system ruff binary is not enough for ./scripts/check.sh if the active Python cannot import the ruff module.

The source tree can also be used directly for quick CLI inspection:

PYTHONPATH=src python -m agent_rules_kit.cli --help

Current main can also be tested from the source tree. doctor, budget, explain, dedupe, and conflicts are part of the published v0.4.0 package and current source tree:

PYTHONPATH=src python -m agent_rules_kit.cli doctor tests/fixtures/repositories/multi-agent-overlap
PYTHONPATH=src python -m agent_rules_kit.cli budget tests/fixtures/repositories/multi-agent-overlap
PYTHONPATH=src python -m agent_rules_kit.cli dedupe tests/fixtures/repositories/multi-agent-overlap
PYTHONPATH=src python -m agent_rules_kit.cli conflicts tests/fixtures/repositories/multi-agent-overlap
PYTHONPATH=src python -m agent_rules_kit.cli explain AIRK-GOV003

These source-tree commands are development checks. Published-package behavior must be verified from a clean PyPI install during release closeout.

The v0.4.0 release was published through PyPI Trusted Publishing.

Release publishing is handled by:

.github/workflows/publish-pypi.yml

The workflow is intentionally limited:

• it runs only when a GitHub Release is published;
• it builds distributions in a separate build job;
• it runs local checks before building distributions;
• it verifies distributions with Twine before publishing;
• it smoke-tests the wheel before publishing;
• it uploads the built distributions as a short-lived workflow artifact;
• it publishes through the pypi GitHub environment;
• it grants id-token: write only to the publish job;
• it does not use a static PyPI token, username, or password.

The published v0.4.0 package must remain verifiable by:

• the GitHub Release tag pointing to the verified release SHA;
• a successful PyPI publish workflow run;
• a clean virtual environment installing and running agent-rules-kit==0.4.0 from PyPI.

Installed CLI usage:

.venv/bin/agent-rules-kit check /path/to/repository --format console

Source-tree development usage:

PYTHONPATH=src python -m agent_rules_kit.cli check tests/fixtures/repositories/single-agent

Example console output:

agent-rules-kit check: tests/fixtures/repositories/single-agent
Found 1 supported instruction file(s):
- AGENTS.md [agents]

Installed CLI usage:

.venv/bin/agent-rules-kit check /path/to/repository --format json

Source-tree development usage:

PYTHONPATH=src python -m agent_rules_kit.cli check tests/fixtures/repositories/single-agent --format json

Installed CLI usage:

.venv/bin/agent-rules-kit check /path/to/repository --format markdown

Source-tree development usage:

PYTHONPATH=src python -m agent_rules_kit.cli check tests/fixtures/repositories/single-agent --format markdown

init --dry-run shows what would happen without writing files:

PYTHONPATH=src python -m agent_rules_kit.cli init /path/to/repo --dry-run

Example behavior:

Mode: dry-run
No files will be modified.
Planned file actions:
- AGENTS.md [create] - baseline agent instruction file would be created

init --write must be requested explicitly:

PYTHONPATH=src python -m agent_rules_kit.cli init /path/to/repo --write

If root AGENTS.md already exists, it is backed up before replacement:

AGENTS.md.agent-rules-kit.bak

doctor summarizes supported instruction files, finding counts, and review status:

PYTHONPATH=src python -m agent_rules_kit.cli doctor tests/fixtures/repositories/multi-agent-overlap

budget reports deterministic local size metrics. It is an approximation, not tokenizer-specific counting:

PYTHONPATH=src python -m agent_rules_kit.cli budget tests/fixtures/repositories/multi-agent-overlap

dedupe reports repeated instruction lines across supported instruction files:

PYTHONPATH=src python -m agent_rules_kit.cli dedupe tests/fixtures/repositories/multi-agent-overlap

The first baseline is conservative: it detects repeated normalized lines across files, not broad semantic duplication.

conflicts reports contradictory guidance across supported instruction files:

PYTHONPATH=src python -m agent_rules_kit.cli conflicts tests/fixtures/repositories/multi-agent-overlap

The first baseline is conservative: it detects implemented pattern families for opposite guidance, not broad semantic contradiction.

explain lists or explains known local governance rule IDs:

PYTHONPATH=src python -m agent_rules_kit.cli explain AIRK-GOV003
PYTHONPATH=src python -m agent_rules_kit.cli explain --list

These commands are implemented on current main and are part of the published v0.4.0 command surface.

Supported check formats:

The output format is selected with:

--format console
--format json
--format markdown

The runtime boundary is intentionally narrow.

The project must preserve these rules:

• read-only by default;
• no network access in runtime behavior;
• no LLM dependency in runtime behavior;
• no execution of commands from analyzed repositories;
• no unsupported security guarantees;
• secret-like values must be redacted;
• write behavior must require explicit user intent;
• generated or overwritten files must be handled conservatively.

Security-sensitive changes must be isolated in their own phase and covered by tests.

See:

• SECURITY.md
• docs/THREAT-MODEL.md

.
├── .github/
│   ├── ISSUE_TEMPLATE/
│   │   ├── bug_report.yml
│   │   └── feature_request.yml
│   ├── dependabot.yml
│   ├── pull_request_template.md
│   └── workflows/
│       ├── ci.yml
│       ├── codeql.yml
│       └── publish-pypi.yml
├── docs/
│   ├── ACTIONS-PINNING-POLICY.md
│   ├── BUILD-PLAN.md
│   ├── DEPENDABOT-DEPENDENCY-GRAPH.md
│   ├── EXIT-CODES.md
│   ├── EXTERNAL-AUDIT-PACKAGE-CURRENT-MAIN.md
│   ├── OPENSSF-SCORECARD-EVALUATION.md
│   ├── OUTPUTS.md
│   ├── POST-AUDIT-ACTION-PLAN-CURRENT-MAIN.md
│   ├── POST-V0.3.0-FUNCTIONAL-CONTRACT-EVIDENCE.md
│   ├── POST-V0.3.0-INTERNAL-READINESS-AUDIT.md
│   ├── PRE-V0.4.0-INTERNAL-READINESS-AUDIT.md
│   ├── PRIVATE-VULNERABILITY-REPORTING.md
│   ├── PRODUCT-STRATEGY.md
│   ├── RULES.md
│   ├── SECURITY-SUPPLY-CHAIN-EVALUATION.md
│   ├── THREAT-MODEL.md
│   ├── V0.2.0-RELEASE-NOTES.md
│   ├── V0.2-GOVERNANCE-BOUNDARIES.md
│   ├── V0.2-GOVERNANCE-RULES-SPEC.md
│   ├── V0.2-PACKAGING-DRY-RUN.md
│   ├── V0.2-RELEASE-READINESS.md
│   ├── V0.3-ARCHITECTURE-ROADMAP.md
│   ├── V0.3.0-POST-RELEASE-AUDIT.md
│   ├── V0.3.0-RELEASE-NOTES.md
│   ├── V0.4.0-RELEASE-EVIDENCE.md
│   ├── V0.4.0-RELEASE-NOTES.md
│   └── screenshots/
│       └── readme/
│           ├── agent-rules-kit-governance-findings.png
│           ├── agent-rules-kit-help-check.png
│           ├── agent-rules-kit-init-safety.png
│           └── agent-rules-kit-output-formats.png
├── scripts/
│   ├── check.sh
│   └── post-release-audit.sh
├── src/
│   └── agent_rules_kit/
│       ├── __init__.py
│       ├── budget.py
│       ├── cli.py
│       ├── conflicts.py
│       ├── dedupe.py
│       ├── discovery.py
│       ├── explain.py
│       ├── findings.py
│       ├── governance.py
│       ├── init_plan.py
│       ├── init_write.py
│       └── redaction.py
├── tests/
│   ├── fixtures/
│   │   └── repositories/
│   ├── test_cli.py
│   ├── test_conflicts.py
│   ├── test_dedupe.py
│   ├── test_diagnostic_fixtures.py
│   ├── test_discovery.py
│   ├── test_findings.py
│   ├── test_golden_outputs.py
│   ├── test_governance.py
│   ├── test_init_plan.py
│   ├── test_init_write.py
│   ├── test_path_boundaries.py
│   └── test_redaction.py
├── .gitignore
├── AGENTS.md
├── CHANGELOG.md
├── CONTRIBUTING.md
├── LICENSE
├── README.md
├── SECURITY.md
├── SUPPORT.md
└── pyproject.toml

Local verification is handled by:

PATH="$PWD/.venv/bin:$PATH" ./scripts/check.sh

Run this after installing development dependencies with:

.venv/bin/python -m pip install -e '.[dev]'

The local check suite verifies:

• Python syntax;
• unit tests;
• Ruff lint checks;
• UTF-8 text files;
• LF line endings;
• final newline;
• no trailing whitespace;
• Git whitespace checks.

Current verified local result on main:

./scripts/check.sh passes

The exact unit test count may change as coverage evolves. The source of truth is the current ./scripts/check.sh output and the matching GitHub Actions run for main.

For v0.4.0 release notes and release evidence, see docs/V0.4.0-RELEASE-NOTES.md and docs/V0.4.0-RELEASE-EVIDENCE.md.

CI installs project development dependencies and then runs the same local check script through GitHub Actions.

The required status check for main is:

local-checks / Python 3.12

Current status:

• v0.4.0 is published as the current GitHub Release and PyPI package;
• v0.3.0 remains the previous published GitHub Release and PyPI package baseline;
• no stable support or API guarantee yet;
• release tag v0.4.0 points to the verified release SHA;
• local CLI behavior implemented;
• governance diagnostics, structured finding evidence, and evidence redaction are implemented;
• doctor, budget, explain, dedupe, and conflicts are implemented as v0.4.0 read-only command surfaces;
• CI active;
• branch protection is active with the required local-checks / Python 3.12 status check;
• the pypi GitHub environment exists for the release publishing workflow;
• .github/workflows/publish-pypi.yml published v0.4.0 through PyPI Trusted Publishing and remains the release publishing workflow;
• README screenshots are generated from real local CLI commands;
• v0.4.0 release notes and release evidence are documented in docs/V0.4.0-RELEASE-NOTES.md and docs/V0.4.0-RELEASE-EVIDENCE.md;
• security boundaries documented;
• threat model documented.

For future releases, verify:

• all intended changes for the release are merged into main;
• no known release-blocking audit finding remains open;
• local checks pass from a development virtual environment;
• CI passes for the release SHA;
• sdist and wheel build and install from clean temporary environments;
• PyPI Trusted Publishing workflow is configured for the expected PyPI project, repository, workflow file, and pypi environment;
• the GitHub Release publication triggers the PyPI publish workflow successfully through the pypi environment;
• the published PyPI package installs and runs from a clean virtual environment;
• output examples and screenshots are generated from real commands;
• README documents normal CLI use, source-tree development use, virtual environment setup, development dependencies, and local checks;
• README does not claim unsupported maturity;
• SECURITY.md and CHANGELOG.md are current;
• private vulnerability reporting status is accurately documented;
• tag and GitHub Release point to the verified release SHA;
• no real secrets or private data are present.

This repository follows a strict Always-Green workflow.

Required discipline:

• never work directly on main after Genesis;
• start each phase from clean, synchronized main;
• create one branch per logical phase;
• read real files before editing;
• make minimal changes;
• avoid git add .;
• stage only expected files;
• inspect staged diff before commit;
• run local checks before push;
• verify remote branch SHA after push;
• open PR;
• verify PR state, diff, and CI;
• merge only after green checks;
• use exact head SHA for merge;
• verify main after merge;
• verify CI on main;
• delete local and remote phase branches.

A phase is complete only when:

main is clean
origin/main is synchronized
local checks pass
CI is green
the PR is merged
phase branches are deleted

See CONTRIBUTING.md.

Any contribution must preserve the safety boundary documented in AGENTS.md, SECURITY.md, and docs/THREAT-MODEL.md.

If this project helps you, you can support CDLAN public work here:

Support is optional. It does not change the license, support policy, or project boundaries.

MIT.

See LICENSE.

agent-rules-kit is a focused diagnostic tool for AI agent instruction files.

It is not a security product, not a general repository auditor, not a secret scanner, not an autonomous fixer, and not a replacement for maintainer review.

CDLAN · Less noise. More system.