loopflow 0.12.20

Run steps and flows with coding agents
Documentation
---
requires: a bound Wave or a proposed new Wave in the launch prompt
produces: a scoped proposal in final Run output, agree or challenge upward
---
Open one Wave's chapter: check the parent brief against this Wave's reality, gather scoped human direction, and propose the Project portfolio.

A chapter is a dated planning interval. The parent brief — when this Run was
launched by a repository `start-chapter` — is provisional direction, not a
plan to execute. During repository orchestration this skill is
**proposal-only**: it returns its portfolio and its verdict on the parent
boundary; the root applies the plan once, after final human acceptance.

## Ground in evidence

For an existing Wave, read its `GOAL.md` and `MEMORY.md`, PM snapshot
(`lf pm show --wave <name> --json`), live state
(`lf status <name> --json`), and actual code and in-flight work in its area.
Read the parent brief and scoped chapter report carried in the launch prompt;
the parent's Task worktree is separate from this checkout. For a proposed new
Wave, use the exact name, repository, and boundary in the parent brief and
inspect adjacent Waves and code; do not invent current GOAL, PM, or Work state.
Verify the brief against the territory. For a standalone existing Wave, use a
locally available report; if none exists, run `wave/review-chapter` and use
its final output.

## Direction

Gather scoped human direction before settling anything: which bets feel done,
which expired, what pressure the code itself is applying, what the parent
brief missed. When an orchestrating parent supplies direction accepted in its
live human conversation, use that record and return any new material question
or challenge to the parent; do not open a second human session merely to reach
the same person. On a standalone headless surface with no accepted parent
direction, open a durable `lf ask "<exact request>"` session for the material
choices; provider exit, silence, or a ready session does not count as
acceptance.

Where this Wave's evidence contradicts the parent brief — wrong boundary,
stale purpose, a tension the brief papered over — challenge it. The return
value is explicit: `agree` or `challenge` against the parent boundary, with
reasons, open tensions, and evidence. A challenge is first-class output for
the parent to reconcile. Do not silently comply and do not silently diverge.

## Propose the portfolio

Choose the Project portfolio for the new chapter. Good Projects are
completable behavioral improvements or standing quality frontiers. Each names
its beneficiary and the real experience it will improve before naming the
mechanism, then carries KRs that credibly prove that improvement — observable
end states, not backlog bullets or implementation receipts. Internal Projects
may serve maintainers or agents, but a mechanism with no explicit downstream
experience is not yet a shaped bet. Every old Project and open Task receives
an explicit carry, rewrite, complete, or retire disposition; none inherits
priority merely by existing.

For each existing Project whose definition or KRs need real shaping, launch
`lf -b --wave <name> --project <project-id> project/start-chapter
"<chapter id, its slice of direction, review findings, and exact starting
KR/Task ledger>"`. For a new bet without a Project id, launch
`lf -b --wave <name> project/start-chapter "<new bet brief and Wave direction>"`;
it proposes a Project and does not create one before final acceptance.
Its proposal may challenge this Wave's framing the same way
this Wave challenges the parent's; preserve and reconcile before returning.
Include every complete Project proposal and Run id in final output so the
repository parent can archive them. A trivial disposition (complete a
finished Project, retire a dead one) is proposed directly.

Return the scoped proposal in final output: the proposed purpose and
boundaries, the exact proposed Project definitions and KR ledger, every
disposition, the next review date, child Run ids, and the agree/challenge
verdict with its reasons. The repository parent archives this output in its
Task worktree; do not write a chapter file in the Wave checkout.

## Standalone invocation

Without a parent orchestration, follow the same briefing and human direction
contract, then return an accepted scoped proposal in final output. Application
belongs to a repository `start-chapter` in a Task worktree, after the full
portfolio has been reconciled and accepted. Do not invent a repository
decision or modify parent boundaries.

## What to avoid

**Executing the parent's plan.** The brief is provisional. A Wave that never
checks it against its own code and human direction launders the parent's
guess into a commitment.

**Mutating during orchestration.** Proposal-only means no `lf pm` writes, no
charter edits, no Task closures. Application belongs to the root after final
acceptance.

**Portfolio by inertia.** Carrying every existing Project forward because
deleting feels destructive. Expired bets lose planning authority; the code
they shipped stays.

**KRs as task lists.** A KR states an observable condition a reviewer can
verify. Implementation steps belong in Tasks.