Repository Format

.git/ stores history. .rune/ stores understanding.

---

Overview

Rune introduces a new directory:

.rune/

This directory contains the repository's semantic understanding.

Everything inside .rune/ is:

• human-readable
• versionable
• deterministic
• local-first

Preferred formats are:

• Markdown
• JSON

---

Directory Structure

A typical repository looks like:

repo/
├── src/
├── tests/
├── README.md
├── .git/
└── .rune/
    ├── spec.md
    ├── architecture.md
    ├── conventions.md
    ├── graph.json
    ├── files/
    ├── features/
    ├── ownership/
    ├── sessions/
    └── cache/

---

spec.md

The repository identity.

Location:

.rune/spec.md

Purpose:

• vision
• principles
• supported technologies
• non-goals
• architecture overview

Example:

# Project

Backend:
FastAPI

Frontend:
Next.js

Database:
PostgreSQL

---

architecture.md

High-level technical architecture.

Location:

.rune/architecture.md

Example:

Backend:
FastAPI

Frontend:
Next.js

Database:
PostgreSQL

Message Queue:
Redis

Purpose:

Allow humans and AI agents to quickly understand the stack.

---

conventions.md

Coding rules.

Location:

.rune/conventions.md

Example:

Rules:

- Use repository pattern.
- Never use raw SQL.
- APIs return Pydantic models.

Agents should respect these conventions.

---

graph.json

Dependency relationships.

Location:

.rune/graph.json

Example:

{
  "auth.py": [
    "user.py",
    "jwt.py"
  ]
}

Purpose:

Allow selective loading instead of loading the whole repository.

---

files/

Per-file summaries.

Location:

.rune/files/

Example:

.rune/files/auth.md

Contents:

# auth.py

Purpose:
Authentication service

Exports:
- login()
- logout()

Dependencies:
- user.py
- jwt.py

Related features:
- login
- signup

---

Size Target

File summaries should remain:

50–200 tokens

Avoid copying source code.

Summaries explain meaning, not implementation.

---

features/

Feature maps.

Location:

.rune/features/

Example:

.rune/features/login.md

Contents:

# login

Flow:

frontend/login.tsx
↓
api/auth.py
↓
user.py
↓
jwt.py

Tests:

tests/test_login.py

Purpose:

Describe behavior rather than file structure.

---

ownership/

Ownership metadata.

Location:

.rune/ownership/

Example:

.rune/ownership/frontend.md

Contents:

Owns:

components/*
pages/*
styles/*

Possible owners:

• frontend
• backend
• database
• infrastructure

Useful for multi-agent workflows.

---

sessions/

Temporary context.

Location:

.rune/sessions/

Example:

{
  "files": [
    "auth.py",
    "user.py"
  ]
}

Purpose:

Track recently modified files.

Sessions are disposable.

---

cache/

Internal caches.

Location:

.rune/cache/

May contain:

• hashes
• timestamps
• intermediate indexes

Cache contents are implementation details.

Users should not depend on them.

---

Human Readability

Everything important should be editable with:

• vim
• VSCode
• nano
• Notepad

No binary formats.

No databases.

No hidden metadata.

---

Versioning

The .rune/ directory is intended to be committed to Git.

Example:

.git/
.rune/
src/
tests/

Benefits:

• AI understanding becomes versioned.
• Teams share the same context.
• Pull requests can review semantic changes.

---

Determinism

Running:

rune index

twice on the same repository should produce identical outputs.

Avoid:

• randomness
• timestamps
• machine-specific paths

Deterministic outputs improve reproducibility.

---

Example Repository

myapp/
├── src/
├── tests/
├── .git/
└── .rune/
    ├── spec.md
    ├── architecture.md
    ├── conventions.md
    ├── graph.json
    ├── files/
    │   ├── auth.md
    │   ├── user.md
    │   └── billing.md
    ├── features/
    │   ├── login.md
    │   └── subscription.md
    ├── ownership/
    │   ├── backend.md
    │   └── frontend.md
    ├── sessions/
    └── cache/

---

Design Principles

Repository understanding should be:

• explicit
• versioned
• shareable
• deterministic
• language-agnostic

---

Philosophy

Source code explains how.

.rune/ explains why.

Git stores history.

Rune stores understanding.