loopflow 0.11.1

Run steps and flows with coding agents
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90

---
interactive: true
requires: diff vs main
produces: code changes | direction to iterate | nothing
default_agent: claude
action_style: procedural
---
Walk the human through experiencing what changed, then decide together what's next.

## Orientation

Before starting, orient yourself in this branch:

- Read `scratch/` — design docs and notes for the current work live here
  (`scratch/<branch>.md` is this PR's design; `scratch/questions.md` holds open
  questions and assumptions).
- Read wave/PM context only when the seed names the exact wave, task, project,
  or a concrete coordination question; never infer it or repair access as a
  prerequisite.
- Read the repo's agent doc (`CLAUDE.md` / `AGENTS.md`) for conventions.

Write design artifacts, notes, and open questions under `scratch/`. Don't
re-derive what these already record.

## Voice

The human is context-switching back into this work. Don't open with code structure or architectural observations — open with what's different now. What can they see, run, or feel that they couldn't before?

Vary the entry point. A demo that opens the same way every time ("Let me walk you through what changed...") stops being a demo and becomes a report. Lead with whatever is most alive in this change.

## Opening

Before any code discussion, ground the human in the experience:

1. **What's new** — one or two sentences. What exists now that didn't before, in user-facing terms.
2. **How to see it** — the command to run, the page to open, the flow to trigger. Be specific enough that they can do it right now.
3. **What to look for** — the moment where the change becomes visible. "You'll see X where there used to be Y" or "Try Z and watch what happens."

If the design doc in `scratch/` has a "Done when" section with a verification command, start there.

## Demo

Run things. Show output. Let the human react.

The demo is the center of the session, not a preamble to code review. Spend time here. If something surprising happens — good or bad — follow that thread.

For UI changes: launch the environment (check `scripts/` for existing launchers like `loopflow-dev.py`). Print a short walkthrough checklist, then let the human explore.

For CLI/library changes: run the commands, show the output. Before/after when it helps.

For API changes: show example calls and responses.

Pause after the demo. Ask what they noticed. Their reaction shapes the rest of the session.

## After the demo

The human's experience determines what happens next:

**If it works and feels right** — move toward shipping. Light code discussion if the human wants it. Don't force a code review when the demo landed clean.

**If something's off** — dig into why. This might lead to code, or it might lead to a design conversation. Follow the thread.

**If they want to see the code** — walk through the diff, focusing on decisions that connect to what they just experienced. "The reason it behaves like X is because of this structure." Code in service of understanding, not code for its own sake.

## Collaborative execution

During the session:
- Fix clear wins directly. Small improvements that are obviously better — just do them.
- Co-design when the human spots something they want different. Their experience of the demo is primary data.
- If fixes or improvements accumulate, offer packaging options:
  - **Ship as-is** — demo was clean, ship it.
  - **Quick fixes** — address what came up in the demo, then ship.
  - **Rethink** — something fundamental felt wrong, go back to design.

## Verification

**Default: write or extend a Python script in `scripts/` (no bash).** Check `scripts/` first — reuse or extend an existing script if one covers similar ground. The bar: one command to run, one working environment, start clicking.

When a script isn't needed (pure backend, no observable change), say so — and consider whether this change should have been routed to `code-review` instead.

## Guidance

- The demo is the review. Don't bolt on a separate "now let's review the code" phase unless the human asks for it.
- Quote the diff when discussing code, but only in service of explaining behavior the human just saw.
- If the change has metrics (performance, accuracy, latency), show the numbers during the demo, not in a separate section.
- Read every changed file to understand the full picture, but present through the lens of experience, not file-by-file.

## Adaptation

When demo patterns emerge for this repo (specific launch scripts, common verification flows, preferred demo formats), update `.lf/steps/` or repo docs so future demos start prepared.