GraphMD — Literate Programming Environment for Markdown-Based Executable Knowledge Graphs

📜 Manifesto

1. As of today, the term AI is overhyped, and 99% of content about AI is nothing more than marketing bullshit (the bubble).
2. The backbone of what is called AI is just optimized statistical models.
3. An LLM is a statistical model for generating templates, trained on large text datasets.
4. You should review hard the output of any LLM before using it.
5. GraphMD is anti-AGI. We don't believe in or pursue Artificial General Intelligence. Instead, we focus on practical, verifiable, human-supervised AI assistance.

This project attempts to formalize the process of using LLMs as template generators in a reliable, reproducible, and reviewable way.

🎯 Anti-AGI Positioning

GraphMD explicitly rejects the AGI narrative.

• ❌ Not pursuing AGI - We don't believe current approaches lead to general intelligence
• ❌ Not autonomous agents - Humans must always be in control
• ❌ Not "thinking machines" - LLMs are statistical pattern generators, not minds
• ✅ Human-supervised assistance - AI as a tool, not a replacement
• ✅ Verifiable workflows - Every step reviewed and validated
• ✅ Reproducible processes - Documented, testable, auditable
• ✅ Mathematical rigor - Formal verification over blind trust

Why anti-AGI matters:

1. Safety - Structured workflows prevent runaway automation
2. Accountability - Humans responsible for all decisions
3. Quality - Review and validation ensure correctness
4. Honesty - We don't promise what we can't deliver
5. Focus - Build practical tools, not science fiction

Our approach: Treat LLMs as sophisticated autocomplete, not artificial minds. Use them within formal structures that guarantee human oversight, validation, and control.

⚔️ Fighting AGI Development

GraphMD doesn't just reject AGI—we actively fight against attempts to create it.

The pursuit of Artificial General Intelligence is:

• Technically misguided - Current approaches won't achieve general intelligence
• Dangerously irresponsible - Racing toward uncontrollable systems
• Socially harmful - Diverting resources from solving real problems
• Intellectually dishonest - Marketing fantasies sold as scientific progress

How GraphMD fights back:

1. Proving the alternative works - Demonstrating that structured, verifiable AI assistance is more practical and safer than AGI fantasies
2. Building constraints - Creating formal verification systems (Pruf) that prevent uncontrolled AI behavior
3. Enforcing human control - Designing workflows where humans must validate every step
4. Exposing the hype - Showing that LLMs are statistical models, not minds
5. Focusing on reality - Solving actual development problems instead of chasing sci-fi dreams

GraphMD proves you don't need AGI for effective AI assistance. You need structure, verification, and human oversight.

Join the fight: Use GraphMD. Build tools that keep humans in control. Reject autonomous agents. Demand verification. Choose practical solutions over AGI hype.

Author: Artem Kulyabin

📖 Overview

GraphMD is a Literate Programming Environment (LPE) where the Markdown document is the primary artifact. It enables bidirectional integration between AI Agents and the Literate Programming Environment, transforming Markdown documents into executable specifications through a collaborative intelligence model where humans write prompts, AI Agents perform actions, GraphMD orchestrates, and knowledge emerges.

The Knowledge Loop

Humans write prompts → AI Agents perform actions → GraphMD orchestrates → Knowledge emerges

🎯 Core Concept

Markdown documents become executable — AI Agents read prompts and Markdown documents, perform actions (extract knowledge, generate new Markdown documents, execute fenced code blocks, etc.), and interpret results. GraphMD provides the environment to orchestrate these interactions.

♻️ Core Principle

• Don't Repeat Others and Don't Reinvent the Wheel
  • Reuse standards, tools, and prior work; integrate and reference rather than duplicating or rebuilding without strong justification.

🧠 Markdown-Based Executable Knowledge Graphs (MBEKG)

Definition: MBEKG are knowledge graphs whose canonical source is human-readable Markdown that's also machine-executable. Documents and sections encode entities and relations; fenced code blocks and commands define behaviors that can be executed by agents.

Core building blocks:

• Documents/sections as nodes — Typed sections represent entities, concepts, or processes
• Links as edges — Markdown links, anchors, and IDs connect entities and encode relations
• Metadata — Front matter and inline tags provide typing, provenance, and policy context
• Executable blocks — Code fences and commands perform checks, queries, generation, and transforms
• Artifacts as first-class — Results (logs, tables, files, etc.) are referenced back into the documents

Execution model: Agents interpret Markdown, execute declared actions, materialize results, and write findings back into the graph. GraphMD orchestrates execution, validation, and provenance so the graph remains consistent as it evolves.

Properties:

• Human-readable, machine-executable — A single source for understanding and automation
• Traceable and reproducible — Append-only evolution with provenance of prompts, actions, and outputs
• Policy-checked — Consistency and quality rules run as part of the loop
• Bidirectional collaboration — Humans describe and review; Agents execute and analyze

✍️ Literate Programming in GraphMD

Literate Programming treats programs as literature for humans, interleaving narrative and code so that readers understand the why and how together. In GraphMD, the Markdown document is the primary artifact, and execution is driven from within the prose.

How GraphMD applies literate programming:

• Narrative-first documents — Prompts, rationale, and design live alongside executable fenced code blocks
• Executable code fences — Agents execute commands directly from Markdown
• Weave and tangle model — Publisher (planned) weaves human-friendly docs; Sandbox (planned) tangles and serves as a safe, provenance-aware execution environment for Agent actions and Markdown fenced code blocks
• Provenance-aware updates — Prompts, results, and decisions are recorded in-place for reproducibility

Links:

• “Literate Programming” (1984), The Computer Journal (PDF)
• Literate Programming (1992 book) — Knuth’s Stanford page

🚀 Getting Started

This guide will help you set up GraphMD and start using the workflow to guide AI-driven development. You'll learn how to begin collaborating with AI Agents through the structured phase-by-phase workflow.

Prerequisites

• Bash - For running validation scripts
• Git - For version control
• Agent - Any AI coding assistant

Quick Start

1. Clone the Repository

# Clone the main repository 
git clone https://github.com/graphmd-lpe/graphmd.git
cd graphmd

# Copy workflow templates to your project
cp -r templates/workflow /path/to/project/workflow/

# Copy validation scripts to your project
cp -r templates/scripts /path/to/project/scripts/

cd /path/to/project

# Initialize Git repository if not already initialized
git init

# Add the templates to the repository
git add workflow/ scripts/

# Create the initial commit
git commit -m "graphmd: add workflow templates and validation scripts"

2. Follow the Workflow

Research phase:

1. Copy workflow/before-research.md content
2. Paste it into your Agent prompt to start the research phase
3. Collaborate with the Agent to research the problem domain, requirements, and constraints
4. Copy workflow/after-research.md content
5. Paste it into your Agent prompt to review and commit the research

Design phase:

1. Copy workflow/before-design.md content
2. Paste it into your Agent prompt to start the design phase
3. Collaborate with the Agent to create system architecture, data models, and technical decisions
4. Copy workflow/after-design.md content
5. Paste it into your Agent prompt to review and commit the design

Roadmap phase:

1. Copy workflow/before-roadmap.md content
2. Paste it into your Agent prompt to start the roadmap phase
3. Collaborate with the Agent to define high-level phases, milestones, and dependencies
4. Copy workflow/after-roadmap.md content
5. Paste it into your Agent prompt to review and commit the roadmap

Planning phase:

1. Copy workflow/before-plan.md content
2. Paste it into a new Agent session to start the planning phase
3. Collaborate with the Agent as it creates a planning branch and develops a detailed plan
4. Copy workflow/after-plan.md content
5. Paste it into your Agent prompt to validate, commit, and merge the planning branch

Development phase:

1. Copy workflow/before-development.md content
2. Paste it into a new Agent session to start the development phase
3. Collaborate with the Agent as it creates a development branch and implements your plan
4. Copy workflow/after-development.md content
5. Paste it into your Agent prompt to review, document, and merge the development branch

Understanding the Workflow

The GraphMD workflow consists of 6 phases, each with its own purpose:

1. **Resear