Metadata-Version: 2.4
Name: agent-readiness
Version: 1.5.0
Summary: Benchmark how agent-ready a code repository is for LLM coding agents.
Project-URL: Homepage, https://github.com/harrydaihaolin/agent-readiness
Project-URL: Repository, https://github.com/harrydaihaolin/agent-readiness
Project-URL: Changelog, https://github.com/harrydaihaolin/agent-readiness/blob/main/CHANGELOG.md
Project-URL: Bug Tracker, https://github.com/harrydaihaolin/agent-readiness/issues
Project-URL: Documentation, https://github.com/harrydaihaolin/agent-readiness#readme
Author: agent-readiness contributors
License: MIT
Keywords: agents,ai,benchmark,code-quality,developer-experience
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Quality Assurance
Requires-Python: >=3.11
Requires-Dist: agent-readiness-insights-protocol<1.0,>=0.1
Requires-Dist: click>=8.1
Requires-Dist: pyyaml>=6
Requires-Dist: rich>=13.7
Provides-Extra: complexity
Requires-Dist: lizard>=1.17; extra == 'complexity'
Provides-Extra: dev
Requires-Dist: build; extra == 'dev'
Requires-Dist: pytest>=8; extra == 'dev'
Requires-Dist: ruff>=0.4; extra == 'dev'
Provides-Extra: full
Requires-Dist: jinja2>=3.1; extra == 'full'
Requires-Dist: lizard>=1.17; extra == 'full'
Requires-Dist: mcp>=1.0; extra == 'full'
Provides-Extra: mcp
Requires-Dist: mcp>=1.0; extra == 'mcp'
Provides-Extra: report
Requires-Dist: jinja2>=3.1; extra == 'report'
Description-Content-Type: text/markdown

# agent-readiness

**A benchmark for AI agent readiness of a code repository.**

You bought the seats. Your team is using Claude Code, Cursor, Copilot, Cline.
And the agents keep going off the rails on *your* codebase.

The model is the variable you can't change. The repo is what you can.

`agent-readiness` scans a repository and scores how ready it is for AI
coding agents — across cognitive load, feedback loops, and flow — then
hands you a prioritised punchlist of fixes. Like Lighthouse, but for AI
agent readiness instead of page load.

```
$ agent-readiness scan .

AI Readiness  62 / 100

  Cognitive load     70 / 100
  Feedback loops     40 / 100   ← biggest drag
  Flow & reliability 75 / 100
  Safety             OK

Top friction (fix these first):
  1. test_command.discoverable — no test invocation found in Makefile,
     package.json, or pyproject.toml
  2. agent_docs.present — no AGENTS.md / CLAUDE.md / .cursorrules at root
  3. headless.no_setup_prompts — README mentions "log in to the dashboard"
     during setup; agents can't traverse this
```

## Design principles

**Agents are headless.** We assume the agent has stdin / stdout / files /
git / HTTP and nothing else. No browser, no dashboard, no clickable
button. If important state is reachable only through a UI, it's invisible
to the agent — and the repo loses points wherever that's true.

This applies to our own tool, too. `agent-readiness` is fully headless:
no required interactive prompts, stable JSON via `--json`, exit codes
that mean things, machine-readable findings.

**Code quality counts only where it predicts agent success.** Mega-files,
ambiguous names, dead code, missing types — those have direct lines to
agent failure modes and get measured. We don't reproduce the full
SonarQube taxonomy. Other tools do that well.

**Run untrusted code in Docker, always.** Any check that executes code
from the target repo runs inside a sandboxed container. See
[`docs/SANDBOX.md`](./docs/SANDBOX.md).

## What gets measured

See [`docs/RUBRIC.md`](./docs/RUBRIC.md) for the full definition. Short version:

| Pillar | What it captures |
|---|---|
| **Cognitive load** | What the agent must absorb to make a correct change. |
| **Feedback loops** | How fast and clear is the signal after a change. |
| **Flow / reliability** | Headless walkability + how often friction outside the task blocks the agent. |
| **Safety & trust** | Secrets, destructive scripts, gitignore hygiene. (Cap, not weight.) |

## This repo's score

Dogfooding: `agent-readiness scan .` run against this repository itself.

```
╭─────────────────────────────╮
│  AI Readiness  100.0 / 100  │
╰─────────────────────────────╯
 Cognitive load      100.0  ████████████████████
 Feedback loops      100.0  ████████████████████
 Flow & reliability  100.0  ████████████████████
 Safety              100.0  ████████████████████

No findings. Looking good.
```

Score updated after each iteration as part of the development workflow.

## Usage

```
# Static scan (no Docker needed)
agent-readiness scan .
agent-readiness scan . --json
agent-readiness scan . --fail-below 70        # exit 1 if score < 70 (CI gate)
agent-readiness scan . --only feedback        # filter to one pillar
agent-readiness scan . --baseline prev.json   # diff against a previous run
agent-readiness scan . --report report.html   # HTML report (requires jinja2)
agent-readiness scan . --badge badge.svg      # score badge SVG
agent-readiness scan . --sarif findings.sarif # SARIF for GitHub code scanning

# Runtime scan (executes tests inside Docker)
agent-readiness scan . --run

# Other commands
agent-readiness list-checks
agent-readiness explain manifest.detected
agent-readiness init                          # write .agent-readiness.toml
```

## Status

All phases implemented (v0.1–v0.9). 22 checks across 4 pillars, Docker
sandbox, HTML + SARIF renderers, CLI surface, plugin API. See
[`docs/PLAN.md`](./docs/PLAN.md) for the full roadmap and
[`CHANGELOG.md`](./CHANGELOG.md) for per-phase release notes.
