Rune Project

Appearance

RUNE-001: Spec Standard ​Accepted

Updated2026-08-23

Summary ​

Defines how Rune specifications are organized, stored, audited, and maintained. Knowledge fragments and referenced source code are the source of truth; complete public Specs are reviewed narrative snapshots assembled from those inputs.

Motivation ​

Monolithic spec files (7-19KB) defeat semantic search and create maintenance burden. Fine-grained domain fragments enable precise AI context retrieval while keeping content self-contained and maintainable.

Design ​

Knowledge-First Architecture ​

  • knowledge/ — Fine-grained domain fragments (<5KB each). Source of truth.
  • docs/spec/ — Complete spec documents assembled from fragments. Generated view.
  • src/ — Source code. Source of truth for APIs and implementations.

Fragment Organization ​

Fragments are organized by domain and topic, not by RUNE-XXX numbers:

knowledge/
├── architecture/    — high-level overview (layers, data flow)
├── render/          — rendering engine (commands, snapshot, commit, compositing)
├── animation/       — animation system (spring, repeat, API)
├── text/            — text rendering (paragraph, layout)
├── interop/         — C#/native boundary (ABI, P/Invoke wrapper)
└── meta/            — knowledge system itself

Fragment Rules ​

Each fragment MUST:

  • Cover a single domain topic (answers one type of question)
  • Be < 5KB
  • Be self-contained (understandable without reading other fragments)
  • Include design rationale ("why X" and "why not Y") where relevant
  • Use tags for precise semantic search

Each fragment MUST NOT:

  • Mix multiple domains (e.g., render + animation + interop in one file)
  • Be a session diary ("in round 8 I learned...")
  • Define terms that belong in another domain's fragment
  • Duplicate information from another fragment

Front Matter ​

yaml
---
tags:
  - render
  - commands
related:
  - render/command-buffer
refs: []
---
  • tags — semantic search discovery
  • related — graph traversal to neighboring fragments
  • refs — pointers to source code (populated when code exists)

Spec Generation ​

When a complete spec is needed:

  1. Search fragments by relevant tags
  2. Assemble fragments into a coherent narrative document
  3. Verify claims against the fragments' source refs
  4. Output to docs/spec/RUNE-XXX.md
  5. Audit the result locally with Copilot against an exact main commit

RUNE-XXX numbers are conversation labels for human reference, not file organization.

There is no required deterministic generator. Mechanical regeneration cannot establish semantic correctness, so CI validates metadata, links, and referenced paths without claiming to audit content.

Public Spec Metadata ​

Every active public Spec records:

  • Status: Draft, Proposed, Accepted, Released, or Superseded
  • Audited at: audit date plus the full 40-character main commit SHA
  • Source: ordered source-of-truth knowledge/ fragment paths
  • Released in: required only for Released
  • Superseded by: required only for Superseded

Audit metadata is independent from maturity. It identifies the exact implementation baseline checked and does not imply continued synchronization after main advances. The full SHA MUST belong to main history; a feature-only commit is not a valid audit baseline.

Numbering ​

  • RUNE-0XX: Meta (standards, architecture)
  • RUNE-1XX: Programming model (DSL, state, execution)
  • RUNE-2XX: UI runtime (element tree, layout, input)
  • RUNE-3XX: Native interop & render system
  • RUNE-9XX: Backend implementations

Status Flow ​

Draft → Proposed → Accepted → Released

  • Draft is incomplete or not coherent enough for public review.
  • Proposed is complete enough for external review and may document beta behavior without becoming a stable compatibility contract.
  • Accepted is adopted as intended project design but is not necessarily a released contract.
  • Released is explicitly designated as the compatibility contract for a named version.
  • Superseded is a terminal historical state for a replaced Spec.

An audit never promotes maturity automatically. Promotion is an explicit project decision.

Writing Conventions ​

  • English for brainstorms, knowledge fragments, and code-facing docs
  • C for native API examples, C# for managed examples, pseudocode for algorithms
  • RFC-style normative language (MUST, SHOULD, MAY) for requirements

Dependencies ​

None (root spec).

Test Strategy ​

  1. All fragments remain below 5 KB
  2. Semantic search returns relevant fragments for domain queries
  3. Every public Spec declares existing knowledge sources and a full-SHA audit baseline
  4. Local audit verifies Spec claims against knowledge and source refs
  5. No broken related: links, Spec sources, or public documentation links

Rune Project brings Rune Story authoring together with the Rune Engine rendering foundation.

MIT License