{
  "schemaVersion": "1",
  "revision": "22ce5d34dbcb5a78",
  "id": "factory-markdown-flows-practice",
  "slug": "markdown-flows-practice",
  "title": "Markdown flows as a repeatable control surface — prompts and exercises",
  "summary": "Complete reusable prompts, setup recipes, success checks, and caveats for markdown flows as a repeatable control surface.",
  "category": "Execution",
  "tags": [
    "prompts",
    "exercises",
    "markdown-flows"
  ],
  "sources": [
    {
      "label": "Markdown flows as a repeatable control surface",
      "url": "https://walnut-virtue-6d22.here.now/"
    },
    {
      "label": "Public setup contract",
      "url": "https://walnut-virtue-6d22.here.now/agent.md"
    }
  ],
  "sourceUnits": [
    "05-mdflow/index.html#Quick start",
    "05-mdflow/index.html#Prompt library",
    "05-mdflow/index.html#Set it up (agent guide)",
    "05-mdflow/index.html#Attachments — install these flows",
    "05-mdflow/index.html#Turn a repeated briefing into a flow",
    "05-mdflow/index.html#Audit a flow before you run it",
    "05-mdflow/index.html#Walk the evolve loop instead of hand-editing",
    "05-mdflow/index.html#Prefer skills? Every flow has a skill twin",
    "05-mdflow/agent.md"
  ],
  "collection": "factory",
  "categoryId": "execution",
  "wordCount": 2143,
  "url": "/topics/factory-markdown-flows-practice/",
  "markdownUrl": "/markdown/factory-markdown-flows-practice.md?raw=1&v=22ce5d34dbcb5a78",
  "jsonUrl": "/api/v1/documents/factory-markdown-flows-practice.json",
  "headings": [
    {
      "id": "quick-start",
      "text": "Quick start",
      "level": 2
    },
    {
      "id": "prompt-library",
      "text": "Prompt library",
      "level": 2
    },
    {
      "id": "turn-a-repeated-briefing-into-a-flow",
      "text": "Turn a repeated briefing into a flow",
      "level": 3
    },
    {
      "id": "audit-a-flow-before-you-run-it",
      "text": "Audit a flow before you run it",
      "level": 3
    },
    {
      "id": "walk-the-evolve-loop-instead-of-hand-editing",
      "text": "Walk the evolve loop instead of hand-editing",
      "level": 3
    },
    {
      "id": "set-it-up-agent-guide",
      "text": "Set it up (agent guide)",
      "level": 2
    },
    {
      "id": "attachments-install-these-flows",
      "text": "Attachments — install these flows",
      "level": 2
    },
    {
      "id": "prefer-skills-every-flow-has-a-skill-twin",
      "text": "Prefer skills? Every flow has a skill twin",
      "level": 2
    },
    {
      "id": "complete-reusable-setup-contract",
      "text": "Complete reusable setup contract",
      "level": 2
    },
    {
      "id": "mdflow-markdown-flows-as-an-agent-control-plane-agent-setup-guide",
      "text": "mdflow: markdown flows as an agent control plane — agent setup guide",
      "level": 2
    },
    {
      "id": "prerequisites",
      "text": "Prerequisites",
      "level": 2
    },
    {
      "id": "steps",
      "text": "Steps",
      "level": 2
    },
    {
      "id": "success-check",
      "text": "Success check",
      "level": 2
    },
    {
      "id": "flow-attachments-raw-downloads",
      "text": "Flow attachments (raw downloads)",
      "level": 2
    },
    {
      "id": "skill-twins-if-the-user-prefers-agent-skills-over-flows",
      "text": "Skill twins (if the user prefers agent skills over flows)",
      "level": 2
    },
    {
      "id": "notes-for-agents",
      "text": "Notes for agents",
      "level": 2
    }
  ],
  "markdown": "# Markdown flows as a repeatable control surface — prompts and exercises\n\nComplete reusable prompts, setup recipes, success checks, and caveats for markdown flows as a repeatable control surface.\n\n## Quick start\n\n``` text\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 + capabilities, nothing executed\nmd flows/review.md                   # run a flow (stage a change first)\nmd.claude \"quick one-off question\"   # ad-hoc, no file needed\n```\n\n## Prompt library\n\n### Turn a repeated briefing into a flow\n\n- Agent: Claude Code (or any coding agent)\n- Working directory: your project root, after `npx mdflow init -y`\n- Expected result: a new flow whose `md explain` lists every inline as a capability\n\n``` text\nI keep re-typing the same briefing at the start of agent sessions. Turn it into an mdflow flow. Create flows/standup.claude.md: frontmatter with a one-line description, then a body that preloads live state with !`command` inlines (git status --short --branch, git log --oneline -5, plus any command I name below), then a short instruction section telling the agent to work only from the preloaded context. Tell the agent the output was captured at prompt-build time so it must not re-run the commands. Then run `md explain flows/standup.claude.md` and confirm ISOLATION reads ON and every inline appears as a command capability. Briefing to encode: <describe your repeated briefing here>\n```\n\n### Audit a flow before you run it\n\n- Agent: any coding agent\n- Working directory: a repo containing `flows/`\n- Expected result: engine, isolation state, every prompt-build command, token estimate\n\n``` text\nAudit an mdflow flow before I run it. Run `md doctor --json` and `md explain <flow path>` (both are free and execute nothing). Report: which engine the flow resolves to and why (flag, env var, filename, frontmatter, config, or default); whether ISOLATION is ON; every command capability that will execute at prompt-build time; and the estimated token usage. Flag any capability that reaches the network or mutates files. Flow to audit: <path>\n```\n\n### Walk the evolve loop instead of hand-editing\n\n- Agent: any coding agent\n- Working directory: a repo where a flow just disappointed you\n- Expected result: an off-path proposal with an outcome word; the flow file untouched until apply\n\n``` text\nA flow just gave a bad result. Do NOT edit the flow file. Instead: 1) Record it with `md feedback <flow path> \"<what went wrong>\"` and show me the durable fb_ id. 2) Run `md eval <flow path> --plan` and `md evolve plan <flow path>` (both free) and summarize the evidence, verification plan, and cost. 3) Only if I say go: run `md evolve propose <flow path>`, then `md evolve show <run-id>`, and report the outcome word (verified_improvement, regression_safe, rejected, inconclusive, or capability_rejected) plus the prompt diff. Never run `md evolve apply` without my explicit approval. Flow: <path>. What went wrong: <describe>\n```\n\n## Set it up (agent guide)\n\n1.  From your project root, scaffold the roster. This writes `.mdflow.yaml` and five starter flows, each with a sibling eval suite, and invokes no engine:\n\n    ``` text\n    npx mdflow init -y\n    ```\n\n2.  Create the standup flow. This is the whole trick: the `` !`command` `` inlines run at prompt-build time, so the agent's first token arrives with git state, terminal panes, and tickets already in front of it.\n\n    ``` text\n    ---\n    description: pane-aware standup — agent starts already knowing git, panes, and tickets\n    model: sonnet\n    print: true\n    ---\n\n    You are a standup assistant. Everything below was captured at prompt-build\n    time, BEFORE you started — do not re-run these commands.\n\n    ## Repo state (git)\n\n    !`git status --short --branch`\n\n    !`git log --oneline -5 2>/dev/null || echo \"(no commits yet)\"`\n\n    ## Terminal workspace (herdr panes)\n\n    !`herdr api snapshot 2>/dev/null | head -40 || echo \"(herdr not running)\"`\n\n    ## Open tickets (linear)\n\n    !`echo \"(placeholder: linear 'list my in-progress issues' — sandboxed agent call)\"`\n\n    ## Your job\n\n    From the preloaded context only:\n    1. Say what I'm in the middle of (branch, dirty files, visible panes).\n    2. Flag anything that looks stalled or contradictory.\n    3. Suggest the single next action, one sentence.\n    ```\n\n3.  Inspect it without executing anything, then run it:\n\n    ``` text\n    md explain flows/workshop-standup.claude.md   # expect ISOLATION: ON (default)\n    md flows/workshop-standup.claude.md           # prints your standup\n    ```\n\n**Success check:** the project parses cleanly with all six flows registered.\n\n``` text\nmd doctor --json | node -e 'const d=JSON.parse(require(\"fs\").readFileSync(0,\"utf8\"));console.log(\"flows:\",d.summary.flows,\"structuralErrors:\",d.summary.structuralErrors)'\n```\n\n``` text\nflows: 6 structuralErrors: 0\n```\n\nFallback: if `structuralErrors` is non-zero, check whether the errors are `CONFIG_INVALID` from a pre-existing global `~/.mdflow/config.yaml` rather than from the flows — an invalid global config fails this check even when every flow is clean. Verify per-flow with `md explain flows/<name>.md` instead.\n\n## Attachments — install these flows\n\nBoth flows discussed on these pages are hosted on this site as raw markdown attachments. `md install` pulls a remote flow straight into your project's registry (npx-style; first use asks you to trust the domain). Reversible with `md remove <name>`; list what you have with `md list`.\n\nThe pane-aware standup flow (this section's money artifact):\n\n``` text\nmd install \"https://walnut-virtue-6d22.here.now/flows/workshop-standup.claude.md?raw\"\n```\n\nThe captured this-or-that Elo voting loop (the flow from the [Session Replay](https://walnut-virtue-6d22.here.now/replay.html)'s final beat):\n\n``` text\nmd install \"https://walnut-virtue-6d22.here.now/flows/this-or-that.md?raw\"\n```\n\nPrefer plain files in `flows/`? Fetch the raw attachments directly:\n\n``` text\nmkdir -p flows\ncurl -fsSL \"https://walnut-virtue-6d22.here.now/flows/workshop-standup.claude.md?raw\" -o flows/workshop-standup.claude.md\ncurl -fsSL \"https://walnut-virtue-6d22.here.now/flows/this-or-that.md?raw\" -o flows/this-or-that.md\n```\n\nNote: `this-or-that.md` injects taste records via `@../…/RESULTS.md` includes that exist in the workshop repo — outside it, point those includes at your own vote records. Audit either flow for free with `md explain`.\n\n## Prefer skills? Every flow has a skill twin\n\nIf your stack runs on [agent skills](https://www.skills.sh/) rather than mdflow, every flow on these pages is also hosted here as a `SKILL.md` twin under `/skills/` — same job, no mdflow required. The trade is the section's own lesson in reverse: a flow preloads shell output at prompt-build time and runs isolated from ambient config; the skill twin has the agent run those commands itself inside your normal session. Six twins are hosted here — `workshop-standup`, `review`, `changelog`, `fix-tests`, `onboard`, `pr-description`. Stage them anywhere *except* a dir named `skills/` (the skills CLI claims that name as its own symlink target and you'd install an empty skill):\n\n``` text\nfor s in workshop-standup review changelog fix-tests onboard pr-description; do\n  mkdir -p skill-src/$s\n  curl -fsSL \"https://walnut-virtue-6d22.here.now/skills/$s/SKILL.md?raw\" -o skill-src/$s/SKILL.md\n  npx skills add ./skill-src --skill $s -y\ndone\n```\n\nTrim the list to just the names you want. The this-or-that loop's skill twin lives on [the This-or-That section site](https://gentle-lasso-9d5n.here.now/).\n\n## Complete reusable setup contract\n\n## mdflow: markdown flows as an agent control plane — agent setup guide\n\nFollowing this file sets up: mdflow in the current project — a starter flow roster plus one context-preloading \"standup\" flow that briefs the agent with `git status`, recent commits, terminal panes, and tickets before its first token.\n\nHuman companion pages (context for you, reading for your user): the [Session Replay](https://walnut-virtue-6d22.here.now/replay.html) — an annotated transcript of the session that built this exact setup — and the [Dialogue](https://walnut-virtue-6d22.here.now/dialogue.html) — skeptical Q&A about why flows work this way. This file remains the canonical machine copy: execute it top-to-bottom.\n\nPlaceholders used below: `<project-root>` = the project you are working in. All other paths are literal and relative to `<project-root>`.\n\n## Prerequisites\n\nCheck each before starting:\n\n```bash\nnode --version\nnpx mdflow help | head -4\nclaude --version\n```\n\nExpected: Node 18+; the mdflow usage banner (`Usage: md <file.md> ...`); any Claude Code version string. If `npx mdflow` fails, stop and tell your user to check their network/npm setup. If `claude` is missing, see Notes for agents — the flow can run on another engine.\n\n## Steps\n\n1. From `<project-root>`, scaffold the roster. This writes `.mdflow.yaml` and five starter flows (each with a sibling `.eval.ts` suite) and invokes no engine:\n\n   ```bash\n   npx mdflow init -y\n   ```\n\n2. Create `flows/workshop-standup.claude.md` with exactly this content. The `` !`command` `` inlines run at prompt-build time — mdflow executes them and splices the output into the prompt before the agent starts:\n\n   ```markdown\n   ---\n   description: pane-aware standup — agent starts already knowing git, panes, and tickets\n   model: sonnet\n   print: true\n   ---\n\n   You are a standup assistant. Everything below was captured at prompt-build\n   time, BEFORE you started — do not re-run these commands.\n\n   ## Repo state (git)\n\n   !`git status --short --branch`\n\n   !`git log --oneline -5 2>/dev/null || echo \"(no commits yet)\"`\n\n   ## Terminal workspace (herdr panes)\n\n   !`herdr api snapshot 2>/dev/null | head -40 || echo \"(herdr not running)\"`\n\n   ## Open tickets (linear)\n\n   !`echo \"(placeholder: linear 'list my in-progress issues' — sandboxed agent call)\"`\n\n   ## Your job\n\n   From the preloaded context only:\n   1. Say what I'm in the middle of (branch, dirty files, visible panes).\n   2. Flag anything that looks stalled or contradictory.\n   3. Suggest the single next action, one sentence.\n   ```\n\n3. Inspect the flow without executing anything. Confirm ISOLATION reads `ON (default)` and the FINAL PROMPT section shows all four inlined commands (there is no separate capability section in `md explain`; per-flow capability lists live in `md doctor --json`):\n\n   ```bash\n   md explain flows/workshop-standup.claude.md\n   ```\n\n4. Run the flow. It prints a standup summary built only from the preloaded context:\n\n   ```bash\n   md flows/workshop-standup.claude.md\n   ```\n\n## Success check\n\nRun:\n\n```bash\nmd doctor --json | node -e 'const d=JSON.parse(require(\"fs\").readFileSync(0,\"utf8\"));console.log(\"flows:\",d.summary.flows,\"structuralErrors:\",d.summary.structuralErrors)'\n```\n\nExpected observable result: `flows: 6 structuralErrors: 0` — five starter flows plus the standup flow, all parsing cleanly. (`md doctor` is free and read-only.)\n\nFallback: if `structuralErrors` is non-zero, check the report's `diagnostics` before assuming the flows are broken — a pre-existing invalid global `~/.mdflow/config.yaml` surfaces here as a `CONFIG_INVALID` error even when every flow is clean. In that case verify per-flow with `md explain flows/<name>.md`: if each flow explains cleanly, the flows are fine and only the global config needs fixing.\n\nReport to your user: what you set up, the success-check output, and anything you had to adapt.\n\n## Flow attachments (raw downloads)\n\nBoth flows discussed on the site are hosted here as raw markdown attachments. Machine-fetch URLs (the `?raw` suffix is required — the bare `.md` URL serves an HTML viewer):\n\n- `https://walnut-virtue-6d22.here.now/flows/workshop-standup.claude.md?raw` — the pane-aware standup flow from Step 2 (identical content; fetching it is an alternative to writing the file by hand).\n- `https://walnut-virtue-6d22.here.now/flows/this-or-that.md?raw` — the captured this-or-that Elo voting loop flow. Its `@../…/RESULTS.md` includes reference the workshop repo's vote records; outside that repo, repoint them at your user's own records before running.\n\nInstead of writing Step 2's file manually you may run, from `<project-root>`:\n\n```bash\nmkdir -p flows\ncurl -fsSL \"https://walnut-virtue-6d22.here.now/flows/workshop-standup.claude.md?raw\" -o flows/workshop-standup.claude.md\n```\n\n`md install \"<url>?raw\"` also works and registers the flow in the project registry instead of `flows/` (reversible with `md remove <name>`).\n\n## Skill twins (if the user prefers agent skills over flows)\n\nEvery flow discussed on the site also ships as a skills.sh-format `SKILL.md` twin hosted under `/skills/` — same job, no mdflow required. The difference: a flow preloads shell output at prompt-build time and runs isolated; the skill twin instructs the agent to run those commands itself in the normal session. Available names: `workshop-standup`, `review`, `changelog`, `fix-tests`, `onboard`, `pr-description` (the this-or-that twin is hosted at `https://gentle-lasso-9d5n.here.now/skills/this-or-that/SKILL.md?raw`). Machine-fetch URL pattern (`?raw` required): `https://walnut-virtue-6d22.here.now/skills/<name>/SKILL.md?raw`.\n\nTo install for your user (stage anywhere EXCEPT a dir named `skills/` — the skills CLI claims that name and you'd install an empty skill):\n\n```bash\nfor s in workshop-standup review changelog fix-tests onboard pr-description; do\n  mkdir -p skill-src/$s\n  curl -fsSL \"https://walnut-virtue-6d22.here.now/skills/$s/SKILL.md?raw\" -o skill-src/$s/SKILL.md\n  npx skills add ./skill-src --skill $s -y\ndone\n```\n\nTrim the loop to the names the user wants. Only install skills when the user prefers them over flows — the flows remain the primary artifact of this section.\n\n## Notes for agents\n\n- If `md` is not on PATH, substitute `npx mdflow` for `md` in every command above (`md setup` configures PATH and aliases for the user's shell).\n- The flow degrades gracefully by design: the `herdr` and `linear` inlines are guarded with `2>/dev/null || echo \"...\"`, so machines without those tools get placeholder lines in the prompt instead of a failed run.\n- The `.claude.md` filename pins the claude engine. If the `claude` CLI is not installed, name the file `flows/workshop-standup.md` instead — it will use the project default engine from `.mdflow.yaml` (`pi`). Check `engines.installed` in `md doctor --json` to see what is available.\n- In a directory with no git repo, the git inlines print an error/placeholder line into the prompt. The flow still runs; the standup will just say so.\n- Eval verdicts in `md doctor --json` read `Unverified` until a full eval receipt is recorded. That is a missing receipt, not an error — `structuralErrors: 0` is the success signal here.\n- Re-running `npx mdflow init -y` leaves an existing roster untouched; it is safe in a project that already has `flows/`."
}
