SuperAPI AI Directory
Partner中文AI newsFavorites
Skillsbuild-workflow-execute

build-workflow-execute

Office & productivity

View repository

Updated 10-16 09:45

About this skill

Execute — incremental generation

Entry/Exit

  • Entry: Approved plan (docs/features/<name>/03-plan.md + optional docs/features/<name>/plans/*.md）
  • Exit: Software code or content artifacts + verification evidence + ADR (if there are decisions)
  • Points to: Done → verify-workflow-review; Bug encountered → verify-workflow-debug
  • Output path: → verify-workflow-review
  • Preload: CANON.md + build-quality-tdd/SKILL.md + build-cognitive-execution-engine/SKILL.md

When not to use

  • Exploratory prototype (annotated // UNTESTED may skip TDD, but is subject to HARD GATE constraints)
  • Pure configuration changes (adding environment variables, changing CI configuration) — commit directly, no incremental loop needed

Prerequisites

First read the plan topology, then call build-cognitive-execution-engine to select the execution mode.

Reading order:

  1. Read docs/features/<name>/03-plan.md master control plan
  2. If docs/features/<name>/plans/*.mdexists, read the subplans one by one in file number order
  3. Confirm from the master control plan Plan Topology、Subplans、Parallel Execution Matrix、Integration Order
  4. Verify that every subplan has Write Scope、Read Scope、Shared Contracts、Global Invariants、Parallel Safety、Verification Evidence、Cross-check Command、Merge Checkpoint

Task-by-task Execution Contract

For execution: implement this plan task-by-task.

  • 03-plan.md each ### Task N in is the /build smallest execution unit.
  • plans/*.md each ### Task N in is the smallest execution unit within that subplan.
  • Do not proceed to the next Task N until the verification step of the current Task N passes.
  • Only when Parallel Execution Matrix explicitly proves parallel_safe: yes is it allowed to execute multiple tasks or subplans in parallel.
  • /build Do not recreate the task list. If during execution a task is missing, acceptance criteria are missing, or a slice cannot be executed, record PLAN GAP, and if necessary return to /plan to patch it.
  • During the build phase, any pre-review / implementation gate result is only used as an internal quality gate and cannot replace formal /review

Execution mode:

  • inline — Execute directly in the current session
  • subagent — One new subagent per task or per complex subplan, used to isolate high-noise context, perform specialized execution, and compress conclusions + two-stage review
  • parallel — Only for parallel_safe subplan parallel subagents

When selecting a mode, the reason must be recorded:

  • Large amounts of searching, test logs, diffs, file reads, or specialized reviews will pollute the main session → subagent may be selected
  • Multiple subplans parallel_safe: yes and Write Scopes do not overlap → parallel may be selected
  • Small changes, continuous edits to the same file, strongly shared context, or frequent confirmation needed → keep inline

Without Parallel Execution Matrix or without parallel_safe evidence, downgrade to serial execution. The reason for downgrade must be written into the build record.

Agent Dispatch Contract

/build The main flow of is controlled by this skill and build-cognitive-execution-engine ; the persona only executes the corresponding Task N or subplan after being selected by a phase skill.

  • agents/task-planner.md: only used to read the plan, extract the task queue, check the Parallel Execution Matrix, and select inline / subagent / parallel; must not be used in /build to rewrite the formal task list.
  • agents/software-engineer.md：artifact_type: software default implementer, executes TDD, implementation, and verification.
  • agents/api-designer.md: execute first when Task N is an API contract, endpoint shape, request/response/error contract, or versioning strategy; after outputting the contract, hand it to software-engineer for implementation.
  • agents/data-architect.md: Execute first when Task N involves schema, migration, indexes, constraints, or data migration strategy; after outputting the data contract, hand it over to software-engineer for implementation.
  • agents/content-writer.md：document / article / deck 's content slicing implementer.
  • agents/visual-designer.md：visual and deck 's layout/visual slicing implementer; deck must wait for content-writer to complete the narrative skeleton before entering layout.
  • Parallel dispatch is only allowed for Parallel Execution Matrix to prove parallel_safe 's Task N or sub-plan; each persona's changed_files must fall within the Write Scope and satisfy the Shared Contracts / Global Invariants / Cross-check Command contract.

Then read the spec's artifact_type, and load domain skills as needed:

  • software(default) → confirm 02-design.md is approved; load build-quality-tdd + load by sub-domain build-frontend-* / build-backend-api-design / build-backend-database / build-backend-service-patterns
  • document / article → load build-content-writing; when layout is involved, load build-content-layout
  • deck → first build-content-writing completes the narrative skeleton → then build-content-layout does the visual hierarchy. Execute sequentially, not in parallel.
  • visual → load build-content-layout, and when copy is involved, load build-content-writing

Plan Topology Execution Rules

serial

Execute directly in ### Task N order. When plans/*.md exists, execute sub-plans in file-number order, and within each sub-plan in Task N order. Do not dispatch parallel subagents.

gated-parallel

  1. First execute contracts / serial / gated sub-plans serially
  2. Verify that shared contracts pass (API, schema, design, content, brand, or export specs are stable)
  3. After confirming Write Scopes do not overlap and shared contracts are frozen, call build-cognitive-execution-engine fan-out
  4. After all parallel sub-plans are complete and verified, first run their respective Cross-check Command, then merge serially and run full verification according to Integration Order Serial merging and full verification

parallel

fan-out must simultaneously satisfy:Parallel Execution Matrix lists parallel_safe: yes, dependencies are complete, there is a clear Write Scope, the Write Scopes of any two sub-plans do not overlap, shared contracts are frozen, and global invariants can be independently verified by Cross-check Command .

When not satisfied: missing Write Scope / Cross-check Command / Semantic Independence Reason → STOP and return to /plan; shared writes → downgrade to serial; release/export/ship marked parallel_safe → STOP closing tasks must be serial; shared contracts incomplete → first execute the contract according to gated-parallel .

Incremental Loop

每个 Task N：实现 → 测试 → 验证 → 记录/提交 → 下一个 Task N

Step 1: Choose a slicing strategy

  • Plan topology first — 03-plan.md When a topology is defined, execute according to the topology
  • Task-by-task first — when the plan has listed ### Task N , execute according to the task queue without merging
  • Vertical slicing (recommended) — build one complete path (DB + API + UI) at a time
  • Risk-first slicing — do the hardest/most uncertain parts first
  • Contract-first slicing — define interface contracts first, then work on frontend and backend in parallel

Step 2-4: Implement → Test → Verify

  • Step 2: implement the minimum code to make the tests pass. Do not abstract prematurely and do not add unrequested features.
  • Step 3: after each slice, run the corresponding verification.software do TDD first (build-quality-tdd）；document/article fact-checking + logic chain + tone;deck narrative line + information density + speaker notes;visual visual hierarchy + alignment + contrast.
  • Step 4：software Tests pass + build succeeds + type check + lint + new feature works as expected; non-software artifact review evidence is complete + the export can be opened and conforms to spec.

Step 5: Commit

Commit with a descriptive message. One commit, one logical change.

Step 6: Loop

Proceed to the next slice, do not start over. In multi-plan mode, the loop unit is the sub-plan: within a sub-plan, loop by task slice; at the end, record changed_files / artifact_paths / test_results; the main agent merges according to Integration Order and runs full verification.

Task deviation handling

  • Blocked (missing external dependency) → record the blocker, skip the current slice, switch to the next independent slice
  • Technical obstacle → STOP. Call build-cognitive-decision-record to record the issue, execute the fallback plan
  • PLAN GAP → STOP. Record the gap, return to /plan to patch, do not create new tasks in build
  • scope creep → record as "NOTED", do not move it out of the current task scope
  • Estimated time doubles → communicate with the user

Discipline rules

Rule 0：Simple First（YAGNI + Rule of Three）

Before writing any code, ask: "What is the simplest thing that works?" Three similar lines of code > one premature abstraction. Do not build an abstraction before the third use case appears.

Rule 0.5：Scope Discipline

Only change what should be changed. If you see something worth improving but unrelated → record NOTICED BUT NOT TOUCHING, do not change it. Do not change adjacent code, do not refactor imports in files you did not change, do not delete content you do not understand.

Rule 1-3

  1. One commit = one logical change. Do not mix refactoring and new features.
  2. After each slice, the project must be buildable and existing tests must pass.
  3. Isolate incomplete features with a feature flag (process.env.FEATURE_X === 'true').

Rule 4-5

  1. New code defaults to conservative behavior, opt-in rather than opt-out.
  2. New files are easy to roll back; minimize modifications; migrations must have rollback; deletion and replacement are not in the same commit.

When encountering an architecture decision → write an ADR

Call build-cognitive-decision-record/SKILL.md, output to docs/features/<name>/adr/<num>-<title>.md。

Verification failure handling

Failure scenario Handling method
Test failure New code → fix until it passes; existing tests → check for regressions and fix
Build failure Check the error message, fix compilation/type errors, do not skip
Checkpoint gate not passed STOP. Mark the failed items → return to the corresponding task to fix → rerun the checkpoint → continue only when everything is green
Sub-plan missing Write Scope / Cross-check Command / Semantic Independence Reason STOP. Cannot dispatch subagent, return to /plan to patch
PLAN GAP STOP. Record the gap, return to /plan to patch
Two parallel_safe sub-plans write to the same path Downgrade to serial or return to /plan to re-split
shared contract / global invariant cross-check fails Downgrade to serial, and if necessary return to /plan to re-split
release/export/ship marked parallel_safe STOP. Closing tasks must be serial
Slice is more complex than expected Assess decomposition. Communicate with the user when the estimated time doubles.
Architectural decision blocker Stop implementation, record an ADR, execute the alternative
Scope creep Record as "NOTED", do not move it out of the current scope

Verification evidence

The output or record must include:

  • Input/source: the spec, plan, code, feedback, or release context that was read
  • Actions performed: the checks, generation, fixes, exports, or release steps actually completed
  • Verification result: commands, review conclusions, artifact paths, screenshots, or manual confirmation
  • Blockers/fallback: failed items, fallback paths, or issues requiring a human partner decision

Common excuses

Excuse Reality Consequence
"Write the code first, run the tests all together at the end" Bugs stack up. A bug in slice 1 makes slices 2-5 all wrong. Delayed bug discovery → localization cost grows linearly → 5 stacked slices ≥ 4h, vs < 5min per slice
"Doing it all at once is faster" It feels faster until you've changed 500 lines and can't find which line caused the problem. Large commit error rollback scope = everything; small commit rollback scope = the last slice, a 10-50x difference
"This change is too small to need its own commit" Small commits have no cost. Large commits hide bugs and make rollback difficult. Mixed commit rollback of behavior changes → formatting is also lost → an extra 30-60 minutes
"Add a feature flag later" If the feature is incomplete, don't expose it to users. Add the flag now. No flag → if something goes wrong you can only roll back the entire deployment → all users affected vs turning off the flag in < 1min
"Refactor a bit while I'm at it" Mixing refactoring into new features makes both review and rollback harder. Mixed commits cannot independently revert the refactoring → formatting improvements are lost

Red flags

  • Wrote more than 100 lines without running tests
  • A single slice contains multiple unrelated changes
  • Did not read plans/*.md before executing a multi-plan task
  • Skipped the ### Task N order and reorganized tasks according to one's own understanding
  • Temporarily created a new formal task list in /build Temporarily create a new formal task list
  • No Parallel Execution Matrix yet dispatching subagents in parallel
  • Subagent modifies files beyond the subplan's Write Scope
  • parallel_safe changed_files conflicts appear between subplans
  • "Let me quickly add this" scope creep
  • Skipping tests/verification to speed up
  • Build fails or tests are interrupted between slices
  • Accumulating a large number of uncommitted changes
  • Building an abstraction before the third use case appears
  • Creating a utility file for a one-off operation

Verification checklist

After each slice:

  • The verification step for the current ### Task N has passed
  • The change does one thing and does it completely
  • All tests pass
  • The build succeeds
  • Type checking passes
  • Lint passes
  • New functionality works as expected
  • Committed with descriptive message

Additional checks for multi-plan tasks:

  • Read 03-plan.md and all plans/*.md
  • Plan Topology Execution mode decided
  • Within each sub-plan, ### Task N Completed item by item with evidence recorded
  • Parallel Execution Matrix Supports all fan-out decisions
  • For each parallel sub-plan, Cross-check Command Passed
  • Each subagent's changed_files did not exceed the Write Scope
  • Full verification passed after merging

Good and bad examples

Good — incremental slicing + TDD

Task 1: User registration API → RED (write a failing test) → GREEN (minimal implementation to make the test pass) → Commit (feat: add user registration endpoint). One logical change, descriptive message.

Bad — large batch + skipping tests

Write 500 lines at once including registration, login, task creation, and list query → no tests, bugs stack up → a single commit contains 4 features, rollback loses everything → no feature flag, everything is exposed if registration fails → no vertical slicing, any step blocking others stalls the rest.

Output template

### Build Execute 交付记录

**Plan 来源**: [03-plan.md / plans/*.md 子计划名]
**执行模式**: [inline / subagent / parallel]
**模式选择原因**: [噪音隔离 / 独立验证 / parallel_safe / inline 简单连续执行]
**artifact_type**: [software / document / article / deck / visual]

**Task 完成状态**:
| Task N | 实现描述 | 测试结果 | 验证证据 | 提交 SHA |
|--------|---------|---------|---------|---------|
| Task 1 | [描述] | PASS / FAIL | [证据] | [SHA] |

**PLAN GAP**（如有）: [缺口描述 + 处理方式]
**ADR**（如有）: [adr/<num>-<title>.md 路径]
**合并后全量验证**: [通过 / 失败]