Agentic Software Factory · 2026-07-17 · mdflow section guide

Session Replay: the briefing becomes a flow

An annotated transcript of the session that built this section's demo project: scaffold the roster, turn a re-typed briefing into flows/workshop-standup.claude.md, audit it for free, run it once, and end with a flow captured from a session. Watch the beats, not the steps.

The session

You

Set up mdflow in this project. No engine calls — just the scaffold.

Agent
npx mdflow init -y

Twelve files landed, zero engine invocations:

.mdflow.yaml                # engine: pi, evolve mode: suggest
flows/README.md             # roster operator card
flows/review.md             + review.eval.ts
flows/changelog.md          + changelog.eval.ts
flows/pr-description.md     + pr-description.eval.ts
flows/onboard.md            + onboard.eval.ts
flows/fix-tests.md          + fix-tests.eval.ts

First beat is always the scaffold. init is deterministic — it never overwrites an existing roster, never calls an engine, and every starter flow arrives with a sibling eval suite on day one.

You

I open every session re-explaining the same three things: the branch, which panes are running, what ticket I'm on. Make that a flow — flows/workshop-standup.claude.md. Preload git status, the last five commits, a herdr pane snapshot, and a tickets line, then tell the agent to work only from what was preloaded.

Agent

Wrote the flow. The whole trick is in lines like these — !`command` inlines that mdflow executes while building the prompt, splicing their output in before the agent exists:

## Repo state (git)

!`git status --short --branch`

## Terminal workspace (herdr panes)

!`herdr api snapshot 2>/dev/null | head -40 || echo "(herdr not running)"`

The body opens by telling the agent the output was captured at prompt-build time, before it started, and must not be re-run. Complete file lands at the end of this replay.

The agent never spends a tool-call round trip on git status — and never skips or reorders it. Every inline is guarded (2>/dev/null || echo "…"), so a machine without herdr gets a placeholder line in the prompt instead of a failed run.

You

Before anything runs: prove exactly what this file will do.

Agent

Ran md explain flows/workshop-standup.claude.md — it resolves the full configuration and executes nothing. Captured output from this project (middle sections elided):

COMMAND
Resolved command: claude
Source: Filename pattern (.claude.md)

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

FINAL CLI ARGS
--print --safe-mode --no-session-persistence --model sonnet

TOKEN USAGE
Estimated tokens: 174
Context limit: 200,000
Usage: 0.1%

Two reveals in one audit. Engine: the .claude.md filename pinned claude — the full ladder is --engine flag → MDFLOW_ENGINE → filename → frontmatter → project config → default (pi). Isolation: ON without any frontmatter asking for it — no CLAUDE.md, hooks, or MCP leak in. (Context isolation, not a host sandbox — the inlines and the engine still reach your filesystem and network.)

You

Run it.

Agent
md flows/workshop-standup.claude.md

The standup printed with the agent already briefed: it named the branch and dirty files from the git inline, the visible panes from the herdr snapshot, and the ticket placeholder line — without making a single tool call. Everything rode in on the prompt.

The production version of this pattern goes further: a flow in ~/.mdflow/ runs a preload script that fetches workshop ticket buyers and calendar attendees, prints the computed diff as markdown, and tells the agent "fetched moments ago — do NOT re-fetch." The script exits 0 even on failure, printing a PRELOAD ERROR section instead, so the error lands inside the prompt and the agent relays it and stops.

You

Prove the project is still healthy.

Agent
md doctor --json | node -e 'const d=JSON.parse(require("fs").readFileSync(0,"utf8"));console.log("flows:",d.summary.flows,"structuralErrors:",d.summary.structuralErrors)'
flows: 6 structuralErrors: 0

md doctor is free and read-only. Its JSON also lists every flow's declared capabilities — the standup flow reports exactly its four inlined commands.

Eval verdicts in this project read Unverified — no full eval receipt has been recorded. That's a missing receipt, not an error; structuralErrors: 0 is the success signal here.

You

One more. The voting process that chose this page format — capture it as a flow so we never re-litigate it.

Agent

Done in a prior session: flows/this-or-that.md now lives at the workshop repo root, captured from the very session that picked this two-page format. It encodes the whole Elo round — frame the axis, scaffold the lab, generate structurally distinct options, QA, hand over, bank the results — and injects the accumulated taste record fresh on every run:

---
description: Run one this-or-that Elo voting round — generate structurally distinct options over a constant subject, stand up the duel harness, wait for votes, then bank the taste as explicit rules
_inputs: [_question, _subject]
_interactive: true
---
…
## Accumulated taste record (injected fresh each run — read before generating options)

@../authoring-lab/RESULTS.md

@../07-variations/template-lab/RESULTS.md

md explain flows/this-or-that.md is free and read-only if you want to audit it yourself.

Flows evolve, but never by vibes: when one disappoints, record md feedback (a durable fb_… ID), preview with md eval --plan, and let md evolve plan → propose → apply do the rest. The source file stays byte-identical until an explicit apply.

Agent

The file this session produced, complete:

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

You are a standup assistant. Everything below was captured at prompt-build
time, BEFORE you started — do not re-run these commands.

## Repo state (git)

!`git status --short --branch`

!`git log --oneline -5 2>/dev/null || echo "(no commits yet)"`

## Terminal workspace (herdr panes)

!`herdr api snapshot 2>/dev/null | head -40 || echo "(herdr not running)"`

## Open tickets (linear)

!`echo "(placeholder: linear 'list my in-progress issues' — sandboxed agent call)"`

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

File landed. Versioned, inspectable for free, isolated by default. Both this flow and this-or-that.md are downloadable attachments — the install block is on the section guide.

Total session: six prompts, one paid run. The pattern the transcript demonstrates — scaffold → preload → audit → run → verify → capture — repeats for every briefing you catch yourself typing twice.