4.4 KiB
4.4 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. The landing stage setsdelivery=trueand lists the full check commands; the server runs them on the committed candidate. A model running the suite puts every log line into its context, and every later call pays for it again. - Code runs focused tests only: the test file or package it touched, with quiet or summary output. Never the full suite.
- Review reads the diff, not the repository. Start from the server-captured
changed-file list the runner adds to the prompt and
git diff --stat, then read only the changed hunks and the code around them. Review runs no suites; it judges the reported checks and names missing coverage. - Land/committer relies 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 has
delivery=true(error otherwise). - Every stage that can modify the workspace declares
checks, even if onlynone: <reason>(references/format.md, Checks). 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 (internal/stage/model_prompt.go). 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).
Memory and handoffs
- The runner inlines the essential memory (
memory.md: task, previous stage's handoff, outcome ledger, changed files; capped) into every prompt, and asks each stage to start its output with a short# handoff: what it did, outcome, files changed, open findings, in a few lines. Do not repeat that instruction; say only what this stage's handoff must carry if it is special. - The full history (
history.md) and fullinput.mdare on demand. 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".
Loops and budgets
- Loops get limits. An edge back to the same or an earlier stage needs
limitson the source outcome or the target (error). Usemax_visits2–3. - Re-entry gets only findings: a rejected review hands back must-fix items
with location and fix, not a full re-review, and the implementer fixes those
items rather than redoing the task. Use
advisoryfor non-blocking notes so they do not buy another loop. - Set per-stage
budget_tokens(andbudget_usdif wanted) as a runaway guard on stages that loop or explore, sized a few times a normal visit.
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.