md.sh

A high-fidelity, "under-the-hood" Markdown synchronization engine designed to maintain consistency across AI agent context files and project documentation.

The Problem

In multi-agent environments, agents often work in silos. Claude might refactor a module while Gemini is still reading an outdated prd.md. This leads to context drift, conflicting changes, and redundant "just-in-case" logic.

The Solution

md.sh acts as the shared hippocampal system for your repository. It automatically synchronizes core project documents (prd.md, design.md, memory.md) into agent-specific context files (claude.md, gemini.md) and injects "Activity Warnings" based on recent Git history.

Architecture Workflow

graph TD
    A[Global Source of Truth] -->|prd.md, design.md, memory.md| B(md.sh Sync Engine)
    G[Git History & Diff] -->|Recent activity/authors| B
    B -->|Markdown AST Reconstruction| C{Agent Contexts}
    C -->|Update| D[claude.md]
    C -->|Update| E[gemini.md]
    C -->|Update| F[agents.md]
    D -.->|Agent adds Notes| D
    E -.->|Agent adds Notes| E

Loading

Features

• AST-Aware Merging: Unlike simple text appending, md.sh parses Markdown into an Abstract Syntax Tree. It manages specific H1 sections while preserving user/agent-owned sections like # Agent Notes.
• Git Activity Injection: Automatically summarizes recent commits and uncommitted changes, warning agents if a file they are looking at was recently modified by another entity.
• Headless & Glamourless: Designed to run via CLI or Git hooks. It doesn't interfere with your workflow; it just keeps your context fresh.
• Heading Demotion: When nesting global context, md.sh automatically demotes headings to maintain document structure integrity.

Installation

cargo install --path .

Getting Started

1. Initialize your repository

mdsh init

This scaffolds the required documentation structure.

2. Synchronize Context

mdsh sync

Execute this before starting a new task or after an agent finishes its work.

Project Structure

• src/main.rs: CLI Entry point (Clap).
• src/markdown.rs: AST parser and section manager (pulldown-cmark).
• src/git.rs: Git diff and activity extractor (git2).
• src/sync.rs: Core reconciliation logic.
• src/init.rs: Scaffolding logic.

Repository Layout (Dev Kit Style)

The repo is organised in five layers — rules, knowledge, guardrails, delegation, distribution — so an agent can pick up the project cold and know where to look.

Layer	Folder	Purpose
L1 Memory	CLAUDE.md/	Workflow rules (CLAUDE.md), sync safety invariants (Sync.md), local overrides (Sync.local.md, gitignored).
L2 Knowledge	skills/	Playbooks: init-project.md, resync-drift.md, agent-onboarding.md.
L3 Guardrails	hooks/	Shell hooks: PreCommit.sh (auto-sync before commit), PostSync.sh (log drift), PreRelease.sh (test + version).
L4 Delegation	subagents/	Subagent briefs: doc-auditor.md, sync-validator.md, release-notes.md.
L5 Distribution	plugins/	alerts/ (notifications) and reports/ (periodic drift summaries) — currently README stubs.

Note: CLAUDE.md/ is a folder; claude.md (lowercase) is md.sh's auto-managed agent context file. They coexist on case-sensitive filesystems.

Versioning Rule

Our versioning follows a high-frequency update pattern:

• v0.[PR_COUNT].[COMMIT_COUNT]
• Every commit increment the patch version.
• Every merged Pull Request increments the minor version.