agents-verify

Template-driven AGENTS.md quality verifier CLI. Checks sections, scores quality, grades A-F.

Installation

git clone https://github.com/Lanier-Developments/Agents_Validator.git
cd Agents_Validator
pip install -e ".[dev]"

Usage

# Verify an AGENTS.md against the default template
agents-verify ./path/to/AGENTS.md

# Use a custom template
agents-verify ./path/to/AGENTS.md --template ./path/to/template.md

# Save report to file
agents-verify ./path/to/AGENTS.md --output report.txt

Sample Output

Section Results
  What This Project Is:          PRESENT
  What This Project Is NOT:      PRESENT
  Architecture:                  PRESENT
  Tech Stack:                    PRESENT
  Coding Standards:              PRESENT
  Testing Standards:             WEAK
  Monitoring & Observability:    MISSING
  ...

Score: 20/26 (77%) Grade: B
  PRESENT: 9  WEAK: 2  MISSING: 2

Scoring

Total = (PRESENT x 2) + (WEAK x 1) + (MISSING x 0)
Max   = sections_in_template x 2

Grade:
  90-100%  ->  A  (Sprint-ready)
  73-89%   ->  B  (Minor gaps)
  45-72%   ->  C  (Significant gaps)
  <45%     ->  F  (Do not start sprint)

Architecture

template.md (standard)      target AGENTS.md
       |                           |
       v                           |
  template_parser.py               |
  extracts ## headings             |
       |                           |
       +-------------+-------------+
                     v
               checker.py
               presence + quality heuristics
                     |
                     v
               scorer.py
               tallies -> score -> grade
                     |
                     v
               reporter.py
               Rich output -> terminal or file

The template drives the section list. Change the template, not the code.

Quality Heuristics

Section	WEAK triggers
What This Project Is	No date, team, status, or timeline
What This Project Is NOT	Fewer than 2 items, no specific exclusions
Architecture	No diagram markers, no data flow words
Tech Stack	No table, fewer than 3 entries, no language
Coding Standards	No code example, no naming conventions
Testing Standards	No numeric %, no isolation, no naming
Monitoring & Observability	No health check, no metrics, no logging
CI/CD & Security Standards	No scanner, no dependabot, no branch protection
Credentials	No credential path, no "never echo" rule
Execution Policy	Fewer than 3 tiers, no forbidden, no recursive delete
Guardrails	Fewer than 5 items
Output Format	Fewer than 2 items, no format guidance
Directory Structure	Fewer than 5 entries, no inline comments

Coverage per Module

Module	Coverage
__init__.py	100%
template_parser.py	100%
checker.py	99%
scorer.py	100%
reporter.py	100%
rules.py	99%
cli.py	78%
Total	96%

Directory Structure

Agents_Validator/
├── AGENTS.md                    # Project spec
├── README.md                    # This file
├── pyproject.toml               # Package config + entry point
├── .gitea/
│   └── workflows/
│       └── ci.yml               # Bandit + pytest CI workflow
├── template/
│   └── standard_template.md     # Standard template (source of truth)
├── agents_verify/
│   ├── __init__.py              # Package init
│   ├── cli.py                   # Argparse entry point
│   ├── template_parser.py       # Extracts ## sections from template
│   ├── checker.py               # Presence check + quality heuristics
│   ├── scorer.py                # Score calculation + grading
│   ├── reporter.py              # Rich terminal output
│   └── rules.py                 # Quality heuristic functions
└── tests/
    ├── fixtures/
    │   ├── standard_template.md # Pinned template for test stability
    │   ├── perfect.md           # Scores A
    │   ├── minimal.md           # Scores B/C
    │   └── empty.md             # Scores F
    ├── test_template_parser.py
    ├── test_checker.py
    ├── test_scorer.py
    ├── test_reporter.py
    ├── test_cli.py
    └── test_rules.py

License

MIT