---
schema_version: 1
revision: "22ce5d34dbcb5a78"
id: "factory-markdown-flows-practice"
title: "Markdown flows as a repeatable control surface — prompts and exercises"
---

# 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.

## Quick start

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

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

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

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

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

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

3.  Inspect it without executing anything, then run it:

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

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

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):

``` text
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](https://walnut-virtue-6d22.here.now/replay.html)'s final beat):

``` text
md install "https://walnut-virtue-6d22.here.now/flows/this-or-that.md?raw"
```

Prefer plain files in `flows/`? Fetch the raw attachments directly:

``` text
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](https://www.skills.sh/) 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):

``` text
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](https://gentle-lasso-9d5n.here.now/).

## 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](https://walnut-virtue-6d22.here.now/replay.html) — an annotated transcript of the session that built this exact setup — and the [Dialogue](https://walnut-virtue-6d22.here.now/dialogue.html) — 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:

```bash
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:

   ```bash
   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:

   ```markdown
   ---
   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`):

   ```bash
   md explain flows/workshop-standup.claude.md
   ```

4. Run the flow. It prints a standup summary built only from the preloaded context:

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

## Success check

Run:

```bash
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>`:

```bash
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):

```bash
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/`.

## Original references

- [Markdown flows as a repeatable control surface](https://walnut-virtue-6d22.here.now/)
- [Public setup contract](https://walnut-virtue-6d22.here.now/agent.md)
