Metadata-Version: 2.4
Name: agentslint
Version: 0.1.0
Summary: Validate referential integrity in AGENTS.md files
Project-URL: Homepage, https://github.com/jyablonski/agentslint
Project-URL: Repository, https://github.com/jyablonski/agentslint
Project-URL: Issues, https://github.com/jyablonski/agentslint/issues
License-Expression: MIT
License-File: LICENSE
Keywords: agents,agents-md,documentation,lint,static-analysis
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Quality Assurance
Requires-Python: >=3.11
Requires-Dist: markdown-it-py<5,>=4
Requires-Dist: pyyaml<7,>=6
Description-Content-Type: text/markdown

# agentslint

A tool to keep `AGENTS.md` instructions honest as the repository changes.

`agentslint` is a static referential-integrity checker for AI agent instruction files. It finds stale file paths, broken internal links, missing command targets, and undeclared development tools before an agent follows outdated guidance.

```text
services/api/AGENTS.md:18: error[path-exists]: path does not exist: src/legacy.py
services/web/AGENTS.md:27: error[npm-script]: npm script does not exist in services/web/package.json: verify
AGENTS.md:42: warning[scope-ambiguous]: make command has multiple applicable Makefiles: services/api/Makefile, services/web/Makefile

agentslint: checked 3 instruction files; 2 errors, 1 warning
```

The validator reads repository content but never executes commands from `AGENTS.md`, imports application code, installs project dependencies, or accesses external URLs.

## Why agentslint?

Agent instructions are operational documentation. A renamed test, moved service, removed script, or retired formatter can silently turn correct guidance into a bad plan. Ordinary code tests rarely catch that drift because the Markdown itself did not change.

`agentslint check .` scans every tracked root and nested `AGENTS.md`, even when those files are unchanged. It checks the current working tree against the repository structure and manifests that the instructions describe.

Use it to:

- Catch references to files and directories that were moved or deleted.
- Verify internal Markdown links, heading anchors, globs, and path templates.
- Check Make targets, npm scripts, Python modules, pytest nodes, Go tests, and dbt selectors without running them.
- Detect development tools still named in instructions after their declarations were removed.
- Surface ambiguous project scopes before an agent chooses the wrong service.
- Add a focused, read-only integrity check to local development, pre-commit, and CI.

## Install

agentslint requires Python 3.11 or newer.

Run it without a persistent installation:

```bash
uvx agentslint check .
```

Or install it permanently onto your machine with `uv`:

```bash
uv tool install agentslint
```

Then run:

```console
$ agentslint check .
agentslint: checked 1 instruction file; no issues found
```

## Quick start

No configuration is required for conventional repositories. From anywhere inside a Git repository:

```bash
agentslint check .
```

agentslint discovers tracked `AGENTS.md` files recursively and uses the Git index as its canonical repository inventory. Staged additions count; deleted and untracked references do not count unless an untracked root is explicitly configured. Outside a Git worktree, agentslint falls back to a filesystem walk with standard dependency and VCS directories excluded.

To check one subtree or instruction file while retaining repository-wide resolution:

```bash
agentslint check services/frontend
agentslint check services/frontend/AGENTS.md
```

Use `--strict` when warnings about ambiguity or unsupported syntax should also fail:

```bash
agentslint check . --strict
```

## What it validates

| Reference             | Validation                                                                                                                               |
| --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| Paths and directories | Resolves tracked paths in the instruction file, repository-root, and inferred project scopes; preserves file/directory expectations.     |
| Globs and templates   | Requires globs to match and established templates to have a concrete tracked example; creation destinations only require a valid parent. |
| Markdown links        | Checks relative files and GitHub-style heading anchors. External URLs are intentionally skipped.                                         |
| Shell examples        | Tokenizes supported inline, indented, and fenced shell examples while tracking explicit `cd` changes.                                    |
| Make                  | Finds the applicable Makefile, literal targets, and local static includes without asking Make to parse the file.                         |
| npm and pnpm          | Checks scripts, lifecycle commands, directory options, and literal workspace selectors against the applicable `package.json`.            |
| Python, Poetry and uv | Resolves scripts, local modules, nested test commands, declared distributions, project scripts, and project-directory options.           |
| pytest                | Resolves paths and literal `file.py::Class::test_name` nodes with Python's AST, without collecting tests.                                |
| Go                    | Resolves `go test` packages and simple literal `-run` test names from the applicable module.                                             |
| dbt                   | Resolves model, source, and tag selectors from committed project sources or configured manifests.                                        |
| Managed tools         | Checks tools against pyproject, requirements, Node, Go, and pre-commit inventories; prohibited mentions are skipped.                     |

Dynamic shell expressions and selectors that cannot be proven statically produce warnings instead of being evaluated. The tool favors an explicit ambiguity diagnostic over silently selecting one plausible project.

## Exit codes and output

| Exit code | Meaning                                                                 |
| --------- | ----------------------------------------------------------------------- |
| `0`       | No errors. Warning-only runs also return `0` unless `--strict` is set.  |
| `1`       | At least one confirmed validation error, or a warning under `--strict`. |
| `2`       | Invalid configuration or an internal execution error.                   |

Text output is the default and ends with the number of instruction files checked plus error and warning totals. GitHub annotations and versioned JSON are also available:

```bash
agentslint check . --format text
agentslint check . --format github
agentslint check . --format json
```

## Configuration

See [Configuration](https://github.com/jyablonski/agentslint/blob/main/docs/configuration.md).

## GitHub Actions

See [GitHub Actions](https://github.com/jyablonski/agentslint/blob/main/docs/github-actions.md).

## Safety and boundaries

agentslint treats repository content as untrusted input:

- Documented shell commands, Makefiles, tests, dbt projects, and application modules are never executed or imported.
- Validation is local and read-only apart from normal tool caches and report output.
- External links are not fetched.
- Paths are constrained to the repository.
- Input files are size-bounded and parsed with data-only readers.

It checks whether instructions refer to real repository objects. It does not judge whether the advice is strategically correct, prove that a command succeeds at runtime, rewrite documentation, or replace language-specific tests and linters.
