{
  "schemaVersion": "1",
  "revision": "22ce5d34dbcb5a78",
  "id": "factory-markdown-flows-reference-patterns",
  "slug": "markdown-flows-reference-patterns",
  "title": "Markdown flows as a repeatable control surface — reference patterns",
  "summary": "Extended explanations, comparisons, experiments, and practical actions for the same operating pattern.",
  "category": "Execution",
  "tags": [
    "markdown-flows",
    "reference",
    "examples"
  ],
  "sources": [
    {
      "label": "Prepared module reference",
      "url": "https://walnut-virtue-6d22.here.now/"
    }
  ],
  "sourceUnits": [
    "05-mdflow/folio/index.html#Abstract",
    "05-mdflow/folio/index.html#Notice what a blind agent session costs",
    "05-mdflow/folio/index.html#Preload context, then verify it landed",
    "05-mdflow/folio/index.html#Explain what a global specialist flow carries",
    "05-mdflow/folio/index.html#Choose one launcher for every flow",
    "05-mdflow/folio/index.html#Compare an ambient run with an isolated run",
    "05-mdflow/folio/index.html#Adjust a flow with feedback, not hand edits",
    "05-mdflow/folio/index.html#Practical action"
  ],
  "collection": "factory",
  "categoryId": "execution",
  "wordCount": 2053,
  "url": "/topics/factory-markdown-flows-reference-patterns/",
  "markdownUrl": "/markdown/factory-markdown-flows-reference-patterns.md?raw=1&v=22ce5d34dbcb5a78",
  "jsonUrl": "/api/v1/documents/factory-markdown-flows-reference-patterns.json",
  "headings": [
    {
      "id": "abstract",
      "text": "Abstract",
      "level": 2
    },
    {
      "id": "notice-what-a-blind-agent-session-costs",
      "text": "Notice what a blind agent session costs",
      "level": 2
    },
    {
      "id": "preload-context-then-verify-it-landed",
      "text": "Preload context, then verify it landed",
      "level": 2
    },
    {
      "id": "explain-what-a-global-specialist-flow-carries",
      "text": "Explain what a global specialist flow carries",
      "level": 2
    },
    {
      "id": "choose-one-launcher-for-every-flow",
      "text": "Choose one launcher for every flow",
      "level": 2
    },
    {
      "id": "compare-an-ambient-run-with-an-isolated-run",
      "text": "Compare an ambient run with an isolated run",
      "level": 2
    },
    {
      "id": "adjust-a-flow-with-feedback-not-hand-edits",
      "text": "Adjust a flow with feedback, not hand edits",
      "level": 2
    },
    {
      "id": "practical-action",
      "text": "Practical action",
      "level": 2
    }
  ],
  "markdown": "# Markdown flows as a repeatable control surface — reference patterns\n\nExtended explanations, comparisons, experiments, and practical actions for the same operating pattern.\n\n## Abstract\n\nEvery fresh agent chat starts blind. You re-explain the repo, the tickets, and the terminal state, and you pay context for config the task never needed. mdflow makes each repeatable job a markdown file: shell output is inlined before the agent's first token, ambient config is stripped by default, and prompt changes go through evals and reviewable proposals. These notes trace each claim to a file or captured command in the demo project. They do not claim benchmark results, and the demo project's own eval verdicts are still unverified.\n\n## Notice what a blind agent session costs\n\nYou open an agent, and the first minutes go to briefing: what branch you are on, which panes are running, which ticket this serves. Next session, you type it all again. The easy mistake is to treat that briefing as free. It is not. It costs your time, and the agent's context window fills with your ambient setup before work starts.\n\nmdflow's answer is one markdown file per repeatable job — a \"flow\" — kept in the repo, runnable on any installed engine, and inspectable before it executes (S1). [1](https://walnut-virtue-6d22.here.now/#note-1)\n\n1\\. The engine is environment, not ceremony. Resolution order from S1: `--engine` flag, then `MDFLOW_ENGINE`, then the filename (`review.claude.md`), then frontmatter `engine:`, then project config, then the built-in default, pi. [↩](https://walnut-virtue-6d22.here.now/#note-ref-1)\n\nThe project README states the thesis directly: mdflow is \"a Git-native control plane for repeatable agent work\" — define the job as markdown, run it, inspect its inputs, and gate prompt revisions with behavioral evals (S1).\n\nThe contrast to hold on to: a chat session is a performance you repeat; a flow is a script you version. When you catch yourself typing the same briefing twice, that job wants to be a file. The rest of these notes show what the file buys you: preloaded context, isolation, and a change process with receipts.\n\n## Preload context, then verify it landed\n\nA flow can embed shell output in its prompt with a `` !`command` `` inline. mdflow runs the command at prompt-build time, so the agent's very first token arrives with the results already in front of it. The likely mistake is to instead tell the agent \"run git status first\" — now you pay a tool-call round trip, and the agent may skip or reorder it. Preloading removes that choice.\n\n``` text\n---\ndescription: pane-aware standup — agent starts already knowing git, panes, and tickets\nmodel: sonnet\nprint: true\n---\n\n## Repo state (git)\n\n!`git status --short --branch`\n\n## Terminal workspace (herdr panes)\n\n!`herdr api snapshot | head -40`\n\n## Open tickets (linear)\n\n!`(ticket CLI call — placeholder in the public demo)`\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\n**Figure 1.** The demo project's `flows/workshop-standup.claude.md`, lightly condensed (S5). Source evidence, not a mock-up: `git status`, a terminal-pane snapshot, and a ticket lookup all run before the agent starts, so it \"knows about all the panes\" at token one.\n\nThe same pattern scales past one-liners. A production flow on this 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: the data below was fetched moments ago — do not re-fetch (S6). [2](https://walnut-virtue-6d22.here.now/#note-2)\n\n2\\. A detail worth stealing from S6: the preload script exits 0 even on failure, printing a `PRELOAD ERROR` section instead. The error lands inside the prompt, so the agent can relay it and stop, rather than the flow dying silently. [↩](https://walnut-virtue-6d22.here.now/#note-ref-2)\n\nYour test loop: write the inline, then run `md explain flows/your-flow.md`. Explain resolves the full configuration and lists every inline as a declared capability — without executing anything. If the capability list shows your command, the context will land. In this project, `md doctor --json` reports the standup flow's capabilities as exactly the four inlined commands (S5). That is the feedback signal; if a command is missing, fix the backticks and re-check. The boundary: preloading captures state at launch. It does not keep updating — a long-running agent that needs fresh state must still fetch it.\n\n## Explain what a global specialist flow carries\n\nSome jobs recur across every project: keyboard config, shell config. On this machine, roughly sixty-five `flow-*` commands sit on PATH — `flow-git`, `flow-ffmpeg`, `flow-karabiner`, `flow-zsh`, and more — each a globally installed specialist flow (S4). You should be able to explain why these beat a generic assistant, because the reason is the whole design.\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\n**Figure 2.** Condensed frontmatter of the installed `flow-zsh` flow (S4). Derived display: excerpted and abridged from the real file; ellipses mark removed sections. The full file maps the entire modular zsh config — owner modules, lazy stubs, tests — into a command map the agent gets every single run.\n\nThe specialist's edge is not a smarter model — it is that the whole config domain is preloaded as navigable structure, plus a mission, a tool-output trust boundary, and a mutation policy that demands verification after every edit (S4). [3](https://walnut-virtue-6d22.here.now/#note-3)\n\n3\\. `flow-karabiner`'s mutation policy in S4: read the config, make the smallest edit, run the compiler (`goku`), then grep the generated JSON to prove the mapping exists. Edit, compile, verify — encoded in the prompt itself. [↩](https://walnut-virtue-6d22.here.now/#note-ref-3)\n\nThe weak move is a monolithic \"dotfiles assistant\" that knows a little about everything and answers from memory. The strong move is one flow per domain, each opening with \"never answer from memory\" and a first-step inspection command (S4). When you can explain that distinction — domain map in the prompt, evidence before answers, verification after edits — you can write your own specialist. The evidence stops here, though: these files show the design, not measured accuracy gains.\n\n## Choose one launcher for every flow\n\nSixty-five global flows plus project rosters create a discovery problem: which flows exist here, and which can you trust? Bare `md` answers it. It opens the Flow Workbench — one searchable list of project flows, global flows, registry installs, and runnable markdown found on PATH, each labeled with its provenance: `PROJECT`, `GLOBAL`, `INSTALLED`, or `PATH` (S1).\n\nSetting up a new project is one deterministic command. `npx mdflow init` creates a starter `flows/` roster and `.mdflow.yaml` with zero engine invocations, and repeat runs leave an existing roster untouched (S1). This demo project ran exactly that: twelve files, five starter flows, each with a sibling eval suite (S5).\n\n``` text\n# In any repo:\nnpx mdflow init -y      # starter roster + .mdflow.yaml, no engine calls\nmd                      # Flow Workbench: one searchable launcher\nmd doctor --json        # free, read-only project diagnosis\nmd explain flows/review.md   # resolved config, nothing executed\nmd.claude \"quick one-off question\"   # ad-hoc, no file needed\n```\n\n**Figure 3.** The adoption path, assembled from commands documented in S1/S7 and executed in this project (S5). Derived display: sequence chosen editorially; every command exists verbatim in `md --help`.\n\n**Engine default** The starter roster's flows default to the **pi** engine via `.mdflow.yaml`; the demo's standup flow pins claude through its filename instead (S5). If you demo with a different engine installed, the same files run — but do not present pi output and claude output as interchangeable.\n\nYour choice rule: reach for bare `md` when you want to find or run existing work; reach for `md create` or `init` when a briefing repeats and no flow exists yet. The signal that the setup worked is `md doctor --json` reporting your flows with zero structural errors — this project's captured run reports six flows, zero structural errors (S5).\n\n## Compare an ambient run with an isolated run\n\nYour interactive agent session hauls everything you have configured: memory files, hooks, MCP servers, skill lists, project instructions. A flow that reviews a diff needs none of it. The mistake is assuming that ambient baggage is harmless; it spends context on every run and can steer the agent off the declared task.\n\nmdflow strips ambient engine context by default, using each engine's own verified flags — claude runs with `--safe-mode --no-session-persistence`, codex with `--ignore-user-config --ephemeral` plus a zeroed project-doc budget, gemini with `--extensions none`, copilot with `--no-custom-instructions` (S1). [4](https://walnut-virtue-6d22.here.now/#note-4)\n\n4\\. Anything the flow genuinely needs — a skill, an MCP server, extra context — is declared explicitly in frontmatter, and `_isolated: false` opts back into ambient. Explicit beats implicit either way. [↩](https://walnut-virtue-6d22.here.now/#note-ref-4)\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\n**Figure 4.** Captured output of `md explain flows/workshop-standup.claude.md` in this project (S5). Source evidence: isolation is on without any frontmatter asking for it.\n\n**Isolation is not a sandbox** Context isolation strips prompts, hooks, and extensions — it does **not** confine the host. The flow's inline commands and the engine still reach your filesystem, network, environment, and credentials (S1). And engines with no isolation controls (droid, cursor-agent, agy) run ambient and warn rather than pretend (S1).\n\nRun the comparison yourself: `md explain` any flow and read the ISOLATION block, then run the same job in your normal interactive session and watch what extra material loads. The isolated run's prompt is exactly what the file declares — that is the point. Claims about token savings stop at \"ambient material is not loaded\"; the sources publish no percentage, so do not quote one.\n\n## Adjust a flow with feedback, not hand edits\n\nA flow that never changes goes stale; a flow edited by vibes regresses silently. The tempting shortcut is to tweak the prompt in place after a bad run and move on. mdflow's evolve loop replaces that with a proposal process that leaves the canonical file byte-identical until you explicitly apply a change (S2).\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\n**Figure 5.** The evolve loop, quoted from the evolve documentation's quick start (S2). Source evidence: feedback gets a durable `fb_…` ID; rejected attempts do not consume the underlying problem.\n\nThe outcome vocabulary is deliberately honest. `verified_improvement` means a feedback-linked case failed on the current prompt and passed on the proposal with clean guardrails; `regression_safe` means guardrails passed but the reported problem was not proven fixed; `rejected`, `inconclusive`, and `capability_rejected` cover the rest (S2).\n\n**Unverified in this demo** Every flow in this demo project currently reports the eval verdict **Unverified** — the suites exist, but no full eval receipt has been recorded yet (S5). Present the loop as the mechanism it is; do not imply this roster has already earned `verified_improvement` badges.\n\nYour adjustment habit: when a flow disappoints, file `md feedback` in the moment — it is free and durable — and let the eval suite, not your memory, decide whether a proposal actually fixed it. The observable signal is the outcome word on the proposal. If it says `regression_safe`, treat the fix as unproven and keep the feedback open.\n\n## Practical action\n\nIn the repo where you brief agents most often, run `npx mdflow init -y`, then `md doctor --json` to confirm the roster parses with zero structural errors. Take the one briefing you typed twice this week and make it a flow: put the explanation in the body and the state-gathering in `` !`command` `` inlines. Check your work with `md explain` — the ISOLATION block should read ON and the capability list should name every inline. When the flow first disappoints, do not hand-edit: file `md feedback`, then walk the evolve loop and read the outcome word before trusting the change. If your team should discover flows too, opt in explicitly with `md roster sync --agents`."
}
