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.
52 lines
2.5 KiB
Markdown
52 lines
2.5 KiB
Markdown
# 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.
|