Complete reusable prompts, setup recipes, success checks, and caveats for markdown flows as a repeatable control surface.
Quick start
npx mdflow init -y # starter roster + .mdflow.yaml, no engine calls
md # Flow Workbench: one searchable launcher
md doctor --json # free, read-only project diagnosis
md explain flows/review.md # resolved config + capabilities, nothing executed
md flows/review.md # run a flow (stage a change first)
md.claude "quick one-off question" # ad-hoc, no file needed
Prompt library
Turn a repeated briefing into a flow
- Agent: Claude Code (or any coding agent)
- Working directory: your project root, after
npx mdflow init -y - Expected result: a new flow whose
md explainlists every inline as a capability
I keep re-typing the same briefing at the start of agent sessions. Turn it into an mdflow flow. Create flows/standup.claude.md: frontmatter with a one-line description, then a body that preloads live state with !`command` inlines (git status --short --branch, git log --oneline -5, plus any command I name below), then a short instruction section telling the agent to work only from the preloaded context. Tell the agent the output was captured at prompt-build time so it must not re-run the commands. Then run `md explain flows/standup.claude.md` and confirm ISOLATION reads ON and every inline appears as a command capability. Briefing to encode: <describe your repeated briefing here>
Audit a flow before you run it
- Agent: any coding agent
- Working directory: a repo containing
flows/ - Expected result: engine, isolation state, every prompt-build command, token estimate
Audit an mdflow flow before I run it. Run `md doctor --json` and `md explain <flow path>` (both are free and execute nothing). Report: which engine the flow resolves to and why (flag, env var, filename, frontmatter, config, or default); whether ISOLATION is ON; every command capability that will execute at prompt-build time; and the estimated token usage. Flag any capability that reaches the network or mutates files. Flow to audit: <path>
Walk the evolve loop instead of hand-editing
- Agent: any coding agent
- Working directory: a repo where a flow just disappointed you
- Expected result: an off-path proposal with an outcome word; the flow file untouched until apply
A flow just gave a bad result. Do NOT edit the flow file. Instead: 1) Record it with `md feedback <flow path> "<what went wrong>"` and show me the durable fb_ id. 2) Run `md eval <flow path> --plan` and `md evolve plan <flow path>` (both free) and summarize the evidence, verification plan, and cost. 3) Only if I say go: run `md evolve propose <flow path>`, then `md evolve show <run-id>`, and report the outcome word (verified_improvement, regression_safe, rejected, inconclusive, or capability_rejected) plus the prompt diff. Never run `md evolve apply` without my explicit approval. Flow: <path>. What went wrong: <describe>
Set it up (agent guide)
-
From your project root, scaffold the roster. This writes
.mdflow.yamland five starter flows, each with a sibling eval suite, and invokes no engine:npx mdflow init -y -
Create the standup flow. This is the whole trick: the
!`command`inlines run at prompt-build time, so the agent's first token arrives with git state, terminal panes, and tickets already in front of it.--- description: pane-aware standup — agent starts already knowing git, panes, and tickets model: sonnet print: true --- You are a standup assistant. Everything below was captured at prompt-build time, BEFORE you started — do not re-run these commands. ## Repo state (git) !`git status --short --branch` !`git log --oneline -5 2>/dev/null || echo "(no commits yet)"` ## Terminal workspace (herdr panes) !`herdr api snapshot 2>/dev/null | head -40 || echo "(herdr not running)"` ## Open tickets (linear) !`echo "(placeholder: linear 'list my in-progress issues' — sandboxed agent call)"` ## Your job From the preloaded context only: 1. Say what I'm in the middle of (branch, dirty files, visible panes). 2. Flag anything that looks stalled or contradictory. 3. Suggest the single next action, one sentence. -
Inspect it without executing anything, then run it:
md explain flows/workshop-standup.claude.md # expect ISOLATION: ON (default) md flows/workshop-standup.claude.md # prints your standup
Success check: the project parses cleanly with all six flows registered.
md doctor --json | node -e 'const d=JSON.parse(require("fs").readFileSync(0,"utf8"));console.log("flows:",d.summary.flows,"structuralErrors:",d.summary.structuralErrors)'
flows: 6 structuralErrors: 0
Fallback: if structuralErrors is non-zero, check whether the errors are CONFIG_INVALID from a pre-existing global ~/.mdflow/config.yaml rather than from the flows — an invalid global config fails this check even when every flow is clean. Verify per-flow with md explain flows/<name>.md instead.
Attachments — install these flows
Both flows discussed on these pages are hosted on this site as raw markdown attachments. md install pulls a remote flow straight into your project's registry (npx-style; first use asks you to trust the domain). Reversible with md remove <name>; list what you have with md list.
The pane-aware standup flow (this section's money artifact):
md install "https://walnut-virtue-6d22.here.now/flows/workshop-standup.claude.md?raw"
The captured this-or-that Elo voting loop (the flow from the Session Replay's final beat):
md install "https://walnut-virtue-6d22.here.now/flows/this-or-that.md?raw"
Prefer plain files in flows/? Fetch the raw attachments directly:
mkdir -p flows
curl -fsSL "https://walnut-virtue-6d22.here.now/flows/workshop-standup.claude.md?raw" -o flows/workshop-standup.claude.md
curl -fsSL "https://walnut-virtue-6d22.here.now/flows/this-or-that.md?raw" -o flows/this-or-that.md
Note: this-or-that.md injects taste records via @../…/RESULTS.md includes that exist in the workshop repo — outside it, point those includes at your own vote records. Audit either flow for free with md explain.
Prefer skills? Every flow has a skill twin
If your stack runs on agent skills rather than mdflow, every flow on these pages is also hosted here as a SKILL.md twin under /skills/ — same job, no mdflow required. The trade is the section's own lesson in reverse: a flow preloads shell output at prompt-build time and runs isolated from ambient config; the skill twin has the agent run those commands itself inside your normal session. Six twins are hosted here — workshop-standup, review, changelog, fix-tests, onboard, pr-description. Stage them anywhere except a dir named skills/ (the skills CLI claims that name as its own symlink target and you'd install an empty skill):
for s in workshop-standup review changelog fix-tests onboard pr-description; do
mkdir -p skill-src/$s
curl -fsSL "https://walnut-virtue-6d22.here.now/skills/$s/SKILL.md?raw" -o skill-src/$s/SKILL.md
npx skills add ./skill-src --skill $s -y
done
Trim the list to just the names you want. The this-or-that loop's skill twin lives on the This-or-That section site.
Complete reusable setup contract
mdflow: markdown flows as an agent control plane — agent setup guide
Following this file sets up: mdflow in the current project — a starter flow roster plus one context-preloading "standup" flow that briefs the agent with git status, recent commits, terminal panes, and tickets before its first token.
Human companion pages (context for you, reading for your user): the Session Replay — an annotated transcript of the session that built this exact setup — and the Dialogue — skeptical Q&A about why flows work this way. This file remains the canonical machine copy: execute it top-to-bottom.
Placeholders used below: <project-root> = the project you are working in. All other paths are literal and relative to <project-root>.
Prerequisites
Check each before starting:
node --version
npx mdflow help | head -4
claude --version
Expected: Node 18+; the mdflow usage banner (Usage: md <file.md> ...); any Claude Code version string. If npx mdflow fails, stop and tell your user to check their network/npm setup. If claude is missing, see Notes for agents — the flow can run on another engine.
Steps
-
From
<project-root>, scaffold the roster. This writes.mdflow.yamland five starter flows (each with a sibling.eval.tssuite) and invokes no engine:npx mdflow init -y -
Create
flows/workshop-standup.claude.mdwith exactly this content. The!`command`inlines run at prompt-build time — mdflow executes them and splices the output into the prompt before the agent starts:--- description: pane-aware standup — agent starts already knowing git, panes, and tickets model: sonnet print: true --- You are a standup assistant. Everything below was captured at prompt-build time, BEFORE you started — do not re-run these commands. ## Repo state (git) !`git status --short --branch` !`git log --oneline -5 2>/dev/null || echo "(no commits yet)"` ## Terminal workspace (herdr panes) !`herdr api snapshot 2>/dev/null | head -40 || echo "(herdr not running)"` ## Open tickets (linear) !`echo "(placeholder: linear 'list my in-progress issues' — sandboxed agent call)"` ## Your job From the preloaded context only: 1. Say what I'm in the middle of (branch, dirty files, visible panes). 2. Flag anything that looks stalled or contradictory. 3. Suggest the single next action, one sentence. -
Inspect the flow without executing anything. Confirm ISOLATION reads
ON (default)and the FINAL PROMPT section shows all four inlined commands (there is no separate capability section inmd explain; per-flow capability lists live inmd doctor --json):md explain flows/workshop-standup.claude.md -
Run the flow. It prints a standup summary built only from the preloaded context:
md flows/workshop-standup.claude.md
Success check
Run:
md doctor --json | node -e 'const d=JSON.parse(require("fs").readFileSync(0,"utf8"));console.log("flows:",d.summary.flows,"structuralErrors:",d.summary.structuralErrors)'
Expected observable result: flows: 6 structuralErrors: 0 — five starter flows plus the standup flow, all parsing cleanly. (md doctor is free and read-only.)
Fallback: if structuralErrors is non-zero, check the report's diagnostics before assuming the flows are broken — a pre-existing invalid global ~/.mdflow/config.yaml surfaces here as a CONFIG_INVALID error even when every flow is clean. In that case verify per-flow with md explain flows/<name>.md: if each flow explains cleanly, the flows are fine and only the global config needs fixing.
Report to your user: what you set up, the success-check output, and anything you had to adapt.
Flow attachments (raw downloads)
Both flows discussed on the site are hosted here as raw markdown attachments. Machine-fetch URLs (the ?raw suffix is required — the bare .md URL serves an HTML viewer):
https://walnut-virtue-6d22.here.now/flows/workshop-standup.claude.md?raw— the pane-aware standup flow from Step 2 (identical content; fetching it is an alternative to writing the file by hand).https://walnut-virtue-6d22.here.now/flows/this-or-that.md?raw— the captured this-or-that Elo voting loop flow. Its@../…/RESULTS.mdincludes reference the workshop repo's vote records; outside that repo, repoint them at your user's own records before running.
Instead of writing Step 2's file manually you may run, from <project-root>:
mkdir -p flows
curl -fsSL "https://walnut-virtue-6d22.here.now/flows/workshop-standup.claude.md?raw" -o flows/workshop-standup.claude.md
md install "<url>?raw" also works and registers the flow in the project registry instead of flows/ (reversible with md remove <name>).
Skill twins (if the user prefers agent skills over flows)
Every flow discussed on the site also ships as a skills.sh-format SKILL.md twin hosted under /skills/ — same job, no mdflow required. The difference: a flow preloads shell output at prompt-build time and runs isolated; the skill twin instructs the agent to run those commands itself in the normal session. Available names: workshop-standup, review, changelog, fix-tests, onboard, pr-description (the this-or-that twin is hosted at https://gentle-lasso-9d5n.here.now/skills/this-or-that/SKILL.md?raw). Machine-fetch URL pattern (?raw required): https://walnut-virtue-6d22.here.now/skills/<name>/SKILL.md?raw.
To install for your user (stage anywhere EXCEPT a dir named skills/ — the skills CLI claims that name and you'd install an empty skill):
for s in workshop-standup review changelog fix-tests onboard pr-description; do
mkdir -p skill-src/$s
curl -fsSL "https://walnut-virtue-6d22.here.now/skills/$s/SKILL.md?raw" -o skill-src/$s/SKILL.md
npx skills add ./skill-src --skill $s -y
done
Trim the loop to the names the user wants. Only install skills when the user prefers them over flows — the flows remain the primary artifact of this section.
Notes for agents
- If
mdis not on PATH, substitutenpx mdflowformdin every command above (md setupconfigures PATH and aliases for the user's shell). - The flow degrades gracefully by design: the
herdrandlinearinlines are guarded with2>/dev/null || echo "...", so machines without those tools get placeholder lines in the prompt instead of a failed run. - The
.claude.mdfilename pins the claude engine. If theclaudeCLI is not installed, name the fileflows/workshop-standup.mdinstead — it will use the project default engine from.mdflow.yaml(pi). Checkengines.installedinmd doctor --jsonto see what is available. - In a directory with no git repo, the git inlines print an error/placeholder line into the prompt. The flow still runs; the standup will just say so.
- Eval verdicts in
md doctor --jsonreadUnverifieduntil a full eval receipt is recorded. That is a missing receipt, not an error —structuralErrors: 0is the success signal here. - Re-running
npx mdflow init -yleaves an existing roster untouched; it is safe in a project that already hasflows/.