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.
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
How-to docs with confidence levels and gotcha callouts that grow with each implementation. Located in `.context/guides/`.
Session Checkpoints
Structured handoff protocol for context boundary crossings — conversation ends, agent swaps, machine switches.
Evidence Epistemology
4-tier claim tagging, evidence hierarchy, bias ledger. Prevents strategy built on unverified claims.
IP Safety
Pre-write verification checks — no misattribution, no AI co-author, no leaked secrets, no internal paths.
Context Budget Management
Treats context window as finite computational resource. Budget allocation and progressive disclosure.
Multi-Agent Coordination
Task queue format, agent contracts, cross-agent handoff, parallel execution rules.
Cross-Repo References
Hub-and-spoke model with repo registry, explicit relative paths, no-duplication rules.
Discovery Order
Formalized 10-step navigation sequence with token-aware loading strategy.
MCP Integration
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 |
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 | .cursorrules | copilot-inst. | .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 | ✓ | — | — | ✓ | — | ✓ |
Fully backward-compatible
All v3 additions are optional. A valid v2 project is already a valid v3 project. Adopt features incrementally.
- 1
Bump version30 sec
Change version in surfcontext.json from "2.0" to "3.0"
- 2
Add guides directory2 min
Create .context/guides/ and add guidesDir to surfcontext.json
- 3
Add discovery order1 min
Document your project's navigation sequence in surfcontext.json
- 4
Start checkpointingOngoing
Write session checkpoints to plans/sessions/ when context gets long
- 5
Tag evidenceOngoing
Add [verified], [unverified], [assumption] tags to claims
- 6
Configure IP safety1 min
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