Markdown flows as a repeatable control surface — reference patterns

Extended explanations, comparisons, experiments, and practical actions for the same operating pattern.

Extended explanations, comparisons, experiments, and practical actions for the same operating pattern.

Abstract

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

Notice what a blind agent session costs

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

mdflow'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

1. 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. ↩

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

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

Preload context, then verify it landed

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

---
description: pane-aware standup — agent starts already knowing git, panes, and tickets
model: sonnet
print: true
---

## Repo state (git)

!`git status --short --branch`

## Terminal workspace (herdr panes)

!`herdr api snapshot | head -40`

## Open tickets (linear)

!`(ticket CLI call — placeholder in the public demo)`

## Your job

From the preloaded context only:
1. Say what I'm in the middle of (branch, dirty files, visible panes).
2. Flag anything that looks stalled or contradictory.
3. Suggest the single next action, one sentence.

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.

The 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

2. 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. ↩

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

Explain what a global specialist flow carries

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

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.

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.

The 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

3. 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. ↩

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

Choose one launcher for every flow

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

Setting 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).

# In any repo:
npx mdflow init -y      # starter roster + .mdflow.yaml, no engine calls
md                      # Flow Workbench: one searchable launcher
md doctor --json        # free, read-only project diagnosis
md explain flows/review.md   # resolved config, nothing executed
md.claude "quick one-off question"   # ad-hoc, no file needed

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.

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.

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

Compare an ambient run with an isolated run

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

mdflow 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

4. 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. ↩

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

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.

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

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

Adjust a flow with feedback, not hand edits

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

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

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.

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

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.

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

Practical action

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

Source references