mdflow: markdown flows as an agent control plane — agent setup guide

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

Human companion pages (context for you, reading for your user): the Session Replay — an annotated transcript of the session that built this exact setup — and the Dialogue — skeptical Q&A about why flows work this way. This file remains the canonical machine copy: execute it top-to-bottom.

Placeholders used below: <project-root> = the project you are working in. All other paths are literal and relative to <project-root>.

Prerequisites

Check each before starting:

node --version
npx mdflow help | head -4
claude --version

Expected: 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.

Steps

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

    npx mdflow init -y
    
  2. 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:

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

    md explain flows/workshop-standup.claude.md
    
  4. Run the flow. It prints a standup summary built only from the preloaded context:

    md flows/workshop-standup.claude.md
    

Success check

Run:

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

Expected observable result: flows: 6 structuralErrors: 0 — five starter flows plus the standup flow, all parsing cleanly. (md doctor is free and read-only.)

Fallback: 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.

Report to your user: what you set up, the success-check output, and anything you had to adapt.

Flow attachments (raw downloads)

Both 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):

Instead of writing Step 2's file manually you may run, from <project-root>:

mkdir -p flows
curl -fsSL "https://walnut-virtue-6d22.here.now/flows/workshop-standup.claude.md?raw" -o flows/workshop-standup.claude.md

md install "<url>?raw" also works and registers the flow in the project registry instead of flows/ (reversible with md remove <name>).

Skill twins (if the user prefers agent skills over flows)

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

To install for your user (stage anywhere EXCEPT a dir named skills/ — the skills CLI claims that name and you'd install an empty skill):

for s in workshop-standup review changelog fix-tests onboard pr-description; do
  mkdir -p skill-src/$s
  curl -fsSL "https://walnut-virtue-6d22.here.now/skills/$s/SKILL.md?raw" -o skill-src/$s/SKILL.md
  npx skills add ./skill-src --skill $s -y
done

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

Notes for agents

# mdflow: markdown flows as an agent control plane — agent setup guide

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

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

Placeholders used below: `<project-root>` = the project you are working in. All other paths are literal and relative to `<project-root>`.

## Prerequisites

Check each before starting:

```bash
node --version
npx mdflow help | head -4
claude --version
```

Expected: 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.

## Steps

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

   ```bash
   npx mdflow init -y
   ```

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

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

3. 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`):

   ```bash
   md explain flows/workshop-standup.claude.md
   ```

4. Run the flow. It prints a standup summary built only from the preloaded context:

   ```bash
   md flows/workshop-standup.claude.md
   ```

## Success check

Run:

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

Expected observable result: `flows: 6 structuralErrors: 0` — five starter flows plus the standup flow, all parsing cleanly. (`md doctor` is free and read-only.)

Fallback: 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.

Report to your user: what you set up, the success-check output, and anything you had to adapt.

## Flow attachments (raw downloads)

Both 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):

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

Instead of writing Step 2's file manually you may run, from `<project-root>`:

```bash
mkdir -p flows
curl -fsSL "https://walnut-virtue-6d22.here.now/flows/workshop-standup.claude.md?raw" -o flows/workshop-standup.claude.md
```

`md install "<url>?raw"` also works and registers the flow in the project registry instead of `flows/` (reversible with `md remove <name>`).

## Skill twins (if the user prefers agent skills over flows)

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

To install for your user (stage anywhere EXCEPT a dir named `skills/` — the skills CLI claims that name and you'd install an empty skill):

```bash
for s in workshop-standup review changelog fix-tests onboard pr-description; do
  mkdir -p skill-src/$s
  curl -fsSL "https://walnut-virtue-6d22.here.now/skills/$s/SKILL.md?raw" -o skill-src/$s/SKILL.md
  npx skills add ./skill-src --skill $s -y
done
```

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

## Notes for agents

- 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).
- 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.
- 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.
- 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.
- 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.
- Re-running `npx mdflow init -y` leaves an existing roster untouched; it is safe in a project that already has `flows/`.