Specification

Version 0.1 Draft

This document defines the Rune Context Protocol (RCP).

The purpose of RCP is to standardize repository understanding in a portable, deterministic, and human-readable format.

---

Status

Current Version:

RCP 0.1 (Draft)

Stability:

Experimental

Future versions may change incompatible formats.

Version 1.0 aims to provide long-term compatibility guarantees.

---

Goals

RCP aims to:

• provide persistent repository understanding
• reduce unnecessary token consumption
• support any programming language
• remain human-readable
• remain versionable
• remain deterministic

---

Non-Goals

RCP does not define:

• code generation
• LLM behavior
• editing strategies
• vector databases
• cloud APIs
• model interfaces

RCP provides context.

Agents provide intelligence.

---

Repository Layout

Repositories implementing RCP contain:

.rune/

Example:

repo/
├── src/
├── tests/
├── .git/
└── .rune/

---

Directory Structure

.rune/
├── spec.md
├── architecture.md
├── conventions.md
├── graph.json
├── files/
├── features/
├── ownership/
├── sessions/
└── cache/

---

Required Files

Implementations MUST provide:

spec.md
graph.json

Implementations SHOULD provide:

architecture.md
conventions.md

Implementations MAY provide:

ownership/
sessions/
cache/

---

spec.md

Purpose:

Repository identity.

Example:

# Project

Backend:
FastAPI

Frontend:
Next.js

Database:
PostgreSQL

Requirements:

• UTF-8 encoding
• Markdown format

---

architecture.md

Purpose:

Technology stack and architectural overview.

Requirements:

• Markdown
• UTF-8

---

conventions.md

Purpose:

Coding conventions.

Example:

Rules:

- Use repository pattern.
- Never use raw SQL.

---

graph.json

Purpose:

Dependency relationships.

Example:

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

Requirements:

• UTF-8
• JSON object
• deterministic ordering

---

files/

Purpose:

Per-file summaries.

Example:

.rune/files/auth.md

Contents:

# auth.py

Purpose:
Authentication service

Exports:
- login()
- logout()

Dependencies:
- user.py
- jwt.py

---

features/

Purpose:

Feature summaries.

Example:

.rune/features/login.md

Contents:

# login

Flow:

login.tsx
↓
auth.py
↓
jwt.py

---

ownership/

Purpose:

Ownership metadata.

Example:

frontend/*
backend/*

Optional.

---

sessions/

Purpose:

Temporary context.

Example:

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

Optional.

---

cache/

Purpose:

Implementation-specific cache.

Optional.

Cache contents are not part of the protocol.

---

File Encoding

All files MUST use:

UTF-8

---

Preferred Formats

Preferred formats:

• Markdown
• JSON

Avoid:

• binary formats
• databases

---

Determinism

Given identical repositories:

rune index

MUST produce identical outputs.

Implementations SHOULD avoid:

• timestamps
• random identifiers
• machine-specific paths

---

Human Readability

Important information MUST remain inspectable by humans.

Users SHOULD be able to view .rune/ with:

• vim
• VSCode
• nano
• Notepad

---

Source Code

Source code remains authoritative.

RCP stores:

• summaries
• relationships
• metadata

RCP never replaces source code.

---

Context Retrieval

Implementations MAY expose:

rune context "<task>"

Example:

rune context "Add Google OAuth"

Output:

{
  "related_files": [
    "auth.py",
    "user.py",
    "settings.py"
  ]
}

Output format is implementation-defined.

---

Plugins

Language support SHOULD be external.

Examples:

rune-python
rune-go
rune-typescript

Core implementations SHOULD remain language-agnostic.

---

Compatibility Levels

Minimal

Required:

spec.md
graph.json

---

Standard

Adds:

architecture.md
conventions.md
files/
features/

---

Extended

Adds:

ownership/
sessions/

---

Versioning

Future versions:

RCP 0.1
RCP 0.2
RCP 0.3
RCP 1.0

Major versions may introduce incompatible changes.

Version 1.0 aims to guarantee long-term stability.

---

Design Principles

Implementations SHOULD prioritize:

• simplicity
• portability
• determinism
• local-first operation

Implementations SHOULD avoid:

• network dependencies
• databases
• hidden state

---

Philosophy

History explains what changed.

Understanding explains what it means.

Git stores history.

Rune stores understanding.