---
schema_version: 1
revision: "22ce5d34dbcb5a78"
id: "factory-markdown-flows-worked-example"
title: "Markdown flows as a repeatable control surface — worked example"
---

# Markdown flows as a repeatable control surface — worked example

Detailed worked example with concrete prompts, observable outcomes, and the limits of the example.

## The session

You

Set up mdflow in this project. No engine calls — just the scaffold.

Agent

``` text
npx mdflow init -y
```

Twelve files landed, zero engine invocations:

``` text
.mdflow.yaml                # engine: pi, evolve mode: suggest
flows/README.md             # roster operator card
flows/review.md             + review.eval.ts
flows/changelog.md          + changelog.eval.ts
flows/pr-description.md     + pr-description.eval.ts
flows/onboard.md            + onboard.eval.ts
flows/fix-tests.md          + fix-tests.eval.ts
```

First beat is always the scaffold. `init` is deterministic — it never overwrites an existing roster, never calls an engine, and every starter flow arrives with a sibling eval suite on day one.

You

I open every session re-explaining the same three things: the branch, which panes are running, what ticket I'm on. Make that a flow — `flows/workshop-standup.claude.md`. Preload git status, the last five commits, a herdr pane snapshot, and a tickets line, then tell the agent to work only from what was preloaded.

Agent

Wrote the flow. The whole trick is in lines like these — `` !`command` `` inlines that mdflow executes while *building* the prompt, splicing their output in before the agent exists:

``` text
## Repo state (git)

!`git status --short --branch`

## Terminal workspace (herdr panes)

!`herdr api snapshot 2>/dev/null | head -40 || echo "(herdr not running)"`
```

The body opens by telling the agent the output was captured at prompt-build time, before it started, and must not be re-run. Complete file lands at the end of this replay.

The agent never spends a tool-call round trip on `git status` — and never skips or reorders it. Every inline is guarded (`2>/dev/null || echo "…"`), so a machine without herdr gets a placeholder line in the prompt instead of a failed run.

You

Before anything runs: prove exactly what this file will do.

Agent

Ran `md explain flows/workshop-standup.claude.md` — it resolves the full configuration and executes nothing. Captured output from this project (middle sections elided):

``` text
COMMAND
Resolved command: claude
Source: Filename pattern (.claude.md)

ISOLATION
ON (default) — ambient engine context is disabled; host capabilities
remain available
   safe-mode: true
   no-session-persistence: true
   (opt out with _isolated: false)

FINAL CLI ARGS
--print --safe-mode --no-session-persistence --model sonnet

TOKEN USAGE
Estimated tokens: 174
Context limit: 200,000
Usage: 0.1%
```

Two reveals in one audit. Engine: the `.claude.md` filename pinned claude — the full ladder is `--engine` flag → `MDFLOW_ENGINE` → filename → frontmatter → project config → default (pi). Isolation: ON without any frontmatter asking for it — no CLAUDE.md, hooks, or MCP leak in. (Context isolation, not a host sandbox — the inlines and the engine still reach your filesystem and network.)

You

Run it.

Agent

``` text
md flows/workshop-standup.claude.md
```

The standup printed with the agent already briefed: it named the branch and dirty files from the git inline, the visible panes from the herdr snapshot, and the ticket placeholder line — without making a single tool call. Everything rode in on the prompt.

The production version of this pattern goes further: a flow in `~/.mdflow/` runs a preload script that fetches workshop ticket buyers and calendar attendees, prints the computed diff as markdown, and tells the agent "fetched moments ago — do NOT re-fetch." The script exits 0 even on failure, printing a PRELOAD ERROR section instead, so the error lands inside the prompt and the agent relays it and stops.

You

Prove the project is still healthy.

Agent

``` text
md doctor --json | node -e 'const d=JSON.parse(require("fs").readFileSync(0,"utf8"));console.log("flows:",d.summary.flows,"structuralErrors:",d.summary.structuralErrors)'
```

``` text
flows: 6 structuralErrors: 0
```

`md doctor` is free and read-only. Its JSON also lists every flow's declared capabilities — the standup flow reports exactly its four inlined commands.

Eval verdicts in this project read `Unverified — no full eval receipt has been recorded`. That's a missing receipt, not an error; `structuralErrors: 0` is the success signal here.

You

One more. The voting process that chose this page format — capture it as a flow so we never re-litigate it.

Agent

Done in a prior session: `flows/this-or-that.md` now lives at the workshop repo root, captured from the very session that picked this two-page format. It encodes the whole Elo round — frame the axis, scaffold the lab, generate structurally distinct options, QA, hand over, bank the results — and injects the accumulated taste record fresh on every run:

``` text
---
description: Run one this-or-that Elo voting round — generate structurally distinct options over a constant subject, stand up the duel harness, wait for votes, then bank the taste as explicit rules
_inputs: [_question, _subject]
_interactive: true
---
…
## Accumulated taste record (injected fresh each run — read before generating options)

@../authoring-lab/RESULTS.md

@../07-variations/template-lab/RESULTS.md
```

`md explain flows/this-or-that.md` is free and read-only if you want to audit it yourself.

Flows evolve, but never by vibes: when one disappoints, record `md feedback` (a durable `fb_…` ID), preview with `md eval --plan`, and let `md evolve plan → propose → apply` do the rest. The source file stays byte-identical until an explicit apply.

Agent

The file this session produced, complete:

``` text
---
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.
```

File landed. Versioned, inspectable for free, isolated by default. Both this flow and `this-or-that.md` are downloadable attachments — the install block is on the [section guide](https://walnut-virtue-6d22.here.now/index.html#attachments-install-these-flows).

Total session: six prompts, one paid run. The pattern the transcript demonstrates — scaffold → preload → audit → run → verify → capture — repeats for every briefing you catch yourself typing twice.

## Original references

- [Markdown flows as a repeatable control surface — worked example](https://walnut-virtue-6d22.here.now/replay.html)
