programing-pipeline

Programming Workflow

A multi-agent programming workflow independent of specific products and tools: defines the collaboration contract among the main agent, execution sub-agents, and review sub-agents, as well as rules for task tickets, acceptance tests, evidence, recovery, and merging. Does not specify how sub-agents are invoked, commands, or notification methods.

Applicable Scenarios

Used when AI agents modify, refactor, fix, extend, or verify Git projects, especially tasks requiring isolated worktrees, independent review, and real testing.

The executing agent must be able to read and write project files, run build/test commands, create Git worktrees, and create sub-agents; if capabilities are insufficient, mark the evidence boundaries in the results—single-agent self-check ≠ independent review. A successful return from the main agent, an increase in test count, an exit code of 0, or the existence of a report file cannot by themselves represent product completion.

Role Contracts

User: provides goals and priorities; adjudicates real design decisions, external authorization, and irreversible risks.
Main Agent: read state → break down tasks → write task tickets + item-by-item acceptance tests → dispatch after the commit is frozen → schedule execution/review sub-agents → verify all evidence and re-run key acceptance checks → update task tickets/roadmap → merge after all gates pass and re-verify in the main worktree. Does not write business code on behalf of execution sub-agents by default; at real decision points, preserve the scene and stop rather than guess.
Execution Sub-agent: in the specified worktree, implement the frozen task ticket following red→green→blue; run acceptance commands and necessary regression; write the execution report only in its own task evidence directory. Does not modify frozen goals/scope/acceptance tests, and does not expand the product design on its own.
Review Sub-agent: in an independent context, read the task ticket, code, and execution report; personally re-run acceptance tests; check correctness, boundaries, scope, coverage, and evidence freshness; report BLOCKED/FAIL upon finding problems. Read-only by default, does not modify product code.

Main Agent Phase-Advancement Invariants

The main agent treats execution/review sub-agents as stage-level tool calls. A sub-agent's return only proves that stage returned, not that the task is complete; the main agent must not end the current task merely because it received a sub-agent result, saw a test summary, or has already written a stage summary.

After each sub-agent returns, the main agent must re-read the current task ticket, Git/worktree identity, and this round's .workflow/<task-id>/ evidence, and verify the task-id, branch, HEAD, role, and report freshness.
When the task ticket specifies further stages, the main agent must continue to the next stage rather than first sending a summary to the user; a stage report is not a termination condition.
The standard loop is: execution sub-agent → independent review sub-agent → main agent final check → post-merge re-verification in the main worktree. Passing review does not equal passing the main agent's final check.
When a sub-agent returns FAIL, BLOCKED, times out, or evidence is missing, the main agent must classify it and, per the recovery rules, preserve the scene, create a continuation task, or report the blockage; it must not rewrite stage results as PASS, nor skip subsequent verification.
Only when all final evidence for the current task is complete, or when encountering a blockage that requires user adjudication, external authorization, or cannot be self-healed, may the main agent end this round. After completing the current task, stop as agreed with the user and do not automatically start the next task.

Facts and Context Rules

Facts may only come from files, command outputs, or test artifacts directly read in this round; inferences must be marked as inferences, and anything not executed or not read must be marked as unverified—results must not be fabricated.
PASS must be traceable to the current task-id, HEAD, worktree, branch, full command, exit code, key assertions and artifacts; notifications, agent self-reports and old reports cannot substitute for current evidence.
The main agent reads this file and the relevant references on demand and does not load all materials by default; delegation briefs convey only the task identity, frozen contract path, allowed scope, acceptance IDs/commands, decision points and report format, and further reading is expanded only when evidence is insufficient.

Mechanical tools and project-level feedback

Mechanical checks and statistics are performed by the pipeline_tools command program built into this skill; do not depend on the deprecated standalone programing-pipeline-tools worktree. The skill only specifies when to invoke them and the boundaries of judgment. A new task ticket must include the pipeline-contract machine block, validated by pipeline-tools task validate ; run before task execution task preflight, during execution use command run for unified timeouts and logs, for scope use scope check, run before formal evidence validation evidence readiness, and before and after merging use evidence verify and gate。

The exit codes and raw logs output by tools are mechanical facts; terminal summaries do not replace logs.
Run runtime preflight before dispatching an executor/reviewer to confirm Node/pnpm/Git, native ABI and the test capabilities required by the project; an environment mismatch must not be disguised as a product failure or used to continue formal acceptance.
After the subagent starts, first execute runtime handshake: confirm the task and worktree are readable, the acceptance commands are executable, and .workflow/**is writable; the reviewer may not write product code; the handshake JSON must land in the current task's evidence directory.
The main agent may not modify product code without explicit user authorization; after an executor/reviewer failure it should re-dispatch, establish a continuation, or preserve the decision point, and must not take over the implementation.
OpenCode Desktop sessions can use metrics import-opencode-session to import structured process signals; the importer must not infer a product PASS from natural language.
Programmatic commands should preferentially use --format json --output <path>; the JSON result is the authoritative input for subsequent stages, and short terminal summaries are not used as a source of process state.
Use lifecycle status to obtain the current stage and allowed/forbidden actions; semantic agents may only submit recommendations/findings and cannot directly treat natural-language conclusions as gate state.
The structured execution loop uses dispatch write、result verify and freshness; only when the current task-id, role, HEAD, acceptance results and evidence references all pass mechanical validation can the semantic agent's recommendation be handed to the next stage.
When tools are unavailable, commands time out, evidence is missing, or identity/scope drifts, mark it as BLOCKED/drift, and do not bypass the tools by rewriting it as PASS.
Reports must include a machine-readable pipeline-evidence block; natural-language reports cannot alone produce an acceptance conclusion.
Each non- metrics of pipeline-tools stage command by default automatically writes a observed result event to the project .workflow/metrics/; timeouts, environment blocks, evidence gaps, scope drift, etc. only append derived feedback events based on mechanical exit codes and structured results. This directory should be Git-tracked as an auditable history of process improvement.reported can only retain traceability; statistics do not participate in acceptance and do not automatically rewrite skills or contracts.
Automatic collection must not infer a product PASS from natural-language reports; it must not record prompts, full command output, credentials, tokens or business data. Use only for tests/explicit diagnostics PIPELINE_TOOLS_DISABLE_AUTO_METRICS=1 to disable.
formal evidence verify before running evidence readiness; when final-check or required reports are missing, record "not ready"; do not mistake stage-order issues for product acceptance failures. Prefer explaining metric reports by task/run/terminal dimension; do not substitute project-wide cumulative success_rate for terminal-state conclusions.
Normally only put a short summary into context; keep full outputs, reports and statistical events in project files, and read them when diagnosis is needed.

Non-negotiable rules

Task ticket before implementation: the contract must be committed before creating a worktree or dispatching.
Contract freeze: do not change acceptance tests to accommodate implementation; record design changes as rulings and open continuation tasks (machine task-id/path retained continuation), preserving the original history.
Acceptance tests are the cases: each must point to the current test file, case, assertion, command, and result boundary.
Independent review: directly re-verify in an independent context; relaying others' results does not count.
Evidence belongs to the current task: task-id, worktree, branch, test output, and report path must be consistent and generated in this round.
Real链路 cannot be replaced: unit/component/protocol/persistence/real browser/device each prove their own boundaries.
Post-merge re-verification: worktree passing ≠ main worktree passing (dependencies, build artifacts, native modules may differ).
Bounded timeouts: a single test has a default hard limit of 3 minutes; on timeout, stop and diagnose; for the full suite use a larger explicit cumulative limit.
Stop at decision points: when product decisions, protocol compatibility, permissions, external services or acceptance environments are missing, preserve the scene and escalate; do not decide on the user's behalf.
Count ≠ coverage: green counts, exit codes, completion notifications, report existence, and increased lines of code cannot alone constitute PASS.

Standard lifecycle

Recovery check: read entry documents, roadmap, task pointers, Git status, and existing evidence; if multiple active tasks or inconsistent states are found, reconcile first; do not blindly re-dispatch or rebuild the scene.
Planning and breakdown: use user behavior or verifiable capabilities as units; define dependencies, scope, contracts, risks, decision points, and the acceptance matrix; if not written as concrete cases, the design is not complete. Execute sequentially when there are artifact dependencies; parallelize only when file scopes and fixtures do not overlap at all and there are no implicit dependencies.
Freeze the task ticket: default docs/tasks/<task-id>.md, evidence .workflow/<task-id>/; after committing the task ticket, record the contract commit; before creating a worktree, confirm the relationship between the main branch HEAD, the new worktree, the branch, and the contract commit; thereafter the contract is frozen.
Execution: subagents implement only in the task worktree; user features must run through UI→frontend/protocol→core→domain facts→persistence/projection→display→restart recovery; pure infrastructure tasks are marked prerequisite and must not masquerade as product closed loops.
Independent review: new context verifies identity and report freshness, re-verifies item by item; passing ≠ merged.
Final check: read task ticket/execution/review/final-check reports, spot-check high-risk tests, rerun key acceptance, full tests, build, lint, scope, and conflict checks; only with all evidence is it ready-to-merge.
Merge re-verification: commit implementation + evidence, merge using the branch ref; reinstall dependencies in the main worktree, rerun focused acceptance, full tests, build, lint, and diff checks; only after passing mark as merged.
Persistence: update the acceptance ledger, execution records, continuation task index, final results, roadmap, and task pointer; the completion notification includes the project, task-id, stage, branch, merge commit, acceptance status, and outstanding items.

Minimum evidence directory requirements

.workflow/<task-id>/ Must contain at least executor-report.md、review-report.md、final-check.md; each document must state the task-id, worktree, branch, round, command, exit code, key assertions, and evidence file. Old task directories serve only as history.

Task scale and continuation tasks

For tasks containing multiple independent domain aggregates, acceptance families with more than ten fixtures that do not share fixtures, or multi-platform tasks, first split them into independently reviewable slices.
Record implementation failures, missing evidence, environment blockers, and design changes separately; when the design or contract changes, create a continuation task using a new ID, new task ticket, and new evidence directory (machine ID/path retain continuation); the parent task's failures, rulings, and already-accepted parts must not be overwritten.
Preserve the implementation and evidence as they are; do not delete worktrees, branches, or reports without reason.

Reference files (read as needed)

Concern	File
Task ticket template	`templates/task-sheet.md`
Planning, splitting, contract freezing	`references/task-design.md`
Acceptance matrix, evidence completeness, conclusion classification	`references/acceptance-evidence.md`
Execution/review sub-agent rules, main agent final check	`references/execution-and-review.md`
Recovery, merging, main worktree re-verification	`references/merge-and-recovery.md`
Real browsers, devices, multi-layer evidence	`references/live-and-browser.md`
Cross-medium operation failure matrix	`references/multi-medium.md`
Task ticket structure validation	`scripts/validate_task_sheet.py`