Website • Releases • Getting Started • Documentation
Literate (Extended-by-Agent) Programming (LEAP) is a modern, AI-centric evolution of Donald Knuth's foundational concept of Literate Programming. Where traditional LP relied on complex, specialized compilation tools (like WEB, noweb, or Docco) to weave together source code and documentation, LEAP leverages conversational AI coding agents (such as Claude, Gemini, GPT) to naturally bridge explanation, intent, and implementation.
With LEAP, documentation and code co-evolve through an iterative, agent-friendly development lifecycle. By structuring your project's knowledge base and instructing your AI assistants to recognize and respect it, you ensure that your codebase remains fully comprehensible, maintainable, and aligned for both human engineers and AI coding agents.
- Documentation First: Define feature goals and execution plans before writing a single line of implementation code.
- Iterative Refinement: Code in discrete, logical phases with clear verification checkpoints.
- Test Throughout: Maintain high unit test and integration coverage (targeting 90%+) at every phase.
- Transparent Evolution: Track design decisions, architecture choices, and deferred technical debt in real time.
- Agent-Friendly Conventions: Style markdown consistently so that parsing, indexing, and LLM comprehension are frictionless.
The LEAP repository contains three key pillars to bootstrap your project's agent-extended development workflow:
A standardized directory structure for maintaining usage guides, architecture specifications, Architecture Decision Records (ADRs), and feature development progress.
kb/guide-*.md: End-user or developer usage documentation (APIs, CLI syntax, configuration).kb/impl-*.md: Technical design and implementation details (algorithms, data structures).kb/adr/: Architecture Decision Records to track the "why" behind system design.kb/feature/<username>/<feature-name>/: Standardized directory containing the goals, plans, and completion summaries of active features.- Templates: Pre-structured markdown templates for goals, plans, ADRs, tech debt, and more, located directly in
leap/kb/template-*.md.
A fast, Python-based CLI tool located in /check-md that ensures your documentation conforms to strict CommonMark and agent-friendly guidelines. It enforces five core formatting rules:
- Rule 1: Semantic Headings: Structure documents using proper markdown headings (
#,##, etc.) instead of bold text, facilitating document outlines and outline-based navigation. - Rule 2: Block Separation: Separate all block elements (lists, code blocks, blockquotes, tables) from preceding paragraph text with empty lines to prevent visual wrapping or rendering errors.
- Rule 3: Heading Level Increment: Maintain sequential heading hierarchy; never skip heading levels (e.g., from
##to####). - Rule 4: Nested Code Blocks: Correctly escape and nest code block formatting when writing documentation that demonstrates code examples.
- Rule 5: Label-Value Sequences: Use HTML
<br>tags rather than implicit spaces or empty lines to group contiguous bold-prefixed metadata lists (e.g., Status, Author, Date).
On-device semantic search tooling located in /scripts/qmd utilizing QMD to build local full-text search indexes of your documentation, allowing AI agents to query your knowledge base programmatically.
To adopt LEAP in your project, choose one of the two standard integration paths. In both cases, your project's custom documentation lives in an empty, root-level kb/ directory (separate from leap/kb/), which the setup script will configure for you automatically.
If your project is managed under Git, run the following single command in your project root to add LEAP as a submodule and launch the interactive configurator:
git submodule add https://github.com/blunderstone/leap.git leap && bash leap/scripts/setup-leap.sh(Note: If you use GitHub SSH keys, you can run git submodule add git@github.com:blunderstone/leap.git leap && bash leap/scripts/setup-leap.sh instead. To easily pin or update the submodule to a specific release tag, commit, or the 'latest' stable version while auto-generating LEAP compliance documents, use the automated pinning utility: bash leap/scripts/pin-leap.sh latest.)
If you are not using Git or prefer to copy files directly, download the LEAP repository, place it in a folder named leap at your project root, and run:
bash leap/scripts/setup-leap.shFor more details on custom configurations, manual workspace setup, and environments like Windows, refer to our comprehensive guide:
- LEAP Installation & Setup Guide: Prerequisites, manual setups, Windows troubleshooting, and verification.
For LEAP to succeed, the AI agents operating in your workspace must be explicitly instructed to follow the LEAP methodology—including its documentation-first and testing-first lifecycles, and its structured kb/ directory layout.
The interactive setup-leap.sh configurator will automatically generate pre-configured agent instruction files in your repository root during setup. It supports:
- Claude (
CLAUDE.md): For Claude Code, Cline, and Roo Code. - Gemini & Antigravity (
GEMINI.md): For Gemini CLI and Antigravity CLI. - GitHub Copilot (
.github/copilot-instructions.md): For Copilot Chat. - Cursor & Windsurf (
.cursorrules): For AI-powered IDEs.
(If you choose to configure your workspace manually, the raw template blocks for these agent instruction files can be found in our LEAP Installation & Setup Guide.)
For a complete explanation of the methodology, compliance requirements, and guides, refer to the following resources in the kb/ directory:
- LEAP Methodology Guide: Comprehensive deep dive into LP history, agent workflows, and core principles.
- LEAP Cheatsheet: Quick reference for branch names, folders, and markdown standards.
- Compliance Levels: Essential, Standard, and Comprehensive criteria.
- Markdown Formatting Standards ADR: Detailed reasoning behind
check-mdrules. - QMD Configuration Guide: Setup instructions for semantic search.
- Changelog: Automated release and version history driven by Conventional Commits.
This project is licensed under the terms of The Apache License, Version 2.0 (see LICENSE).
By contributing to this repository, you agree that your submissions are governed by the terms outlined in our Contributing Guide.
LEAP™ and Literate (Extended-by-Agent) Programming™ are trademarks of Blunderstone LLC.