by Velvet Tiger | https://velvettiger.com.au
A specification and skill set for making codebases safe for AI agent work.
The AI Readiness Framework defines the minimum practices, files, and code quality standards a project needs before AI coding agents can operate on it reliably. It gives agents the ability to orient themselves, produce consistent output, verify their own work, and know when to stop and ask.
The framework is structured as four tiers:
| Tier | Name | What it enables |
|---|---|---|
| 0 | Supervised | Agent can be pointed at the project without producing harmful output; human reviews every change |
| 1 | Guided | Agent understands conventions and makes consistent changes within a scoped area |
| 2 | Safe | Agent completes normal engineering tasks, runs its own checks, and escalates correctly — the target for most teams |
| 3 | Autonomous | Agent works across broader areas with less guidance; mechanical enforcement replaces documentation-only rules |
framework.md The specification — requirements, how to satisfy them, and examples
RULES.md Coding rules for agents working on this repository itself
skills/ Agent skills for implementing the framework in other projects
skill.json Package manifest for skill distribution
Ten skills are included for agents to use in other projects. Install them and invoke them by name.
| Skill | What it does |
|---|---|
ai-readiness-audit |
Audits a project against the full tier checklist and produces a prioritised gap report |
ai-readiness-scaffold |
Generates AGENTS.md, RULES.md, and ARCHITECTURE.md from codebase discovery |
| Skill | What it does |
|---|---|
agents-md |
Creates or updates AGENTS.md with all required sections |
rules-md |
Creates or updates RULES.md with stack-specific, non-generic rules |
architecture-md |
Creates or updates ARCHITECTURE.md including a Mermaid diagram |
| Skill | What it does |
|---|---|
dead-code-cleanup |
Removes commented-out code, resolved feature flags, and unused symbols |
error-handling-audit |
Finds and fixes silent failures, empty catches, and inconsistent error patterns |
boundary-audit |
Detects and remediates layer violations and cross-service boundary breaches |
| Skill | What it does |
|---|---|
escalation-check |
Checks a change against escape hatch conditions before commit or PR |
convention-check |
Verifies new code follows RULES.md conventions; produces a deviation report |
Run ai-readiness-scaffold to generate the required files from what can be discovered in the codebase. Review the output, fill in the marked placeholders, and check against the Tier 0 checklist in framework.md.
Run ai-readiness-audit to get a gap report showing which tier the project currently satisfies and what is missing. Work through the gaps tier by tier, starting at Tier 0.
Each tier in framework.md lists its requirements with identifiers (e.g. 2.2a, 1.7b). The checklist in the appendix groups them by tier. Use the document authoring and remediation skills to address individual gaps.
Add escalation-check and convention-check to your agent workflow as pre-commit gates. They read the project's own AGENTS.md and RULES.md, so they require no configuration beyond those files existing.
Skills follow the skill.json standard. Install with any compatible skill package manager, or copy the relevant skills/ directory into your project's .claude/skills/ directory.
- Tier 0 — Create a minimal
AGENTS.md, declare restricted areas, confirm a verification command exists. Takes an hour for most projects. - Tier 1 — Address code quality gaps (consistency, naming, dead code, error handling) and write full
AGENTS.md,RULES.md, andARCHITECTURE.md. Expect days to weeks depending on codebase condition. - Tier 2 — Add type coverage, a fast reliable test suite, clean layer boundaries, and operational documentation. This is the target for most teams.
- Tier 3 — Encode architectural rules into CI, restructure
AGENTS.mdas an index, build adocs/knowledge base with mechanical freshness checks. Only pursue this after validating agent workflows at Tier 2.
Do not skip tiers. The requirements at each level are prerequisites for the ones above.
MIT
Copyright 2026 Christopher Skene | https://velvettiger.com.au