MRRS — Machine-Readable Repo Standard

Make GitHub repos understandable by everyone: non-technical users, developers, and AI agents.

graph LR
    subgraph "Today's Repos"
        A[README.md] --> B[Written for<br/>developers only]
        B --> C["Non-technical<br/>users bounce"]
        B --> D["AI agents<br/>guess at structure"]
    end

    subgraph "MRRS Repos"
        E[Structured<br/>template] --> F["Everyone<br/>understands"]
        E --> G["AI agents<br/>parse instantly"]
        E --> H["Developers<br/>get full depth"]
    end

    style C fill:#ff6b6b,color:#fff
    style D fill:#ff6b6b,color:#fff
    style F fill:#4ecdc4,color:#fff
    style G fill:#4ecdc4,color:#fff
    style H fill:#4ecdc4,color:#fff

Loading

What is MRRS?

A standard file structure and documentation pattern you copy into any GitHub repo. No build step, no external tools — just markdown and YAML that GitHub renders natively.

Your repo becomes readable by three audiences simultaneously:

graph TD
    R[Your Repo + MRRS] --> T1
    R --> T2
    R --> T3

    subgraph T1["Tier 1 — Everyone"]
        A["Plain-english overview<br/>Mermaid diagrams<br/>No jargon"]
    end

    subgraph T2["Tier 2 — Users"]
        B["Non-technical path<br/>(clicks + settings)"]
        C["Developer path<br/>(terminal commands)"]
    end

    subgraph T3["Tier 3 — Developers + AI"]
        D["REPO_MANIFEST.yml<br/>Architecture docs<br/>Command reference"]
    end

    style A fill:#4ecdc4,color:#fff
    style B fill:#4ecdc4,color:#fff
    style C fill:#45b7d1,color:#fff
    style D fill:#ff9f43,color:#fff

Loading

The Key Innovation: REPO_MANIFEST.yml

A structured YAML file in .github/ that gives any reader — human or machine — instant understanding of your repo:

schema: mrrs/v0.1
name: my-project
description: One sentence a non-technical person would understand

overview:
  what: What it does (plain english)
  why: What problem it solves
  who: Who it's for

architecture:
  type: cli
  languages: [python, bash]
  components:
    - name: Main Script
      file: main.py
      purpose: Does the thing
      entry_point: true

commands:
  - name: run
    usage: my-project run
    destructive: false

When Claude, Copilot, or any AI agent encounters this file, it instantly knows what the project does, every command, the tech stack, and how components connect — no README parsing required.

File Structure

graph TD
    Root["your-repo/"] --> README["README.md<br/><i>Three-tier progressive disclosure</i>"]
    Root --> ARCH["ARCHITECTURE.md<br/><i>System design + diagrams</i>"]
    Root --> QS["QUICKSTART.md<br/><i>Zero to working, all skill levels</i>"]
    Root --> GH[".github/"]
    Root --> Docs["docs/"]

    GH --> Manifest["REPO_MANIFEST.yml<br/><i>Machine-readable metadata</i>"]

    Docs --> Concepts["CONCEPTS.md<br/><i>Explain like I'm not a developer</i>"]
    Docs --> Technical["TECHNICAL.md<br/><i>Developer deep-dive</i>"]
    Docs --> Trouble["TROUBLESHOOTING.md<br/><i>Decision-tree format</i>"]
    Docs --> Change["CHANGELOG.md<br/><i>What changed, in human language</i>"]

    style Manifest fill:#ff9f43,color:#fff,stroke:#ff9f43
    style README fill:#4ecdc4,color:#fff,stroke:#4ecdc4

Loading

Quick Start

Apply MRRS to an existing repo

git clone https://github.com/joemahoney-cloud-latitude/mrrs.git
cp -r mrrs/template/* my-existing-project/
cp mrrs/template/.github/REPO_MANIFEST.yml my-existing-project/.github/
cd my-existing-project
# Fill in the {placeholders}, delete the HTML comments, push

Start a new repo with MRRS

git clone https://github.com/joemahoney-cloud-latitude/mrrs.git
cp -r mrrs/template/ my-new-project/
cd my-new-project && git init
# Fill in templates, commit, push

What's in the Template

File	Audience	Purpose
README.md	Everyone	Three-tier front door with diagrams
ARCHITECTURE.md	Developers + AI	System design with mermaid visuals
QUICKSTART.md	Users	Zero-to-working for all skill levels
.github/REPO_MANIFEST.yml	AI + Tools	Structured metadata (the key file)
docs/CONCEPTS.md	Non-technical	Plain-english explainer, no code
docs/TECHNICAL.md	Developers	Deep-dive implementation details
docs/TROUBLESHOOTING.md	Everyone	Decision-tree problem solving
docs/CHANGELOG.md	Everyone	What changed, in human language

Design Principles

1. GitHub renders everything — no external tools, no build step, no images to maintain
2. Three audiences — non-technical, developers, AI agents
3. Progressive disclosure — simple first, depth on demand
4. Predictable structure — same file locations across every MRRS repo
5. One template to apply — copy, fill in placeholders, push

See DESIGN.md for the full specification.

License

MIT — Joe Mahoney / Cloud Latitude

---

_{MRRS v0.1 — Created by Joe Mahoney at Cloud Latitude}