5090f1cf4e
Rewrite format.md around turn files, the output.md order (# outcome, edge word, # handoff, detail), checks, configs, human stages and the land stage delivery gate (sh -c in a fresh detached worktree, clean checkouts incl. untracked, 64 KB output cap, opencode only). Align review guidance across practices, verification, orchestration and the feedback-loop example. Fix loop-limit semantics in control.md against runner.go, budget_tokens sizing, read for large inputs, blocked-else-error and one stage naming set. Move dated verification logs to docs/verification-history.md and brokered chat, TUI keys and harness internals to docs/operator-reference.md; label operator-only references in SKILL.md.
4.7 KiB
4.7 KiB
Good practices
Pipelines are written by models through this skill, and a run's cost is roughly
model calls × context per call. Most waste comes from stages that re-read or
re-generate large output. pipelines validate enforces the mechanical rules
below (errors block publishing; warnings print and do not).
Where work belongs
- Deterministic checks belong in the server
checksblock, not the model. Thelandstage setsdelivery=trueand lists the full check commands; the server runs them on the committed candidate (references/format.md, Delivery gate). A model running the suite puts every log line into its context, and every later call pays for it again. implementruns focused tests only: the test file or package it touched, with quiet or summary output. Never the full suite.reviewreads the changed hunks, not the repository. Start from the server-captured changed-file list the runner adds to the prompt andgit diff --stat, then read per-file diffs and only the code around them. Review runs no suites; it judges the reported checks and names missing coverage.landrelies on server checks. With a delivery gate its prompt commits and stops; it does not re-run what the gate runs. Do not claim "the server lands it" unless a stage hasdelivery=true(error otherwise).- Every stage that can modify the workspace declares
checks, even if onlynone: <reason>. Checks must fail when a tool is missing: no|| true,[ ! -x tool ] || ...or similar guards (error). Cover every language the run can change.
Prompts
- Short stage prompts: the goal and the real constraints. Over 2000 bytes warns. Shared procedure belongs in project docs or this skill.
- No runner boilerplate. The runner already explains
output.md, the# outcomeand# handoffsections, allowed outcomes, turn files, tools and honesty rules. Repeating them warns. - Every outcome a prompt names is a declared edge. "Return skipped" with no
skippededge, or an undeclaredblocked_retryable, fails the stage at run time; validation rejects it (unquoted outcome words such asskipped,blocked,rejected,approved,advisory; other back-quoted words after return/report warn). - Missing tools or evidence: declare
blockedwhere a stage can lack required input; the runner tells the model to chooseblockedwhen declared, elseerror.
Memory and handoffs
- The runner inlines the essential
memory.mdinto every prompt and asks each stage for a short# handoffafter its# outcome(references/format.md). Do not repeat that instruction; say only what this stage's handoff must carry if it is special. - The full
history.mdandinput.mdare on demand for stages withread. Never tell a stage to read the whole history every visit (warning); say when it needs it, e.g. "read history.md only if the handoff lacks a detail you need". - A stage without
readgetsinput.mdinlined (up to 32 KB) on every call. Givereadto any stage that follows a large output so it reads detail only when needed.
Loops and budgets
- Loops get limits. Put
{"max_visits":3,"on":["rejected"]}on the reviewer; leave the loop target unlimited or capped at least as high (references/control.md). - Re-entry gets only findings: a rejected review hands back must-fix items
with location and fix, and the implementer fixes those items rather than
redoing the task. Use
advisoryfor non-blocking notes so they do not buy another loop. budget_tokensonly when the user asks or a measured visit exists (pipelines inspect RUN_ID --json,usage.tokens_total). Size it 3–5× that visit, remembering totals include cache reads, so a normal visit never trips it.
Commands and scope
Every earlier tool result is re-sent on each later model call, so output a stage reads once is paid for on every call after it.
- Quiet commands: use the project's quiet/summary test or analyze wrapper (failures only plus a log path) and summary flags; never print generated or vendored files.
- Diffs:
git diff --stator--name-onlyfirst, thengit diff -- <path>only for the files you need. Never a full diff orgit log -p. - Files:
grep/globfirst, then read only the relevant line range. Read a whole file only when it is short or mostly being edited, and do not re-read a file that has not changed. - Logs: when a test log is needed, grep the log path for the failing test instead of reading the log whole.
- Batch independent tool calls into one step instead of one call per step.
- Small task scope: one independently testable change per run (roughly a 10–15 minute change). Split larger work into several runs in parallel.