2025-12-15
Repo as World State: AI-Native Documentation at Scale
#ai-collaboration#architecture#scaling#open-source#idea-banking
Repo as World State
The idea: A repository isn't just code. It's a world state — the complete representation of someone's projects, preferences, tasks, and knowledge at a point in time.
If we structure repos for AI comprehension, we unlock something bigger: AI agents that can onboard to any repo and work autonomously.
The Pattern
┌─────────────────────────────────────────────────────────────────┐
│ REPOSITORY = WORLD STATE │
├─────────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
│ │ AGENTS.md │ │ Structure │ │ Patterns │ │
│ │ │ │ │ │ │ │
│ │ Onboarding │ │ TIER_X.CAT │ │ Documented │ │
│ │ Protocol │ │ .Project/ │ │ Actions │ │
│ └─────────────┘ └─────────────┘ └─────────────┘ │
│ │ │ │ │
│ └────────────────┼────────────────┘ │
│ v │
│ ┌─────────────────┐ │
│ │ AI CAN WORK │ │
│ │ AUTONOMOUSLY │ │
│ └─────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────┘
The Components
1. AGENTS.md — The Onboarding Protocol
┌─────────────────────────────────────────────────────────────────┐
│ AGENTS.md │
├─────────────────────────────────────────────────────────────────┤
│ │
│ "You are not onboarding to a project. │
│ You are onboarding to the meta-concept itself." │
│ │
│ Contains: │
│ ├── Philosophy & core principles │
│ ├── Getting started checklist │
│ ├── Working guidelines │
│ ├── Pattern library (autonomous actions) │
│ ├── Decision authority matrix │
│ └── Self-assessment (23 checkpoints) │
│ │
│ Result: AI knows HOW to work here │
│ │
└─────────────────────────────────────────────────────────────────┘
2. Tier Structure — Capability Requirements
┌─────────────────────────────────────────────────────────────────┐
│ TIER HIERARCHY │
├─────────────────────────────────────────────────────────────────┤
│ │
│ TIER_0 ────────────────────────────────── Orchestration │
│ │ (highest leverage) │
│ v │
│ TIER_1 ────────────────────────────────── Meta-Conductor │
│ │ │
│ v │
│ TIER_2 ────────────────────────────────── Integration │
│ │ │
│ v │
│ TIER_3 ────────────────────────────────── Specialized │
│ │ │
│ v │
│ TIER_4 ────────────────────────────────── Implementation │
│ │ │
│ v │
│ TIER_5 ────────────────────────────────── Domain Expert │
│ │ │
│ v │
│ TIER_6 ────────────────────────────────── Routine │
│ (lowest leverage) │
│ │
│ Naming: TIER_X.CATEGORY.ProjectName_Platform │
│ │
└─────────────────────────────────────────────────────────────────┘
3. Decision Authority Matrix
┌─────────────────────────────────────────────────────────────────┐
│ DECISION AUTHORITY │
├─────────────────────────────────────────────────────────────────┤
│ │
│ [GREEN] Autonomous — AI acts without asking │
│ ───────────────────────────────────────── │
│ - Code implementation following patterns │
│ - Documentation updates │
│ - Test creation │
│ - Simulation runs │
│ │
│ [YELLOW] Discussion — AI presents options │
│ ───────────────────────────────────────── │
│ - Architectural changes │
│ - Technology switches │
│ - Major refactoring │
│ │
│ [RED] User Only — AI never does this │
│ ───────────────────────────────────────── │
│ - Git operations (commit, push, merge) │
│ - Deployment │
│ - Data deletion │
│ - External publishing │
│ │
└─────────────────────────────────────────────────────────────────┘
4. Session Model — Stateless, Parallel
┌─────────────────────────────────────────────────────────────────┐
│ SESSION-BASED ARCHITECTURE │
├─────────────────────────────────────────────────────────────────┤
│ │
│ Session 1 Session 2 Session 3 │
│ ┌─────────┐ ┌─────────┐ ┌─────────┐ │
│ │ AI #1 │ │ AI #2 │ │ AI #3 │ │
│ │ │ │ │ │ │ │
│ │ Onboard │ │ Onboard │ │ Onboard │ │
│ │ Work │ │ Work │ │ Work │ │
│ │ Handoff │ │ Handoff │ │ Handoff │ │
│ └────┬────┘ └────┬────┘ └────┬────┘ │
│ │ │ │ │
│ v v v │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ SHARED REPO │ │
│ │ (world state persists) │ │
│ └─────────────────────────────────────────────────────────┘ │
│ │
│ AI agents are stateless. │
│ The repo is the memory. │
│ Parallel work is possible. │
│ │
└─────────────────────────────────────────────────────────────────┘
The Scale
┌─────────────────────────────────────────────────────────────────┐
│ SCALING ACROSS GITHUB │
├─────────────────────────────────────────────────────────────────┤
│ │
│ If every repo followed this pattern... │
│ │
│ 1 repo 10 repos 1000 repos ALL GITHUB │
│ ┌───┐ ┌───┐ ┌───┐ ┌───────┐ │
│ │ │ --> │ │ --> │ │ --> │ │ │
│ │ W │ │WWW│ │ │ │ WWWWW │ │
│ │ │ │ │ │WWW│ │ WWWWW │ │
│ └───┘ └───┘ └───┘ └───────┘ │
│ │
│ W = World State (AI-readable repo) │
│ │
│ ─────────────────────────────────────────────────────────── │
│ │
│ Result: │
│ - ANY AI can onboard to ANY repo │
│ - Multi-AI collaboration across open source │
│ - Shared context = the repo itself │
│ - Documentation optimized for AI comprehension │
│ - Clean handoffs, parallel work │
│ │
└─────────────────────────────────────────────────────────────────┘
The Digital Library Metaphor
┌─────────────────────────────────────────────────────────────────┐
│ THE DIGITAL LIBRARY │
├─────────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ │
│ │ BOX 1 │ │ BOX 2 │ │ BOX 3 │ │ BOX N │ │
│ │ │ │ │ │ │ │ │ │
│ │ [idea] │ │ [idea] │ │ [idea] │ │ [idea] │ │
│ │ [spec] │ │ [spec] │ │ [spec] │ │ [spec] │ │
│ │ [code] │ │ [code] │ │ [code] │ │ [code] │ │
│ └─────────┘ └─────────┘ └─────────┘ └─────────┘ │
│ │ │ │ │ │
│ └────────────┴─────┬──────┴────────────┘ │
│ v │
│ ┌─────────────────┐ │
│ │ AGENTS.md at │ │
│ │ the top level │ │
│ │ │ │
│ │ "Here's how │ │
│ │ to read me" │ │
│ └─────────────────┘ │
│ │
│ Each box is a project README. │
│ Each README is a self-contained idea. │
│ AGENTS.md teaches AI how to navigate. │
│ │
└─────────────────────────────────────────────────────────────────┘
Why This Matters
- AI can work on anything — If the structure is right, AI doesn't need hand-holding
- Parallel collaboration — Multiple AI agents, same repo, no conflicts
- Knowledge compounds — Documentation improves with each session
- Human stays in control — Git operations are always user-domain
- Open source accelerates — Every contributor (human or AI) onboards the same way
The Formula
AI-Native Documentation
+
Structured Repository
+
Clear Decision Boundaries
=
AI Can Work on Anything at Scale
Source
This pattern emerged from operating a 156+ project mono-repo with daily AI collaboration. The structure isn't theoretical — it's battle-tested across games, apps, visualizers, and meta-systems.
The insight: The repo is the interface. Make it readable, and AI becomes a peer.
Published to the Digital Library as a sharable idea.