MARKDOWN AGENTS
THAT EVOLVE.
One file per agent. Any engine.
Evals that guard declared behavior.
Feedback becomes capability-checked, reviewable proposals.
One command, start to finish. No flows yet? It offers first-run setup — guided by the agent CLI you already use, a zero-engine scaffold of ./flows, or a setup prompt to paste into any agent. Once a roster exists, the same command opens the Workbench.
./flows
EVERY REPO DESERVES
AN AGENT ROSTER.
./flows holds one markdown agent per job: code review, release notes, issue triage. They're diffable in PRs. They're provable with md eval. And new teammates, human or AI, learn how the project actually works by reading them.
A flow is one markdown file: frontmatter config, prompt body, colocated evals. Run it on any engine. Every rough run is raw material. Bad outputs become failing eval cases. Fixes arrive as reviewable diffs. Nothing lands unless the suite passes. Your agents get better because you used them.
four ways to start
SET UP A PROJECT. CREATE A FLOW.
IMPROVE IT. TAKE IT EVERYWHERE.
These browser-only fixtures show a guided engine inspecting a project and suggesting flows, then how md creates one from an empty terminal, evolves it from evidence, and resolves personal flows everywhere.
Add flows to your project
Let a guided session inspect the repo, suggest a numbered roster, and wait for your approval.
The interactive terminal uses JavaScript. Read the documentation for commands you can run locally.
Pick a story, then use Previous, Play, Next step, or the terminal. Gates still require confirmation.
change with proof
FEEDBACK IN.
REVIEWABLE PROOF OUT.
Tell a flow what went wrong with md feedback. mdflow drafts a private prompt proposal, checks its capability delta, and measures current versus candidate behavior. Your working tree does not change until you explicitly apply a reviewed run.
feedback → reviewed eval → plan → proposal → proof → review → apply. Every transition has stable status and reason codes. Cost and writes are printed before paid work begins.
Claims match proof
“Verified improvement” requires a feedback-linked red/green case. A clean uncovered change is labeled regression-safe, never “fixed.”
Canonical source stays still
Current and proposal run from separate off-path snapshots. Drafting and verification never expose a half-gated candidate at the real flow path.
Evidence is durable
Stable feedback IDs move through open, targeted, resolved, or dismissed. Rejection and infrastructure failures leave the reported problem open.
Capabilities cannot sneak in
The prompt body may change, but new commands, executable fences, URLs, providers, globs, or broader file access are blocked before candidate execution.
Proof is content-bound
Receipts bind flow imports, suite code, merged config, engine/model, mdflow version, and cases. Timeouts and flakes are inconclusive, not passes.
Apply is transactional
Review first. Explicit apply uses a per-flow lock, hash compare-and-swap, atomic writes, lineage, and a hash-guarded rollback command.
Agent-first
LET YOUR AGENT
SET IT UP.
You already have an agent open. Paste one of these and let it build your ./flows roster, wire the engines, and add behavioral guardrails. You watch.
Start my agent roster
Scaffolds flows, starter evals, and suggest-only evolution; then tailors them to your repo. Zero paid invocations until you say go.
Set up and tailor this repository's mdflow roster safely:
1. Run `command -v md || npm i -g mdflow`.
2. Run `md doctor --json` and branch on its stable diagnostic codes and effect-labelled next actions.
3. Preview deterministic setup, then run `npx mdflow init --yes`; do not launch the guided ENGINE setup unless I separately approve it.
4. Run `md doctor --json` again. Preserve user-authored text in flows/README.md and keep only its managed block current with `md roster sync`.
5. Tailor flows and their evals to this repository. Suite presence is not verification: init may copy real catalog suites, while md create emits fail-closed drafts.
6. For a waiting interactive specialist, put identity in `_system-prompt`, stable rules in `_append-system-prompt`, declare `_task: ""`, and make the body exactly `{{ _task }}`; reject any `User task:` wrapper or empty/placeholder positional prompt.
7. Use `md explain <flow.md> --json` and `md eval <flow.md> --plan` before asking separately for a real flow run or eval run.
8. Treat .eval.ts and .hooks.ts as executable local code. Engine isolation is not a host sandbox. Registry install adds one flow, not trusted sidecars.Install the mdflow skill
One command teaches your agent (Claude Code, Cursor, and friends) how to build and maintain your ./flows roster, wire the engine ladder, and ship evals. Permanently.
npx skills add johnlindquist/mdflow
Add evals to every flow
Behavioral suites with repetition-aware plans and content-bound receipts. Cost is quoted before a paid invocation.
Improve the proof for every project flow without spending an engine invocation yet: 1. Start with `md doctor --json`; use its eval diagnostic codes instead of inferring proof from sibling-file presence. 2. Review each executable .eval.ts sidecar. Replace fail-closed draft cases with 1–3 behavioral cases that check invariants, not exact prose. 3. Run `md eval <flow.md> --plan` and report the exact planned invocation count including repetitions. Static planning must not import suite code. 4. Do not run an eval until I separately approve that ENGINE operation; approval to run the flow is not eval approval. 5. Link reproduced failures to durable feedback with evidence: ["fb_..."]. Only a current fingerprint-bound full all-pass receipt is Verified.
Migrate legacy flows
Loose files move into ./flows, tool: becomes engine:, and engine migrations follow the detected environment. Everything is inspected with free commands first.
Migrate legacy mdflow files conservatively:
1. Run `md doctor --json` first. Move appropriate loose agents into ./flows and use `md roster sync` so user-authored README text is preserved.
2. Change tool:/_tool: to engine: and --_command/--tool to --engine.
3. Do not mass-rename Gemini flows: gemini remains valid for Code Assist Standard/Enterprise; use agy only when the user's environment requires it.
4. For each waiting interactive specialist, put identity in `_system-prompt`, stable rules in `_append-system-prompt`, declare `_task: ""`, and make the body exactly `{{ _task }}`; remove `User task:` wrappers and require no positional prompt.
5. Inspect each result with `md explain <flow.md> --json` and free eval plans. Never infer consent for a real flow run, eval run, proposal, or source apply from another operation.NAME
mdflow - executable markdown for AI agents
SYNOPSIS
md [file] [--_var value] [--engine name] [--_dry-run] [--_edit] [--_context] [flags...]
md <command> [options]
md.ENGINE "prompt" [flags] — ad-hoc, no file needed (md.claude, md.codex, …)
(md and mdflow are the same command; no arguments = interactive flow picker)
Commands
doctor [--json] Inspect project readiness and safe next actions without execution
init [--guided] [--engine <e>] [--yes] [--agents] [--print-guide] Initialize a project flow roster
create [intent] [--global] [--dry-run] Create a flow and a fail-closed draft eval suite
capture Print the guide for capturing the current agent conversation as a flow
explain <flow.md> [--json] Resolve one flow without launching its engine
render <flow.md> [--json|--out <path>|--open] Inspect, write, or open a rendered flow explanation
hooks add|list|remove <flow.md> [event...] Manage executable lifecycle hook sidecars
eval <flow.md> [--plan] [--yes] [--json] Plan or run a flow's behavioral eval suite
feedback <flow.md> <message> | list|show|distill|dismiss|reopen|forget Manage durable evolution evidence
complain <flow.md> <message> Compatibility alias for feedback
evolve plan|status|propose|show|apply|reject|retry|rollback|history|prune Manage proposal-first flow evolution
install <url|gh:org/repo/path@ref> [--global] Install one flow into the registry
remove <name> Remove an installed registry flow
list [--project|--global] List installed registry flows
roster --json | roster sync [--check] [--agents] [--json] Inspect flows or synchronize the managed operator card
catalog [--json] Machine-readable catalog of every discoverable flow (project, global, installed, PATH)
setup Configure shell integration
logs Show flow log locations
help [command] Show CLI or command help
Engine Resolution (the ladder)
Most explicit wins: --engine flag → MDFLOW_ENGINE env → filename (task.claude.md) → frontmatter engine: → config → default (pi). Implicit picks are announced on stderr. No frontmatter + no explicit engine = the file is a document and just prints.
Flags (vary by command)
Flags in frontmatter are passed to the selected CLI. Check your AI tool's docs for available options.
--model model name (all CLIs)
--add-dir include directory
--full-auto codex: sandboxed auto
--dangerously-skip-permissions agy: auto-approve
--allow-all-tools copilot: auto-approve
--allowedTools claude: tool whitelist
Template Variables
--_varname → {{ _varname }}
{{ _stdin }} piped input
{{ _1 }}, {{ _2 }} positional args
_interactive: live session
md-Specific Flags
--engine specify the engine to run
--_dry-run preview without executing (--dry-run is an alias)
--_hooks override or disable the flow's hooks file
--_edit edit prompt in $EDITOR
--_context show context tree
--raw raw output (for piping)
--json single JSON result object
--no-evolve disable post-run evolution handling for this run
File Imports
@./file.ts import file
@./src/**/*.ts glob pattern
@./file.ts:10-50 line range
@./file.ts#Symbol extract symbol
Inline Commands
!`git log -5` shell command output
!`md file.md` sub-agent output
DESCRIPTION
mdflow executes markdown files as AI flows. Frontmatter YAML becomes CLI flags; the body becomes the prompt; the engine resolves via the ladder (default: pi, ambient engine context disabled, with your Codex login bridged automatically). Engines: claude, copilot, codex, gemini, droid, opencode, pi, cursor-agent, agy (Antigravity), grok, kimi, or any CLI binary. Colocated .eval.ts suites guard a flow's declared behavior.
EXAMPLES
# Run a basic task
md review.claude.md
# Pipe git diff into an agent
git diff | md explain.claude.md
# Chain agents together (research → plan → code)
md research.md | md plan.claude.md | md code.codex.md
# Prove a flow's behavior
md eval review.md --plan
# Evidence → private proposal → explicit review
md feedback review.md "misses renamed files"
md evolve plan review.md
md evolve propose review.md
INSPECT & DEBUG
Preview what your template will render to before running the agent. Use md explain to see the resolved config chain, or --_dry-run to inspect the command plan and safe prompt preview. Inline commands and executable code fences are shown but not run.
# Analyze agent configuration
md explain review.claude.md
# Preview the rendered template
md review.claude.md --_dry-run
# Show context tree and token usage
md review.claude.md --_context
ZSH SUFFIX ALIAS
With ZSH, you can run .md files directly. No command needed. The suffix alias makes markdown files executable. Inline commands like `!md file.md` also run automatically without the md prefix.
# Add to ~/.zshrc
alias -s md=mdflow
# Then just run the file directly
./review.claude.md
AGENT LIBRARY
Store agents in ~/.mdflow/ for global access or .mdflow/ per project. Run md without arguments to pick from available agents. Add to your PATH for tab completion anywhere.
# Global agents
~/.mdflow/review.claude.md
~/.mdflow/commit.agy.md
# Interactive file picker
md ← picks from ~/.mdflow/ and .mdflow/
# Add to PATH for autocomplete
export PATH="$HOME/.mdflow:$PATH"
Engine Resolution · No Filename Ceremony
The Engine Ladder
The engine is environment, not filename ceremony. Bare review.md runs on your default engine (pi, bridging your Codex login automatically). Pin one per file, per shell, or per project. The ladder resolves it and tells you which rung won.
Evals · Trust Ledger
Evals: Prove It
If a guardrail isn't covered by an eval, it's a wish. Colocate review.eval.ts with your flow. Each case runs in an isolated temporary workspace. The cost is printed before a single turn is spent. Clean runs are stamped in the trust ledger.
Multi-Agent
Parallel Analysis
Spawn sub-agents to analyze different parts of your codebase in parallel. Each expert focuses on their domain. The parent synthesizes insights and prioritizes action.
Chain Agents
Agent Pipelines
Pipe agents together. Research flows into planning flows into implementation. Each agent's output becomes the next agent's input.
Sub-Agents
Orchestrated Workflows
Parent agents spawn children, wait for results, then continue. Build release pipelines, review workflows, or any multi-step process.
@ References
File Imports
Pull in files, globs, line ranges, or URLs. Import conventions, examples, or entire directories. The agent sees exactly what it needs.
Multi-Provider
Any AI, One Syntax
Same template, any AI. Pin an engine in the filename (task.claude.md, task.agy.md), the frontmatter (engine: codex), or nowhere at all. The ladder resolves it. Portable keys like model translate per engine.
.i. Sessions
Interactive Mode
Add .i. to the filename for a live conversation. Debug issues, explore ideas, iterate on solutions, without re-running the agent.