wave-execution

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Wave Execution

波次执行

Use this skill when work should be organized as wave-based parallel execution instead of ad hoc tasking.

当工作需要组织为基于波次的并行执行，而非临时任务分配时，可使用本技能。

Start Here

入门指引

Before doing anything else, orient yourself to the project by reading:

The project's root
```
README.md
```
or equivalent overview doc
Any roadmap or target-state document
The execution plan directory (e.g.,
```
.planning/execution/README.md
```
)
The wave roadmap (e.g.,
```
.planning/execution/ROADMAP.md
```
)
The task registry (e.g.,
```
.planning/execution/tasks.json
```
)

Use domain-specific research or design docs when the current phase touches a specialized layer (e.g., data modeling, API contracts, UI systems).

Use these companion references when drafting or reviewing execution artifacts:

```
references/task-template.md
```
```
references/handoff-template.md
```
```
references/ownership-examples.md
```

在开展任何工作前，请先阅读以下材料了解项目整体情况：

项目根目录的
```
README.md
```
或等效概述文档
所有路线图或目标状态文档
执行计划目录（例如
```
.planning/execution/README.md
```
）
波次路线图（例如
```
.planning/execution/ROADMAP.md
```
）
任务注册表（例如
```
.planning/execution/tasks.json
```
）

当当前阶段涉及特定层级（例如数据建模、API契约、UI系统）时，请查阅对应领域的研究或设计文档。

起草或审核执行产出物时可参考以下配套文档：

```
references/task-template.md
```
```
references/handoff-template.md
```
```
references/ownership-examples.md
```

Core Rule

核心规则

Parallelize by disjoint write scope, not by vague topic.

Safe:

two agents each owning a separate package, module, or directory
research/docs vs implementation code
UI vs data layer (when shared schema is already stable)

Unsafe:

two threads editing the same file
two threads editing the same narrow module boundary
starting downstream work before the upstream contract or schema is stable

按照不相交的写入范围进行并行化，而非按照模糊的主题划分。

安全的划分方式：

两个agent各自负责独立的包、模块或目录
研究/文档工作与代码实现工作分离
UI层与数据层分离（当共享 schema 已经稳定时）

不安全的划分方式：

两个线程编辑同一个文件
两个线程编辑同一个窄模块边界内的内容
在上游契约或schema尚未稳定前就启动下游工作

The Workflow

工作流

1. Lock the wave

1. 锁定波次信息

Before launching subagents:

define the wave goal
define task ids
define dependencies
define write ownership
define verification commands
define handoff paths

Record this in your project's execution plan and task registry before any work starts.

在启动subagent前：

定义波次目标
定义任务ID
定义依赖关系
定义写入所有权
定义验证命令
定义交接路径

在任何工作启动前，将以上信息记录到项目的执行计划和任务注册表中。

2. Split only non-overlapping work

2. 仅拆分无重叠的工作

Good split examples:

research/docs vs implementation
module A vs module B (when no shared file)
UI/reporting vs data layer (when schema is stable)
configuration/calibration vs validation logic

Bad split examples:

two agents both touching a shared types or contracts file
two agents both touching the same service or repository module
two agents editing the same data or config files

Use

references/ownership-examples.md

when deciding whether a split is actually safe.

合理拆分示例：

研究/文档与实现工作分离
模块A 与模块B分离（无共享文件时）
UI/报表与数据层分离（当schema稳定时）
配置/校准与验证逻辑分离

不合理拆分示例：

两个agent都修改共享的类型或契约文件
两个agent都修改同一个服务或仓库模块
两个agent编辑同一个数据或配置文件

判断拆分是否安全时可参考

references/ownership-examples.md

。

3. Make each task self-contained

3. 保证每个任务自包含

Each task should include:

precise goal
owned files or directories
dependencies
what not to touch
required verification
required handoff file

Use

references/task-template.md

for the worker prompt shape.

每个任务应当包含：

明确的目标
负责的文件或目录
依赖关系
禁止修改的范围
required verification
required handoff file

编写worker提示词模板时可参考

references/task-template.md

。

4. Require a handoff before closure

4. 关闭任务前要求完成交接

Every task writes a handoff under your project's designated handoffs directory (e.g.,

.planning/execution/handoffs/<wave-id>/

The handoff must state:

what changed
what was verified
blockers or residual risks
what the next thread should know

Use

references/handoff-template.md

when drafting or reviewing handoffs.

每个任务都需要在项目指定的交接目录下编写交接文档（例如

.planning/execution/handoffs/<wave-id>/

）。

交接文档必须说明：

变更内容
已验证的内容
阻塞项或残余风险
后续线程需要知晓的信息

起草或审核交接文档时可参考

references/handoff-template.md

。

5. Merge only through gates

5. 仅通过门禁完成合并

Do not consider a wave done until:

all required task handoffs exist
integration review is complete
verification passes

Define gate commands appropriate to your project's toolchain. Common examples:

```
npm run typecheck
```
/
```
tsc --noEmit
```
```
npm test
```
/
```
pytest
```
/
```
cargo test
```
```
npm run build
```
/
```
make build
```

满足以下条件前，不可认为波次已完成：

所有要求的任务交接文档已提交
集成审核已完成
验证全部通过

请定义适配项目工具链的门禁命令，常见示例：

```
npm run typecheck
```
/
```
tsc --noEmit
```
```
npm test
```
/
```
pytest
```
/
```
cargo test
```
```
npm run build
```
/
```
make build
```

Subagent Rules

Subagent使用规则

Use subagents when:

there are 2 or more independent tracks
the write scopes do not overlap
waiting on one result is not required for the next local step

Keep work local when:

the task is on the critical path
the schema or contract is still moving
file ownership is shared or ambiguous

When spawning a worker, always specify:

exact owned paths
exact deliverable
instruction not to revert unrelated changes
instruction to write or update the expected handoff artifact

满足以下条件时可使用subagent：

存在2条及以上独立的工作轨道
写入范围无重叠
后续本地步骤不需要等待某一个结果返回

满足以下条件时请在本地完成工作：

任务属于关键路径
schema或契约仍在调整
文件所有权共享或不明确

创建worker时，必须明确指定：

准确的负责路径
准确的交付物
不要回滚无关变更的指令
编写或更新预期交接产出物的指令

Recommended Wave Shape

Common Failure Modes

常见失效模式

launching parallel work before the contract is stable
allowing two threads to touch the same shared file
treating existing artifacts as sufficient research when a real research phase is needed
marking a task complete without a handoff
claiming a wave is done before the project-level gate passes

在契约稳定前就启动并行工作
允许两个线程修改同一个共享文件
当需要实际研究阶段时，误将现有产出物当做足够的研究依据
未提交交接文档就标记任务完成
在项目级门禁通过前就宣称波次已完成

Output Style

输出风格

When using this skill, prefer:

wave ids
task ids
explicit dependencies
explicit write scopes
short merge gates

Do not produce fuzzy plans like "frontend/backend/data in parallel" without file ownership.

使用本技能时，优先使用：

波次ID
任务ID
明确的依赖关系
明确的写入范围
轻量化合并门禁

请勿产出类似"前端/后端/数据并行开发"这类没有明确文件所有权的模糊计划。