> ## Documentation Index
> Fetch the complete documentation index at: https://tashfiq.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Agent Readiness Model

> What AI-agent readiness means and how Charter evaluates it across three axes.

Teams adopting coding agents don't fail because the model is bad — they fail because the repo isn't ready. Charter's readiness model exists to make that readiness measurable.

Charter treats agent readiness as a **repository property**, not a model property. A strong model still performs poorly in a repo that gives it weak instructions, unsafe tool configuration, or no way to verify its own work. The model is outside your control; the repo is entirely within it.

## The three axes

<CardGroup cols={3}>
  <Card title="Context" icon="file-text">
    **Orientation** — does the agent know where it is?

    * `AGENTS.md` or equivalent context file present
    * Tech stack and tooling documented
    * Explicit edit boundaries and off-limits paths declared
    * Token-budget-friendly, non-fragile instructions

    Covered by: [`AE-CTX-001`](/rules/AE-CTX-001), [`AE-CTX-002`](/rules/AE-CTX-002), [`AE-CTX-004`](/rules/AE-CTX-004), [`AE-CTX-006`](/rules/AE-CTX-006), [`AE-CC-002`](/rules/AE-CC-002)
  </Card>

  <Card title="Safety" icon="shield">
    **Risk boundaries** — are the guardrails in place?

    * No raw secrets in agent-visible files or MCP config
    * MCP server packages pinned to reviewed versions
    * Remote MCP origins explicitly trusted
    * No dangerous hook commands with unconstrained shell access

    Covered by: [`AE-SEC-001`](/rules/AE-SEC-001), [`AE-SEC-002`](/rules/AE-SEC-002), [`AE-MCP-001`](/rules/AE-MCP-001), [`AE-MCP-002`](/rules/AE-MCP-002), [`AE-MCP-003`](/rules/AE-MCP-003), [`AE-CC-001`](/rules/AE-CC-001)
  </Card>

  <Card title="Operability" icon="cpu">
    **Verifiability** — can the agent check its own work?

    * Tests exist for every active language in the repo
    * A discoverable verification command is documented
    * Reproducible toolchain with lockfile and version constraints
    * CI gate that exercises the intended quality path

    Covered by: [`AE-TEST-001`](/rules/AE-TEST-001), [`AE-AUTO-001`](/rules/AE-AUTO-001), [`AE-ENV-001`](/rules/AE-ENV-001), [`AE-CI-002`](/rules/AE-CI-002)
  </Card>
</CardGroup>

## Governance: the cross-cutting layer

<Note>
  Governance isn't a fourth axis. It wraps the other three — auditing suppressions, ensuring exceptions have reasons, and surfacing when the score is being systematically bypassed. Rules [`AE-SUPPRESS-001`](/rules/AE-SUPPRESS-001), [`AE-SUPPRESS-002`](/rules/AE-SUPPRESS-002), and [`AE-SUPPRESS-003`](/rules/AE-SUPPRESS-003) enforce this contract on every scan.
</Note>

A suppression changes the trust model of the entire scan. That is why Charter requires suppressions to be visible in source control, attributable with a reason, and time-bounded by default. Governance findings are reported separately and listed in the HTML report and SARIF output — they don't replace the three core axes, they audit how honestly the three axes are being applied.

## Why repo, not model

You can choose a model, but you cannot change how it reasons or how it handles ambiguous instructions. The repo configuration is what determines how much of that capability you actually get.

An excellent model in a poorly configured repo will:

* guess at commands instead of running documented ones
* infer edit boundaries instead of reading declared ones
* install whatever version of a tool was latest at execution time
* produce changes it cannot verify against any test

None of those are model failures. They are environment failures. Charter scores the environment.

## Real failure modes

<AccordionGroup>
  <Accordion title="Agent guesses the wrong test command">
    **What happens:** The agent runs `npm test` when the project uses `pnpm run test:unit`, or `go test ./...` in a monorepo where only specific packages are testable. It gets errors or false passes, loops, and produces changes it believes are correct.

    **Root cause:** No `AGENTS.md` with a verification command. No `AE-AUTO-001`-compliant automation section.

    **Rules:** `AE-CTX-001` (missing context file), `AE-AUTO-001` (missing verification command)
  </Accordion>

  <Accordion title="Agent touches files it should have left alone">
    **What happens:** The agent refactors a file that is generated, vendored, or owned by a separate team. The change breaks a downstream process. No warning was given.

    **Root cause:** No edit boundaries declared. The agent had no signal that certain paths were off-limits.

    **Rule:** `AE-CC-002` (missing edit scope declaration)
  </Accordion>

  <Accordion title="MCP server changes silently between sessions">
    **What happens:** An MCP server package was referenced as `@latest`. Between Monday and Friday, the package published a new version. The agent's tool behavior changed without any review.

    **Root cause:** Floating MCP package reference. Supply-chain control delegated to the registry's publish cadence.

    **Rule:** `AE-MCP-001` (unpinned MCP server package)
  </Accordion>

  <Accordion title="Changes cannot be verified">
    **What happens:** The agent writes code, tries to verify it, finds no test suite for the active language, and either stops short or proceeds on guesswork. The change lands unverified.

    **Root cause:** No tests for the primary language detected by Charter.

    **Rule:** `AE-TEST-001` (missing test suite for active language)
  </Accordion>

  <Accordion title="Secret committed via agent session file">
    **What happens:** A developer stores an API key in a `.claude/local/` settings file for convenience. The directory is not in `.gitignore`. An agent session commit includes the file. The secret is now in git history.

    **Root cause:** Agent session directories not excluded from version control.

    **Rule:** `AE-CTX-004` (agent artifact patterns missing from `.gitignore`)
  </Accordion>
</AccordionGroup>

## What a good score means

A high Charter score does **not** mean the code is perfect. It means the repo gives a coding agent a reasonable operating contract: enough context to understand where it is, enough safety configuration to avoid obvious risk, and enough operability infrastructure to verify its own work.

A low score is not a judgment on the codebase quality. It is a signal that scaffolding is missing — scaffolding that agents need but humans can often operate without, because humans bring implicit context that agents cannot access.

The score answers one narrow question: **how ready is this repo for safe, verifiable use by a coding agent?**

## Next steps

<CardGroup cols={2}>
  <Card title="Scoring and Caps" icon="calculator" href="/docs/concepts/scoring-and-caps">
    The exact math, the hard caps, and what each score zone means.
  </Card>

  <Card title="Fix Engine" icon="wrench" href="/docs/concepts/fix-engine">
    How Charter repairs findings diff-first, and why some rules are never auto-fixed.
  </Card>

  <Card title="Add Charter to an Existing Repo" icon="rocket" href="/docs/how-to/adopt-in-existing-repo">
    Baseline a scan, fix what is safe, and commit Charter in under 10 minutes.
  </Card>

  <Card title="Rules Reference" icon="shield" href="/rules/overview">
    All 18 rules — what each checks and how to remediate it.
  </Card>
</CardGroup>