36fad7d130
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.
174 lines
9.6 KiB
Markdown
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`).
|