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.
2.5 KiB
Small tasks and execution
Choose the simplest reliable route: direct work, delegation or a pipeline. The manager remains responsible for completion and may take over any role directly.
An item
One item changes one observable behavior. State its goal, relevant files, a few testable acceptance checks and scope boundaries. Avoid long history, invented implementation plans and boilerplate rules already in the project map. Separate independent features even when they share a file; resolve small hunks at integration. Serialize only actual dependency or resource conflicts.
Stage jobs
plan: a short approach and acceptance checks when they help.implement: the focused change, tests and focused checks.review: the changed hunks (server-captured changed list,git diff --stat, then per-file diffs) and the reported checks; it runs no suites.ui-review: rendered behavior with controlled data and captures.decide: a human choice between edges.land: commit the reviewed work; the delivery gate checks and lands it.
Names are a convention, not a requirement; a pipeline can use any clear stage names. Keep each stage's job narrow enough to judge its output.
Hand off the desired behavior and the evidence that should exist at the end, not another stage's restrictions. A clean worktree is a successful no-op for preparation, not a failure. Nonvisual work needs no rendered evidence; a visual change does.
Pipeline choice
Prefer the smallest workflow that makes the work verifiable: plan when the design is genuinely uncertain, review when a change is risky or broad, and a visual survey when appearance is the question. Stage names describe jobs, not fixed roles. Read the project's own maps and commands instead of assuming an area layout. Keep models and costs as agreed.
Recovery and landing
Inspect pipelines inspect ID --json and actual files after failure. Preserve
partial changes. Prefer resuming the original stage with corrected input or fixing
and merging directly; do not repeat completed work or add a merger pipeline.
For delivery=true, return a clean checked candidate and let the server land it.
For direct recovery, merge safely and verify it. Only then check ancestry.
Record real failures without blocking unrelated progress. Never delete branches.
Use pipelines wait ID as a background wait for active runs; no polling driver.
Record stale docs in a per-item note unless documentation itself is the task.
Keep reports short and separate code, testing, landing and deployment status.