Your operating system runs on binaries. Your AI agents should run on Markdown.

Think about it: A traditional OS has binary executable files—compiled, opaque, rigid. You execute /usr/bin/python and it does exactly what it was compiled to do. No negotiation. No adaptation. No editing the binary mid-execution.

Now imagine an operating system where there are no binaries. Just Markdown files. Prompts in plain English. An AI coding agent reads them, interprets them, executes them—and can edit them while running.

That’s not science fiction. That’s 2025. And it’s called Markdown-as-OS.

The Core Idea: Markdown Files Are the System

A normal operating system:

• Executables: Binary files in /bin, /usr/bin

• Configuration: Opaque formats (Registry, plist, binary configs)

• State: Scattered across databases, memory, temp files

• Logs: Binary formats, syslog, proprietary tools to read them

• Interface: APIs, CLIs, GUIs built in code

A Markdown operating system:

• Executables: Markdown prompts (plain English instructions)

• Configuration: AGENT.md, config.md (human-readable specs)

• State: state.md, queue.md (current system snapshot)

• Logs: journal.jsonl + runs/*.md (greppable, diffable)

• Interface: The Markdown files themselves (agents read and write them)

Nothing is compiled. Nothing is interpreted. It’s just Markdown. In English. And the agent reads it, understands it, executes it.

The agent can also edit it. Mid-execution. See a TODO in spec.md? Complete it, update the file, commit. State changes? Update state.md. Task done? Check the box in queue.md.

Dynamic. Transparent. Self-modifying. Auditable.

The 2025 Shift: Spec-Driven Development

In September 2025, GitHub open-sourced Spec Kit—a toolkit for spec-driven development with coding agents (GitHub Copilot, Claude Code, Gemini CLI). The idea: start with a specification (Markdown), make it the source of truth, let agents generate/test/validate code from it.

Same month, the AGENT.md standard gained native support across major coding agents:

• Amp: Native support since May 2025, multiple AGENT.md files since July 2025

• Claude Code, Cursor, Firebase Studio, Gemini CLI, OpenAI Codex: All support AGENT.md (native or via symbolic linking)

AGENT.md is “the README your AI coding agents actually read.” Place it at repo root (or subpackages in monorepos). Sections:

• Project overview, architecture notes

• Build/test commands

• Code style guidelines

• Testing instructions

• Security considerations

• Data constraints

Example from builder.io (real production AGENT.md):

The agent reads this before writing any code. Result: code matches project conventions, uses correct library versions, follows team style—on the first try.

No more “That’s not what we wanted” after three weeks of work.

LLMunix: The Pure Markdown OS

The most extreme example: LLMunix (GitHub: EvolvingAgentsLabs/llmunix).

Tagline: “Transform any LLM into an intelligent operating system using pure markdown.”

Architecture:

• Agents and tools defined entirely in Markdown documents

• No code compilation, no complex APIs

• Just Markdown that any LLM can interpret

Core concept: Treat everything as either an Agent (decision maker) or Tool (executor), all defined in Markdown. The framework automatically interprets agent definitions, routes tasks, handles tool execution—purely from Markdown instructions.

Use cases LLMunix handles:

• Research & analysis (multi-source data gathering, report generation)

• Development workflows (code generation, testing, deployment)

• Complex orchestration (multi-agent task decomposition, parallel execution)

Supported runtimes: Claude Code (recommended for production), Qwen Runtime (lightweight, learning/dev).

Files: CLAUDE_CODE_ARCHITECTURE.md, GEMINI.md, QWEN.md, setup scripts—all configuration in Markdown.

The Markdown OS Directory Structure

A typical Markdown-as-OS project looks like this:

Let’s walk through each directory.

1. /specs/ — The Source of Truth

specs/AGENT.md:

Agent reads this file first. Knows the stack, the rules, the workflow. No guessing.

specs/feature.md (requirement doc):

Agent reads this → knows exactly what to build. No ambiguity. No “I thought you meant…”

2. /plans/ — Agent-Generated Execution Plans

Agent reads specs/feature.md, generates plans/feature-plan.md:

Human reviews plan → approves → agent executes.

3. /runs/ — Execution Logs + Replayable Tests

runs/2025-09-30.md (human-readable log):

Human reads this → sees exactly what happened. No digging through binary logs.

runs/journal.jsonl (detailed NDJSON event stream):

Queryable with grep, jq, awk:

runs/test.md (replayable test script):

Agent (or human) can replay this script to verify the feature still works after changes. Deterministic. Reproducible.

4. /state/ — Current System State

state/queue.md (task queue with checkboxes):

Agents grep for – [ ], claim tasks, update to – [x], commit. Simple. Transparent.

state/deployment-state.md (current deployment state):

Agent reads this → makes deployment decisions → updates the file → commits. State is always current, always visible.

5. /reports/ — Human-Readable Summaries

reports/summary.md:

Human reads this → understands what happened, what to do next. No need to dig through logs.

How Agents Use Markdown OS

Agent workflow (Python pseudocode):

Key point: Agent reads Markdown, writes Markdown, edits Markdown. The OS is Markdown.

Real-World Example: WordPress Landing Page Deployment

Scenario: Marketing team wants a new landing page for a product launch.

Traditional workflow:

1. Marketing writes requirements in Slack/email (ambiguous, scattered)

2. Developer interprets requirements (guesses missing details)

3. Developer builds page (may not match intent)

4. Marketing reviews (requests changes)

5. Developer revises (2-3 rounds of back-and-forth)

6. Deploy (manual, error-prone)

7. QA (finds bugs, back to step 5)

Total time: 3-5 days. Frustration: high.

Markdown OS workflow:

1. Marketing writes specs/product-launch.md (structured requirement doc)

2. Agent reads spec → generates plans/product-launch-plan.md

3. Marketing reviews plan → approves (or edits the Markdown, re-runs)

4. Agent executes plan:Generates HTML/CSS from specWrites tests (runs/test.md)Runs tests (logs to runs/journal.jsonl)Deploys to WordPress (updates state/deployment-state.md)Verifies deployment (checks staging URL)

5. Agent writes reports/summary.md (what was built, links, next steps)

6. Marketing reviews report → page is live

Total time: 30 minutes. Frustration: zero.

Why? The spec was clear. The plan was visible. The execution was logged. The outcome was verified. All in Markdown.

The Advantages: Why Markdown Wins

1. Greppable

Find all TODO items:

Find all failed deployments:

Find when feature X was deployed:

No proprietary log viewers. No complex queries. Just grep.

2. Diffable

See what changed today:

Compare two execution runs:

Review agent’s changes before committing:

Markdown diffs are human-readable. JSON/binary diffs are gibberish.

3. Version-Controlled

Full audit trail in git history:

Rollback to previous state:

Branch strategies work naturally (feature branches, release branches, hotfix branches).

4. Agent-Friendly

LLMs understand Markdown natively. No parsing libraries. No schema validation. Agent reads Markdown → understands intent → acts.

Example: Agent reads this checkbox:

Agent understands:

• Unchecked = pending

• Task = “Fix auth bug”

• Owner = auth_agent (that’s me!)

• Priority = high (do this first)

No JSON schema. No API docs. Just English.

5. Human-Readable

Developers, PMs, marketers, executives—everyone can read Markdown. No specialized tools. Open it in:

• VSCode

• Obsidian

• Notion (import)

• GitHub web UI

• Terminal (cat, less)

• Any text editor

Transparent by default. No black boxes.

6. Portable

Markdown files work everywhere:

• macOS, Linux, Windows

• GitHub, GitLab, Bitbucket

• Slack, Discord (inline preview)

• Email (copy-paste works)

• Obsidian, Notion, Roam Research

No vendor lock-in. No proprietary formats. Plain text forever.

7. Composable

Link files wiki-style:

Obsidian, Foam, Dendron render these as clickable links. Agents can follow them to gather context.

8. Self-Modifying

Agent can edit its own instructions mid-execution:

1. Agent reads specs/AGENT.md

2. Discovers new best practice during execution

3. Edits specs/AGENT.md to add the practice

4. Commits change: “Add: Prefer async/await over .then() chains”

5. Future executions follow updated instructions

The system learns by editing its own Markdown.

Try that with a compiled binary.

Comparison: Traditional OS vs Markdown OS

Traditional OSMarkdown OSBinary executablesMarkdown prompts (plain English)Compiled/interpreted codeNo code—just instructionsOpaque configuration (Registry, plist)Human-readable config (AGENT.md)State in databases/memoryState in markdown files (state.md)Binary logs (need tools to read)Markdown + NDJSON (grep/diff friendly)APIs for inter-process communicationMarkdown files (agents read/write)Rigid (recompile to change)Dynamic (edit Markdown mid-run)Developer-only (CLI/code)Everyone (plain English)Version control as afterthoughtGit-native by designProprietary tools to inspectAny text editor

The 2025 Industry Validation

GitHub Spec Kit (September 2025):

• Open-source toolkit for spec-driven development

• Works with GitHub Copilot, Claude Code, Gemini CLI

• Core idea: specification as source of truth

• Agents generate/test/validate code from Markdown specs

Reference: https://github.blog/ai-and-ml/generative-ai/spec-driven-development-with-ai-get-started-with-a-new-open-source-toolkit/

AGENT.md standard (2025):

• Universal agent configuration file format

• Native support: Amp (May 2025+), Claude Code, Cursor, Firebase Studio, Gemini CLI, OpenAI Codex

• Standard sections: overview, build, test, style, security

• Placed at repo root or subpackages (monorepos)

Reference: https://github.com/agentmd/agent.md

agentic.md project:

• Define, visualize, execute AI agents using Markdown + Mermaid diagrams

• Slash command system: agents report progress by writing to markdown files

• Shared rules for consistency across agents

Reference: https://github.com/drivly/agentic.md

LLMunix:

• “Pure Markdown Operating System”

• Agents and tools defined entirely in Markdown

• No code compilation, no complex APIs

• Any LLM can interpret and execute

Reference: https://github.com/EvolvingAgentsLabs/llmunix

Medium articles:

• “The Markdown Revolution: Why Specifications Are King” (2025)

• “AGENTS.md: The README Your AI Coding Agents Actually Read” (August 2025)

• “AGENTS.md: A New Standard for Unified Coding Agent Instructions” (September 2025)

Consensus: 2025 is the “Year of Spec-Driven Development.” Markdown is the universal interface between humans and agents.

Implementation: Building Your First Markdown OS

Step 1: Set up directory structure

Step 2: Write AGENT.md

Step 3: Write your first spec

specs/feature.md:

Step 4: Build a simple agent

agent.py (minimal example):

Run it:

Result:

• plans/feature-plan.md created

• runs/journal.jsonl logged events

• runs/2025-09-30.md human-readable log

• reports/summary.md summary generated

Step 5: Add version control

Now every agent action is versioned. Full audit trail.

Step 6: Iterate

Add:

• Task queue (state/queue.md with checkboxes)

• LLM integration (Claude, GPT-4, etc.)

• MCP tools (shell, HTTP, git, Playwright)

• Replayable tests (runs/test.md)

• Multi-agent orchestration (router/worker pattern)

Common Patterns

1. Task Queue with Checkboxes

state/queue.md:

Agent script:

2. State Snapshots

state/deployment-state.md:

Agent updates this file after every deployment. Git history = full deployment history.

3. Replayable Test Scripts

runs/test.md:

Agent (or human) can copy-paste these commands to verify feature works.

4. Wiki-Style Links

In plans/feature-plan.md:

Obsidian/Foam render these as clickable links. Agent can follow them to gather context.

When NOT to Use Markdown OS

Markdown OS is powerful, but not universal. Don’t use it for:

• Performance-critical code: If you need microsecond latency, compile to binary

• Binary data processing: Images, video, audio—use appropriate formats

• Large-scale data pipelines: Use databases, not markdown files

• Real-time systems: Markdown editing has latency, not suitable for real-time control

Use Markdown OS for:

• Agent orchestration: Task planning, execution logging, state management

• Development workflows: Specs, plans, deployment scripts

• Knowledge management: Documentation, runbooks, playbooks

• Human-agent collaboration: Transparent, auditable, editable by both

The Future: Markdown-Native Tooling

Emerging tools optimized for Markdown OS:

• Obsidian: Graph view, backlinks, plugin ecosystem (Dataview, Templater)

• Foam: VSCode extension for wiki-style linking

• Dendron: Hierarchical note-taking, schema validation

• Logseq: Outliner-based, bidirectional links

• Notion: Collaborative, database views (imports Markdown)

Future possibilities:

• Real-time collaborative editing: Multiple agents + humans editing same file (CRDTs)

• Markdown query language: SQL-like queries over markdown files (Dataview already does this in Obsidian)

• Markdown databases: Treat markdown files as tables (front matter = schema)

• Markdown CI/CD: GitHub Actions triggered by markdown file changes

Why This Matters in 2025

AI coding agents are everywhere. GitHub Copilot. Claude Code. Cursor. Gemini CLI. OpenAI Codex. They all need instructions.

Traditional approach: Write code comments, hope the agent understands.

2025 approach: Write AGENT.md. Specs in Markdown. Plans in Markdown. State in Markdown. Reports in Markdown.

The agent reads it. Understands it. Executes it. Edits it. Commits it.

No binaries. No compilation. No interpretation. Just Markdown. In English. Dynamic. Transparent. Auditable.

Your operating system runs on binaries. Your AI agents should run on Markdown.

—

Mini Repo Example

Full working example: https://github.com/markdown-os/starter-kit (fictional, but you get the idea—build this!)

References:

• GitHub Spec Kit: https://github.blog/ai-and-ml/generative-ai/spec-driven-development-with-ai-get-started-with-a-new-open-source-toolkit/

• AGENT.md Standard: https://github.com/agentmd/agent.md

• agentic.md: https://github.com/drivly/agentic.md

• LLMunix: https://github.com/EvolvingAgentsLabs/llmunix

• Spec-Driven Development (The New Stack): https://thenewstack.io/spec-driven-development-the-key-to-scalable-ai-agents/

• AGENTS.md (Medium, Aug 2025): https://gyliu513.medium.com/agents-md-the-readme-your-ai-coding-agents-actually-read-b37a32876900

• AGENTS.md Best Practices: https://www.builder.io/blog/agents-md

• Claude Code Subagents (July 2025): https://www.cursor-ide.com/blog/claude-code-subagents

Want the starter kit? DM “MARKDOWN OS” for the full repo template (AGENT.md + queue system + agent.py + example specs) to build your first Markdown-driven agent system.