build-workflow-plan

Plan — Task decomposition

Entry/Exit

• Entry: Approved spec (docs/features/YYYYMMDD-<name>/01-spec.md) + approved design (if required)
• Exit: docs/features/<name>/03-plan.md; large/parallel tasks additionally produce docs/features/<name>/plans/*.md + user approval
• Points to: after the user approves the plan, must call build-workflow-execute
• Output path: → build-workflow-execute
• Preload: CANON.md
• Auxiliary reference: task-templates.md(task templates, Subplan Contract, Parallel Safety determination, code example rules),plan-review.md(detailed Plan Review Army rules)

When not to use

• The change involves only 1-2 files and the scope is obvious
• The spec already contains clearly defined tasks (in this case go directly to build)

Agent Dispatch Contract

/plan The main execution persona is agents/task-planner.md。

• Plan Review Army selects at Step 7.5 according to plan-review.md the minimum trigger conditions agents/plan-ceo-reviewer.md、agents/plan-eng-reviewer.md、agents/plan-design-reviewer.md、agents/plan-security-reviewer.md
• Standard changes require at least CEO + Eng; only large, security, compliance, or --full fully activate it
• Unselected reviewers do not produce placeholder feedback; all selected reviewer feedback is triaged before plan approval

Core anchors

Vertical Slicing

Each task delivers one complete, independently verifiable functional path. Do not slice horizontally by technical layer.

Execution rules:

• Software: one task = one user path (schema + API + UI), do not split into "build all DB → build all API → build all UI"
• Content (document/article): one section = one task (objective + draft + fact-check + editorial verification)
• Deck: one group of consecutive pages = one task (title + content + visuals + speaker notes)
• The word "and" appearing in a task title = a signal to split

Plan Topology

Choose the topology based on dependencies and parallel needs.

Execution rules:

• serial: ordered dependencies, shared files, small tasks → write only 03-plan.md
• parallel: no shared files, no sequential dependencies, and the shared contract has been frozen → 03-plan.md + multiple plans/*.md, mark parallel_safe
• gated-parallel: define shared contracts first, then subsequent work can be parallel → 03-plan.md + plans/01-contracts.md + subsequent subplans
• Implementation order follows the dependency graph bottom-up; only Parallel Execution Matrix marker parallel_safe: yes subplans can run in parallel

Bite-sized Tasks

Each task has 3-7 steps, ≤5 files, and 2-5 minutes of executable actions.

Execution rules:

• Software tasks use the RED → GREEN → REFACTOR structure; non-software uses an artifact slicing + verification evidence structure
• No placeholders allowed: TBD/TODO/"implement later"/"add appropriate error handling" (with no concrete code) = plan failure
• Provide direction and constraints to the executing agent, not a complete implementation (except for complex algorithms/security logic/precise artifacts)

Core flow

Step 1: Enter read-only mode

Do not write code. Read the spec, design, and relevant codebase, identify patterns and dependencies.

Single-plan vs multi-plan decision gate:

• XS/S tasks: write only 03-plan.md
• M/L or cross-subsystem:03-plan.md master control + plans/*.md subplans
• Shared contracts but splittable: write first plans/01-contracts.md, subsequent subplans proceed in parallel based on the contract

Step 2: Identify the dependency graph and Plan Topology (anchor execution)

First read artifact_type to select the dependency graph model (software/content/deck/visual), then select the topology according to the Plan Topology anchor.

Step 3: Determine the file structure

Map out which files will be created or modified. Each file has one clear responsibility; things that change together go together; follow existing patterns.

If 01-spec.md 's Documentation Impact is not feature_only, here you must also map the project doc write surface: which are root docs, which are project docs, and which remain in feature docs。

Step 4: Vertical slicing (anchor execution)

Step 5: Write bite-sized tasks (anchor execution)

See the task template in task-templates.md。

Step 6: Ordering, Topology, and checkpoints

Order tasks so that dependencies are satisfied, the system remains working, high-risk tasks come first, and a verification checkpoint is set every 2-3 tasks.

In multi-plan mode, 03-plan.md must include: Subplans + Parallel Execution Matrix + Integration Order + Shared Contracts. Any subplan without Write Scope / Shared Contracts / Global Invariants / Cross-check Command / Semantic Independence Reason cannot be dispatched; the Write Scope of two parallel_safe subplans must not overlap, and shared contracts must already be frozen.

Step 6.5: Write Project Doc Sync Plan

If the spec declares project_truth_changed: yes or doc_intent != feature_only，03-plan.md , you must additionally write:

• Must update: project-level document paths that must be synced this time
• Optional update: optional sync, but not a release gate
• Stage owner: closed out by which phase, /build、/review or /ship Which phase closes out
• Verification method: how to determine that these documents have been fulfilled
• Deferred docs with reason: explicitly deferred items and reasons

Even if doc_intent: feature_only, you must still explicitly write Project Doc Sync Plan, and explain not-needed。

Step 7: Self-review

After writing the plan, check against the following 10 items:

• Spec coverage: every spec requirement can be traced to a corresponding task
• Placeholder scan: no TBD/TODO/"implement later"/"add appropriate error handling"
• Type consistency: function signatures in later tasks match those defined earlier
• Subplans complete: every plans/*.md exists and has a Subplan Contract
• Parallel safety:parallel_safe subplans have no overlapping writes, and semantic independence is stated
• Closeout order: release/ship-type subplans are serial by default
• Task independence: every task has acceptance criteria, independent verification steps, and dependencies marked
• Verification completeness: every verification step has a concrete command + expected output + failure diagnosis
• Code example style: minimal examples + intent comments, no full implementation logic
• Task granularity: ≤5 files, 3-7 steps, no "and" in the title
• Document sync: if the spec requires syncing project docs, the plan has written Project Doc Sync Plan

Step 7.5：Plan Review Army

After self-review passes, execute Review Army with risk-based escalation. See plan-review.md。

Step 8: User approval

Verification failure handling

Failure scenario	Handling method
User rejects the plan	Ask for the reason, modify the plan, resubmit
Plan misses a spec requirement	Add tasks; every spec requirement must be traceable to a corresponding task
Dependencies are incorrect	Redo the dependency graph verification
Task is too large	Break down to ≤5 files; "and" in the title = split
Missing acceptance criteria	Mandatory addition; tasks without acceptance criteria cannot enter build
parallel_safe write overlap	Mark as serial, adjust Integration Order
shared contract / global invariant not frozen	Change to gated-parallel or serial
spec requires syncing project docs but plan does not specify owner / verification	Block. Add Project Doc Sync Plan before entering build

Common excuses

Excuse	Reality	Consequence
"Think while doing"	10 minutes of planning saves hours.	No plan misses 2-3 dependencies, each causing 2-4 hours of rework
"The task is obvious, no need to write it down"	Writing it down exposes hidden dependencies and edge cases.	Undocumented "obvious" tasks hide 1-2 edges, bugs after launch
"Planning is overhead"	Planning is the task. Implementation without a plan is just typing.	No plan → dependency chaos → >50% of code needs rework during integration
"Add acceptance criteria later"	Without acceptance criteria, there is no way to judge "done".	Acceptance criteria added later tend to conform to the implemented behavior, omissions are permanently locked in

Red flags

• Starting implementation without a written task list
• Task says "implement feature" but has no acceptance criteria
• No verification steps in the plan
• Spec says to sync project docs, but the plan does not specify Project Doc Sync Plan
• All tasks are L or XL size
• No checkpoints between phases
• Dependency order not enforced
• "and" appears in task titles in the plan (= two tasks)

Verification checklist

• Every task has acceptance criteria and verification steps
• Task dependencies are identified and correctly ordered
• No task exceeds ~5 files
• Checkpoints are set between major phases
• The plan has no placeholders
• Every spec requirement has a corresponding task in the plan
• Project Doc Sync Plan already exists; when syncing is needed, include owner / verification / deferred reason
• Multi-plan tasks have Subplans, Parallel Execution Matrix, Integration Order
• parallel_safe No overlapping writes between subplans
• The user has reviewed and approved the plan

Good and bad examples

Good — vertical slice + acceptance criteria

Task 1: 用户注册 — Files: User.ts, register.ts, RegisterForm.tsx
  Step 1: 定义 schema → 验证: prisma validate
  Step 2: 实现 API → 验证: curl POST /api/register → 201
  Step 3: 实现 UI → 验证: 浏览器提交表单 → 成功提示
  Verification: npm test --coverage --grep register > 80%

Bad — horizontal slice + no acceptance

Task 1: 建数据库（整个 schema）
Task 2: 建所有 API
Task 3: 建所有 UI
→ 水平切片: Task 3 完成前无法验证任何用户路径
→ 无验收条件: "建完"无法判定
→ 依赖链过长: 任何前置阻塞后续全部

Output template

### Plan — <feature-name>

Plan Topology: [serial / parallel / gated-parallel] | artifact_type: [software/...]

Project Doc Sync Plan:
- Must update: [paths or none]
- Optional update: [paths or none]
- Stage owner: [phase / task]
- Verification method: [review / validate / manual]
- Deferred docs with reason: [items or none]

Task 清单:
| Task N | 标题 | 文件数 | 验收条件 | 验证命令 | 依赖 |
|--------|------|-------|---------|---------|------|
| 1 | [标题] | [N] | [条件] | [命令] | [无/Task N] |

子计划索引（如适用）:
| 子计划 | Write Scope | Shared Contracts | Cross-check Command | parallel_safe | 依赖 | 验证 |
|--------|------------|------------------|---------------------|--------------|------|------|
| plans/01-*.md | [范围] | [契约] | [命令] | [yes/no] | [依赖] | [命令] |

Parallel Execution Matrix（如适用）:
| A | B | safe | 无重叠 |
|---|---|------|--------|
| [1] | [2] | [yes/no] | [✓/✗] |

用户批准: [已批准 / 待批准]