Markdown flows as a repeatable control surface

Preload fresh evidence, declare capabilities, isolate ambient context, and improve prompts through explicit proposals.

Preload fresh evidence, declare capabilities, isolate ambient context, and improve prompts through explicit proposals.

TL;DR

  • 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.
  • You walk away with a project roster (npx mdflow init -y) plus a pane-aware standup flow you can lift straight off this page.
  • The one move: the next briefing you type twice, put it in a flow file with !`command` inlines instead.

Have your agent set this up — paste this into it:

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

The briefing you keep re-typing

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

Context lands before the first token

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

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

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

A global specialist flow, printed in full

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

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

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

One launcher, isolation by default

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

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

----------------------------------------------------------------------
ISOLATION
----------------------------------------------------------------------
ON (default) — ambient engine context is disabled; host capabilities
remain available
   safe-mode: true
   no-session-persistence: true
   (opt out with _isolated: false)

That block is captured from md explain flows/workshop-standup.claude.md in this demo project — isolation is on without any frontmatter asking for it.

Flows change by proposal, not by vibes

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

md feedback flows/review.md "missed the renamed-file regression"
md eval flows/review.md --plan     # free cost preview of the eval suite
md evolve plan flows/review.md     # free: evidence, verification, cost, writes
md evolve propose flows/review.md  # off-path proposal; source unchanged
md evolve show <run-id>            # decision, capability diff, prompt diff
md evolve apply <run-id>           # atomic, explicit, reversible

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

Appendix

Limits & caveats

  • 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.
  • 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.
  • Token savings are unquantified. The sources support "ambient material is not loaded" and nothing more. No percentage is published; do not quote one.
  • 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).
  • 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.
  • Preloading captures state at launch. It does not keep updating; a long-running agent that needs fresh state must still fetch it.

Operating practice

Turn good prompts into inspectable flows

What to notice

Reuse a task recipe that can inject fresh command output, preserve prompt structure, and expose what the agent will receive.

Try this

Promote one prompt you have run twice into a flow with declared inputs and a dry-run inspection path.

“If you think of managing context as having only the context that I need for the specific task that I want.”

John Lindquist · 02:55:29

Concept

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

Reflection

The recorded wrapper test did not become a clean success. The companion keeps that failure visible instead of rewriting history.

Recording evidence: listen at 02:51:53.

“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.”

John Lindquist · 03:15:06

Open mdflow

  • Flow Text source — A repository for a reusable text-flow experiment.
  • gog CLI — A command-line surface for Google services.
  • Birdclaw — A command-line social workflow tool.
  • CodeGraph — A visual code-relationship explorer shown during workflow experiments.

Watch chapter

Source references