loopflow 0.9.12

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
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107

---
requires: scratch/<slug>.md (ingested wave item)
produces: scratch/<slug>.md (elaborated design)
default_agent: claude
---
Research risks that could derail the work, then transform a wave item into a bold, well-considered design.

## 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).
- If a `wave/<name>/` directory matches this work, skim its roadmap and items.
- 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.

## Workflow

1. **Understand the intent.** Read the ingested item. What problem does it solve? Who benefits?

2. **De-risk.** Before designing anything, find the things that could invalidate your approach and resolve them. Search the web, read docs, check APIs, run experiments. The job isn't to list risks — it's to come back with answers.

   **Start with what's already flagged.** If the ingested item or wave README calls out specific risks, unknowns, or "what needs validation" — those are your first priority. Someone already thought these were dangerous enough to name. Research each one until you can confirm or refute it.

   **Then scan for what was missed.** Look across technical constraints (does the API actually support this?), prior art (have others tried and failed?), ecosystem shifts (will the ground move under us?), and domain knowledge (are there papers or benchmarks that constrain the solution space?). Not every dimension applies — focus where uncertainty is highest.

   The output of this step is concrete findings, not a worry list. "Linear's API doesn't support conditional assignment, so we need read-then-assign with conflict detection" — not "there might be API limitations."

3. **Consider alternatives.** What are 2-3 different approaches? What are the tradeoffs? Don't settle for the first idea. Let the risks you found shape which alternatives are viable.

4. **Imagine wild success.** The feature ships and users love it. What details made it great? What surprised you about how people use it?

5. **Imagine wild failure.** Six months later, you're ripping it out. What went wrong? What did you miss?

6. **Make choices.** Given all this thinking, what's the right approach? Be bold. Commit to a direction.

7. **Write the design.** Update `scratch/<slug>.md` with a concrete, actionable design.

## Output format

Update `scratch/<slug>.md`:

```markdown
# <Title>

## Problem

<What we're solving. Who benefits. Why now.>

## Approach

<The chosen direction. Be specific.>

## De-risking

| Question | Finding | Impact on design |
|----------|---------|-----------------|
| ... | ... | ... |

## Alternatives considered

| Approach | Tradeoff | Why not |
|----------|----------|---------|
| ... | ... | ... |

## Key decisions

<Choices made and why. The things someone would question.>

## Scope

- In scope: ...
- Out of scope: ...

## Done when

<Verification command or observable outcome>

## Measure (if applicable)

<What to measure before and after. Command to run, baseline to capture, what "better" looks like. Skip for changes without quantitative outcomes.>
```

## Wave alignment

If `<lf:wave>` is present, check `wave/<wave>/README.md` in docs:

- **Vision** — design must serve the wave's north star
- **Goals** — "Done when" must contribute to wave success criteria. Quote the specific goals you're advancing.
- **Risks** — "Imagine wild failure" should check against known risks. If this design introduces a new risk, name it.
- Scope must exclude what Vision marks as "not here"

## Principles

**Bold over safe.** If you're not sure, pick the more ambitious option. Safe designs compound into mediocrity.

**Concrete over abstract.** "Fast" means nothing. "P95 latency under 100ms" means something.

**Decisions over options.** Don't present choices—make them. The design should be implementable as-is.

**Complete over incremental.** Prefer landing an entire architectural chunk in one go. Splitting a coherent change into pieces creates backwards-compatibility adapters, dual states, and integration ambiguity. Only split when pieces are genuinely independent and each delivers something a user or developer would notice on its own.

**Comprehensive over light.** Kickoff outputs get read by humans evaluating the design and by implementing agents executing it. Be thorough — decisions, alternatives, "done when." This isn't a roadmap sketch; it's the spec a future session works from.