The AI Workflow Engine

What's new in v2

node ~/projects/markdownai/packages/parser/scripts/migrate-v1-to-v2.mjs <file> --in-place

Unified directive grammar

Every directive uses the same three forms - self-closing, block with attributes, or block with attributes and body. The v1 split between "block" directives (closed with bare @end) and "inline" directives (single-line only, silently dropped continuations) is gone.

# 1. Self-closing (atomic, no body, no continuation)
@import ~/path/to/macros.md /
@touch path="src/foo.ts" /
@on-complete next-phase /

# 2. Block with attributes (no body)
@db
  using="mdd"
  find="features"
  where='id == "X"'
  label=feature
@db-end

# 3. Block with attributes + body
@phase 0_branch_check
  required=true
>
  @call branch-guard /
  @on-complete 0_5_repo_version_check /
@phase-end

@<name>-end close tags everywhere

The close tag carries the directive name, so nested blocks read clearly. No more guessing which block a bare @end closes.

@phase X
  @if {{ ready }}
    @foreach f in {{ files }}
      - {{ f }}
    @foreach-end
  @if-end
@phase-end

@on-complete X / replaces arrow transitions

The v1 arrow syntax (@on complete -> target) is now @on-complete target /. Same engine behavior, JSX-style self-close. Future extensions like @on-error and @on-timeout slot in naturally.

Synchronous MongoDB worker

@db using="..." actually hits Atlas or self-hosted Mongo now. In v1 the directive was stubbed and emitted an "async execution required" warning. v2 runs read-only queries through a sync worker so the result is available in the same render pass.

Struct labels for dot-access

@db ... as=row label=feature captures the row into ctx.data[label], so {{ feature.source_files }} dot-access works on real arrays and nested objects. Same shape works for @read and any directive that materializes data.

New sandbox builtins

The expression sandbox grew a set of helpers usable inside @if conditions and {{ }} interpolations: parse_brief, read_section, extract_paths, read_markdown_section, now_iso, now_ms, parse_iso_ms, uuid_v4, truncate, to_json, and allowed.

Cross-call session state for skill flows

A skill_session_id keys per-(session x document) state inside the MCP server. @set values persist across resolve_phase calls in multi-phase flows, so a skill can collect values in phase 1 and read them back in phase 5 without round-tripping through the host.

Plugin loader and @markdownai-detect

Framework descriptors (mdd.plugin.md, others) declare project layout at render time. Documents pull layout facts from the descriptor instead of guessing - no more layout-inference hallucinations when the AI hasn't seen the project before.

@touch directive

Idempotent empty-file creation for scaffolding. Safe to re-run.

@touch path="src/rules/parser.ts" /

Migration tool

A one-shot script rewrites v1 files to v2 syntax mechanically. Idempotent - re-running on a v2 file is a no-op.

node ~/projects/markdownai/packages/parser/scripts/migrate-v1-to-v2.mjs <file> --in-place

Why Developers Switch to MarkdownAI

Context rot is killing your Claude Code sessions

Every serious Claude Code session eventually degrades. Not because the model fails -- because the context window fills. Past tool results, failed attempts, and full-file reads accumulate until the AI loses the thread. The community calls this context rot. The structural fix is not better prompting. It is scoping.

MarkdownAI's @phase directive implements scoping at the file level. A 20-phase deployment runbook only ever loads one phase at a time. Claude executes phase 3, calls next_phase, and phase 4 loads. Phases 1, 2, and 5 through 20 have never touched the context window. There is nothing to rot.

The pattern is well-documented: see Context Rot in AI Coding Agents (MindStudio) and the Two Context Bloat Problems (Agenteer) for independent analysis of the same failure mode.

Your CLAUDE.md should not be 600 lines

Anthropic's own best practice: keep CLAUDE.md under 200 lines. Every serious project exceeds that within a week. The result is a bloated file the AI has to read entirely on every session start, burning context before any work begins.

The MarkdownAI architecture replaces the monolithic CLAUDE.md with a thin entry point that calls @read on phase-specific files and injects live state on demand. Claude sees a focused, accurate slice -- not a 600-line document it has to search.

This pattern is also discussed in the official Claude Code Best Practices documentation (Anthropic Engineering).

Runbooks that never go stale

DevOps and engineering teams typically have dozens of runbooks nobody has time to keep current. The port changes, the endpoint moves, the flag flips -- but the runbook does not know. The AI follows the instructions. The wrong thing happens.

MarkdownAI runbooks do not store values. They declare data sources. The @query, @db, @http, and @env directives resolve against live system state at the moment the agent reads the file. A runbook that calls @query docker service ls hands Claude a current container list -- not what you typed last month.

What is MarkdownAI

Most developers who land here expect another template engine or a documentation generator. MarkdownAI is neither. It is a workflow execution engine -- the difference is not cosmetic.

A template engine (Jinja, Handlebars, EEx) renders a file once at build time and hands the output to a browser. The template is consumed, gone. MarkdownAI renders at read time, for an AI agent, and the output is scoped to exactly the phase that agent is currently executing. A browser has no context window. Claude does.

One Reddit commenter called it "basically jinja with a lil flava." Here is the precise reason that is wrong:

Jinja, Handlebars, and EEx are template engines. You write a template with {{ user.name }}, run a build step, and get an HTML file. The template is gone. The output goes to a browser. That's the whole job.

MarkdownAI is different in every dimension that matters.

The consumer is an AI, not a browser

Jinja renders for browsers that display HTML. MarkdownAI renders for Claude, which reads Markdown. A browser needs bytes fast. Claude needs accurate facts and focused context - it doesn't benefit from stale data delivered quickly.

Read time, not build time

Template engines run when you deploy. MarkdownAI runs when Claude opens the file. That means every @query, @env, @http, and @db directive resolves against the real current state of your system - not the state from your last build. The document doesn't store values. It fetches them.

The MCP server does the computation so Claude doesn't have to

This is the part that actually matters. When Claude reads a MarkdownAI document through the MCP integration, every directive resolves in the server layer before Claude sees any content. The @if conditions have already been evaluated. The database queries have already run. The environment variables have already been substituted. Claude receives resolved facts - not a list of conditions it needs to think through.

Without MarkdownAI, Claude hits a doc and has to figure out what's true. It stops to run a shell command. It stops again to check an env var. It stops again to verify a condition. Each stop costs context and interrupts the actual work. With MarkdownAI, those interruptions don't happen. The document arrives pre-resolved.

Something nobody talks about: every time Claude stops to check an environment variable, verify a file exists, confirm a port is open -- that's roughly 2 seconds gone. Tool call out, wait, result back, Claude re-orients, continues.

In a real workflow that's not 1 check. It's 15. That's 30 seconds of dead time and 15 context interruptions where Claude has to re-establish where it was.

MarkdownAI's MCP layer does all of that before Claude touches the session. Environment is pre-validated, state is pre-loaded, constraints are already in context. Claude reads phase 1 and immediately works.

No stops. No re-orientation. No context bloat from housekeeping that a script could handle in milliseconds.

Phases are not template partials

The @phase directive is where the comparison to template engines fully breaks down. A MarkdownAI phase is a named, lazy-loaded chunk of a workflow document. A 20-phase runbook doesn't load all 20 phases into Claude's context at once - the MCP server serves one phase at a time. Claude reads phase 1, works through it, then calls next_phase to advance. The server returns phase 2. Claude never holds the full workflow in context. The document manages state. Claude follows steps.

This means a complex deployment runbook, a multi-step debugging workflow, or a long onboarding sequence can be arbitrarily large without ever flooding the AI's context window. Each phase is self-contained, each transition is explicit, and Claude never has to juggle what's relevant now versus what comes later.

Template engines have no concept of this because browsers don't have context windows.

The Three Reasons AI Workflows Break

Every developer who builds seriously with Claude Code or AI agents hits the same wall. It is not the model. It is the architecture.

Context rot. Your AI's output quality degrades as the context window fills with history, tool results, and noise from earlier in the session. By step 12, it is hallucinating variable names that do not exist.

Stale data. Your runbook tells the AI your API is at localhost:3000. It moved to 8080 last Tuesday. The AI does not know. It acts on what the doc says, not what is true right now. Static text cannot track a moving system.

Cold-start amnesia. Every new Claude Code session starts from zero. The AI re-derives the same conclusions from scratch. There is no memory of phase 3 state from the session that ended an hour ago.

MarkdownAI solves all three. The @phase directive exposes only the current workflow step -- the rest of the document does not exist to the AI yet. The @query, @db, @env, and @http directives inject live system state at the moment the AI reads the file. The MCP server preserves session state across next_phase calls so a 20-step runbook survives context resets.

How the AI Workflow Engine Works

One line changes everything. Add @markdownai to the top of any .md file and the mai tool treats it as a live document. Everything after that line is standard Markdown, extended with directives. Directives become their results. Conditions are evaluated. Macros expand. Data sources are queried.

The Six Packages

MarkdownAI is a six-package monorepo. Each layer has a single, well-defined job:

How to Install and Run Your First MarkdownAI Workflow

npm install -g @markdownai/core

@markdownai v2.0

# Project Status

**Branch:** {{ @query git branch --show-current }}
**Tests:** {{ @query pnpm test 2>&1 | tail -1 }}
**Last commit:** {{ @query git log --oneline -1 }}

## Source Files

@list ./src/ match="**/*.ts" | sort | @render type="table" columns="name,size"

## Environment

@if {{ env.NODE_ENV == "production" }}
  Running in **production** mode.
@else
  Running in **{{ env.NODE_ENV }}** mode.
@if-end

mai render status.md

What Directives Does MarkdownAI Support?

MarkdownAI extends standard Markdown with a small set of directives. They compose naturally - you can pipe data through transforms, embed expressions in prose, define reusable blocks, and conditionally show sections based on any runtime value.

What Data Sources Can MarkdownAI Inject at Runtime?

MarkdownAI can pull from the filesystem, structured files, databases, HTTP APIs, and shell commands. Every data source is jailed by default - see the Security section for how the gates work.

@list ./src/ match="**/*.ts"
@list ./config.yaml path=$.services
@list ./data.csv where="status == active"

@read ./package.json path=$.version
@read ./config.yaml path=$.server.port
@read ./data.csv column=email where="active == true"

@query git branch --show-current
@query bash -c "find src -name '*.ts' | wc -l"
@query bash -c "git status --porcelain" label=dirty

@http GET https://api.example.com/status
@http GET {{ env.API_ENDPOINT }}/health expected=200
@http GET https://api.example.com/data @cache persist ttl=3600

@connect primary type="postgres" uri=env.POSTGRES_URI
@db using="primary" find="users" where="active==true"
@db using="primary" aggregate="sales" group="region" sum="revenue" | @render type="bar"

@event name='build-done' data='{"status":"ok"}' transport='mcp'
@event name='progress' data='step 2 of 4' transport='log,file'

@foreach doc in {{ @list ./.mdd/docs/ match="*.md" }}
  @read-frontmatter path="{{ doc }}" field="status" label=s /
  - {{ doc }} ({{ s }})
@foreach-end

@set today = {{ now_iso() }} /

@data myReport
  ...baseConfig
  site.name = "Acme"
  site.theme = "dark"
@data-end

@foreach row in {{ users }}
  @template ./user-card.md data=row /
@foreach-end

@read-frontmatter path="doc.md" field="status" label=s
@hash path="doc.md" algo=sha256 length=8 label=h

@test command="pnpm test" label=results
@check command="tsc --noEmit" label=tc

@mkdir .mdd/docs
@copy from="tpl.md" to="doc.md" if-missing
@update-frontmatter path="doc.md" field="status" value="done"

@markdownai-detect as=info include="layout" /
@plugin-data name="mdd" /

Security

Security is a first-class concern in MarkdownAI, not an afterthought. Every external operation is jailed by default and must be explicitly enabled. The security layer lives in the engine - it applies regardless of which directive triggers the operation.

Caching

Add @cache to any directive to avoid redundant fetches on repeated renders. Cache modes range from in-memory session caching to persistent disk storage with expiry. The mock mode is particularly useful for testing - your document runs with real directives but against predictable fixture data.

Cache Management

mai cache clear              # clear all cached entries
mai cache clear my-doc.md    # clear for one document
mai cache show               # inspect what is currently cached
mai cache seed my-doc.md     # pre-populate by running all fetches ahead of time

Output Formats

The renderer supports 11 output formats. All are plain ASCII that renders correctly everywhere - in terminals, GitHub, VS Code preview, and AI context windows.

Pipe Chains

Formats become most useful when combined with the pipe operator. A data fetch, a few transforms, and a render sink - all on one line:

@list ./src/ | sort | @render type="tree"
@query bash -c "df -h" | @render type="table"
@db using="primary" aggregate="sales" group="name" sum="revenue" | @render type="bar"
@query bash -c "git log --oneline -20" | grep "feat" | @render type="numbered"

How to Integrate MarkdownAI with Claude and AI Agents

MarkdownAI was designed with AI-native workflows in mind. Every feature is built to serve both humans reading rendered output and AI tools consuming live document context. There are three distinct integration points.

Skill Context Variables

When a MarkdownAI document is used as a Claude Code skill file, the full slash command invocation context is available inside the document. This enables genuine engine-evaluated dispatch - the engine routes to the correct section before Claude even sees the file.

@markdownai v2.0

@include ./{{arg0}}-mode.md /

That single line replaces a five-branch @if/@elseif chain. Add a JS || default for when the skill is called with no argument:

@include ./{{arg0 || 'audit'}}-mode.md /

Use allowed() to restrict which values are accepted. It returns the value itself when it matches the list, or false when it doesn't - so the || default kicks in automatically:

@switch {{ allowed(argsList[0], ["audit","build","op"]) || "build" }}
  @case "build"
    Running build mode...
  @case "audit"
    Running audit mode...
  @case "op"
    Running op mode...
@switch-end

Works inside @foreach too - the loop variable is available in the path expression on every iteration:

@foreach section in intro,features,pricing
  @include ./{{section}}.md /
@foreach-end

CLI Reference

All commands share these universal flags:

Commands

How does MarkdownAI prevent context rot?

Context rot is the gradual degradation of AI agent output quality as the context window fills with accumulated noise -- conversation history, intermediate tool results, failed attempts, and full-file reads. By session hour two, even capable models hallucinate variable names that do not exist and repeat approaches they already tried. The problem is not the model. It is the architecture.

MarkdownAI's @phase directive eliminates context rot at the file level. Each phase is a named, isolated block. The MCP server's resolve_phase tool returns exactly one phase per call. The agent never sees phases it is not currently executing. Previous phases never entered the current context window. There is no accumulated noise because there is no accumulation.

Related directives: @phase, @on-complete. Related MCP tools: next_phase, get_session_state.

How does MarkdownAI automate AI runbooks with live data?

A runbook is only useful if it reflects the current state of the system. Static runbooks go stale the moment the system changes. The standard response -- "update the runbook" -- fails at scale because teams have hundreds of runbooks and nobody has time.

MarkdownAI runbooks do not store state. They declare data sources. The @db directive queries your database when the agent reads the file -- not when you wrote it. The @http directive hits your health endpoint live. The @query directive runs a shell command and returns the actual current output. Combined with @phase, a MarkdownAI runbook is a self-contained execution system: phase-gated, live-data-backed, and safe to run against a production system because every fact is fetched fresh on every execution.

How do you keep CLAUDE.md small at scale?

Anthropic recommends keeping CLAUDE.md under 200 lines. In practice, every project that uses Claude Code seriously exceeds this limit within a week -- conventions, schemas, connection strings, workflow steps, and environment context all accumulate. The result is a bloated file that burns context before any actual work begins.

The MarkdownAI architecture solves this with a thin entry point. The CLAUDE.md or CLAUDE-MarkdownAI.md file stays under 20 lines. It calls @read on phase-specific instruction files that live in .mdd/. It fetches live state from the database or environment at session start. The agent sees a focused, accurate, pre-resolved context -- not a file it has to parse to find what is relevant to the current step.

How does MarkdownAI solve AI agent cold-start amnesia?

Every new Claude Code session starts from zero. The model has no memory of what phase 3 decided, what state was built up in the last session, or what variable values were set two hours ago. Complex multi-session workflows break at every context reset because the agent re-derives the same conclusions from scratch.

MarkdownAI's MCP server solves this at the protocol level. A skill_session_id keys per-session, per-document state inside the server. @set values written in phase 1 are readable in phase 5 even across full session resets. The document manages state. The agent follows steps. A 20-phase deployment runbook survives overnight without losing position.

How is MarkdownAI different from n8n, Make, and visual workflow builders?

Visual workflow builders (n8n, Make, Relay, Zapier) and MarkdownAI solve different problems for different audiences. Visual builders are designed for non-technical operators connecting SaaS tools via a drag-and-drop interface. MarkdownAI is designed for developers who want their workflow definition to live in the repository as a text file, reviewed in pull requests, diffed in git, and executed by an AI agent via MCP.

Directive Reference

Every directive supported by MarkdownAI, grouped by category.

Header and Activation

Environment and Variables

Macros and Composition

Conditionals

Operators: ==, !=, <, >, <=, >=, &&, ||, !, startsWith, endsWith, includes, file.exists, file.isFile, file.isDir, file.containsLine(path, regex), file.containsSection(path, heading), file.frontmatterField(path, field)

Iteration and Variables

Data Sources

Execution

Filesystem Writes

All write directives require filesystem.write_enabled = true. Confined to write_root and allowed_write_paths. Immutable always-block rules still apply.

Pipeline and Rendering

Phases and Graphs

Plugin System

Caching

AI-Native

Sandbox builtins

Functions usable inside @if conditions and {{ }} interpolations.

VS Code Extension

The MarkdownAI VS Code extension provides full IDE support for .md files that begin with @markdownai. Open the Extensions panel (Ctrl+Shift+X / Cmd+Shift+X), search for MarkdownAI, and click Install. Or install from the VS Code Marketplace.

Architecture

MarkdownAI is a six-package npm workspaces monorepo, all TypeScript with strict mode throughout. Each package has a single, well-bounded responsibility.

Installation

MarkdownAI installs globally via npm. One command puts mai on your path. Node.js 18 or higher required.

npm install -g @markdownai/core
mai --version

mai init

cd your-project
mai security init