{
  "schemaVersion": "1",
  "revision": "22ce5d34dbcb5a78",
  "id": "factory-markdown-flows-questions",
  "slug": "markdown-flows-questions",
  "title": "Markdown flows as a repeatable control surface — questions and tradeoffs",
  "summary": "Detailed questions and tradeoffs with concrete prompts, observable outcomes, and the limits of the example.",
  "category": "Execution",
  "tags": [
    "markdown-flows",
    "questions"
  ],
  "sources": [
    {
      "label": "Markdown flows as a repeatable control surface — questions and tradeoffs",
      "url": "https://walnut-virtue-6d22.here.now/dialogue.html"
    }
  ],
  "sourceUnits": [
    "05-mdflow/dialogue.html#The Q&A"
  ],
  "collection": "factory",
  "categoryId": "execution",
  "wordCount": 940,
  "url": "/topics/factory-markdown-flows-questions/",
  "markdownUrl": "/markdown/factory-markdown-flows-questions.md?raw=1&v=22ce5d34dbcb5a78",
  "jsonUrl": "/api/v1/documents/factory-markdown-flows-questions.json",
  "headings": [
    {
      "id": "the-q-a",
      "text": "The Q&A",
      "level": 2
    }
  ],
  "markdown": "# Markdown flows as a repeatable control surface — questions and tradeoffs\n\nDetailed questions and tradeoffs with concrete prompts, observable outcomes, and the limits of the example.\n\n## The Q&A\n\nIsn't a flow just a saved prompt?\n\nA saved prompt is frozen text. A flow executes while the prompt is being *built*: every `` !`command` `` inline runs at prompt-build time and its output is spliced in, so the agent's first token arrives already knowing your branch, your terminal panes, your tickets. Here is the one this section's demo actually runs — lift it:\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\nAnd it's a file in your repo — versioned, diffable, reviewable like any other code. This flow is also a downloadable attachment — the install block is on the [section guide](https://walnut-virtue-6d22.here.now/index.html#attachments-install-these-flows).\n\nWhy preload? My agent can run `git status` itself.\n\nIt can — for a tool-call round trip, and only if it decides to. Preloading makes the briefing deterministic: never skipped, never reordered, already in the prompt. The production version of this pattern runs a preload script that fetches workshop ticket buyers and current calendar attendees, prints the computed diff as markdown, and then tells the agent: fetched moments ago — do *not* re-fetch. One detail worth stealing: the script exits 0 even on failure and prints a `PRELOAD ERROR` section instead, so the error lands inside the prompt and the agent relays it and stops rather than dying silently.\n\nI've spent months on my CLAUDE.md, hooks, and MCP servers. A flow throws all that away?\n\nDeliberately — by default. A flow that summarizes a standup doesn't need your memory files, plugin lists, or MCP servers; hauling them in costs context and blurs focus. mdflow strips ambient config using each engine's own flags — claude gets `--safe-mode --no-session-persistence`, codex `--ignore-user-config --ephemeral`, gemini `--extensions none`, copilot `--no-custom-instructions`. Captured from this very project:\n\n``` text\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```\n\nAnything a flow genuinely needs, it declares in frontmatter; `_isolated: false` opts back into ambient. Straight caveat: this strips *context*, it is not a host sandbox — the inline commands and the engine still reach your filesystem, network, and credentials.\n\nWhat does a run cost me before I've even seen what it will do?\n\nNothing to look. The two audit commands are free and execute no engine, no inline, no hook:\n\n``` text\nmd explain flows/workshop-standup.claude.md   # engine + why, isolation, every inline, token estimate\nmd doctor --json                              # whole-project diagnosis, read-only\n```\n\n`md explain` on the standup flow reports which engine won and why (the `.claude.md` filename), every prompt-build command as a declared capability, and an estimated 174 tokens — 0.1% of the context window. If your command shows up in the capability list, the context will land.\n\nSixty flows later, how do I find anything?\n\nBare `md`. It opens the Flow Workbench: one searchable list of everything runnable, each entry labeled with its provenance — `PROJECT`, `GLOBAL`, `INSTALLED`, or `PATH`. My machine has roughly sixty-five `flow-*` commands on PATH — `flow-git`, `flow-ffmpeg`, `flow-karabiner`, `flow-zsh` — each a globally installed specialist that preloads its *entire* config domain plus a mission, trust boundary, and mutation policy on every single run. The installed `flow-zsh` file is printed complete on the [section guide](https://walnut-virtue-6d22.here.now/index.html) — study its anatomy, don't paste it.\n\nA flow gives a bad answer — I just edit the file, right?\n\nThat's how flows regress silently. Instead, record the failure and let the eval suite — not your memory — decide whether a fix is real:\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 canonical file stays byte-identical until an explicit apply, and the outcome vocabulary is honest: `verified_improvement` means a feedback-linked case failed on the old prompt and passed on the new one; `regression_safe` means guardrails held but your reported problem wasn't proven fixed.\n\nDo you actually work this way, or is this a workshop demo?\n\nThis repo answers that itself. The Elo-voting process that chose the very format of this page was captured as a flow — `flows/this-or-that.md` at the workshop repo root, written from that session the day before the workshop. It encodes the whole round (frame the axis, scaffold the duel harness, generate distinct options, bank the taste rules) and re-injects the accumulated vote record fresh on every run via `@`-includes. Auditing it is free: `md explain flows/this-or-that.md`. In prior sessions the same week, a Stripe-to-calendar sync workflow became a flow the same way. Flows aren't the demo — they're how the demo got made."
}
