Entry/Exit
- Entry:
build-workflow-plancompleted, task list is ready - Exit: all tasks completed + tests passed + code merged
- Points to: after all tasks are completed, suggest
/review - Output Path: → verify-workflow-review
- Preloading: CANON.md +
build-quality-tdd/SKILL.md+build-workflow-execute/SKILL.md
When Not to Use
- There is not yet an approved plan or task list
- Currently only exploring, diagnosing, or writing spec/design, not entering implementation
- There is only one tiny document or configuration change, and no execution mode needs to be selected
Task Input Contract
The execution engine only consumes the /plan approved task list:implement this plan task-by-task。
- Each
### Task Nis an execution unit and must have acceptance criteria and verification evidence plans/*.mdsub-plans are also execution units; within a sub-plan, execution still proceeds item by item according to### Task NExecute item by item- The engine can choose inline / subagent / parallel, but cannot recreate the formal task list
- Any subagent input must be bound to an explicit
Task Norplans/*.mdsub-plan
Subagent Operating Principle
The goal of a Subagent is to isolate high-noise context, execute specialized tasks, and compress decision-ready information; parallelism is only an optional benefit, not the default goal.
Suitable for dispatching a subagent:
- Large amounts of search, logs, test output, diffs, or file reads would pollute the main session
- The task can be completed independently, and the main session only needs a summary, evidence, risks, and next steps
- Tool permissions, Read Scope, or Write Scope need to be restricted
- Multiple modules, assumptions, or risk points can be verified independently
Not suitable for dispatching a subagent:
- Small changes, simple formatting, continuous editing of a single file
- Decisions that require frequent confirmation from a human partner
- Strong shared context between plan -> implementation -> testing that must be continuously judged by the main session
- The output summary would be longer than the task itself
Each dispatch must clearly state: Goal, Task Source, Selected Persona, Read Scope, Write Scope, Forbidden Actions, Allowed Tools, Output Limit, Completion Criteria.
Default to read-only first; only implementer / debugger type tasks allow Edit / Write.
Returned content must not include raw logs, complete diffs, large blocks of code, lengthy reasoning, or irrelevant background. By default, compress to within 1200 words; the last line must be single-line JSON:{"status":"...","changed_files":[],"test_results":[],"artifact_paths":[]}。
Agent Dispatch Contract
When the execution engine selects an execution mode, it must also select an explicit persona; persona selection does not change Task N / Write Scope / Verification Evidence.
- Plan / mode selection →
agents/task-planner.md - Software implementation →
agents/software-engineer.md - API contract task →
agents/api-designer.mdfirst, thenagents/software-engineer.md - Data schema / migration task →
agents/data-architect.mdfirst, thenagents/software-engineer.md - Document / article task →
agents/content-writer.md - Deck task →
agents/content-writer.mdfor narrative first, thenagents/visual-designer.mdfor layout - Visual task →
agents/visual-designer.md
Mode B fan-out can use different personas in parallel only when their Write Scope does not overlap and semantic independence is explicit. Mode C implementer/reviewer prompts must name the selected persona and include its required skills, inputs, outputs, scope, allowed tools, output limit, and completion criteria.
Three Execution Modes
Mode A: Direct Execution
The main agent executes in the order of ### Task N . Suitable for single-file modifications, simple bug fixes, and configuration changes.
Rule: implementation → test verification → record/commit → next Task N. Do not proceed to the next until the current Task N verification passes. Each task has < 100 lines of changes. Do not open multiple implementation branches at the same time.
Mode B: Parallel Fan-Out
When facing 2+ truly independent Task N or plans/*.md sub-plans (no shared files, no shared state, no sequential dependency), dispatch all at once.
Rule:
- One message dispatches all subagents (true parallelism)
- Each subagent has an independent context, independent files, independent results
- Parallel inputs must come from an explicit
Parallel Execution Matrixinparallel_safe: yestask or sub-plan - Each subagent may only modify the
Write Scope - after dispatch → wait for results → review → merge
Parallelism forbidden: tasks have dependencies, modify the same file, share DB schema changes, share API/type/flag/config/test contracts not yet frozen, sub-plans lack Write Scope / Verification Evidence / Merge Checkpoint / Cross-check Command / Semantic Independence Reason, release/export/ship finalization sub-plans.
gated-parallel
When Plan Topology is gated-parallel: the main agent first executes contracts/gated/serial sub-plans serially → shared contract verification passes → only then dispatch the parallel_safe sub-plans that depend on that contract. When the contract changes, all dispatched sub-plans are void.
Dispatch template: Each subagent must specify Goal, Task Source, Selected Persona, Write Scope, Read Scope, Forbidden Actions, Allowed Tools, Shared Contracts, Global Invariants, Verification Evidence, Cross-check Command, Merge Checkpoint, Output Limit, Completion Criteria. The last line of output is JSON containing status + changed_files + test_results + artifact_paths.
Mode C: Subagent Pre-Review Gate pipeline
Used for highly complex tasks (crossing multiple modules, critical business logic, requiring security review).
Flow: Implementer subagent → returns status → Spec Gate subagent (independent verification) → Code Quality Gate subagent (five-axis review).
Positioning: This is an internal fuse for the build phase, not formal /review. Passing this gate only means "allowed to continue integration / enter the formal review candidate", not "formal review already completed".
Key rules:
- Implementer input must contain the specific Task N / sub-plan path, acceptance criteria, Write Scope, Verification Evidence
- Implementer / reviewer input must contain Allowed Tools, Forbidden Actions, Output Limit and Completion Criteria
- Each subagent has a fresh context — do not pass the previous subagent's conversation history
- Spec Gate does not trust the Implementer report — independent verification
- Code Quality Gate must start only after spec compliance is confirmed
- Parallel dispatch of Implementer is strictly forbidden
- Serial gating in the review phase: Spec Gate first, and only after SPEC_MATCH dispatch Code Quality Gate
- Mode C results must not be written as APPROVED / LGTM / READY TO MERGE; formal
/reviewstill requires separately producing04-review.md
Prompt template: Use implementer-prompt.md、spec-reviewer-prompt.md、quality-reviewer-prompt.md。
Subagent model selection
| Complexity | Model | Applicable to |
|---|---|---|
| Low | Haiku / cheap model | Boilerplate code, formatting changes, copy-paste refactoring |
| Medium | Sonnet / standard model | Routine implementation, CRUD, frontend components |
| High | Opus / most capable model | Core business logic, complex algorithms, security-critical code |
Principles: Don't skimp on what shouldn't be skimped on. Use Opus for Entity relationship refactoring, use Haiku for changing color variables.
Fan-Out merge
After parallel agents return: all DONE → merge changes + run full tests; any failure → revert the failed agent's changes + redispatch; any conflict → merge the valid parts + handle conflicts manually.
Required before merging:
- Each agent's tests pass
- The full test suite passes (cross-impact detection)
- Each sub-plan's
Cross-check Commandhas been run and passed - No file conflicts
- The Task N bound to each agent returns DONE or BLOCKED
- changed_files ⊆ Write Scope
- Verification Evidence and Merge Checkpoint have been satisfied
When not to use these patterns
- Don't use Pattern B when the task has sequential dependencies/shared files, or
Parallel Execution Matrixhas not provenparallel_safe - Don't use Pattern C when the task is simple enough for 1 agent to finish in 20 minutes — two-phase review is insurance for complex tasks, not a process tax
- Don't use subagents to handle decisions that require real-time human confirmation — the main agent should ask directly
- Don't use subagents to handle a series of small edits within the same file — serial execution by the main agent is clearer
- Don't use subagents just to "open a few more agents" — if there's no value in noise isolation, narrowed permissions, or independent verification, keep it inline
Common rationalizations
| Rationalization | Reality | Consequence |
|---|---|---|
| "Dispatching is too slow, I'll just write it myself" | 1 complex task done by a subagent in 15 min > 2 h of your guessing. 3 in parallel at 15 min vs 45 min serially. | Main agent guessing at the implementation > 30-50% single rework, total time 2-3x |
| "Parallel won't conflict" | Two agents editing the same file = guaranteed merge conflict. | Manual merge conflict resolution > 30 min/conflict; in severe cases, all changes from one agent are discarded |
| "It was already reviewed in the build, no need for /review" | Mode C is only a pre-review gate and cannot replace formal /review。 |
Lack of independent formal review → merge quality gate fails → rework and missed-detection risk compound |
| "Skip the review, the code looks right" | Two-phase review prevents errors where code "looks right but doesn't match the spec". | No review → Implementer deviates from spec → non-compliant code merged in → rework > 2x |
| "Dispatching again will be the same" | First deviation → add constraints → only then can the second attempt be right. | Redispatch without adding constraints → same deviation → 3 cycles wasted 45+ min |
| "Opening a few more agents is safer" | Subagents with no defined goals, tools, or output limits turn noise into multiple noise summaries. | The main session is polluted by duplicated context, full logs, and irrelevant suggestions, degrading decision quality |
Red flags — STOP
- No clear
Task Nor sub-plan but dispatching a subagent - Subagent dispatch lacks Goal / Scope / Forbidden Actions / Allowed Tools / Output Limit / Completion Criteria
- Pattern B tasks are not truly independent of each other (implicit dependencies or shared files)
- Subagent reports "DONE" but has no changed_files list
- Subagent returns raw logs, full diffs, large code blocks, or long reasoning
- Spec Gate reports SPEC_MATCH but provides no independent verification evidence
- Implementer returns ISSUES 3 times in a row — the constraints/task description may be problematic
- Two parallel agents are modifying the same file — roll back, serialize
- subagent modified a file outside the Write Scope — roll back the change, re-dispatch, or execute serially
parallel_safenot fromParallel Execution Matrixexplicit conclusion — stop parallelism- Sub-plan missing
Cross-check CommandorSemantic Independence Reasonyet marked asparallel_safe - Code Quality Gate found an issue that Spec Gate should have found — the review order is wrong
- Subagent context does not contain the spec document — working blind
Verification Checklist
- Execution mode matches the nature of the task (independent/dependent/complex)
- Parallel task files do not overlap
- Shared contracts, global invariants, and semantic independence for parallel tasks are explicitly documented
- Multi-plan fan-out uses only
parallel_safesub-plans - Each execution unit is bound to an explicit
Task Nor sub-plan - Each subagent has a sub-plan path, Write Scope, Read Scope, Verification Evidence, Merge Checkpoint, Cross-check Command
- Each subagent has Forbidden Actions, Allowed Tools, Output Limit, Completion Criteria
- Each subagent returns a compressed summary, with the last line being JSON with status / changed_files / test_results / artifact_paths
- changed_files did not exceed the Write Scope
- Two-phase review order is correct
- Full test suite passes after merge
- No state where it "looks DONE but has no evidence"
Verification Failure Handling
| Failure Scenario | Handling Method |
|---|---|
| Implementer returns BLOCKED | Human intervention. Do not guess the reason, do not silently skip |
| Implementer returns NEEDS_CONTEXT | Provide more context, re-dispatch |
| Spec Gate returns SPEC_GAP | Send back to Implementer for correction, listing the specific gaps |
| Code Quality Gate finds an issue that Spec Gate should have found | STOP, redo the Spec → Quality order |
| Implementer returns ISSUES 3 times in a row | STOP. Go back to /plan to patch, do not dispatch a fourth time |
| Parallel agent changed_files out of bounds | Roll back the out-of-bounds agent, downgrade to serial execution, or re-cut the Write Scope |
| Parallel agent file conflict | Merge the valid parts, redo the conflicting parts serially |
| Cross-check Command fails | Treat as uncontrolled semantic coupling, roll back the related parallel results and downgrade to serial execution |
| Full test suite fails after merge | Locate the failing agent, roll back its changes, and rerun after fixing |
Output Template
### Execution Engine 交付记录
**执行模式**: [inline / subagent / parallel fan-out]
**任务来源**: [03-plan.md Task N / plans/*.md 子计划名]
**任务完成状态**:
| Task N | 状态 | changed_files | test_results | 验证证据 |
|--------|------|--------------|-------------|---------|
| [Task N] | DONE / BLOCKED / NEEDS_CONTEXT | [文件列表] | [通过/失败] | [描述] |
**并行结果**(如适用):
- Agent 1: [status] — Write Scope: [范围] — changed_files ⊆ Write Scope ✓/✗
- Agent 2: [status] — Write Scope: [范围] — changed_files ⊆ Write Scope ✓/✗
**Cross-check 结果**: [命令 + PASS/FAIL]
**合并后全量验证**: [通过 / 失败 — 具体原因]