run-implementation-plan

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Run an Implementation Plan

执行Implementation Plan

Complete the incomplete behaviours in current scope. You can confirm this if unsure.

Treat the scoped specs as the source of truth. Keep working across turns until the definition of done below is satisfied. Do not expand into unrelated specs, unscheduled future behaviours, or another feature area.

The card is still the unit of work: one behaviour or implementation-plan chunk per pass. The skill does not stop after the first card.

Commands and paths:

.engineering/config.yaml

. Spec format:

references/spec-format.md

. Host

/goal

(Cursor, Codex, and others) starts this loop. Repo-specific extras:

paths.goal

(default

.engineering/goal.md

完成当前范围内的未完成行为。如有疑问可进行确认。

将限定范围的specs视为唯一依据。持续跨轮次工作直至满足下方的完成定义。请勿扩展至无关specs、未排期的未来行为或其他功能领域。

卡片仍是工作单元：每次处理一个行为或implementation-plan chunk。本技能不会在处理完第一张卡片后停止。

命令与路径：

.engineering/config.yaml

。Spec格式：

references/spec-format.md

。Host

/goal

（Cursor、Codex及其他）会启动此循环。仓库专属配置：

paths.goal

（默认值

.engineering/goal.md

）。

When to use

使用场景

```
/goal
```
/ "complete the incomplete behaviours in current scope".
"Run the implementation plan" / "finish the plan" / "run them all" /
```
run-implementation-plan-all
```
.
"Do the next chunk" / "ship B4" / "run E1."

Not this skill: writing a plan (

author-implementation-plan

). A named chunk starts there; it does not mean "stop after it" unless I say only that chunk.

```
/goal
```
/ "完成当前范围内的未完成行为"。
"Run the implementation plan" / "finish the plan" / "run them all" /
```
run-implementation-plan-all
```
。
"Do the next chunk" / "ship B4" / "run E1."。

不属于本技能：编写计划（

author-implementation-plan

）。指定某chunk会从该步骤开始，但除非我明确说只处理该chunk，否则不意味着“处理完就停止”。

Host continuation

Host续执行

After each card, if dependency-ready work remains, do not wait for another prompt.

Same session, if context is healthy — start the next card immediately.
New turn required — same scope, same checkpoint:
- Hosts with
  /goal
  (Cursor, Codex, and others) —
```
/goal
```
  with the same scope. The interval is "next card". The stop condition is the definition of done, not a clock.
- Neither — keep working in this session anyway.

Do not reset

.active/

on a continuation turn. If I attached supplementary text, or the goal overlay exists, honour it. Slash text wins for this run.

处理完每张卡片后，若仍有依赖就绪的工作，无需等待新的提示。

会话上下文正常时——立即开始处理下一张卡片。
需要新轮次时——保持相同范围和检查点：
- 支持
```
/goal
```
  的Host（Cursor、Codex及其他）——使用相同范围调用
```
/goal
```
  。间隔为“下一张卡片”。停止条件为完成定义，而非时间限制。
- 其他情况——无论如何继续在本次会话中工作。

续执行轮次中请勿重置

.active/

目录。若我附加了补充文本，或存在目标覆盖层，请遵循其要求。本次运行中，命令行文本优先级最高。

Before implementation

实现前准备

Read every scoped spec, its linked implementation plan or design document, and the repository rules.
Identify behaviour statuses, dependencies, existing implementation, test coverage, and Open Questions.
Resolve questions only when authoritative evidence in the specs, code, tests, or linked decisions establishes the answer.
Batch genuinely blocking product decisions for me before coding via
```
ask-questions
```
. Do not invent a product decision. If I tell you not to stop for questions, skip blocked behaviours and record them instead.
Build a dependency-ordered work queue. Work on one behaviour or implementation-plan chunk at a time.
Keep a concise checkpoint under
```
.active/
```
containing the scope, queue, completed cards, verification evidence, current database state, blockers, and next action. Do not commit
```
.active/
```
.

Starting card, in order: the ID I named; the plan's "Next up" marker; the first incomplete chunk in execution order. Verify Depends on either way. If prerequisites aren't complete and you cannot complete them inside this scope, record the blocker — do not skip ahead. If everything is complete, say so; don't start new scope.

阅读所有限定范围的specs、其关联的implementation plan或设计文档，以及仓库规则。
识别行为状态、依赖关系、现有实现、测试覆盖率和未解决问题（Open Questions）。
仅当specs、代码、测试或关联决策中存在权威证据能给出答案时，才解决问题。
在编码前，通过
```
ask-questions
```
将真正阻塞的产品决策批量提交给我。请勿自行制定产品决策。若我告知无需因问题停止，则跳过阻塞的行为并记录下来。
构建按依赖顺序排序的工作队列。每次处理一个行为或implementation-plan chunk。
在
```
.active/
```
目录下保存简洁的检查点，包含范围、队列、已完成卡片、验证证据、当前数据库状态、阻塞项和下一步操作。请勿提交
```
.active/
```
目录。

起始卡片顺序：我指定的ID；计划中的“Next up”标记；执行顺序中第一个未完成的chunk。无论哪种情况都需验证依赖项。若先决条件未完成且无法在当前范围内完成，请记录阻塞项——请勿跳过。若所有工作已完成，请告知，勿启动新范围。

For each card

每张卡片的处理步骤

Read the complete relevant spec and acceptance criteria. Read the flow contract and the exact transitions assigned to this card. The YAML governs; Mermaid is a human view. Read Work, Done when, Out of scope. Out of scope is a hard wall. If the code seems to need an undeclared transition, stop and change the contract first.
Check the implementation for drift and assess existing test coverage.
Add or update tests that prove the specified behaviour, but only where
```
write-tests
```
says they earn their keep. Include permission, tenancy, invariant, decision-table, and regression cases where applicable. Each cited flow transition gets a test, and each behavioural guard gets both branches, where there is a test surface for it — not a page mock, not a type the compiler already checks.
Implement until the relevant tests pass. Follow the repo's conventions. If you add a dependency, use
```
package_manager
```
from the config — never guess
```
npm
```
vs
```
pnpm
```
. Do not commit
```
.env
```
or put a real secret in
```
.env.example
```
.
Use browser testing for genuinely user-facing paths. Exercise the local app when the acceptance criteria require observable UI behaviour. Actually do it; don't assume.
If this repo's tests build their database from source schema (often
```
src/db/schema/**
```
), do not run
```
commands.db_generate
```
or
```
commands.db_migrate
```
merely to make tests see a schema change.
Run
```
commands.db_generate
```
only when generated migration files must be verified, or when a real app or browser path needs the schema change. Run
```
commands.db_migrate
```
only when that real database needs those generated or committed migrations. Omit both steps when the config does not define them.
Treat database coordination notices as informational. Do not ask me to confirm an external chat or ticket state. Keep generated migration artifacts uncommitted unless I have explicitly authorised committing them.
Update the spec and implementation plan so behaviour badges, tickets, Open Questions, and completion state match reality (
```
spec-maintain-on-ship
```
). Mark the chunk complete with a dated status line and advance "Next up".
Run the card's targeted tests, changed-file lint and format checks, relevant type checking, and git diff checks. Review the card's complete diff and fix verified functional, permission, tenancy, and coverage findings. Use
```
review.always_check
```
from the config.
Clean only temporary or generated output created by this card whose removal is proven safe. Never delete pre-existing or unexplained files, and never discard migration artifacts blindly.
If
```
commands.checkpoint_commit
```
is set, create a local checkpoint commit through that command, update the checkpoint file, and continue to the next dependency-ready card without waiting for another prompt. If it is not set, update the checkpoint and continue; do not invent a commit tool, and do not commit unless I asked.

Then go back to card step 1 for the next dependency-ready card. Use the host continuation rules when a new turn is required.

Stop only when every in-scope card is done, I asked for only one named chunk, or the remaining work is blocked by a decision or external dependency. Skip a blocked card, record it, and continue with anything that does not depend on it.

阅读完整的相关spec和验收标准。阅读流程契约及分配给本卡片的具体转换规则。YAML文件为权威依据；Mermaid图仅供人类查看。阅读Work、Done when、Out of scope部分。Out of scope为硬性限制。若代码似乎需要未声明的转换，请先停止并修改契约。
检查实现是否存在偏差，并评估现有测试覆盖率。
添加或更新能验证指定行为的测试，但仅在
```
write-tests
```
判定有必要时进行。适当时包含权限、租户、不变量、决策表和回归测试用例。每个引用的流程转换都需对应一个测试，每个行为守卫都需覆盖两个分支（若存在测试场景）——而非页面模拟或编译器已检查的类型。
实现直至相关测试通过。遵循仓库约定。若添加依赖，请使用配置中的
```
package_manager
```
——切勿猜测是
```
npm
```
还是
```
pnpm
```
。请勿提交
```
.env
```
文件，也不要在
```
.env.example
```
中填写真实密钥。
对真正面向用户的路径使用浏览器测试。当验收标准要求可观察的UI行为时，运行本地应用。实际执行，勿假设结果。
若本仓库的测试从源schema（通常为
```
src/db/schema/**
```
）构建数据库，则勿仅为让测试识别schema变更而运行
```
commands.db_generate
```
或
```
commands.db_migrate
```
。
仅当必须验证生成的迁移文件，或真实应用/浏览器路径需要schema变更时，才运行
```
commands.db_generate
```
。仅当真实数据库需要这些生成或已提交的迁移时，才运行
```
commands.db_migrate
```
。若配置未定义这些命令，则省略这两个步骤。
将数据库协调通知视为信息性内容。请勿要求我确认外部聊天或工单状态。除非我明确授权提交，否则请勿提交生成的迁移产物。
更新spec和implementation plan，使行为徽章、工单、Open Questions和完成状态与实际情况一致（
```
spec-maintain-on-ship
```
）。添加带日期的状态行标记该chunk已完成，并更新“Next up”。
运行卡片的针对性测试、变更文件的lint和格式检查、相关类型检查以及git diff检查。审核卡片的完整diff，并修复已验证的功能、权限、租户和覆盖率问题。使用配置中的
```
review.always_check
```
。
仅清理本卡片生成的、已确认可安全删除的临时或生成输出。切勿删除预先存在或无法解释的文件，也切勿盲目丢弃迁移产物。
若设置了
```
commands.checkpoint_commit
```
，通过该命令创建本地检查点提交，更新检查点文件，无需等待新提示即可继续处理下一个依赖就绪的卡片。若未设置，则更新检查点并继续；请勿自行创建提交工具，除非我要求，否则请勿提交。

之后返回卡片步骤1，处理下一个依赖就绪的卡片。需要新轮次时，遵循Host续执行规则。

仅当所有范围内的卡片处理完成、我要求只处理某个指定chunk，或剩余工作因决策或外部依赖阻塞时，才停止。跳过阻塞的卡片，记录下来，继续处理不依赖它的工作。

Definition of done

完成定义

Every in-scope behaviour is implemented or explicitly recorded as blocked by a decision or external dependency.
Every implemented behaviour, invariant, and decision-table row has appropriate test evidence — only the tests
```
write-tests
```
would allow.
Required browser paths have been exercised successfully.
Specs and implementation plans accurately describe the final behaviour and state.
A full branch self-review has been performed (
```
branch-self-review
```
) and verified findings have been fixed.
The
```
ready-for-pr
```
gates pass — types, lint, dead code (knip where that is the command), and tests, in the config's
```
gates
```
order.
A final spec drift and coverage check (
```
spec-audit-drift
```
,
```
spec-assess-coverage
```
) finds no unaddressed in-scope gap.
The final checkpoint records what shipped, verification performed, generated migration artifacts left uncommitted, remaining blockers, and any developer action.

Do not push, submit, open a PR, commit protected migration artifacts, implement unrelated future scope, or broaden the branch without explicit authorisation.

所有范围内的行为已实现，或被明确记录为因决策或外部依赖阻塞。
每个已实现的行为、不变量和决策表行都有适当的测试证据——仅包含
```
write-tests
```
允许的测试。
必要的浏览器路径已成功执行。
Specs和implementation plan准确描述最终行为和状态。
已完成完整的分支自审核（
```
branch-self-review
```
），并修复了已验证的问题。
```
ready-for-pr
```
门禁已通过——按配置
```
gates
```
中的顺序完成类型检查、lint、死代码检查（若命令为knip）和测试。
最终的spec偏差和覆盖率检查（
```
spec-audit-drift
```
、
```
spec-assess-coverage
```
）未发现未解决的范围内缺口。
最终检查点记录了已交付内容、执行的验证操作、未提交的生成迁移产物、剩余阻塞项以及任何开发者操作。

未经明确授权，请勿推送、提交、打开PR、提交受保护的迁移产物、实现无关的未来范围或扩展分支。

Quality gate

质量门禁

Every scoped spec, plan, and Open Question read before the first card.
Queue is dependency-ordered; blockers batched or recorded, not invented through.
Each card followed the twelve steps, including tests before calling it done.
Nothing implemented outside Work, or inside Out of scope.
No undeclared transition, guard, bypass, or exit added.
Schema generate and migrate ran only when the config defines them and the card actually needed them.
Spec badges, plan, and
```
.active/
```
checkpoint match reality after each card.
The skill did not stop while dependency-ready work remained, unless I asked for only one chunk.
Close-out ran self-review, ready-for-pr, drift, and coverage.

处理第一张卡片前已阅读所有范围内的spec、计划和Open Questions。
队列按依赖顺序排序；阻塞项已批量提交或记录，未自行处理。
每张卡片都遵循了12个步骤，包括在标记完成前编写测试。
未在Work范围外或Out of scope范围内实现任何内容。
未添加未声明的转换、守卫、绕过或退出逻辑。
仅当配置定义了schema生成和迁移命令，且卡片确实需要时，才运行这些命令。
每张卡片处理完成后，spec徽章、计划和
```
.active/
```
检查点与实际情况一致。
若仍有依赖就绪的工作，本技能不会停止，除非我要求只处理一个chunk。
收尾阶段已执行自审核、ready-for-pr、偏差和覆盖率检查。

Anti-patterns

反模式

Stopping after the first card because the old skill did. The loop is the job.
Two cards in one pass because the second is small. The most common failure.
Inventing a product decision so the queue can keep moving.
Running schema generate or migrate to make tests pass when tests already build from source schema.
Asking me to confirm an external Slack or ticket state.
Committing generated migration artifacts without explicit authorisation.
Pushing or opening a pull request as part of the loop.
Using
/loop
on a wall-clock interval instead of "next card until done".

处理完第一张卡片就停止：因为旧技能是这样的。但本技能的核心是循环执行。
一次处理两张卡片：因为第二张很小。这是最常见的错误。
自行制定产品决策：以便队列能继续推进。
为让测试通过而运行schema生成或迁移：当测试已从源schema构建时。
要求我确认外部Slack或工单状态。
未经明确授权就提交生成的迁移产物。
将推送或打开PR作为循环的一部分。
使用
/loop
按时间间隔执行：而非“处理下一张卡片直至完成”。