Files
pipelines/internal/author/skill/references/orchestration.md
T
alan 36fad7d130 Merge lane-go: keep the lane's reviewed work
Combines lane-go's typed omni search, launch-time model overrides, TUI
artifacts view, run-state websocket push, and the "reflect the change where
it belongs" committer rule with the Templates gallery, chat/omni-search and
other reviewed work already on main. The 12 files both sides touched keep
both intents composed rather than dropping either side: the omni search keeps
the typed search contract (CLI `pipelines search` and the TUI popup with type
badges and marked snippets) alongside the run-list quick filter; cli.md and
ui-ux-review.md document both the search rework and the artifacts view;
orchestration.md, harnesses.md and operations.md keep the model-override and
reflect-where-it-belongs guidance; and the protocol/CLI/server/TUI code keeps
the new search, run-event, override and artifacts paths alongside the existing
run, title and help surfaces.

Checks before committing:
- go build ./...  -- pass
- go vet ./...  -- pass
- go test -count=1 ./internal/... ./cmd/...  -- all pass

Doc check before committing: nothing needs updating. The lane's own docs and
references (docs/cli.md, docs/ui-ux-review.md, and the orchestration,
harnesses and operations skill references) already carry the new features.
format.md and the packaged templates already describe the line-oriented result
format and the human decision stage from the earlier lane-go merge. The root
README already describes the omni search popup. Model overrides, the search
command, run events and the artifacts view are runtime/CLI/TUI surfaces that
cli.md documents; no template, README or topic-doc edit is required by this
merge.
2026-10-17 02:04:58 +01:00

174 lines
9.6 KiB
Markdown

# Orchestrate work through runs
When the operator asks for a change to this project, the agent's product is a set of
briefs and a set of managed runs, not the change itself. The implementer stage makes
the change; the reviewer stages check it; the committer stage commits it. Route all
project work through Pipelines runs.
## Stance
- **Reconnoitre first.** Read enough of the repository, its notes and recent history
to write a truthful brief: name the exact files, functions, commands and existing
helpers the change touches. Do not guess and do not hand-roll the change to avoid
reading.
- **Then route every work item through a run.** Do not edit the project's files
yourself, not even a one-line unblock. A hand edit has no brief, no independent
review and no recorded run, so nothing about it can be reviewed or trusted.
- **Fix the cause, not the symptom.** When a run wedges, fix the pipeline definition,
the stage configuration or the Pipelines/harness service. Do not reach around a
stuck stage and finish its work by hand. Diagnose with `references/debugging.md`.
- The agent decides scope, decomposition, pipeline choice and what to publish; the
operator owns the decisions a run cannot make — which items to accept, what to
publish, when to restart a service, when to install on real hardware. Ask only for
those.
## Work items
Decompose the request into **single-purpose items, roughly an hour of agent work
each**.
- One item is one coherent change with its own brief, its own evidence and its own
review, so the operator can review it on its own.
- One item = one run = one commit (the committer stage commits). Do not batch
unrelated changes into one run; a run whose reviewer is arguing about two
independent changes is unreviewable.
- State dependencies and ordering: which items must land first and which are
independent. Independent items may go to parallel lanes
(`references/lanes.md`); dependent items run in order.
- Prefer more, smaller items to fewer large ones: a smaller item is cheaper to
review, cheaper to retry, and less likely to loop back through the reviewer.
## The brief
A brief is the entire task a run receives. The run does not see this conversation,
the operator's intent beyond the brief's words, or any context that is not on disk.
Write it self-contained.
Every brief has:
1. **Goal** — one line naming the change.
2. **The observed problem** — what is wrong today and why it matters, in the
repository's own terms, naming the exact files, commands or runs.
3. **Requirements** — a short bulleted list of the exact behaviour, the surfaces it
touches, and every constraint the change must honour.
4. **Falsifiable evidence required** — the exact commands the run must run and the
output it must report, plus the screenshots the reviewer must read. Say plainly:
"report the exact commands and their observed results. Do not claim a check you
did not run."
5. **Where it belongs** — the packaged templates, the repository's guidelines (README
and topic docs) and the packaged skill references the change is expected to touch,
so the committer can check and update them before it commits.
6. **The hard constraints block** (below).
7. **Publishing rules** (`references/delivery.md`).
Template:
```
<one-line goal: the change, in the repository's own words.>
<what is wrong today and why it matters; name the exact files, commands or runs.>
- <requirement 1: the behaviour and the surface it touches>
- <requirement 2>
...
Evidence: <exact build/test commands> and <the screenshots or captures asked for>;
report the exact commands and their observed results. Do not claim a check you did
not run.
Constraints: <scope: the one subtree or package this item may touch>; no new
dependencies; do not restart, rebuild or reconfigure the Pipelines or OpenCode
server, the installer, the ntfy service or any other service - runs and lanes are
active; never install on the operator's physical device; keep geometry and values
from their single existing sources rather than new literals; commit locally only,
never push; <the item's publishing rules>.
```
Requirements must be concrete and checkable. Name files, functions, commands, and
the existing helpers to reuse. State what must survive — existing behaviour, other
lanes' work. If a requirement cannot be checked by a command or by an image a
reviewer can open, it is not evidence: rewrite it.
Do not write a brief that asks a stage to do a vague job ("make the UI better"). A
reviewer cannot falsify it and the run will drift. One item, one observable outcome.
## Hard constraints to carry into every brief
Adapt the scope and publishing lines per item; keep the rest.
- **Scope** — the single subtree or package the item may touch, and nothing else.
- **No new dependencies** unless the brief argues the exception in-line.
- **Do not restart, rebuild or reconfigure** the Pipelines server, the CLI, the
installer, the OpenCode service or ntfy, and do not touch another lane's worktree
or device.
- **Never install on the operator's physical device** — only the lane's own emulator
or device (`references/lanes.md`).
- **Keep values from single sources** — geometry, tokens, sizes and constants come
from the source that already owns them, not from new literals.
- **Commit locally only, never push** — the committer stage commits, no other stage.
- **Reflect the change where it belongs** — before committing, the committer checks
that the change is reflected in the packaged templates, the repository's guidelines
(README and topic docs) and the packaged skill references, updates anything stale,
and states in the commit body what it checked or that nothing needed updating.
- **Publish rules** — WIP artefact naming and LAN URLs per `references/delivery.md`.
## Pipeline choice
- Use a pipeline that keeps **implementer + reviewer + ui_reviewer + committer** for
anything that matters. The planner is the only stage a leaner variant may drop.
- **Never remove a review stage to go faster.** The reviewer stages are the
independent evidence the operator reviews against; dropping them is exactly how a
regression ships unreviewed.
- The `ui_reviewer` must build, capture and read the actual screenshots, or return
`skipped` with a reason when the change has no rendered surface. Never accept a UI
change approved without the images.
- The committer is the only stage that commits, and it stages only the run's changed
files. Before committing it checks that the change is reflected in the packaged
templates, the repository's guidelines (README and topic docs) and the packaged
skill references, updates anything stale, and states in the commit body what it
checked or that nothing needed updating. It must also select `input.server_changed_files`
(the runner's captured evidence, `references/control.md`) alongside the implementer's
declared `changed_files` and stage their union: an implementer's declared list can be
incomplete, and a captured path it omitted is still this run's change. Its prompt carries
the pre-commit checklist in `references/format.md`; it commits locally and stops, never pushing.
- A run cannot approve its own work. When an item genuinely needs an operator gate
before it continues or commits, insert a `type=human` decision stage
(`references/format.md`); never invent a model stage that pretends to approve.
- Choose per item: a logic, server or format change usually wants the planner
(a plan/implement/review pipeline); a small, fully understood tweak may use the
leaner implementer-first variant. Both keep all review stages.
## Running and watching
- Launch with the authoritative `CLI_PREFIX` (`pipelines run`). The brief text is the
run's task; pass it whole. Read `references/operations.md` for the exact flags —
`--json`, confirmation (`--yes`) and `--wait`/`--wait-timeout`.
- **Model overrides at launch.** Use `--model PROVIDER/MODEL` to override the model
for every model stage of that run, and repeatable `--stage-model
STAGE=PROVIDER/MODEL` to override individual stages. Precedence is per-stage >
whole-run > the model pinned in the pipeline version. Overrides apply to that run
only (the pinned pipeline is never edited), are validated before the run starts,
and are recorded on the run; `retry` reuses them. See `references/harnesses.md`
for how a stage's model and its repair path both use the effective model.
- Watch to a **terminal state** (`succeeded`, `failed`, `canceled`, `interrupted`).
Poll `CLI_PREFIX inspect RUN_ID --json` (or use `--wait`) until terminal. A reached
client wait limit is not a run failure: the run stays active; keep waiting or
reattach with the original request key, never start a duplicate run.
- Read the **outcomes**, not just the status: the option each stage returned, the
evidence it recorded, and any run or step diagnostic. Interpret diagnostics by
category (`references/debugging.md`).
- **Retry once, then record and continue.** Retry a failed or interrupted item at
most once. If it fails again, record the brief as failed and move to the next item;
never loop or start duplicates to force a pass.
- **Stop the chain on failure and verify by hand.** Do not push the next item on top
of a broken tree. Inspect the failure, fix the pipeline or service cause, and
verify the tree by hand before continuing. Report the failure; never hide it by
re-running until something passes.
## What the operator reviews
From the run record alone, the operator must be able to see: the brief, the changed
files and diff, the reviewer's exact commands and observed results, the screenshots
the visual reviewer read, and the commit. Produce those, and say plainly what was
**not tested** (`references/verification.md`).