Linked Literate Programming (LLP)

Keep humans in markdown. Let AI write and review the code.

LLP is infrastructure for codebases where humans work at the level they're good at — English prose, design decisions, principles, tradeoffs — and AI handles the code and most of the review. It's a structured way to give AI agents the context they need so that what they produce stays consistent with what the humans (and other AIs) behind the project actually want.

Rule of thumb: if an AI agent might "simplify" this code in a way that would break the design intent, it needs a reference.

Reference syntax at a glance

Element	Format	Example
LLP reference	@ref LLP NNNN#anchor — gloss	@ref LLP 0005#token-strategy — Why we rotate tokens
With relation	@ref LLP NNNN#anchor [rel] — gloss	@ref LLP 0005#token-strategy [implements] — Token rotation
LLP (broad)	@ref LLP NNNN	@ref LLP 0012 — Auth subsystem
Path reference	@ref path/to/file#anchor	@ref docs/vendor/spec.md#tokens — Token format
URL reference	@ref https://…	@ref https://datatracker.ietf.org/doc/html/rfc6749#section-4.1

The problem

Living codebases carry an enormous amount of implicit knowledge: the decisions, principles, and constraints behind why things are the way they are. Today that knowledge lives in Notion pages, Google Docs, Slack threads, and the heads of senior engineers. When an AI agent writes new code, it can't see any of it — and no model capability closes that gap, because the why behind code is information the code doesn't contain. A smarter model doesn't recover unrecorded rationale; it produces a more convincing guess.

Some AI harnesses address this with "memory" — ambient notes the agent accumulates. That helps, but it's unstructured and hard to curate: when you change your mind, remnants of the old decision linger and keep influencing new code. LLP is the structured, explicit version of that idea. Decisions live in markdown documents in the repo, versioned like code. When a decision changes, you update the document, and the next thing the AI writes reflects the new intent — not an echo of the old one.

The core idea

Humans stay in markdown. That's where they read fastest, argue most clearly, and make the decisions that matter. The code itself, and most of the review, can be left to AI — but the AI needs to know why the code exists in the form it does. LLP gives it that, via thin pointers from code to the exact section of the exact document that explains a given decision:

// @ref LLP 0042#token-strategy — Session tokens must be rotated on privilege escalation
pub fn escalate_privilege(session: &Session) -> Result<Session> {

The @ref comment is a machine-readable link. An agent reviewing this function follows it to the rationale and checks whether a proposed change still satisfies the constraint. Review shifts from "what is this doing?" to "does this still match the referenced decision?" — and the documentation can't drift into stale-wiki territory without the code starting to drift with it, because the documentation is what the agents work from.

Quick start

1. Create an llp/ directory and a root document:

# LLP 0000: My Project

**Type:** Explainer
**Status:** Active
**Systems:** Core
**Role:** Root
**Author:** ...
**Date:** YYYY-MM-DD

## Overview
What the project does and why.

## Architecture
Major subsystems and how they relate.

2. Reference decisions from the code that implements them:

// @ref LLP 0000#architecture — Widget service boundary
export function handleWidgetRequest(req: Request): Response {

3. Validate references and metadata with ref-check — a single-file, dependency-free checker suitable for CI (this repo runs it on every push):

./ref-check

For drift that takes judgment — code that no longer matches its referenced section, docs gone stale — use the llp-maintain skill interactively.

The full workflow (greenfield and retrofit) is in LLP 0001, and the llp-adopt skill automates it.

Skills

Five skills cover the LLP loop — each a plain-markdown directory under skills/ with a SKILL.md contract (trigger · invariants · artifact · hand-offs). Claude Code consumes them directly; other agent tools can adopt the same shape. Install by copying:

cp -r skills/llp-orient ~/.claude/skills/      # or all of skills/

Skill	Slash command	What it does
llp-orient	/llp-orient <path-or-task>	Load the governing LLP context before coding: root LLP, @refs in scope, the LLPs covering the relevant systems. Emits a compact context pack. Read-only.
llp-create	/llp-create <title>	Author one LLP — next number, filename, metadata scaffold. Prefers extending an existing LLP that already covers the topic.
llp-review	/llp-review <llp>	Run the LLP 0005 review loop, scaled to stakes. One provenance-tracked artifact per review actually received, under llp/reviews/. Never fabricates; never accepts on the author's behalf.
llp-adopt	/llp-adopt	Bring LLP to any repo — scaffold (fresh) or retrofit (survey, draft provenance-tagged docs, propose a plan), auto-detected.
llp-maintain	/llp-maintain --intent <mode>	Keep code and docs co-evolving: drift, ref repairs, provenance, retirements. Modes: pre-pr, audit, reconcile, retire-proposal. Proposes; never applies.

The skills are deletable adapters: every MUST in a SKILL.md cites the LLP section it comes from (as a pinned upstream URL, so copies stay resolvable), and a runtime with no skills mechanism gets the same behavior from the AGENTS.md routing block plus the documents. See LLP 0008 for the design and LLP 0009 for why the set is this small.

Writing new skills

A skill is a directory with a SKILL.md: YAML frontmatter (name, description, optionally source) plus markdown instructions. Keep descriptions precise — they're the signal for invocation — and keep policy in LLP documents, with the skill citing it.

What's in this repo

• New to LLP? LLP 0000 — the root spec: documents, @ref grammar, lifecycle, conventions.
• Adopting LLP in a project? LLP 0001 — greenfield and retrofit, one guide.
• The thinking behind it: LLP 0003 (prior art) and LLP 0004 (design principles).
• Authoring and review process: LLP 0005 — stakes-scaled review with fixed honesty rules.
• The skills design: LLP 0008.
• Why it's this simple: LLP 0009 — the capability-invariant core, and what was cut to get here.

All documents live under llp/ (llp/tombstones/ holds the retired ones); skills under skills/; the checker is ref-check with its fixture under fixtures/.

License

MIT