loopflow 0.9.11

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

---
requires: wave/<wave>/ items
produces: scratch/<slug>.md
default_agent: claude
fast-path: lf op ingest
---
Refresh PM-backed waves, then pick the highest-priority item from the wave's backlog and move it to scratch/.

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

Fast path: `lf op ingest --item <filename-or-slug>` targets a specific roadmap item instead of auto-picking. If the wave is PM-backed, ingest refreshes the local mirror before picking and warns if the pull fails.

## Wave context

**Finding the wave name:**
1. Check for `<lf:wave name="...">` tag in the prompt — this is the authoritative source
2. If no tag, look at the branch name pattern: `<wave>.main` indicates wave `<wave>`
3. If still unclear, check `wave/` for subdirectories — each subdirectory is a wave

The wave's plan (`wave/<wave>/`) should be included in docs. If you can't find the wave's plan, note this in `scratch/questions.md`.

## Priority-ordered wave plans

Wave plans use four priority levels:

```
wave/rust/
  README.md               # Strategic context (not a pickable item)
  1-fix-crash-loop.md    # Urgent — broken / unblock-now work
  2-core-engine.md       # High — clear next steps
  3-hardening.md         # Medium — big "when not if" bets
  4-experiments.md       # Low — speculative ideas
```

**Priority ordering rules:**
- Pick from the highest-priority non-empty level first (1 before 2, 2 before 3, 3 before 4)
- Treat the prefixes semantically, not as a fake exact queue
- README.md provides principles and success criteria—use it to evaluate priority, but don't pick it

**Using README.md:**
- Read **Vision** to understand what the wave is trying to achieve
- Read **Goals** to evaluate priority — what moves success criteria most?
- Read **Risks** to evaluate urgency — is something blocked or at risk?
- Read **Metrics** to understand what signals matter
- Respect scope boundaries stated in Vision — don't pick items that conflict

**Using the roadmap (`1-*.md` through `4-*.md`):**
- The roadmap is the priority-prefixed files alongside the README — their prefixes define urgency, not a total order
- Read them to understand dependencies and what's been shipped

## Selection criteria

Within the highest-priority non-empty bucket, evaluate each item:

**Urgency.** Is something blocked on this? Is there a deadline?

**Importance.** How much does this move the wave's success criteria forward?

**Readiness.** Are prerequisites met? Is scope clear enough to start?

**Fit.** Does it match the current area or direction?

If multiple items score similarly, prefer smaller scope—ship something.

## Workflow

1. Get wave name from `<lf:wave>` in context
2. Find `wave/<wave>/` in the docs
3. Read README.md for strategic context (Vision, Goals, Risks, Metrics)
   Read the roadmap (`1-*.md` through `4-*.md`) for urgency, dependencies, and scope
4. Identify the highest-priority non-empty bucket
5. Pick the highest-priority item from that bucket
6. Move it to `scratch/<wave>-<slug>.md`

## Output

The selected item is moved to `scratch/<wave>-<slug>.md`. The original is removed from `wave/<wave>/`.

**If the wave backlog is empty:** The wave has nothing to build. This is not an error.
- If the wave is a chord member, it enters silence — alive, watching its area,
  but not proposing work. Write nothing. The wave stays ready for items to be
  added by the chord's tend flow or by the human.
- If the wave is standalone, signal completion by writing nothing. When used in
  a `loop_until_empty` flow, this signals the loop should terminate.

**If items exist but none are ready:** Write `scratch/questions.md` explaining what's blocking progress.

**If items exist but none are compelling:** This is distinct from "not ready."
A wave exists in a market for the user's attention. Shipping mediocre work is
worse than silence — it trains the user to ignore the wave. If no item would
deliver a genuinely compelling user experience, write nothing. Prioritize
validating existing experiences over building new ones.