---
schema_version: 1
revision: "22ce5d34dbcb5a78"
id: "factory-markdown-flows"
title: "Markdown flows as a repeatable control surface"
---

# Markdown flows as a repeatable control surface

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

## Related working material

- [Markdown flows as a repeatable control surface — prompts and exercises](/topics/factory-markdown-flows-practice/)
- [Markdown flows as a repeatable control surface — questions and tradeoffs](/topics/factory-markdown-flows-questions/)
- [Markdown flows as a repeatable control surface — worked example](/topics/factory-markdown-flows-worked-example/)

## 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:

``` text
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.

``` text
----------------------------------------------------------------------
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.

``` text
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](https://proud-anchor-53zn.here.now/watch.html?t=10529#recording-player)

#### 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](https://proud-anchor-53zn.here.now/watch.html?t=11706#recording-player)

[Open mdflow](https://walnut-virtue-6d22.here.now/)

#### Links shared for this topic

- [Flow Text source](https://github.com/johnlindquist/flow-text/) — A repository for a reusable text-flow experiment.
- [gog CLI](https://gogcli.sh/) — A command-line surface for Google services.
- [Birdclaw](https://birdclaw.sh/) — A command-line social workflow tool.
- [CodeGraph](https://colbymchenry.github.io/codegraph/) — A visual code-relationship explorer shown during workflow experiments.

[Watch chapter](https://proud-anchor-53zn.here.now/watch.html?t=10313#q2-markdown-flows)

## Original references

- [Markdown flows as a repeatable control surface](https://walnut-virtue-6d22.here.now/)
- [Companion lesson](https://proud-anchor-53zn.here.now/learn.html#q2-markdown-flows)
