Files
pipelines/internal/author/skill/references/orchestration.md
T
alan 5090f1cf4e Pipelines skill: outcome-first output, aligned review and loop guidance, operator material moved to docs
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.
2026-11-04 17:27:01 +00:00

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.