Markdown flows as a repeatable control surface — prompts and exercises

Complete reusable prompts, setup recipes, success checks, and caveats for markdown flows as a repeatable control surface.

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 explain lists 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)

  1. From your project root, scaffold the roster. This writes .mdflow.yaml and five starter flows, each with a sibling eval suite, and invokes no engine:

    npx mdflow init -y
    
  2. 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.
    
  3. 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

  1. From <project-root>, scaffold the roster. This writes .mdflow.yaml and five starter flows (each with a sibling .eval.ts suite) and invokes no engine:

    npx mdflow init -y
    
  2. Create flows/workshop-standup.claude.md with 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.
    
  3. 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 in md explain; per-flow capability lists live in md doctor --json):

    md explain flows/workshop-standup.claude.md
    
  4. 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.md includes 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 md is not on PATH, substitute npx mdflow for md in every command above (md setup configures PATH and aliases for the user's shell).
  • The flow degrades gracefully by design: the herdr and linear inlines are guarded with 2>/dev/null || echo "...", so machines without those tools get placeholder lines in the prompt instead of a failed run.
  • The .claude.md filename pins the claude engine. If the claude CLI is not installed, name the file flows/workshop-standup.md instead — it will use the project default engine from .mdflow.yaml (pi). Check engines.installed in md doctor --json to 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 --json read Unverified until a full eval receipt is recorded. That is a missing receipt, not an error — structuralErrors: 0 is the success signal here.
  • Re-running npx mdflow init -y leaves an existing roster untouched; it is safe in a project that already has flows/.

Source references