SuperAPI AI Directory

build-cognitive-execution-engine

General & other

View repository

Updated 10-16 09:45

About this skill

Execution Engine — 3 Execution Modes

Entry/Exit

  • Entry: build-workflow-plan completed, 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 N is an execution unit and must have acceptance criteria and verification evidence
  • plans/*.md sub-plans are also execution units; within a sub-plan, execution still proceeds item by item according to ### Task N Execute 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 N or plans/*.md sub-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.md first, then agents/software-engineer.md
  • Data schema / migration task → agents/data-architect.md first, then agents/software-engineer.md
  • Document / article task → agents/content-writer.md
  • Deck task → agents/content-writer.md for narrative first, then agents/visual-designer.md for 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 Matrix in parallel_safe: yes task 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 /review still requires separately producing 04-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 Command has 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 Matrix has not proven parallel_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 N or 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_safe not from Parallel Execution Matrix explicit conclusion — stop parallelism
  • Sub-plan missing Cross-check Command or Semantic Independence Reason yet marked as parallel_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_safe sub-plans
  • Each execution unit is bound to an explicit Task N or 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]
**合并后全量验证**: [通过 / 失败 — 具体原因]