{
  "schemaVersion": "1",
  "revision": "22ce5d34dbcb5a78",
  "id": "factory-markdown-flows-worked-example",
  "slug": "markdown-flows-worked-example",
  "title": "Markdown flows as a repeatable control surface — worked example",
  "summary": "Detailed worked example with concrete prompts, observable outcomes, and the limits of the example.",
  "category": "Execution",
  "tags": [
    "markdown-flows",
    "examples"
  ],
  "sources": [
    {
      "label": "Markdown flows as a repeatable control surface — worked example",
      "url": "https://walnut-virtue-6d22.here.now/replay.html"
    }
  ],
  "sourceUnits": [
    "05-mdflow/replay.html#The session"
  ],
  "collection": "factory",
  "categoryId": "execution",
  "wordCount": 1042,
  "url": "/topics/factory-markdown-flows-worked-example/",
  "markdownUrl": "/markdown/factory-markdown-flows-worked-example.md?raw=1&v=22ce5d34dbcb5a78",
  "jsonUrl": "/api/v1/documents/factory-markdown-flows-worked-example.json",
  "headings": [
    {
      "id": "the-session",
      "text": "The session",
      "level": 2
    }
  ],
  "markdown": "# Markdown flows as a repeatable control surface — worked example\n\nDetailed worked example with concrete prompts, observable outcomes, and the limits of the example.\n\n## The session\n\nYou\n\nSet up mdflow in this project. No engine calls — just the scaffold.\n\nAgent\n\n``` text\nnpx mdflow init -y\n```\n\nTwelve files landed, zero engine invocations:\n\n``` text\n.mdflow.yaml                # engine: pi, evolve mode: suggest\nflows/README.md             # roster operator card\nflows/review.md             + review.eval.ts\nflows/changelog.md          + changelog.eval.ts\nflows/pr-description.md     + pr-description.eval.ts\nflows/onboard.md            + onboard.eval.ts\nflows/fix-tests.md          + fix-tests.eval.ts\n```\n\nFirst 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.\n\nYou\n\nI 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.\n\nAgent\n\nWrote 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:\n\n``` text\n## Repo state (git)\n\n!`git status --short --branch`\n\n## Terminal workspace (herdr panes)\n\n!`herdr api snapshot 2>/dev/null | head -40 || echo \"(herdr not running)\"`\n```\n\nThe 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.\n\nThe 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.\n\nYou\n\nBefore anything runs: prove exactly what this file will do.\n\nAgent\n\nRan `md explain flows/workshop-standup.claude.md` — it resolves the full configuration and executes nothing. Captured output from this project (middle sections elided):\n\n``` text\nCOMMAND\nResolved command: claude\nSource: Filename pattern (.claude.md)\n\nISOLATION\nON (default) — ambient engine context is disabled; host capabilities\nremain available\n   safe-mode: true\n   no-session-persistence: true\n   (opt out with _isolated: false)\n\nFINAL CLI ARGS\n--print --safe-mode --no-session-persistence --model sonnet\n\nTOKEN USAGE\nEstimated tokens: 174\nContext limit: 200,000\nUsage: 0.1%\n```\n\nTwo 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.)\n\nYou\n\nRun it.\n\nAgent\n\n``` text\nmd flows/workshop-standup.claude.md\n```\n\nThe 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.\n\nThe 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.\n\nYou\n\nProve the project is still healthy.\n\nAgent\n\n``` text\nmd doctor --json | node -e 'const d=JSON.parse(require(\"fs\").readFileSync(0,\"utf8\"));console.log(\"flows:\",d.summary.flows,\"structuralErrors:\",d.summary.structuralErrors)'\n```\n\n``` text\nflows: 6 structuralErrors: 0\n```\n\n`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.\n\nEval 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.\n\nYou\n\nOne more. The voting process that chose this page format — capture it as a flow so we never re-litigate it.\n\nAgent\n\nDone 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:\n\n``` text\n---\ndescription: 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\n_inputs: [_question, _subject]\n_interactive: true\n---\n…\n## Accumulated taste record (injected fresh each run — read before generating options)\n\n@../authoring-lab/RESULTS.md\n\n@../07-variations/template-lab/RESULTS.md\n```\n\n`md explain flows/this-or-that.md` is free and read-only if you want to audit it yourself.\n\nFlows 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.\n\nAgent\n\nThe file this session produced, complete:\n\n``` text\n---\ndescription: pane-aware standup — agent starts already knowing git, panes, and tickets\nmodel: sonnet\nprint: true\n---\n\nYou are a standup assistant. Everything below was captured at prompt-build\ntime, BEFORE you started — do not re-run these commands.\n\n## Repo state (git)\n\n!`git status --short --branch`\n\n!`git log --oneline -5 2>/dev/null || echo \"(no commits yet)\"`\n\n## Terminal workspace (herdr panes)\n\n!`herdr api snapshot 2>/dev/null | head -40 || echo \"(herdr not running)\"`\n\n## Open tickets (linear)\n\n!`echo \"(placeholder: linear 'list my in-progress issues' — sandboxed agent call)\"`\n\n## Your job\n\nFrom the preloaded context only:\n1. Say what I'm in the middle of (branch, dirty files, visible panes).\n2. Flag anything that looks stalled or contradictory.\n3. Suggest the single next action, one sentence.\n```\n\nFile 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).\n\nTotal 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."
}
