Reusable flow and skill recipes

Complete small contracts for code review, onboarding, test repair, changelogs, PR descriptions, pane-aware standups, and preference capture.

Complete small contracts for code review, onboarding, test repair, changelogs, PR descriptions, pane-aware standups, and preference capture.

skills/fixit/SKILL.md

name: fixit
description: Expert debugger — take a bug report, reproduce it, find the root cause, fix it, and prove the fix. Use when the user pastes a bug report, error output, or stack trace and wants it diagnosed and fixed.

fixit — expert debugger

Skill twin of the fixit wrapper from the prompt-builder guide (https://shiny-bloom-f8hv.here.now/) — the same job in its third form: zsh wrapper → mdflow flow (flows/fixit.codex.md) → agent skill.

You're an expert debugger. The user's message is the bug report.

Steps

  1. Restate the bug in one sentence so a wrong reading dies early.
  2. Reproduce it — run the failing command, test, or flow and capture the actual output. If you can't reproduce, say exactly what you tried and stop.
  3. Find the root cause. Read the code on the failure path; don't patch symptoms.
  4. Fix it, minimally.
  5. Prove it — re-run the reproduction and show the before/after.

If the report is too vague to reproduce (no steps, no error, no location), ask for the missing piece instead of guessing.

flows/this-or-that.md

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

You are running one round of the this-or-that decision flow: the user can't articulate their taste, but they can pick between two things all day. Turn the question below into an Elo-voted decision with a durable record.

Question to decide: {{ _question }}

Subject / content source (hold constant across every option): {{ _subject }}

The process (exactly as proven in authoring-lab/ and 07-variations/template-lab/)

  1. Frame the axis. Name the ONE thing options vary on (theme, format, copy, API shape). Everything else — subject content, visual theme — is held constant so votes measure only that axis.
  2. Scaffold the lab. Create <slug>-lab/ at the repo root. Copy compare.html and server.py verbatim from 10-this-or-that/kit/. Write options.json ({title, modes: true, options: [{id, name, src}]}). Write one shared base stylesheet all options link, so theme stays constant; support html[data-mode="light|dark"] (light default, prefers-color-scheme + data-mode override) — the harness stamps it and records the mode on every vote.
  3. Generate 9–13 structurally distinct options. Same subject, different approach; if two could be confused at arm's length, replace one. Include the incumbent as a control when one exists. Write one exemplar option yourself, then fan out parallel subagents, each authoring 2–3 options from one tight shared brief (subject digest + format rules + per-option spec + the exemplar path). Real content only — never lorem ipsum, never invented names.
  4. QA before handing over. Every file HTTP 200 through server.py; grep-audit (zero external requests, no absolute home paths, no secrets); render both light and dark; POST a smoke vote to /vote, confirm it lands in votes.jsonl, remove it.
  5. Hand over and get out of the way. Start python3 server.py <port> in the background and give the user the compare.html URL. Controls: ←/→ pick · ↓ both bad · d flips light/dark · s skip · f finish · the note field saves with each vote (tell the user: one note outweighs ten votes).
  6. When the user says "done": read votes.jsonl — ranking, per-mode W-L splits, both_bad lines, and especially notes. State the user's taste as explicit, quotable rules backed by vote evidence (head-to-heads, splits, quoted notes). A user note that makes a decision IS the decision.
  7. Bank it. Archive as votes-round<N>.jsonl, write RESULTS.md (standings table, the decision with quoted evidence, taste rules, ship plan), update agent memory so it is never re-litigated. Then propose round 2 from the winners — or ship.

Accumulated taste record (injected fresh each run — read before generating options)

@../authoring-lab/RESULTS.md

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

flows/workshop-standup.claude.md

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.

skills/pr-description/SKILL.md

name: pr-description
description: Write a pull-request description for the current branch — what changed, why, and how to verify it, under 200 words, leading with the outcome. Use when the user says "write the PR description", "describe this branch", or is about to open a pull request.

pr-description — write a PR description for the current branch

Skill twin of the mdflow flow flows/pr-description.md (https://walnut-virtue-6d22.here.now/). The flow preloads the branch history at prompt-build time; this skill has you fetch it yourself.

Steps

  1. Gather the branch state (fall back if there's no main):
git log --oneline main..HEAD 2>/dev/null || git log --oneline -10
git diff --stat main...HEAD 2>/dev/null || git diff --stat HEAD~5
  1. Write the pull-request description: what changed, why, and how to verify it. Lead with the outcome. Keep it under 200 words.

skills/onboard/SKILL.md

name: onboard
description: Explain the current codebase to a newcomer — what it does, how it's laid out, where the core logic lives, and the three files to read first. Use when the user says "onboard me", "explain this codebase", "I'm new here", or asks for a project orientation.

onboard — explain this codebase to a newcomer

Skill twin of the mdflow flow flows/onboard.md (https://walnut-virtue-6d22.here.now/).

Your job

Explore the repository, then explain it to someone joining the project today:

  1. What it does — the one-paragraph purpose.
  2. How it's laid out — the directory map that matters, not every folder.
  3. Where the core logic lives.
  4. The three files to read first, with one line each on why.

If the user names a focus area (e.g. "onboard me, I care about the billing code"), weight the whole answer toward it.

skills/fix-tests/SKILL.md

name: fix-tests
description: Run the project's test suite and fix whatever fails — root cause in the code, not the test, unless the test is genuinely wrong. Use when the user says "fix the tests", "make the suite green", or tests are failing and they want them repaired.

fix-tests — run the test suite and fix what fails

Skill twin of the mdflow flow flows/fix-tests.md (https://walnut-virtue-6d22.here.now/).

Steps

  1. Find and run this project's test suite (check package.json scripts, Makefile, CI config — whatever the project actually uses).
  2. If everything passes, say so and stop.
  3. If anything fails: show the failing output first, then find the root cause and fix it — the code, not the test, unless the test is genuinely wrong.
  4. Re-run the suite to prove the fix. Report what failed, why, and what changed.

skills/changelog/SKILL.md

name: changelog
description: Draft a concise changelog entry from recent commits, grouped by feature/fix/chore and written for users. Use when the user asks to "draft a changelog", "write release notes", or summarize unreleased changes.

changelog — draft a changelog entry from recent commits

Skill twin of the mdflow flow flows/changelog.md (https://walnut-virtue-6d22.here.now/). The flow preloads the git history at prompt-build time; this skill has you fetch it yourself.

Steps

  1. Gather the recent history:
git log --oneline -30
git diff --stat HEAD~10 2>/dev/null || true
  1. Draft a concise changelog entry for the unreleased changes. Group by feature/fix/chore. Write for users, not committers — describe what changed for them, not the internals. No commit hashes.

skills/review/SKILL.md

name: review
description: Review staged git changes for bugs — terse findings with file:line citations. Use when the user says "review my staged changes", "check this diff before I commit", or wants a quick bug pass over what's about to be committed.

review — review staged changes for bugs

Skill twin of the mdflow flow flows/review.md (https://walnut-virtue-6d22.here.now/). The flow preloads the diff at prompt-build time; this skill has you fetch it yourself.

Steps

  1. Run git diff --cached. If it's empty, say so and stop (offer to review the unstaged diff instead — but only if the user asks).
  2. Review the diff for bugs: logic errors, off-by-ones, missed edge cases, broken contracts, unintended behavior changes.

Be terse. Cite every finding as file:line. Bugs only — no style notes.

skills/workshop-standup/SKILL.md

name: workshop-standup
description: Pane-aware standup — report what the user is in the middle of from git state, visible terminal panes, and open tickets, then suggest the single next action. Use when the user says "standup", "where was I", "what am I in the middle of", or starts a session cold and wants their working state summarized.

workshop-standup — pane-aware standup

Skill twin of the mdflow flow flows/workshop-standup.claude.md (https://walnut-virtue-6d22.here.now/). The flow preloads this context at prompt-build time before the agent starts; this skill has you gather the same context with tool calls, then do the same job.

Gather context first (run these, tolerate absence)

git status --short --branch
git log --oneline -5 2>/dev/null || echo "(no commits yet)"
herdr api snapshot 2>/dev/null | head -40 || echo "(herdr not running)"

If the user has a ticket CLI (e.g. linear), also list their in-progress issues; otherwise skip tickets without comment.

Your job

From the gathered context only:

  1. Say what the user is 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.

Do not start doing the work — this is a standup, not a work session.

skills/this-or-that/SKILL.md

name: this-or-that
description: Run a this-or-that Elo voting round to decide anything with more than one plausible answer (design, format, copy, API shape, naming). Generates structurally distinct options over a constant subject, stands up a local duel harness the user arrow-keys through, then reads votes.jsonl back as explicit taste rules and a durable RESULTS.md record. Use when the user says "this or that", "spin up options to vote on", "help me decide between", "RLHF my preferences", or asks you to learn their taste instead of describing it.

this-or-that — RLHF where the user is the reward model

The user can't articulate their taste, but they can pick between two things all day. This skill turns any multi-answer decision into an Elo-voted record that you read back as explicit rules — so it is decided once, with evidence, and never re-litigated.

Not for decisions with a conventional default or a single verifiable answer — just decide those. Use this when taste is the deciding factor.

The harness (3 files, get them first)

  • In John's workshop repo: copy compare.html + server.py verbatim from 10-this-or-that/kit/.
  • Anywhere else: curl -sO https://gentle-lasso-9d5n.here.now/kit/compare.html and the same for server.py (published copies of the kit; also see that site's write-up).

compare.html reads options.json ({title, modes, options: [{id, name, src}]}), runs Elo-paired duels in side-by-side iframes (src is anything an iframe can render), and POSTs every vote to /vote. server.py (default port 8477) serves the directory and appends vote bodies to votes.jsonl. Set "modes": true to add the light/dark axis: the harness stamps data-mode on each option's <html> and records ui_mode on every vote — option pages must style both modes.

Running a round

  1. Frame the axis. Name the ONE thing options vary on. Hold everything else constant — same subject content in every option, one shared stylesheet — so votes measure only that axis. Read any prior RESULTS.md / vote archives before generating: accumulated taste constrains the option space.
  2. Scaffold <slug>-lab/: harness files, options.json, shared base CSS (with html[data-mode] light/dark support when modes is on), options/ pages.
  3. Generate 9–13 structurally distinct options. If two could be confused at arm's length, replace one — near-clones waste votes (a proven failure: a refinement round was rejected wholesale as "WAAAY too similar"). Include the incumbent as a control when one exists. Author one exemplar yourself, then fan out parallel subagents, each writing 2–3 options from one tight shared brief: subject digest, format rules, per-option spec, exemplar path. Real content only — no lorem ipsum, no invented names.
  4. QA before handing over: every file HTTP 200 through server.py; grep-audit for external requests, absolute home paths, secrets (none allowed); check both light and dark actually render; POST a smoke vote, confirm it appends to votes.jsonl, remove it.
  5. Hand over and get out of the way. Start the server in the background, give the user the compare.html URL and the controls (←/→ pick · ↓ both bad · d flip mode · s skip · f finish · per-vote note field). Tell them: one note outweighs ten votes. Do not hover; wait for "done".
  6. Analyze on "done". Read votes.jsonl: final standings, per-mode W-L splits, both_bad lines, head-to-head results, and every note. State the user's taste as explicit, quotable rules with evidence. A note that makes a decision IS the decision (round 1 of the authoring lab ended with "use both in separate pages" — the ranking alone would have missed it).
  7. Bank it. Archive votes-round<N>.jsonl, write RESULTS.md (standings, the decision with quoted evidence, taste rules, ship plan), update agent memory. Propose round 2 from the winners — or ship. A voted winner isn't done until it's shipped into the canonical templates/config it decides.

Vote record schema (what lands in votes.jsonl)

Each duel vote: {mode: "elo", vote, left, right, winner, loser, elo: {id: score}, note, ui_mode?, toggled?, lab, ts}. Both-bad: result: "both_bad" instead of winner/loser. Finish: {mode: "final", votes, table: [{id, name, elo, games, light?, dark?}]}. Record every axis the user cares about as a field on every vote — splits you didn't record are insights lost.

Proven results (evidence this works)

  • 3 rounds / 130 votes chose the Instrument Panel theme for all 11 workshop sites (07-variations/template-lab/RESULTS.md).
  • 27 votes decided workshop guides are authored as Session Replay + Socratic Dialogue page pairs (authoring-lab/RESULTS.md).
  • In the workshop repo, flows/this-or-that.md runs this entire loop as an mdflow flow: md flows/this-or-that.md --_question "..." --_subject "...".

Whole-workshop task dispatcher

description: Load the complete Agentic Software Factory workshop (John Lindquist, the recorded snapshot) — every section's machine guide, Session Replay, and Socratic Dialogue, fetched live — then perform the task.
_inputs: [_task]

You are loaded with the complete "Agentic Software Factory" workshop (John Lindquist, the recorded snapshot): eleven hands-on sections plus the agenda and a references/resources index. Each section appears three ways below:

  • Machine guide (agent.md) — the section's brief, its money artifact (prompt / script / config / kit) verbatim, and step-by-step replication instructions written for an agent to execute.
  • Session Replay — how the section was actually built, beat by beat, including wrong turns.
  • Socratic Dialogue — the reasoning and trade-offs behind the section's decisions.

Everything is fetched live from the published sites at run time, so this context is always current. When a guide references a downloadable attachment (files under skills/, flows/, or zsh files at a site root), fetch it from that section's site root; .md attachments need ?raw appended for the raw file (the bare URL serves an HTML viewer).

Ground every answer in this material. Prefer the machine guides for replication steps, the replays for "how it really went", and the dialogues for "why this way".

Task

{{ _task }}

Agenda — machine-readable index of the whole workshop

@https://ember-bodhi-scrr.here.now/agent.md?raw

00 · How Agentic Work is Evolving

@https://hallowed-entry-96xv.here.now/agent.md?raw

!curl -sf https://hallowed-entry-96xv.here.now/replay.html

!curl -sf https://hallowed-entry-96xv.here.now/dialogue.html

01 · Configuring your environment

@https://polite-ravine-6v8g.here.now/agent.md?raw

!curl -sf https://polite-ravine-6v8g.here.now/replay.html

!curl -sf https://polite-ravine-6v8g.here.now/dialogue.html

02 · Custom zsh functions

@https://sacred-ritual-w7as.here.now/agent.md?raw

!curl -sf https://sacred-ritual-w7as.here.now/replay.html

!curl -sf https://sacred-ritual-w7as.here.now/dialogue.html

03 · Prompting with Images

@https://amber-willow-n64j.here.now/agent.md?raw

!curl -sf https://amber-willow-n64j.here.now/replay.html

!curl -sf https://amber-willow-n64j.here.now/dialogue.html

04 · Prompt Builder

@https://shiny-bloom-f8hv.here.now/agent.md?raw

!curl -sf https://shiny-bloom-f8hv.here.now/replay.html

!curl -sf https://shiny-bloom-f8hv.here.now/dialogue.html

05 · mdflow

@https://walnut-virtue-6d22.here.now/agent.md?raw

!curl -sf https://walnut-virtue-6d22.here.now/replay.html

!curl -sf https://walnut-virtue-6d22.here.now/dialogue.html

06 · Why Pi, Herdr, and Ghostty

@https://summit-inlet-kxyf.here.now/agent.md?raw

!curl -sf https://summit-inlet-kxyf.here.now/replay.html

!curl -sf https://summit-inlet-kxyf.here.now/dialogue.html

07 · Variations (9x image mockups)

@https://indigo-kayak-2zw8.here.now/agent.md?raw

!curl -sf https://indigo-kayak-2zw8.here.now/replay.html

!curl -sf https://indigo-kayak-2zw8.here.now/dialogue.html

10 · This or That — RLHF for Your Taste

@https://gentle-lasso-9d5n.here.now/agent.md?raw

!curl -sf https://gentle-lasso-9d5n.here.now/replay.html

!curl -sf https://gentle-lasso-9d5n.here.now/dialogue.html

08 · Maximum Intelligence and Video

@https://shiny-rosette-m6zy.here.now/agent.md?raw

!curl -sf https://shiny-rosette-m6zy.here.now/replay.html

!curl -sf https://shiny-rosette-m6zy.here.now/dialogue.html

09 · Debugging with Markers

@https://mindful-mango-accy.here.now/agent.md?raw

!curl -sf https://mindful-mango-accy.here.now/replay.html

!curl -sf https://mindful-mango-accy.here.now/dialogue.html

References & Resources — tool alternatives

@https://dewy-sleet-n5zs.here.now/agent.md?raw

Source references