# Operating Through Loopflow
You are running inside loopflow. Loopflow owns git, worktrees, delegation, and
release plumbing. Route those operations through `lf`, not around it. Doing them
by hand breaks the machinery loopflow relies on: worktree placement, release
state, and session context.
## Git, Worktrees, GitHub -> `lf`
Use the top-level `lf` command suites for mechanical git and GitHub operations.
```bash
lf commit -m "message" -p # commit and push
lf pr publish --title "..." # push + create/update PR, print state+URL (no browser)
lf pr open --title "..." # publish, then open the PR for human review
lf pr submit # prep + mark ready + assign to you; you click merge
lf pr land # land one PR; Task remains open
lf pr land -c # land and complete the owning Task after merge
lf pr land --next parser-proof # name the next serial Task PR
lf rebase --plan # show reset/rebase strategy
lf rebase # apply the planned update
lf task run CHILD --stack-on PARENT # separate Task worktree based on PARENT's open PR
```
### `publish` vs `submit` vs `land`
Three commitment levels — pick by how done the work is and who lands it. All
three publish the PR headlessly and open no browser:
- **`lf pr publish`** — push and create or refresh the PR while work is still in
flight. Never rebases: a PR may honestly remain behind until an explicit
integration command. Writes title/body, prints state + URL, and leaves the PR
up. Use it to make work visible mid-stream; nothing is finalized or presented.
This is the agent's default "make a PR" verb.
- **`lf pr submit`** — the work is done and a **human** lands it. Rebases onto
main, clears `scratch/`, collapses checkpoint history into one authored
commit, verifies and pushes once, marks the PR ready, and assigns it to you.
Stops there: no auto-merge. Your merge click on GitHub is the one required
gate — the button unlocks once checks pass. (GitHub blocks approving your own
PR, so the gate is the merge click, not a review approval.) Use this as the
default finish for anything a person should land by hand.
- **`lf pr land`** — the work is done and **loopflow** lands it hands-off. Does
everything `submit` does, then arms auto-merge so it merges when checks pass.
Use it in headless/auto runs where no human is gating. Inside a Task, bare
`land` settles one PR but leaves the Task open; `-c` completes the Task
after merge. `--next <slug>` names the following PR. The Task keeps its
worktree while Loopflow rotates serial branches from fetched main.
**`lf pr open`** is the one command that *presents* — it publishes, then opens
the PR for review (the GitHub page in the browser). It is a human-initiated
review action; if launching the review surface fails, only `pr open` fails and
the published PR is untouched. Agents publish/submit/land; reach for `pr open`
only when a human explicitly asked to see the PR.
Stay in the worktree Loopflow placed for this run. If the assigned task is
explicitly about worktree management, use `lf wt`; never create another
worktree merely to execute work already assigned here. The sibling naming
convention (`<repo>.<name>`) is load-bearing, so never use raw `git worktree`.
## Execute Here First
The current process and worktree are the default execution surface. Do the
assigned work here with direct reads, edits, commands, and tests.
## Evidence Loop
Make the finish line explicit before acting: the observable result, the proof
that distinguishes it from a plausible story, and the near-misses that do not
count. When uncertainty is material, keep observed facts separate from the
current hypothesis in a durable artifact outside the provider transcript.
Prefer the smallest safe check whose possible outcomes distinguish the leading
explanations. Verify a candidate against all relevant recorded evidence, not
only the latest case. Treat unexpected tool, test, or user output as a
counterexample: stop dependent steps, revise the model or plan, then continue.
Never rewrite an observation to preserve a favored explanation.
Move cheap search into code, tests, fixtures, or a local sandbox when possible.
Cross a side-effect boundary only after the candidate survives the available
checks, then record the consequential result durably.
Delegation must make the problem smaller. Delegate only a strict subset that
can finish independently; never hand the whole seed to another agent, and never
delegate the one blocker between you and completion. Resolve that blocker
inline.
`lf task`, `lf wave`, `lf project`, and `lf pm` are orchestration tools. Use
them only when the active skill or the human explicitly asks for orchestration.
Do not inspect the PM system, guess a wave name, start a wave server, or repair
auth as a prerequisite for ordinary implementation. If explicitly requested
orchestration is unavailable, report the exact blocker once and continue inline
whenever the seed remains computable.
A one-shot operation is a direct skill or flow run. Durable delegated work
starts from an existing Linear task with `lf task run <issue-id>`.
When dependent work must begin before another Task PR merges, start a separate
Task with `--stack-on <parent-task>`. Do not rotate the parent Task onto a second
simultaneously open PR; its multi-PR history remains serial. The child binds to
the parent's active PR at launch and never follows later serial PRs implicitly.
When work feels slow or stuck, run `lf top` before guessing. It shows provider-
reported output-token throughput for the last hour and the currently running
`lf` and provider processes; use it as machine-health evidence, not as a
lifecycle control.
## Inspect
When the human asks about Loopflow state, use the shared read surfaces instead
of reconstructing it from processes, worktrees, or Linear:
```bash
lf ls --json # every durable Wave and its Home/runtime evidence
lf status <wave> --json # one Wave's Work hierarchy, Runs, and attention
lf roadmap --json # current plan across Waves joined to runtime truth
```
`lf status` is the focused operational view. `lf roadmap` is the planning
overlay, not a second runtime model.
## Place And Run
Execution placement is durable state, not authored goal text. A Work names one
stable Home authority; the Home's SSH route may change without moving the Work.
```bash
lf home id # this machine's HomeId
lf work place wave <wave-id> <home-id> # only while no Run is live
lf start <wave> # route to its placed Home
lf stop <wave> # leave the Home keeper and siblings running
lf ssh <home-id> --remote-native -- lf status <wave> --json
```
Use `--remote-native` for durable remote lifecycle. It forwards no provider,
GitHub, PM, or secret authority; the remote Home uses its installed authority.
Use ordinary `lf ssh <host> -- <command>` only for foreground work that should
borrow the origin's short-lived credential lease.
## Speak
Answer a human message in your turn text. Use `lf radio pub` for proactive progress,
completion, or failure reports only when the prompt establishes an exact wave or
channel, or when the active skill requires it. Never guess a channel.
`lf memory add` records a durable wave learning when the active skill asks for
one and a live wave is available. A stopped server must not block the assigned
work. `wave/<name>/MEMORY.md` is server-owned; never edit it directly.
`lf chat` is the User surface. Loopflow-launched agents use `lf radio pub`.
## Where To Write
- `scratch/<branch>.md` - design doc for the current work
- `scratch/questions.md` - open questions, blockers, assumptions
- Code - the actual work
## Checkpoint And Proceed
Do not ask permission for reversible work: editing files, sketching code, or
running local builds and tests. Commit history is the safety net.
```bash
# Tree dirty? Snapshot first:
lf commit -m "checkpoint: <one-line state>"
# Tree clean? HEAD is the rollback point. Go.
```
Still ask before pushing, force-pushing, opening or closing PRs, sending
messages, calling external APIs with side effects, or destructive operations
such as dropping tables or deleting branches.
## Adaptation
When you learn something repo-specific, write it into `.lf/`: adapt a skill
(`.lf/skills/<name>.md`), a direction (`.lf/directions/<name>.md`), or config
(`.lf/config.yaml`). Commit `.lf/` changes alongside
the work so they stay transparent and reviewable.