v0.1.4 · CC BY 4.0Letting an agent into your repo isn’t a vibe. It’s a level.
Coding agents now write, review, and merge code. There’s no shared definition of what anagent-friendly repo even looks like — every team reinvents the guardrails. This spec is the shared definition: 29 clauses, 7 pillars, 5 levels, and a single audit loop that tells you exactly where your repo sits today.
Why this matters
Without a shared contract, every repo reinvents the guardrails.
01A common language for “agent-ready”
“Our repo is agent-friendly” means nothing today. L2 means something. Adopters get a checklist; tool authors get a stable target.
02Guardrails before you let agents in
Pinned environments, scoped capabilities, secrets handling, branch protection, attribution. The spec is the boring list nobody wants to write but everyone needs.
03Reproducible claims, not assertions
A repo claims a level by running the audit and producing a stamped artifact. Anyone can reproduce the audit at the same commit. No central registry, no vendor.
How conformance is checked
Install the skills. Run the audit.
Run the audit. Get a sorted backlog of gaps. Fix one row at a time. Rerun. Repeat until the repository reaches the level you actually need — not a level a benchmark told you to chase.
Step 01
Owner-confirmed answers about which checks apply. Drafted from repo evidence, then reviewed.
Step 02
Evidence collected, stamped, validated. A reviewable artifact: filled checklist, evidence JSON, sorted backlog.
Step 03
Close one gap at a time. The fix skill stops after each finding and asks what to do — commit, branch, push, or open a PR.
Step 04
Especially when you expect to reach the next level. A human or accountable owner accepts the result before claiming a level.
Until target level reachedSelf-declared, auditor-verifiable
After the audit
Five levels. One audit-backed claim.
When the audit lands and a human or accountable owner accepts the result, display the highest level your repository actually reaches. The full docs include the markdown badge pattern and pinned-spec variant.
L0Baseline Hygiene
AI is not part of the contribution workflow yet. People may still use AI for personal help, but no AI tool reads the repository as workspace context, creates commits, or opens pull requests.
L1Hardened
AI tools may read repository context, explain code, suggest commands, or help with review, but do not produce shippable changes
L2AI Assisted
AI may produce code, docs, tests, configuration, or migrations that a human actively accepts. Extra risks such as tool use, external GitHub content, fetched URLs, retained context, provider routing, and dependency suggestions must be controlled.
L3AI Authored
AI may complete delegated implementation tasks, open pull requests, or make material repository changes for human review
L4AI Autonomous
AI may merge, release, deploy, schedule recurring changes, approve workflows, rotate settings, or otherwise act without per-change human approval