# 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. Rebases only if behind, writes title/body, prints state + URL, leaves
the PR up. Use it to make work visible mid-stream; nothing is finalized and
nothing is 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/`, 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.
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.
## 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 human surface. 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.