ARDS v3.0 — February 2026

What's new in ARDS v3.0

Nine new capabilities for structuring AI-agent-ready repositories. Living guides, session checkpoints, evidence epistemology, IP safety, context budget management, and more.

All v3 additions are backward-compatible. A valid v2 project is already a valid v3 project.

Read the Full Spec Quick Start
1,398
Spec Lines
27
Sections
9
New in v3
7
Doc Types
6+
Platforms
17
OSS Files

9 new capabilities

Each addresses a real problem discovered in 3+ months of daily production use across 15 repositories with 54 AI agents.

📖

Living Guides

.context/guides/

How-to docs with confidence levels and gotcha callouts that grow with each implementation.

⏰

Session Checkpoints

plans/sessions/

Structured handoff protocol for context boundary crossings -- conversation ends, agent swaps, machine switches.

👁

Evidence Epistemology

Inline tags

4-tier claim tagging, evidence hierarchy, bias ledger. Prevents strategy built on unverified claims.

🛡

IP Safety

surfcontext.json

Pre-write verification checks -- no misattribution, no AI co-author, no leaked secrets, no internal paths.

⚙

Context Budget Management

Spec Section 19

Treats context window as finite computational resource. Budget allocation and progressive disclosure.

👥

Multi-Agent Coordination

.context/queue.md

Task queue format, agent contracts, cross-agent handoff, parallel execution rules.

🔀

Cross-Repo References

repo-registry.md

Hub-and-spoke model with repo registry, explicit relative paths, no-duplication rules.

📚

Discovery Order

surfcontext.json

Formalized 10-step navigation sequence with token-aware loading strategy.

🔌

MCP Integration

surfcontext.json

Standard tool names for exposing .context/ content as MCP tools. Bridges knowledge to capabilities.

7 document types

Each type has a distinct purpose, mutability pattern, and read frequency. Agents load them at different times to optimize context window usage.

Type Location Mutability Read Frequency
Root Context CONTEXT.md Updated weekly Every turn
Agent Config .context/agents/*.md Stable On dispatch
Skill Config .context/skills/*/SKILL.md Stable On invocation
Knowledge Doc .context/docs/*.md Updated on change On demand
Guide .context/guides/*.md Living (grows) On demand
Plan Doc plans/**/*.md Immutable On demand
Research Doc research/**/* Versioned On demand

Formalized discovery order

A 10-step sequence agents follow to navigate any ARDS-compliant repository. Token-aware loading minimizes context window waste.

1
CONTEXT.md Always ~800/turn

Project identity, key files, architecture, active state

2
surfcontext.json Always ~200

Machine-readable config, platform targets, discovery hints

3
.context/docs/ On demand ~600 each

Evergreen knowledge -- architecture, conventions, schemas

4
.context/guides/ On demand ~800 each

Living how-to documents -- patterns, gotchas

5
.context/agents/ On dispatch ~400

Agent definitions -- only the dispatched agent

6
.context/skills/ On invoke ~400

Skill definitions -- progressive disclosure

7
.context/queue.md On request ~300

Multi-agent task queue

8
plans/ On demand ~800 each

Time-stamped work -- glob for relevant files

9
research/ On demand ~800 each

Academic manuscripts

10
Source code On demand varies

Follow architecture guidelines from CONTEXT.md

Feature comparison

ARDS is the only format covering the full documentation architecture. It generates files for every other format.

Feature ARDS AGENTS.md CLAUDE.md Cursor Copilot Gemini
Root context file ✅ ✅ ✅ — ✅ ✅
Agent definitions ✅ — ✅ — — —
Skill/rule definitions ✅ — ✅ ✅ ✅ —
Knowledge doc hierarchy ✅ — — — — —
Living guides ✅ — — — — —
Session checkpoints ✅ — — — — —
Cross-repo references ✅ — — — — —
Evidence epistemology ✅ — — — — —
IP safety rules ✅ — — — — —
Token budget guidance ✅ — — — — —
Discovery order ✅ — — — — ✅
Quality scoring rubric ✅ — — — — —
Multi-platform generation ✅ — — — — —
Machine-readable config ✅ — — ✅ — ✅

ARDS as superset

Not competing with existing formats. ARDS defines the full documentation architecture and generates platform-specific files from a single source.

Root Context → AGENTS.md, CLAUDE.md, copilot-instructions.md
Agents / Skills → Agent Skills (SKILL.md), .cursor/rules/*.mdc
Knowledge Docs → unique to ARDS unique
Living Guides → unique to ARDS unique
Plan Docs → PLANS.md (Codex)
Research Docs → unique to ARDS unique
Session Checkpoints → unique to ARDS unique
Cross-Repo Refs → unique to ARDS unique
Evidence System → unique to ARDS unique
IP Safety → unique to ARDS unique
MCP Integration → bridges ARDS content to MCP tools

Fully backward-compatible

All v3 additions are optional. A valid v2 project is already a valid v3 project. Adopt features incrementally.

1

Bump version

30 seconds

Change version in surfcontext.json from "2.0" to "3.0"

2

Add guides directory

2 minutes

Create .context/guides/ and add guidesDir to surfcontext.json

3

Add discovery order

1 minute

Document your project's navigation sequence in surfcontext.json

4

Start checkpointing

Ongoing

Write session checkpoints to plans/sessions/ when context gets long

5

Tag evidence

Ongoing

Add [verified], [unverified], [assumption] tags to claims

6

Configure IP safety

1 minute

Add ipSafety block to surfcontext.json if relevant

Ready to upgrade to v3?

All new features are opt-in. Start with a version bump and adopt capabilities as you need them.

Get Started Full Specification