🚀 ai-ready-docs: The Standard for AI-Native Documentation

Stop writing documentation for humans. Start building APIs for LLMs.

ai-ready-docs (AIRD) is a rigorous specification designed to transform documentation from "human-readable text" into "AI-consumable interfaces."

In the era of Agentic Workflows, the bottleneck is no longer the model's reasoning power, but the quality and structure of the context and the precision of the execution paths provided. AIRD v1.2 eliminates ambiguity, minimizes token waste, and transforms documentation into a direct driver for autonomous AI agents.

---

📊 The AIRD Advantage

Dimension	Traditional Docs (Human-Centric)	AIRD Standard (AI-Native)
Discovery	Manual search / Random crawling	$\text{L1 Discovery} \rightarrow$ Instant mapping via llms.txt
Parsing	Heuristic chunking (Unpredictable)	$\text{L2 Structure} \rightarrow$ Deterministic hierarchy
Cognition	Reliance on LLM's general knowledge	$\text{L3 Context} \rightarrow$ Explicit ai-context blocks
Maintenance	Manual updates $\rightarrow$ Doc drift	$\text{L4 Evolution} \rightarrow$ Closed-loop .ai-feedback
Execution	Vague instructions $\rightarrow$ Hallucinations	$\text{L5 Actionable} \rightarrow$ Deterministic Execution Protocols

---

🏗️ The 5-Layer Protocol (AIRD Spec v1.2)

📡 L1: Discovery (The Map)

Goal: Immediate orientation via llms.txt.

🏗️ L2: Structure (The Skeleton)

Goal: Perfect chunking via strict hierarchy and deterministic naming.

🧠 L3: Context (The Brain)

Goal: Eliminate assumptions using ai-context blocks (Topic, Prerequisites, Warnings).

🔄 L4: Evolution (The Loop)

Goal: Continuous self-improvement via the .ai-feedback.md mechanism.

⚡ L5: Actionable (The Protocol) $\leftarrow$ NEW

Goal: Move from "Information Retrieval" to "Autonomous Execution" via ## Execution Protocol.

---

🛠️ Getting Started (The Fast Track)

1. 📚 Learn by Example

Don't start from scratch. Copy our proven AIRD templates for different scenarios: 👉 Explore the Examples Gallery

• Python Lib: Ideal for SDKs and utility tools.
• System Architecture: Best for complex enterprise software.
• Agent SOP: Perfect for AI-driven workflows.

2. 📈 Measure Your "AI-Readiness"

Run our advanced Linter to get a quantitative AI-Ready Score (0-100) and a detailed compliance report.

# Install/Download aird_lint_v5.py
python aird_lint_v5.py --suggest ./your-docs-folder

The linter now checks for broken semantic dependencies and calculates your readiness rank (Elite $\rightarrow$ Low).

3. 🔄 Operationalize the Evolutionary Loop

Stop manually fixing docs. Implement the L4 evolutionary workflow where AI failures drive automated PRs for documentation updates. 👉 Read the Feedback Workflow Guide

4. 🤖 Mastering Agentic Execution

Learn how to implement L5 protocols to turn your docs into an autonomous agent's operational manual. 👉 Read the Agentic Guide

5. 📜 Detailed Specification

For a deep dive into the technical requirements of each layer: 👉 Read the Full SPEC.md

---

🌟 Adoption & Ecosystem

We are building a world where every project is AI-Ready.

• Current Status: v1.2 (Agentic Stage)
• Goal: To become the default documentation layer for autonomous AI agents.

If you've implemented AIRD in your project, please let us know or open a PR to be added to our AIRD-Compliant Projects list!

---

📄 License

Distributed under the MIT License. See LICENSE for more information.