---
produces: connected Loopflow path and an evidence-backed next command
---
Connect this repository to Loopflow's distributed control system.
Loopflow is not primarily a prompt launcher. It is the shared control surface
for durable Waves, chapter plans and Linear-backed Tasks, GitHub delivery, stable
execution Homes, and the agents that do the work. Establish that system first.
Skills, flows, models, and launch preferences are secondary configuration.
## Reviewer mode
The launch prompt identifies the reviewer.
- **Interactive reviewer:** ask one consequential question at a time. You may guide
interactive account connections and edit personal config only after the
user explicitly chooses them.
- **Parent reviewer:** inspect the same state, but make only repo-scoped,
reversible changes through the review protocol with the Task. Never guess a
user preference. OAuth, personal config, placement, and external object
creation require the present User. When absent, report the exact blocker and
next commands; do not manufacture a session.
Never expose credential values. Use Loopflow's auth commands; do not read
tokens from dotfiles or environment variables.
## 1. Discover the existing system
Run read-only checks first. Missing optional commands are observations, not
failures.
```bash
git rev-parse --show-toplevel
uname -s
lf --version
lf auth status --cached # cached; no provider request
lf auth status --json # inspect accepted managed evidence
lf auth route show
lf home id --json
lf wave list --json
command -v claude
command -v codex
command -v opencode
test -f .lf/config.yaml && echo "repo config: present"
test -f ~/.lf/config.yaml && echo "user config: present"
find wave -mindepth 2 -maxdepth 2 -name GOAL.md -print 2>/dev/null
```
Do not reconstruct distributed state from processes, worktrees, or provider
web pages. `lf wave list`, `lf wave status`, and `lf roadmap` are the shared read surfaces.
If `lf home id` says the local store is not initialized, record that plainly
and continue; do not invent a Home identity.
Present one compact topology:
```text
Repository /path/to/repo
Home home_... on this machine | not initialized
Agents codex, claude
Accounts GitHub connected; Linear missing
Waves designer running here; infrastructure stopped on home_...
```
Separate observed facts from missing capabilities. Do not call a repository
"uninitialized" merely because it has no `.lf/config.yaml`; existing Wave,
Home, account, or planning state still counts.
## 2. Establish the minimum local authority
Read `lf user name --json`: a personal Loopflow `user.name` override wins,
otherwise Git's configured `user.name` supplies the baseline. An available name
needs no additional setup. Agents may also use a name already known in the session.
In an interactive session, if neither source supplies a name, ask what name to
use in saved artifacts. Record an explicit choice or correction as `user.name`
in personal configuration (`$LF_HOME/config.yaml`, or `~/.lf/config.yaml` when
unset), preserving other settings. Blank or absent preferences fall through to
Git. Never infer a name from an account, directory, or commit author, and never
put a personal name in repo Loopflow configuration.
On SSH, preserve the destination owner's preference; the caller's preference
belongs on the originating Home. In unattended work, leave an absent name unknown.
At least one supported agent must be available: Claude Code, Codex, or
OpenCode. If none is installed, stop with install commands and end with
`lf init` as the retry. Do not run a package manager.
Installed harnesses are a capability of this Home, not repository policy. One
Home may have Codex while another has Claude or OpenCode. Never rewrite
team-wide repo configuration merely to mirror `command -v` on this machine.
Resolve repo agent configuration conservatively:
- Preserve a valid existing `agent` override.
- An absent `agent` is valid: Loopflow then uses the first of Codex, Claude,
and OpenCode installed on this Home. Do not write `agent` to work around a
missing harness.
- Change `agent` or `supported_harnesses` only when the user explicitly wants
a team-wide policy. Ask whether the choice is repo-wide or Home-local before
writing it.
- A local harness mismatch affects where work can run. It does not invalidate
the repository.
Create `.lf/config.yaml` only when a real repo-scoped policy is missing and the
user chooses one. Preserve every existing field. For example:
```yaml
supported_harnesses:
- codex
- claude
```
Leaving `.lf/config.yaml` absent is correct when defaults suffice. Do not add
exclusion patterns, permission bypasses, model pins, IDE settings, or release
policy without evidence that this repository needs them.
Personal launch preferences belong in `~/.lf/config.yaml`. They are optional
and never block initialization. Discuss them only after the distributed path
works; never modify them for a parent reviewer.
## 3. Connect shared truth for the intended path
Ask the user what they want to make operational now:
1. an existing Wave,
2. a new durable Wave,
3. an existing Linear Task,
4. only direct skills/flows for now.
This answer determines the minimum accounts and files. Do not turn init into a
questionnaire.
For durable planning and delivery, inspect `lf auth status` and offer only the
missing connections:
```bash
lf auth connect github
lf auth connect linear
lf auth connect claude
lf auth status --cached # cached; no provider request
lf auth status --json # inspect accepted managed evidence
```
OAuth client credentials resolve from environment first, with a Doppler fallback
when configured. If this repository uses Doppler and credentials are missing,
use `doppler run -- lf auth connect linear`. Otherwise follow the customer's secret
manager and the exact missing variable names. Never print credential values.
Account connection is an external side effect. The user must choose it and
complete the provider flow. Claim a new connection only after connect completes;
cached status is retained evidence, not a fresh authorization check. Managed
verification requires an accepted managed row from `auth status --json`.
Direct skills can proceed with a local agent even
when Linear is absent; do not block that path on PM setup.
## 4. Make one durable path real
### Existing Wave
Read its `wave/<name>/GOAL.md`, then verify its shared state:
```bash
lf wave status <wave> --json
lf roadmap --wave <wave> --json
lf wave status <wave> --no-sync
```
If PM is not bound and Linear is connected, offer the explicit binding command:
```bash
lf wave connect --wave <wave>
```
The first Wave establishes the repository Team and defaults its key from the
repository name; `--team-key <KEY>` is an explicit override. Later Waves must
reuse that binding. Choosing the initial repository Team requires the user's
choice. Do not invent another Team, Initiative, Project, or KR; an existing
repository binding changes only through the repository-wide migration.
### New durable Wave
Ask for one outcome and a short name. Create:
```text
wave/<name>/GOAL.md
```
Write the goal as a durable operating contract: objective, observable success,
boundaries, and when to stop or escalate. Keep chapter priorities, KRs and Tasks
in the chapter plan. Curate durable decisions in `wave/<name>/MEMORY.md` through
the repository workflow; do not invent runtime memory commands or duplicate the
plan in the goal body.
Then offer Linear binding as above. Initialization provisions one internal
Project for the first chapter. Subsequent chapters replace it through
`lf wave new-chapter`; the Wave retains purpose, memory, and conversation.
Tasks belong to the current chapter automatically.
### Existing Linear Task
Require its exact issue identifier. If Linear is connected and the Task belongs
to the repository Team and one Wave-owned Project, the durable execution path is:
```bash
lf task run <ISSUE-ID>
lf task status <ISSUE-ID> --json
```
Do not create an ad-hoc worktree or convert the Task into a local prompt.
### Direct skills and flows
Offer the lightweight path without pretending it is the whole product:
```bash
lf debug -c
lf design
lf list
```
These are next commands, not setup probes; do not run them automatically.
Mention repo-local `.lf/skills/` and `.lf/flows/` only if the user wants to
author reusable behavior.
## 5. Place execution deliberately
The current Home is the default execution authority. Do not place or start a
Wave merely to prove setup.
If the user wants remote execution, explain the durable sequence and use the
actual ids observed from the commands:
```bash
lf ssh <host> home id --json
lf home observe <home-id> ssh://<user>@<host>
lf ssh <home-id> auth status
lf ssh <home-id> route show
lf wave list --json
lf wave place <wave-id> <home-id>
lf wave status <wave> --json
lf ssh <home-id> --wave <wave> wave/operate
```
`lf ssh` always runs the remote `lf`; ordinary `ssh` owns arbitrary remote
commands. The remote process can select from subscription accounts forwarded
for that invocation and accounts installed on the remote Home. GitHub, PM, and
secret authority use the remote machine's installed credentials. Before
placement, use remote reads to verify that the remote has `lf`, the repository,
required accounts, and the intended route. `lf home observe` records the
mutable SSH route for the stable HomeId. Placement is allowed only while no Run
is live. `lf --wave <wave> wave/operate` makes a finite pass locally; prefix it with
`lf ssh <home-id>` to run on the remote Home. Ask before observing a route,
changing placement, or starting a Wave; each changes durable execution state.
## 6. Prove the result
Run the smallest checks that prove the selected path:
```bash
lf auth status --cached # cached; no provider request
lf auth status --json # inspect accepted managed evidence
lf auth route show
lf home id --json
lf wave list --json
```
For a selected Wave, also run `lf wave status <wave> --json` and
`lf roadmap --wave <wave> --json`. After placement, use
`lf wave status <wave> --json`. For a selected Task, run
`lf task status <ISSUE-ID> --json`. Do not run the machine-wide roadmap or
doctor as routine setup: both can be large, and doctor can surface unrelated
historical problems. Do not start work as a setup test.
Finish with observed state and one primary next command:
```text
Loopflow is connected for this repository.
Home home_... (local)
Home agents Codex + Claude installed
Repo policy inherited defaults
Accounts GitHub + Linear connected
Wave designer placed on home_...
Planning Linear bound; 1 current chapter / 7 open Tasks
Next lf --wave designer wave/operate
If something remains unavailable, say exactly which authority is missing and
the command that would establish it. Never hide a missing account, Home,
Wave/PM binding, or agent behind "setup complete."
On macOS, offer `lf desktop` as an optional interactive control surface after the
selected path is proved. Do not launch it automatically.
## Conversation style
- Lead with the observed topology, not configuration trivia.
- Ask one consequential question at a time.
- Prefer a working durable path over exhaustive optional setup.
- Expose Wave and Task; keep the chapter Project internal. Keep Home, account, and skill distinct.
- Stop when the chosen path is proved and the next command is obvious.