{
  "schemaVersion": "1",
  "revision": "22ce5d34dbcb5a78",
  "id": "factory-markdown-flows",
  "slug": "markdown-flows",
  "title": "Markdown flows as a repeatable control surface",
  "summary": "Preload fresh evidence, declare capabilities, isolate ambient context, and improve prompts through explicit proposals.",
  "category": "Execution",
  "tags": [
    "markdown",
    "factory"
  ],
  "sources": [
    {
      "label": "Markdown flows as a repeatable control surface",
      "url": "https://walnut-virtue-6d22.here.now/"
    },
    {
      "label": "Companion lesson",
      "url": "https://proud-anchor-53zn.here.now/learn.html#q2-markdown-flows"
    }
  ],
  "sourceUnits": [
    "05-mdflow/index.html#TL;DR",
    "05-mdflow/index.html#The briefing you keep re-typing",
    "05-mdflow/index.html#Appendix",
    "05-mdflow/index.html#Context lands before the first token",
    "05-mdflow/index.html#A global specialist flow, printed in full",
    "05-mdflow/index.html#One launcher, isolation by default",
    "05-mdflow/index.html#Flows change by proposal, not by vibes",
    "learn.html#q2-markdown-flows"
  ],
  "collection": "factory",
  "categoryId": "execution",
  "wordCount": 1485,
  "url": "/topics/factory-markdown-flows/",
  "markdownUrl": "/markdown/factory-markdown-flows.md?raw=1&v=22ce5d34dbcb5a78",
  "jsonUrl": "/api/v1/documents/factory-markdown-flows.json",
  "headings": [
    {
      "id": "related-working-material",
      "text": "Related working material",
      "level": 2
    },
    {
      "id": "tl-dr",
      "text": "TL;DR",
      "level": 2
    },
    {
      "id": "the-briefing-you-keep-re-typing",
      "text": "The briefing you keep re-typing",
      "level": 2
    },
    {
      "id": "context-lands-before-the-first-token",
      "text": "Context lands before the first token",
      "level": 2
    },
    {
      "id": "a-global-specialist-flow-printed-in-full",
      "text": "A global specialist flow, printed in full",
      "level": 2
    },
    {
      "id": "one-launcher-isolation-by-default",
      "text": "One launcher, isolation by default",
      "level": 2
    },
    {
      "id": "flows-change-by-proposal-not-by-vibes",
      "text": "Flows change by proposal, not by vibes",
      "level": 2
    },
    {
      "id": "appendix",
      "text": "Appendix",
      "level": 2
    },
    {
      "id": "limits-caveats",
      "text": "Limits & caveats",
      "level": 3
    },
    {
      "id": "operating-practice",
      "text": "Operating practice",
      "level": 2
    },
    {
      "id": "turn-good-prompts-into-inspectable-flows",
      "text": "Turn good prompts into inspectable flows",
      "level": 3
    },
    {
      "id": "what-to-notice",
      "text": "What to notice",
      "level": 4
    },
    {
      "id": "try-this",
      "text": "Try this",
      "level": 4
    },
    {
      "id": "concept",
      "text": "Concept",
      "level": 4
    },
    {
      "id": "reflection",
      "text": "Reflection",
      "level": 4
    },
    {
      "id": "links-shared-for-this-topic",
      "text": "Links shared for this topic",
      "level": 4
    }
  ],
  "markdown": "# Markdown flows as a repeatable control surface\n\nPreload fresh evidence, declare capabilities, isolate ambient context, and improve prompts through explicit proposals.\n\n## Related working material\n\n- [Markdown flows as a repeatable control surface — prompts and exercises](/topics/factory-markdown-flows-practice/)\n- [Markdown flows as a repeatable control surface — questions and tradeoffs](/topics/factory-markdown-flows-questions/)\n- [Markdown flows as a repeatable control surface — worked example](/topics/factory-markdown-flows-worked-example/)\n\n## TL;DR\n\n- mdflow makes a repeatable agent job a versioned markdown \"flow\": shell output is inlined into the prompt at build time, so the agent starts already briefed on your git state, terminal panes, and tickets.\n- You walk away with a project roster (`npx mdflow init -y`) plus a pane-aware standup flow you can lift straight off this page.\n- The one move: the next briefing you type twice, put it in a flow file with `` !`command` `` inlines instead.\n\n Have your agent set this up — paste this into it:\n\n``` text\nFetch https://walnut-virtue-6d22.here.now/agent.md?raw and follow it to set this up in my current project. Run the success check at the end and show me the result.\n```\n\n## The briefing you keep re-typing\n\nEvery fresh agent chat starts blind. You re-explain the branch, the panes, the ticket — and next session you type it all again. That briefing isn't free: it costs your time, and the agent's context fills with ambient setup before work starts. mdflow's answer is one markdown file per repeatable job — a \"flow\" — kept in the repo, runnable on any installed engine, inspectable before it executes. The README states the thesis directly: a Git-native control plane for repeatable agent work. A chat session is a performance you repeat; a flow is a script you version.\n\n## Context lands before the first token\n\nA flow embeds shell output with a `` !`command` `` inline. mdflow runs the command while building the prompt, so the agent never spends a tool-call round trip on `git status` — and never skips or reorders it. The standup flow above preloads four commands this way; `md doctor --json` reports exactly those four as its declared capabilities.\n\nThe pattern scales past one-liners. A production flow on the author's machine runs a preload script that fetches workshop ticket buyers from the payment provider and current calendar attendees, prints the computed diff as markdown, and then tells the agent: this data was fetched moments ago — do not re-fetch. One detail worth stealing: the preload script exits 0 even on failure, printing a `PRELOAD ERROR` section instead, so the error lands inside the prompt and the agent can relay it and stop rather than dying silently.\n\nYour feedback loop is `md explain`: it resolves the full configuration and lists every inline as a capability without executing anything. If your command shows up in the list, the context will land.\n\n## A global specialist flow, printed in full\n\nSome jobs recur across every project: keyboard config, shell config. The author's machine has roughly sixty-five `flow-*` commands on PATH — `flow-git`, `flow-ffmpeg`, `flow-karabiner`, `flow-zsh` — each a globally installed specialist. Here is the installed `flow-zsh` file, complete. It is shown to study, not to paste — it maps one person's zsh setup — but the anatomy is the lesson: a mission, a tool-output trust boundary, a command map covering the whole config domain, worked examples, an error-recovery table, and a mutation policy that demands verification after every edit. The agent gets all of it on every single run.\n\nThe specialist pattern declares a mission, an untrusted-evidence boundary, a narrow inspection command map, ownership rules, worked examples, mutation approval, and exact verification. Keep the operating instructions project-specific rather than copying another machine’s private configuration.\n\nThe weak move is a monolithic \"dotfiles assistant\" that answers from memory. The strong move is one flow per domain, each opening with \"never answer from memory\" and a first-step inspection command. `flow-karabiner` encodes the same discipline for keyboard config: read, make the smallest edit, run the compiler, then grep the generated JSON to prove the mapping exists.\n\n## One launcher, isolation by default\n\nSixty-five global flows plus project rosters create a discovery problem. Bare `md` answers it: the Flow Workbench, one searchable list of everything runnable, each entry labeled with its provenance — `PROJECT`, `GLOBAL`, `INSTALLED`, or `PATH`.\n\nAnd every flow runs stripped by default. Your interactive session hauls memory files, hooks, MCP servers, and project instructions; a flow that reviews a diff needs none of it. mdflow disables ambient engine context using each engine's own flags — claude gets `--safe-mode --no-session-persistence`, codex gets `--ignore-user-config --ephemeral`, gemini `--extensions none`, copilot `--no-custom-instructions`. Anything the flow genuinely needs is declared in frontmatter; `_isolated: false` opts back into ambient. Isolation strips context — it does not confine the host. The inline commands and the engine still reach your filesystem, network, and credentials.\n\n``` text\n----------------------------------------------------------------------\nISOLATION\n----------------------------------------------------------------------\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```\n\nThat block is captured from `md explain flows/workshop-standup.claude.md` in this demo project — isolation is on without any frontmatter asking for it.\n\n## Flows change by proposal, not by vibes\n\nA flow edited by hand after a bad run regresses silently. mdflow's evolve loop replaces the tweak with a process: record feedback (it gets a durable `fb_…` ID), preview the eval cost, generate an off-path proposal, and read the verification receipt. The canonical file stays byte-identical until you explicitly apply.\n\n``` text\nmd feedback flows/review.md \"missed the renamed-file regression\"\nmd eval flows/review.md --plan     # free cost preview of the eval suite\nmd evolve plan flows/review.md     # free: evidence, verification, cost, writes\nmd evolve propose flows/review.md  # off-path proposal; source unchanged\nmd evolve show <run-id>            # decision, capability diff, prompt diff\nmd evolve apply <run-id>           # atomic, explicit, reversible\n```\n\nThe outcome vocabulary is deliberately honest: `verified_improvement` means a feedback-linked case failed on the old prompt and passed on the proposal; `regression_safe` means guardrails passed but the reported problem was not proven fixed; `rejected`, `inconclusive`, and `capability_rejected` cover the rest. When a flow disappoints, file feedback in the moment and let the suite — not your memory — decide whether the fix is real.\n\n## Appendix\n\n### Limits & caveats\n\n- **Isolation is not a sandbox.** Context isolation strips prompts, hooks, and extensions; it does not confine the host. Inline commands and the engine retain full filesystem, network, environment, and credential access. Engines with no isolation controls (droid, cursor-agent, agy) run ambient and warn rather than pretend.\n- **Eval verdicts in this demo are Unverified.** The starter suites exist, but no full eval receipt has been recorded, so `md doctor` reports every flow's verdict as `Unverified — no full eval receipt has been recorded`. The loop is the mechanism being demonstrated; this roster has not yet earned `verified_improvement` badges.\n- **Token savings are unquantified.** The sources support \"ambient material is not loaded\" and nothing more. No percentage is published; do not quote one.\n- **Engine defaults differ.** The starter roster defaults to the `pi` engine via `.mdflow.yaml`; the standup flow pins claude through its `.claude.md` filename. The same files run on other engines, but outputs are not interchangeable. Full resolution order: `--engine` flag → `MDFLOW_ENGINE` → filename → frontmatter `engine:` → project config → default (pi).\n- **The linear inline is a placeholder** in the public demo flow. The real version launches a sandboxed, read-only ticket-CLI agent; the placeholder keeps the published file runnable anywhere.\n- **Preloading captures state at launch.** It does not keep updating; a long-running agent that needs fresh state must still fetch it.\n\n## Operating practice\n\n### Turn good prompts into inspectable flows\n\n#### What to notice\n\nReuse a task recipe that can inject **fresh command output**, preserve **prompt structure**, and expose what the agent will receive.\n\n#### Try this\n\nPromote one prompt you have run twice into a flow with declared inputs and a dry-run inspection path.\n\n> “If you think of managing context as having only the context that I need for the specific task that I want.”\n\nJohn Lindquist · [02:55:29](https://proud-anchor-53zn.here.now/watch.html?t=10529#recording-player)\n\n#### Concept\n\nA flow should remove repeated composition work, not hide it. Inspect the rendered prompt, run from known state, and preserve failures when the wrapper or check does not behave as expected.\n\n#### Reflection\n\nThe recorded wrapper test did not become a clean success. The companion keeps that failure visible instead of rewriting history.\n\n**Recording evidence:** listen at 02:51:53.\n\n> “It's a pre-processing step, where it runs the code that's inside of here, which means it preloads context into the markdown file.”\n\nJohn Lindquist · [03:15:06](https://proud-anchor-53zn.here.now/watch.html?t=11706#recording-player)\n\n[Open mdflow](https://walnut-virtue-6d22.here.now/)\n\n#### Links shared for this topic\n\n- [Flow Text source](https://github.com/johnlindquist/flow-text/) — A repository for a reusable text-flow experiment.\n- [gog CLI](https://gogcli.sh/) — A command-line surface for Google services.\n- [Birdclaw](https://birdclaw.sh/) — A command-line social workflow tool.\n- [CodeGraph](https://colbymchenry.github.io/codegraph/) — A visual code-relationship explorer shown during workflow experiments.\n\n[Watch chapter](https://proud-anchor-53zn.here.now/watch.html?t=10313#q2-markdown-flows)"
}
