Agentic Markdown Programming
Markdown as an instruction layer
Markdown started as a lightweight formatting syntax for human readers. It has since taken on a second job: a structured instruction layer for constraining and orchestrating AI agents. The shift is practical, not cosmetic. Almost everything an engineer writes by hand — Dockerfiles, JSON, YAML, config — is ultimately plain text. Agentic Markdown uses that same medium not to describe an application but to direct the model that writes it.
Where a compiler turns C++ or Rust into a running program, an agent turns structured Markdown into one. The person writing the Markdown moves from syntax author to systems orchestrator — setting intent and constraints, and letting the agent handle the tactical code.
The gstack framework
The approach was brought into focus by Garry Tan, President and CEO of Y Combinator, through the gstack framework — a collection of Markdown files that act as defined skills and operational boundaries for a coding agent.
The problem gstack targets is what Tan calls “mushy mode”: left unconstrained, a model executes literal, isolated instructions but loses the broader architecture and product vision, producing fragmented or self-contradicting code. gstack counters this by feeding the agent highly structured Markdown that pins it to a specific, rigidly defined persona. Held inside one role’s parameters, the agent keeps multi-step work coherent and aligned with the project’s goals.
Role-based focus
Managing an agent well means splitting the development lifecycle into discrete, bounded contexts. Agentic Markdown does this by defining explicit roles the agent adopts phase by phase. gstack uses roles like these:
| Role | What the Markdown defines | Expected output |
|---|---|---|
| Product Manager | Scope, user stories, acceptance criteria | Feature specs and architectural blueprints |
| Engineering | How to translate specs into code | Application logic, schemas, API routes |
| Quality Assurance | Testing protocols and edge cases | Unit tests, integration tests, bug reports |
| DevOps | Deployment pipelines and infrastructure | Dockerfiles, CI/CD workflows, environment config |
Heuristic: treat these Markdown files with the same rigor as source code. A poorly structured prompt produces a poorly structured application.
The abstraction ladder
Computing history is a steady climb up abstraction layers, each one moving the operator further from the hardware and closer to pure intent:
- Mechanical — flipping physical switches by hand.
- Electrical — automating those switches with current.
- Low-level — binary and assembler, addressing the CPU directly.
- High-level — languages like C++, Python, and TypeScript that abstract away memory and hardware.
- Agentic — Markdown directives that instruct an AI model, which then writes the high-level code.
Agentic Markdown sits at the top of that ladder today: the human writes strategic intent in Markdown; the agent handles tactical implementation in Python or TypeScript.
What this means for your documentation
Because agents read Markdown natively, the way you structure documentation directly shapes how well an agent executes against it. If you plan to drive agents with frameworks like gstack, the formatting standards on your internal docs stop being a style preference and become an execution dependency.
Three habits make Markdown a reliable instruction set:
- Clear hierarchical headers so the agent can locate scope and context.
- Isolated semantic blocks — one idea per block — so instructions don’t blur together.
- Explicit epistemic markers (what is a rule, what is an example, what is optional) so the agent doesn’t guess.
Well-structured documentation is no longer just good hygiene; for agent-driven work it is the difference between coherent output and mush. See LLM Knowledge Base Architecture for how these same structuring principles extend to an LLM-maintained knowledge store.
