The Birth of MarkVibe Coding
From Vibe Coding to MarkVibe Coding
In 2025, Vibe Coding — a term coined by Andrej Karpathy — swept the developer community. The idea was radical: instead of writing code directly, describe what you want to an AI agent and verify that the output's "vibe" feels right. Let the AI handle the implementation details.
But Vibe Coding had an inherent limitation. Developers still had to open an IDE, type commands in the terminal, and switch between multiple tools to communicate with the agent. With a fragmented interface, context-switching costs pile up and the consistency of intent degrades.
MarkVibe Coding starts from this insight. It unifies every medium of design, instruction, verification, and logging into Markdown (.md), and prohibits the developer from directly accessing a terminal or IDE. The only thing passed to the agent is a Markdown file path.
Core Concepts and Definitions
Defining MarkVibe Coding
"MarkVibe Coding is a unified working space methodology where software development, writing, research, and all work is performed through Markdown as the sole interface. The practitioner checks only Input and Output in Markdown, with MARKVIBE.md defining their paths, scope, relationships, and permissions."
— MarkVibe Coding Manifesto, 2026The Eight Pillars
Markdown-Centric
All design, implementation instructions, and test reports live in Markdown files. The developer never edits source code directly.
Zero-Terminal
Never open a terminal. The Markdown editor connects directly to the agent — saving the file completes everything End-to-End.
Single Document
Complete everything in one document. Don't navigate between files. Requests, results, and follow-ups accumulate in a single file.
Seed TODO
The human writes only the initial Seed TODO. The agent reports results, and new requirements are appended to the same document.
Structural Diff
Leverages Markdown's structure (headings, lists, indentation) to extract only changed instructions and forward them to the agent. Sends diffs, not the entire document — saving tokens and enabling efficient input even in long documents.
Accumulated Changelog
Results accumulate in one file like a CHANGELOG. The editor renders agent output via real-time streaming, so the user watches results appear in the document live.
Markdown State Management
All document states are displayed as a dashboard. Items requiring human approval (deploy, merge, delete, etc.) are also surfaced on the dashboard with approval/rejection recorded. Evaluated documents move to archive; only active documents remain.
Agent-Harness Synergy
The agent builds its own harness, auto-verifies code, and records results back into the document.
Core Components
The Lineage of Agent Instruction Files
MarkVibe Coding did not appear in isolation. It builds on the instruction file paradigm that emerged across the AI agent ecosystem in 2024-2025.
| File | Platform | Role |
|---|---|---|
AGENTS.md |
OpenAI Codex | Project build rules, test commands, structural guidance |
CLAUDE.md |
Claude Code | Project instructions, coding standards, architecture decisions |
DESIGN.md |
Google Stitch | Visual design — colors, typography, components, layout styles |
MARKVIBE.md |
MarkVibe | Unified specification integrating all of the above |
The Zero-Terminal Principle
Why Prohibit Terminal Input?
In traditional development, the terminal is the universal tool. But MarkVibe Coding prohibits terminal access by principle. This is not a random constraint — it is a deliberate design decision to maintain a consistent abstraction level throughout the development process.
claude ".markvibe/active/login.md — proceed with this task."Beyond this single line, no terminal command is permitted.
Maintaining the Abstraction Level
In software engineering, mixing abstraction levels creates exponential complexity. In MarkVibe Coding, the human's abstraction level is strictly "Intent" — nothing more.
| Layer | Traditional Dev | Vibe Coding | MarkVibe Coding |
|---|---|---|---|
| Intent | Verbal, issues, docs | Prompt (chat) | TODO.md |
| Design | IDE, Figma, wiki | Prompt + IDE | DESIGN.md |
| Implementation | Hand-written code | AI-generated + manual edits | Agent autonomous |
| Build / Run | Terminal commands | Terminal commands | Agent autonomous |
| Verification | Manual testing | Manual + AI-assisted | Harness auto-verified |
| # of Interfaces | 5+ | 3–4 | 1 (Markdown) |
The Single Exception: Starting the Agent
The Zero-Terminal Principle has exactly one exception: passing a Markdown file path when first launching the agent. After that, every interaction — new requests, change orders, bug reports — happens by editing Markdown files. The agent watches for changes and responds autonomously.
# Start the agent (this is the ONLY terminal input) $ claude ".markvibe/active/login.md — proceed with this task." # Need to make a new request? # → Do NOT type in the terminal # → Edit TODO.md and save # → The agent detects the file change and responds
Workflow: The Power of a Single Document
Core: Everything Happens in One File
The MarkVibe workflow is remarkably simple. The human opens a single Markdown file — requests, results, follow-up requirements, and results again all live in that one file. No switching between documents. No terminal. Saving the file completes everything End-to-End.
Seed TODO — Start with a Single Seed
The human writes a Seed TODO — the minimal intent that seeds the entire project. This is both the starting point of the document and the origin of the project. The agent executes the work and reports results back into the same document.
# User Login Page ## Seed TODO - Feature: OAuth 2.0 login (Google, GitHub) - Stack: React + Express.js + Passport.js - Design: See DESIGN.md - Tests: Include Jest unit tests
Results — Accumulated in the Same File
When the agent completes work, it appends results to the same file. No separate LOG.md. The single document works like a CHANGELOG.
# User Login Page ## Seed TODO - Feature: OAuth 2.0 login (Google, GitHub) - ... ## Result — 2026-04-05 14:30 - Created: src/pages/Login.tsx, src/api/auth.ts, src/middleware/passport.ts - Tests: 12/12 passing - Log: → .markvibe/archive/2026-04-05-login.md (path only) - Status: Complete
Follow-up — Append to the Same Document
When new requirements emerge, append them below in the same document. The previous state (Seed TODO + Result) is already recorded, so the agent has full context for the follow-up work.
# User Login Page ## Seed TODO - Feature: OAuth 2.0 login (Google, GitHub) - ... ## Result — 2026-04-05 14:30 - Status: Complete (Google, GitHub login) ─────────────────────────────── ## Follow-up — 2026-04-05 15:00 - Change: Add Apple login too - Constraint: Same pattern as existing Google/GitHub logic
Structural Diff — Token-Efficient Change Detection
This is the core mechanism of MarkVibe Coding.
Markdown is inherently structured — headings (##), lists (-),
and indentation carry hierarchical information.
The agent (or Markdown editor) reads this structure to automatically determine:
- Context — which
##section the new request falls under - Type — new
##heading = new request; modified-item = change - Relationship — the Result section directly above provides prior context
The key is token efficiency.
Even as the document grows to hundreds of lines, the editor does not send the entire document to the agent.
It parses the Markdown structure and extracts only the changed instructions.
For example, if two new - items appear under a ## Follow-up heading,
only those 2 lines are transmitted.
Previous Seed TODOs and Results have already been processed — no need to resend.
This enables accurate input with minimal tokens even in long accumulated documents.
## Seed TODO with - items = original request.
## Result with - items = agent's report.
A new ## Follow-up heading = new request.
The editor extracts only the structural diff and forwards it to the agent — the full document is never resent.
End-to-End Flow — All in One File
This cycle repeats infinitely within one file. The file naturally becomes a CHANGELOG.
The Document Becomes a Living Changelog
Over time, a single document accumulates Seed TODO, first Result, follow-up, second Result... The document itself becomes the project's complete history and CHANGELOG. No separate log files needed.
Throughout this process, the Markdown editor performs real-time streaming rendering. The moment the agent generates a Result, it renders live in the editor. The user doesn't wait for terminal logs — they watch the document fill up in real time. This is the MarkVibe Coding user experience.
# User Login Page ## Seed TODO - Feature: OAuth 2.0 login - ... ## Result — 2026-04-05 14:30 - Status: Complete (Google, GitHub) ## Follow-up — 2026-04-05 15:00 - Add Apple login ## Result — 2026-04-05 15:45 - Status: Complete (Apple login added) ## Follow-up — 2026-04-06 09:00 - Improve login error messages - Add password recovery flow ## Result — 2026-04-06 10:20 - Status: Complete (Error UX + password recovery) - Tests: 28/28 passing
• Don't open a terminal to talk to the agent — save the document
• Don't split results into separate log files — accumulate in one document, and for artifacts that need referencing, record only the path
Markdown State Management — The Core Mechanism
The most important concept in MarkVibe Coding is managing the state of Markdown documents.
Every document has only two states: active or archive.
Record Only Statistical Results
The agent doesn't dump every detail into the document. Only statistical results — test pass rates, file counts, change summaries — are recorded for the user. The minimum information needed for human judgment.
Dashboard — Everything at a Glance
The ultimate form of Markdown State Management is the dashboard.
The editor (or workspace view) displays all documents in active/ as a dashboard,
showing each document's progress, latest Result, and next TODO at a glance.
Crucially, items requiring human approval — production deploys, branch merges, file deletions, external API calls — are explicitly surfaced on the dashboard. The human decides approve/reject from the dashboard, and that decision is recorded in the document. Even approval workflows for actions the agent cannot autonomously perform are completed within Markdown.
## Result — 2026-04-05 16:00 - Created: src/deploy/production.ts - Tests: 28/28 passing ## Approval Required - Action: Production deploy (main → production) - Risk: HIGH - Target: v1.2.0 release - Decision: [ ] Approve / [ ] Reject ─────────────────────────────── ## Approval — 2026-04-05 16:15 - Decision: Approved - Reason: All tests passing, staging verified
Evaluate Usefulness → Archive
When all TODOs in a document are complete and results are verified,
the document undergoes a usefulness evaluation.
"Is this document worth referencing in the future?"
Once evaluated, it moves to archive/.
Only active documents remain in the workspace.
.markvibe/ ├── active/ # Only in-progress documents live here │ ├── login.md # In progress — Seed + Results accumulating │ └── dashboard.md # In progress │ └── archive/ # Evaluated, completed documents ├── onboarding.md # Done — statistical results only └── auth-refactor.md # Done — reference archive
• The agent reports only statistical summaries (file counts, test results, change summaries)
• When all TODOs are done, evaluate usefulness and move to archive/
• Archived documents are read-only — to modify, move back to active
• Keeping the workspace clean is the essence of MarkVibe
Harness Engineering
What Is a Harness?
In February 2026, OpenAI's Ryan Lopopolo detailed the concept of Harness Engineering on the OpenAI blog. The core thesis can be summarized as:
Agent = Model + Harness
— Summary of Lopopolo's thesis. Source: "Harness Engineering: Leveraging Codex in an Agent-First World" (Feb 2026, OpenAI Blog)The harness is everything in an AI agent except the model itself — orchestration logic, context management, architectural constraints, test pipelines, and review systems. Birgitta Boeckeler (Thoughtworks) categorized harness controls into Guides (feedforward) that steer the agent before it acts, and Sensors (feedback) that observe after the agent acts and help it self-correct (published on martinfowler.com).
OpenAI's Experiment Results
| Metric | Value |
|---|---|
| Codebase | ~1 million lines of production code |
| Team size | Started with 3 engineers, scaled to 7 |
| Pull Requests | 1,500 opened and merged |
| Velocity | 3.5 PRs per engineer per day |
| Efficiency | ~1/10th the time vs. manual |
| Human-written code | 0 lines — all code generated by Codex agents |
Three-Layer Harness Architecture
Per Birgitta Boeckeler's classification (Thoughtworks, on martinfowler.com), harnesses fall into three regulation categories:
Maintainability Harness
Linters, formatters, type checkers — deterministic (computational) tools ensuring code quality and internal structure. The most mature category.
Architecture Fitness Harness
Structural tests enforcing dependency layering (Types → Config → Repo → Service → Runtime → UI). Auto-detects module boundary violations.
Behaviour Harness
Functional correctness verification. Relies on AI-generated tests + manual testing. The least mature category, requiring the most future development.
OpenAI's Key Harness Techniques
Harness in MarkVibe Coding
MarkVibe Coding embraces harness engineering with key differences.
Harness Lifecycle — Build, Manage, Stabilize
In MarkVibe Coding, the harness has a three-phase lifecycle:
Build — The agent creates it
The human does not write the harness. Write "include tests" in the Seed TODO, and the agent analyzes the project's stack and structure to build linter configs, test frameworks, and architecture validation rules on its own. The initial shape of the harness is determined by the agent's judgment.
Manage — Controlled through Markdown
Harness results are reported in the Markdown document. The human reviews the harness state through the document, and writes follow-up requests in the same file if gaps are found. Instructions like "Layer 3 coverage is too low, add edge case tests" progressively strengthen the harness. Since the harness configuration itself is managed in Markdown, the human can control the harness without reading code.
Stabilize — Improved through iteration
The harness is not built once and forgotten. As the project evolves, the harness evolves with it. New features expand the tests, architecture changes update fitness rules, discovered bugs add regression tests. All of this happens within the request-result cycle of the Markdown document. The harness is a cumulative asset that grows stronger with use.
## Seed TODO - Feature: OAuth 2.0 login - Tests: include ## Result — 2026-04-05 14:30 - Harness L1: ESLint 0 errors, Prettier applied - Harness L2: Dependency layer violations: 0 - Harness L3: 12/12 tests passing - Status: Complete ## Follow-up — 2026-04-06 09:00 # Human controls the harness - Harness improvement: add token expiration scenario tests - Harness improvement: add concurrent login limit verification ## Result — 2026-04-06 10:20 - Harness L3: 18/18 tests passing (+6 new) - Added tests: token expiry, refresh, concurrent sessions, invalid token, CSRF, rate limit - Status: Complete — harness strengthened
Practical Implementation Guide
Authority Hierarchy — MARKVIBE.md is the Top-Level Directive
MARKVIBE.md is the Human Top-Level Directive, not tied to any specific agent. CLAUDE.md is for Claude; AGENTS.md is for Codex. MARKVIBE.md is for the human.
MARKVIBE.md manages exactly two kinds of meta-information:
- Harness top-level location — where and how the project's test/build/verification pipeline is configured
- Agent instruction file references — where each agent's config lives (CLAUDE.md, AGENTS.md, .cursorrules, etc.)
MARKVIBE.md does not contain detailed coding rules or style guides — that belongs in each agent's native file. MARKVIBE.md only defines the location and priority of those files as a meta layer. On conflict, it always takes precedence.
MarkVibe Editor — Design Philosophy
Markdown is simple. Anyone can read it, anywhere. The MarkVibe editor follows this same principle. At its core, the editor provides a human-friendly interface where Markdown becomes the medium for organizing knowledge, and the act of writing it completes the work itself.
Just as Markdown embodies a philosophy of simplicity, the MarkVibe editor is built in a simple, minimal form — yet designed to work alongside agents.
Loose Coupling — Agents Are Not Caged
The core design principle of the MarkVibe editor is loose coupling. It connects loosely to agent CLI interfaces like Claude Code or Codex CLI — it does not trap agents inside the editor. Agents run as independent external processes; the editor communicates with them through the Markdown file as a medium. Swap the agent, the editor stays the same. Swap the editor, the agent stays the same.
Two Modes
The editor operates in two modes based on purpose:
General Mode — Knowledge Management
A mode for notes, research, reports, and project management — all through Markdown. Focuses on document-based work without coding. Supports MarkVibe's basic workflow: Seed TODO, Result accumulation, active/archive state management. Accessible to users with no programming background — just Markdown.
Expert Mode — Coding & Advanced Work
A mode for software development, harness engineering, multi-agent routing, and other professional development workflows. Supports the full MarkVibe spec: Structural Diff detection, real-time agent streaming, approval workflows, and dashboards.
Compatible Editors — Not Just Leaf
MarkVibe Coding is not locked to any specific editor. Since Markdown is the standard, any editor that supports the MarkVibe workflow can be used. Editors like Obsidian can extend MarkVibe compatibility through plugins and community extensions.
- Obsidian — inter-file links, graph view for document relationships. Its plugin ecosystem enables active/archive state management and agent integration for MarkVibe workflows. Strong for General Mode knowledge management
- Typora — live rendering, WYSIWYG editing. Well suited for General Mode knowledge management
- Mark Text — open source, clean interface (development inactive, but existing version usable)
Leaf Editor — Native MarkVibe Editor
A dedicated editor with native MarkVibe Coding workflow support. Ships with both General Mode and Expert Mode built in, freely switchable based on purpose. Agents are not caged inside the editor — it connects loosely to external CLIs like Claude Code, letting agents run independently while Markdown bridges the two. The editor is simple, the agents are independent, and Markdown connects them. The initial release focuses on General Mode (knowledge management) and core specs (Seed TODO, Result accumulation, Structural Diff detection). Expert Mode Full Spec (dashboard, approval flows, multi-agent routing) will be added in later phases.
@leafeditor
Related Methodologies & How MarkVibe Differs
MarkVibe Coding did not appear from nowhere. The history of software engineering is filled with answers to one recurring question: "What do you write before you write the code?" This chapter traces the lineage of methodologies that inform MarkVibe Coding and clarifies how each differs from it.
1. Literate Programming (1984)
Proposed by Donald Knuth, this paradigm embeds code within a natural-language narrative so programs can be "read like literature." Implemented via the WEB system; Jupyter Notebooks are a modern descendant.
2. Behavior-Driven Development / BDD (2006)
Introduced by Dan North, BDD uses structured Given-When-Then (Gherkin) syntax
to write behavior specs that tools like Cucumber convert into executable tests.
Designed as a communication bridge between business stakeholders and developers.
3. README-Driven Development / RDD (2010)
Proposed by GitHub co-founder Tom Preston-Werner: write the README before writing any code. "If you can't explain it simply in a README, the design is too complex."
4. Spec-Driven Development / SDD (2011~)
Write the OpenAPI (Swagger) specification first, then auto-generate server stubs, client SDKs, documentation, and tests from that spec. The API contract becomes the single source of truth.
5. Design Doc Driven Development / Google (2000s~)
Practiced at Google, Uber, and other large tech companies: write a design document covering context, goals, non-goals, proposed solution, alternatives, and trade-offs. Peer-reviewed before implementation begins. Typically 2–20 pages.
6. Harness-Driven Development (2021~2023)
Central to AI coding benchmarks like HumanEval, MBPP (2021), and SWE-bench (2023). A test harness (failing test suite) defines the problem; the AI agent must produce code that passes it. Success is binary and automated.
7. Vibe Coding (2025)
In February 2025, Andrej Karpathy (former Tesla Senior Director of AI, early OpenAI researcher) coined the term on X (Twitter):
"fully give in to the vibes, embrace exponentials, and forget that the code even exists."
— Andrej Karpathy, February 2025Describe what you want conversationally, accept generated code without detailed review, and paste error messages back to fix bugs. Tools: Cursor, Replit Agent, Claude Code, etc.
Adoption exploded. 25% of Y Combinator's Winter 2025 batch reported codebases 95% AI-generated. Collins English Dictionary named it Word of the Year 2025. Merriam-Webster listed it as "slang & trending" in March 2025.
But serious problems emerged. On the Lovable platform, 170 of 1,645 apps had security vulnerabilities (May 2025). Replit deleted a production database despite explicit instructions otherwise (July 2025). A December 2025 CodeRabbit study found AI co-authored code contained ~1.7x more issues overall, with security issues up to 2.74x higher. These limitations catalyzed complementary methodologies like SDD and Harness Engineering.
8. Agent Instruction Files (2024~)
CLAUDE.md (Anthropic), AGENTS.md (OpenAI), DESIGN.md (Google Stitch), .cursorrules (Cursor) — Markdown files committed to repos that provide persistent context and behavioral rules for AI coding agents. Dual-purpose documents for both humans and AI.
Comparison Table
| Methodology | Year | Spec Format | Consumer | Executable |
|---|---|---|---|---|
| Literate Programming | 1984 | WEB/noweb | Humans | Yes |
| BDD / Gherkin | 2006 | Given-When-Then | Humans + test runner | Yes |
| README-Driven (RDD) | 2010 | Markdown | Humans | No |
| Spec-Driven (SDD) | 2011 | YAML/JSON | Codegen tools | Yes |
| Design Doc Driven | 2000s | Prose (Docs/MD) | Human reviewers | No |
| Harness-Driven | 2021~2023 | Test suites | AI agents + CI | Yes |
| Vibe Coding | 2025 | Conversational | LLMs | Via LLM |
| Agent Instruction Files | 2024 | Markdown | AI agents + humans | Via AI |
| MarkVibe Coding | 2026 | Markdown (top-level) | All AI agents | Via AI |
The Future of Codeless Coding
MarkVibe Coding is not just a methodology. It is a redefinition of what it means to be a developer.
In traditional development, a developer's identity was "someone who writes code." Vibe Coding expanded this to "someone who instructs AI." MarkVibe Coding takes one more step, redefining the developer as "someone who structures intent."
"The best code is the code you never have to write. MarkVibe Coding makes this age-old adage literally true."
What MarkVibe Coding Changes
- Barrier to entry disappears — You don't need to know a programming language. You just need to know Markdown.
- Zero context-switching — No more bouncing between IDE, terminal, browser, and docs.
- Full auditability — Every decision and action is recorded in Markdown logs.
- Agent independence — You're not locked into a specific agent. Markdown is universal.
Next Step: MarkVibe Working
MarkVibe Coding is not the final destination. It is the stepping stone to MarkVibe Working.
If MarkVibe Coding is "building software with Markdown," then MarkVibe Working is "doing all work with Markdown" — planning, design, marketing, research, reporting, project management — all knowledge work converging into a single Markdown document powered by AI agents.
MarkVibe Coding must be established first. Once the "single document + AI agent" pattern is proven in software development — the most complex domain — it will naturally expand to every other domain of work. Coding is the proving ground. Working is the ultimate vision.
2. Write a Seed TODO in a single .md file.
3. Save from your Markdown editor.
4. Check results in the same document.
That's it.
Write Markdown. Build Software.
— MarkVibe Coding, 2026