scavi AGENTS.md

Scavi — Agent Instructions

Scavi is an open-source context linter for AI coding agents.

The context linter for AI coding agents. Keep your agents in sync with your code.

These instructions apply to AI coding agents working inside the Scavi repository.

---

Core principle

Scavi should never use an LLM when the repository can provide a deterministic answer.

This is the most important architectural rule in the project.

Before introducing an LLM call, ask:

1. Can this be determined from the filesystem?
2. Can this be determined from a manifest or configuration file?
3. Can this be determined from Git metadata?
4. Can this be determined through static parsing?
5. Can this be determined through deterministic repository search?

If the answer to any of these is yes, do not use an LLM.

Examples of deterministic checks:

• whether a referenced path exists
• whether a package script exists
• which package manager the repository uses
• whether a dependency is installed
• what version is declared in a manifest
• whether a referenced file exists
• whether two context files give conflicting package-manager instructions

LLMs are reserved for claims that require semantic interpretation.

---

Product behavior

Scavi validates instructions intended for AI coding agents against the actual repository.

Initial context formats include:

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

Scavi should detect:

• stale instructions
• invalid paths
• invalid commands
• outdated dependency/version claims
• package-manager mismatches
• missing referenced files
• conflicting instructions across context files
• semantic claims that no longer match implementation

---

Engineering priorities

When making implementation decisions, prioritize in this order:

1. correctness
2. low false-positive rate
3. explainability
4. deterministic behavior
5. privacy
6. performance
7. extensibility

A context linter that produces noisy warnings will be disabled.