Skip to content

DESIGN.md

Latest commit

 

History

History
143 lines (117 loc) · 5.01 KB

DESIGN.md

File metadata and controls

143 lines (117 loc) · 5.01 KB

Machine-Readable Repo Standard (MRRS)

Design Spec — v0.1

Problem

GitHub repos are written for developers. Non-technical users bounce off READMEs full of install commands and API references. DeepWiki solves this by generating visual docs, but requires an external service. We want repos that are natively readable by both humans and machines — no external tools needed.

Principles

  1. GitHub renders everything — Mermaid diagrams, markdown tables, collapsible sections all render natively
  2. Three-audience design — every repo serves: non-technical users, developers, and AI agents (Claude, Copilot, etc.)
  3. Progressive disclosure — simple overview first, technical depth on demand
  4. Standard file structure — predictable locations so any tool can parse any MRRS repo
  5. One command to apply — template can be scaffolded into any existing repo

File Structure

repo/
├── README.md                  # The "front door" — three-tier progressive disclosure
├── ARCHITECTURE.md            # System design with mermaid diagrams
├── QUICKSTART.md              # Zero-to-working in <5 minutes, for all skill levels
├── .github/
│   └── REPO_MANIFEST.yml      # Machine-readable metadata (the key innovation)
├── docs/
│   ├── CONCEPTS.md            # Plain-english explainer of what this does and why
│   ├── TECHNICAL.md           # Deep-dive for developers
│   ├── TROUBLESHOOTING.md     # Common issues, decision tree format
│   └── CHANGELOG.md           # What changed and why, in human language
└── [project files]

REPO_MANIFEST.yml — The Key File

This is what makes repos machine-readable. A structured metadata file that any AI agent, CLI tool, or documentation generator can parse:

schema: mrrs/v0.1
name: project-name
description: One sentence a non-technical person would understand
category: tool | library | template | service | documentation
audience:
  primary: developers | non-technical | mixed
  skill_level: beginner | intermediate | advanced

overview:
  what: What does this do? (plain english, 1-2 sentences)
  why: What problem does it solve? (plain english, 1-2 sentences)  
  who: Who is this for? (plain english)

architecture:
  type: script | cli | web-app | api | action | library | monorepo
  languages: [bash, python]
  dependencies: [python3]
  platform: [macos, linux]
  
  components:
    - name: Main Script
      file: claude-cleanup.sh
      purpose: Core cleanup automation
      entry_point: true
    - name: Monitor
      file: setup-monitor.sh
      purpose: Cron-based config monitoring

  data_flow: |
    User runs command → Script detects OS → Reads config files → 
    Backs up → Modifies → Clears cache → Restarts app

commands:
  - name: doctor
    description: Estimate token usage per connector
    usage: claude-fix doctor
    destructive: false
  - name: slim
    description: Disable heavy connectors, keep lightweight
    usage: claude-fix slim -y
    destructive: true
    backup: true
  - name: nuke
    description: Full cleanup — disable all + clear cache + restart
    usage: claude-fix nuke -y  
    destructive: true
    backup: true
  - name: restore
    description: Restore from most recent backup
    usage: claude-fix restore
    destructive: true

quickstart:
  install_time: 30 seconds
  steps:
    - Clone the repo
    - Make script executable
    - Add shell alias
    - Run doctor to check state
  
related:
  - url: https://support.anthropic.com
    label: Anthropic Support
  - url: https://claude.ai/settings/capabilities
    label: Claude Settings Page

README.md Three-Tier Structure

Every MRRS README follows this pattern:

# Project Name
> One-line description a non-technical person understands

## What This Does (Tier 1 — Everyone)
[2-3 paragraphs, no jargon, with a mermaid diagram]

## How to Use It (Tier 2 — Users)  
[Quickstart for non-technical, install for technical, both paths]

## How It Works (Tier 3 — Developers/AI)
[Architecture diagrams, command reference, config details]

Mermaid Diagram Requirements

Every MRRS repo includes at minimum:

  1. Architecture overview — what are the parts and how do they connect
  2. Data flow — what happens when you use it (sequence diagram)
  3. Decision tree — at least one flowchart for troubleshooting or usage

CONCEPTS.md Pattern

The "explain it to me like I'm not a developer" file:

  • Uses analogies (desk, filing cabinet, traffic, etc.)
  • No code blocks in the first half
  • Defines every technical term on first use
  • Answers: What is it? Why does it exist? How does it help me? Do I need to be technical?

Benefits for AI Agents

When Claude, Copilot, or any LLM encounters an MRRS repo:

  • REPO_MANIFEST.yml gives instant structured understanding
  • Predictable file locations mean no guessing
  • Mermaid diagrams in markdown are parseable
  • Three-tier README means the AI can match response depth to user skill level
  • Commands section gives exact usage without reading source code