specmgr

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Spec-Driven Development Workflow Manager

Spec驱动开发工作流管理器

Individual

*-spec.md

files are treated as the specification for each feature—they define what the feature is and what it must do. These specification files are the authoritative ("canonical") source of requirements for their parts of the application.

All spec files that are created from other raw report documents should reference those documents in the title header of the spec
When writing a new spec, review the existing specs in the specs/ directory and identify any that are clearly superseded by your new specification. List only the directly superseded (first-level) specs.

每个

*-spec.md

文件都被视为对应功能的规范：它们定义了功能是什么以及必须实现的能力。这些规范文件是应用对应模块的权威（"canonical"）需求来源。

所有从其他原始报告文档生成的spec文件，都需要在spec的标题头部引用这些原始文档
编写新spec时，请查阅specs/目录下的现有spec，识别所有明显被新spec替代的旧spec，仅列出直接被替代的（第一层级）spec即可。

Workflow 1: Create DRAFT Spec

工作流1：创建DRAFT Spec

Triggers: "create a DRAFT spec from...", "write a spec for...", "draft spec..."

触发条件： "create a DRAFT spec from..."、"write a spec for..."、"draft spec..."

Before writing the spec

编写spec之前

Read all input/reference files first
Read all files matching
```
*-spec.md
```
in the project's
```
specs/
```
directory; newer specs take priority over older ones
Check
```
specs/README.md
```
for the existing spec index

先通读所有输入/参考文件
通读项目
```
specs/
```
目录下所有匹配
```
*-spec.md
```
格式的文件，新spec优先级高于旧spec
查看
```
specs/README.md
```
获取现有spec索引

STOP: Ask clarifying questions

暂停：询问澄清问题

Do NOT proceed to writing the spec until this step is complete.

Present your questions to the user about:

Anything that needs clarification in the input
Any incompatibilities found with existing specs
Recommendations or design choices you see

Wait for the user's answers before writing the spec document.

本步骤完成前绝对不要继续编写spec。

向用户提出以下相关问题：

输入内容中所有需要澄清的点
发现的与现有spec不兼容的问题
你想到的建议或设计选择

等待用户答复后再编写spec文档。

Naming convention

命名规范

Filename format:
```
specs/<name>-spec.md
```
The
```
<name>
```
portion is derived from the input file or feature name (e.g.,
```
featurereport74.md
```
→
```
specs/featurereport74-spec.md
```
)

文件名格式：
```
specs/<name>-spec.md
```
```
<name>
```
部分从输入文件或功能名称衍生而来（例如：
```
featurereport74.md
```
→
```
specs/featurereport74-spec.md
```
）

Spec template

Spec模板

Include the following fields at the top of every DRAFT spec:

undefined

每个DRAFT spec的顶部都需要包含以下字段：

undefined

Title

Date:

<ISO 8601 format with seconds, America/Denver timezone>

References: list of
```
<other-raw-report-path.md>
```
or
```
<none>
```
Supersedes: list of
```
<other-spec-file.md>
```
Chunkplan:
```
<path-to-chunkplan.md>
```
or
```
none
```
Chunked:
```
true
```
or
```
false
```
State: one of these valid values:
```
DRAFT
```
,
```
IMPLEMENTED
```
,
```
VALIDATED
```

undefined

Date:

<ISO 8601格式，精确到秒，时区为America/Denver>

References: 引用的
```
<other-raw-report-path.md>
```
列表，无引用则填
```
<none>
```
Supersedes: 被替代的
```
<other-spec-file.md>
```
列表
Chunkplan:
```
<path-to-chunkplan.md>
```
或
```
none
```
Chunked:
```
true
```
或
```
false
```
State: 有效值为：
```
DRAFT
```
、
```
IMPLEMENTED
```
、
```
VALIDATED
```

undefined

Setting the

Chunked:

field

设置

Chunked:

字段

Set to
```
true
```
if the spec should be broken into a chunk plan before implementation. Set to
```
false
```
if it can be implemented in a single pass.
Consider
```
true
```
when: the spec touches many files across different subsystems, requires multiple independent features or phases, has complex test strategy spanning several areas, or would exceed what an agent can reliably implement and test in one session.
Consider
```
false
```
when: the changes are mechanical/uniform (e.g., same pattern applied across many call sites), the scope is limited to one subsystem, or the spec is a straightforward bug fix.
This is a recommendation for the human reviewer — the chunk plan is not created until after review.

如果spec在实现前需要拆分为分块计划，设为
```
true
```
；如果可以一次性完成实现，设为
```
false
```
符合以下场景考虑设为
```
true
```
：spec涉及不同子系统的多个文件、需要多个独立功能或阶段、跨多个领域的复杂测试策略、超出Agent在单个会话中可以可靠实现和测试的范围
符合以下场景考虑设为
```
false
```
：改动是机械/统一的（例如在多个调用点应用相同模式）、范围限定在单个子系统、或者spec是简单的bug修复
这是给人工审核者的建议：分块计划会在审核完成后才创建

Root cause analysis

根因分析

If the raw issue is a bug or something broken, perform a root cause analysis and include that in the spec.

如果原始问题是bug或者故障，请执行根因分析并将结果纳入spec中。

Companion agent test plan

配套Agent测试计划

Always create a companion agent test plan file alongside the spec:

<spec-basename>-agent-test-plan.md

(e.g.,

condense-build-header-spec.md

→

condense-build-header-agent-test-plan.md

). The agent test plan must contain concrete CLI commands that an agent can execute to verify the implementation works end-to-end against the real tool and environment. Link the agent test plan from a

## Agent Test Plan

section at the end of the spec (before the

## SPEC workflow

section).

始终在spec旁边创建配套的Agent测试计划文件：

<spec-basename>-agent-test-plan.md

（例如：

condense-build-header-spec.md

→

condense-build-header-agent-test-plan.md

）。Agent测试计划必须包含具体的CLI命令，Agent可以执行这些命令来验证实现在真实工具和环境中是否端到端正常工作。在spec末尾的

## Agent Test Plan

部分（位于

## SPEC workflow

部分之前）添加Agent测试计划的链接。

Agent test plan guidelines

Agent测试计划指南

The point of an agent test plan is to validate that once a spec is implemented, that all the components exist together as part of a coheseive whole. e.g.

website (if any) can start up without errors
expected website content is visible
cli tool (if any) can run with options modified under spec
execute basic functionality against known external data according to the spec

A test plan is not:

a substitute for a unit test
a substitute for an end to end test
a substitute for an integration test
a substitute for passing all CI/CD tests
a comprehensive test of everything changed in the spec

Agent测试计划的作用是验证spec实现后，所有组件可以作为一个整体协同运行，例如：

网站（如果有）可以正常启动无报错
预期的网站内容正常可见
CLI工具（如果有）可以使用spec中修改的参数运行
根据spec使用已知外部数据执行基础功能

测试计划不是：

单元测试的替代品
端到端测试的替代品
集成测试的替代品
所有CI/CD测试通过的替代品
spec中所有改动的全面测试

SPEC workflow section

SPEC工作流部分

Include the following verbatim at the end of every DRAFT spec:

undefined

每个DRAFT spec的末尾都需要逐字添加以下内容：

undefined

SPEC workflow

read
```
specs/CLAUDE.md
```
and follow all rules there to implement this DRAFT spec (DRAFT->IMPLEMENTED)

undefined

read
```
specs/CLAUDE.md
```
and follow all rules there to implement this DRAFT spec (DRAFT->IMPLEMENTED)

undefined

Superseded specs

被替代的spec

When creating a new spec, identify any existing specs that are directly superseded by the new specification. List them in the

Supersedes:

field.

创建新spec时，识别所有直接被新spec替代的现有spec，将它们列在

Supersedes:

字段中。

Workflow 2: Create Chunk Plan

工作流2：生成分块计划

Triggers: "create a plan from spec...", "chunk this spec...", "break down spec...", "create a chunk plan..."

触发条件： "create a plan from spec..."、"chunk this spec..."、"break down spec..."、"create a chunk plan..."

Instructions

操作说明

Load the
```
references/taskcreator.md
```
file from this skill for the full decomposition methodology.
Load the
```
references/chunk-template.md
```
file from this skill for the chunk format template.
Follow all rules in
```
references/taskcreator.md
```
to decompose the spec.

加载本技能的
```
references/taskcreator.md
```
文件，参考完整的拆解方法论
加载本技能的
```
references/chunk-template.md
```
文件，参考分块格式模板
遵循
```
references/taskcreator.md
```
中的所有规则拆解spec

Plan file naming

计划文件命名

Plan files are named:

specs/<spec-basename>-chunkplan.md

(e.g.,

majorfeature47-spec.md

→

specs/majorfeature47-chunkplan.md

)

Plan files are created in the
```
specs/
```
directory (not
```
specs/todo/
```
), regardless of where the source spec file is located. Plans are ready-to-implement artifacts.
After the chunk plan file is written, update the parent spec's
```
Chunkplan:
```
field to reference the chunk plan file.

计划文件命名规则：

specs/<spec-basename>-chunkplan.md

（例如：

majorfeature47-spec.md

→

specs/majorfeature47-chunkplan.md

）

计划文件创建在
```
specs/
```
目录下（不是
```
specs/todo/
```
），无论源spec文件位于何处。计划是可直接用于实现的产出物。
分块计划文件编写完成后，更新父spec的
```
Chunkplan:
```
字段，引用该分块计划文件。

SPEC Workflow in plans

计划中的SPEC工作流

The SPEC Workflow block embedded in plans must use generic language:

"Run all unit tests" (do not hardcode a test runner command — the project's
```
CLAUDE.md
```
or
```
specs/CLAUDE.md
```
specifies the test runner)
"Commit and push" (do not hardcode a push command — the project's conventions apply)
"Update project documentation as specified in the project's CLAUDE.md or specs/CLAUDE.md"

计划中嵌入的SPEC工作流块必须使用通用表述：

"Run all unit tests"（不要硬编码测试运行命令，项目的
```
CLAUDE.md
```
或
```
specs/CLAUDE.md
```
会指定测试运行器）
"Commit and push"（不要硬编码推送命令，遵循项目约定）
"Update project documentation as specified in the project's CLAUDE.md or specs/CLAUDE.md"

Workflow 3: Implement DRAFT Spec (DRAFT → IMPLEMENTED)

工作流3：实现DRAFT Spec（DRAFT → IMPLEMENTED）

Triggers: "implement DRAFT spec...", "implement spec..."

When implementing a DRAFT spec or bug fix, follow these steps in order.

触发条件： "implement DRAFT spec..."、"implement spec..."

实现DRAFT spec或修复bug时，请按顺序遵循以下步骤。

3a Before writing code

3a 编写代码前

Check for chunk plan if there is a chunk plan use Workflow 4 instead of this one
Check build status and confirm the last build is successful. Do not proceed if the build is setup but broken. It is ok if there is no build setup for this project yet.
Run all unit tests and confirm they pass. Do not proceed if there are existing tests but they are failing.

检查是否有分块计划 如果存在分块计划，请使用工作流4而非本工作流
检查构建状态 确认最近一次构建成功。如果项目已配置构建但构建失败，不要继续。如果项目尚未配置构建，可以继续。
运行所有单元测试 确认测试全部通过。如果已有测试但运行失败，不要继续。

3b Implement the feature or fix

3b 实现功能或修复

Write the code as described in the spec's Specification section.
Write or update unit tests as described in the spec's Test Strategy section.
Run all unit tests and confirm they pass (both new and existing).

按照spec的规范部分描述编写代码
按照spec的测试策略部分描述编写或更新单元测试
运行所有单元测试 确认全部通过（包括新测试和现有测试）。

Existing test modification policy

现有测试修改规则

When your implementation causes a pre-existing test to fail, you may fix it and continue — do not stop to ask. However:

Determine spec backing first. Before changing an existing test, identify which section of the spec requires the behavioral change that invalidates the old test.
If the spec backs the change: fix the test and log the change in the implementation review log (see Implementation Review Report section).
If no spec section backs the change: you still may fix it and continue, but you MUST log it with
```
Spec Backing: None
```
in the review log. These entries will be flagged for reviewer attention.
What counts as modifying an existing test: changing assertions, expected values, fixture data, test domain names, or any other change whose purpose is to make a previously-passing test continue to pass under new behavior. Adding new test cases is not a modification.
Never weaken a test to avoid a failure. Changing fixture data to sidestep new validation (e.g. removing a
```
.com
```
suffix so domain validation is never triggered) is weakening, not fixing. If the test was exercising a code path that your implementation changed, the test should still exercise that code path — with correct updated expectations.

如果你的实现导致原有测试失败，你可以修复测试后继续，无需停止询问。但请注意：

先确认spec支撑 修改现有测试前，先确认spec的哪个章节要求的行为变更导致旧测试失效。
如果有spec支撑该变更： 修复测试，并在实现审核日志中记录该变更（见实现审核报告章节）。
如果没有spec章节支撑该变更： 你仍然可以修复测试后继续，但必须在审核日志中标记
```
Spec Backing: None
```
。这些条目会被标记出来供审核者重点关注。
现有测试修改的定义： 更改断言、预期值、测试夹具数据、测试域名，或任何为了让之前通过的测试在新行为下继续通过的改动。添加新测试用例不属于修改。
绝对不要弱化测试来避免失败。 更改夹具数据来回避新的验证逻辑（例如移除
```
.com
```
后缀让域名验证永远不会触发）属于弱化测试，不是修复。如果测试覆盖的代码路径被你的实现修改了，测试仍然需要覆盖该代码路径，只是更新为正确的预期值。

3c Run agent test plan (if present)

3c 运行Agent测试计划（如果存在）

Check if the spec references an agent test plan (look for a
```
## Agent Test Plan
```
section or a companion
```
*-agent-test-plan.md
```
file). If one exists, execute the test plan and verify it is successful.

检查spec是否引用了Agent测试计划 查找
```
## Agent Test Plan
```
部分或者配套的
```
*-agent-test-plan.md
```
文件。如果存在，执行测试计划并验证成功。

3d Verify CI/CD build is green

3d 验证CI/CD构建正常

CI/CD gate — MANDATORY before marking IMPLEMENTED. The spec CANNOT be marked IMPLEMENTED unless the CI/CD build is confirmed GREEN (no failures). Follow this procedure:
1. Check if the project has a
```
buildgit
```
  skill installed (look for a
```
SKILL.md
```
  in a
```
skill/buildgit/
```
  directory) and a configured build job (e.g.
```
JENKINS_URL
```
  is set, or a Jenkinsfile exists).
2. If buildgit is available and a build job is configured: Run
```
buildgit status
```
  (or equivalent) and verify the latest build result is SUCCESS with no test failures. If the build is failing, fix the issues and push again. Repeat until the build is GREEN. Do NOT proceed to mark the spec IMPLEMENTED while the build is broken.
3. If buildgit is NOT installed or no build job is configured: This is acceptable — note it in the implementation review report under the
```
## CI/CD Verification
```
  section (see Implementation Review Report template). Proceed to the next step.

CI/CD关卡 — 标记为IMPLEMENTED前的强制要求 除非CI/CD构建确认是GREEN（无失败），否则spec不能标记为IMPLEMENTED。遵循以下流程：
1. 检查项目是否安装了
```
buildgit
```
  技能（查找
```
skill/buildgit/
```
  目录下的
```
SKILL.md
```
  ）和配置好的构建任务（例如设置了
```
JENKINS_URL
```
  ，或者存在Jenkinsfile）。
2. 如果已安装buildgit且配置了构建任务： 运行
```
buildgit status
```
  （或等效命令），验证最新构建结果为SUCCESS，无测试失败。如果构建失败，修复问题后重新推送，重复直到构建为GREEN。构建失败时绝对不要继续将spec标记为IMPLEMENTED。
3. 如果未安装buildgit或未配置构建任务： 这种情况是可接受的，在实现审核报告的
```
## CI/CD Verification
```
  部分注明即可（见实现审核报告模板），继续下一步。

3e Update documentation and metadata

3e 更新文档和元数据

Update the spec file: Change its
```
State:
```
field to
```
IMPLEMENTED
```
and add it to the spec index in
```
specs/README.md
```
.
Handle referenced files: If the spec lists files in its
```
References:
```
header, move those files to
```
specs/done-reports/
```
and update the reference paths in the spec accordingly.
Run any additional project-specific finalize steps as specified in the project's
```
CLAUDE.md
```
or
```
specs/CLAUDE.md
```
. This is the extension point where project-specific documentation updates, skill file updates, and custom push/CI commands are executed.

更新spec文件： 将
```
State:
```
字段改为
```
IMPLEMENTED
```
，并将其添加到
```
specs/README.md
```
的spec索引中。
处理引用文件： 如果spec的
```
References:
```
头部列出了相关文件，将这些文件移动到
```
specs/done-reports/
```
目录下，并对应更新spec中的引用路径。
执行项目特定的额外收尾步骤 按照项目的
```
CLAUDE.md
```
或
```
specs/CLAUDE.md
```
中的说明执行。这是扩展点，可以执行项目特定的文档更新、技能文件更新、自定义推送/CI命令等操作。

Workflow 4: Implement DRAFT Spec using chunk plan (DRAFT → IMPLEMENTED)

工作流4：使用分块计划实现DRAFT Spec（DRAFT → IMPLEMENTED）

Triggers: "implement DRAFT spec with chunk plan ...", "implement chunk X from chunk plan..."

触发条件： "implement DRAFT spec with chunk plan ..."、"implement chunk X from chunk plan..."

4a Before writing code

4a 编写代码前

Check for chunk plan if there is no chunk plan, use Workflow 3 instead of this one
Run all unit tests and confirm they pass. Do not proceed if tests are failing. If the test commands themselves are broken (e.g. missing tools, build infrastructure failures, repository configuration errors), do NOT skip tests and continue — this is a blocking failure. Output
```
RALPH_BLOCKED=<reason>
```
as the final line and stop.

检查是否有分块计划 如果没有分块计划，请使用工作流3而非本工作流
运行所有单元测试 确认全部通过。如果测试失败，不要继续。如果测试命令本身损坏（例如缺少工具、构建基础设施故障、仓库配置错误），不要跳过测试继续，这是阻塞性故障，在最后一行输出
```
RALPH_BLOCKED=<原因>
```
后停止。

4b Per-Chunk Workflow (every chunk must follow these steps)

4b 分块工作流（每个分块都必须遵循以下步骤）

Implement the chunk as described in its Implementation Details section.
Write or update unit tests as described in the chunk's Test Plan section.
Run all unit tests and confirm they pass (both new and existing). The Existing test modification policy from Workflow 3b applies here as well.
Mark chunk complete Mark ONLY the one chunk you implemented as completed in chunkplan (change '- [ ]' to '- [x]').
Fill in the
#### Implementation Log
for the chunk you implemented — summarize files changed, key decisions, and anything notable.
Commit and push per the project conventions. Use a commit message starting with
```
chunk N/T:
```
followed by a brief description.
Fix build errors Wait for the build to complete. Fix any errors shown. Repeat this step as necessary.

Blocking failure rule: If at any point during the per-chunk workflow you encounter a failure that you cannot fix (broken build infrastructure, missing tools, repository configuration errors, or test failures unrelated to your chunk's changes), do NOT output

REMAINING_CHUNKS=n

. Instead, output

RALPH_BLOCKED=<brief reason>

as the final line and stop immediately. Do not attempt the next chunk.

按照分块的实现细节部分描述实现该分块
按照分块的测试计划部分描述编写或更新单元测试
运行所有单元测试 确认全部通过（包括新测试和现有测试）。工作流3b中的现有测试修改规则同样适用于此。
标记分块完成 仅将你实现的这一个分块在分块计划中标记为完成（将'- [ ]'改为'- [x]'）。
填写你实现的分块对应的
#### Implementation Log
总结修改的文件、关键决策和所有值得注意的内容。
按照项目约定提交并推送代码 提交信息以
```
chunk N/T:
```
开头，后面跟简短描述。
修复构建错误 等待构建完成，修复所有报错，按需重复本步骤。

阻塞故障规则： 在分块工作流的任何阶段，如果你遇到无法修复的故障（构建基础设施损坏、缺少工具、仓库配置错误、与本分块改动无关的测试失败），不要输出

REMAINING_CHUNKS=n

，而是在最后一行输出

RALPH_BLOCKED=<简短原因>

后立即停止，不要尝试实现下一个分块。

4c Run agent test plan (if present)

4c 运行Agent测试计划（如果存在）

Check if the spec references an agent test plan (look for a
```
## Agent Test Plan
```
section or a companion
```
*-agent-test-plan.md
```
file). If one exists, execute the test plan and verify it is successful.

检查spec是否引用了Agent测试计划 查找
```
## Agent Test Plan
```
部分或者配套的
```
*-agent-test-plan.md
```
文件。如果存在，执行测试计划并验证成功。

4d Verify CI/CD build is green

4d 验证CI/CD构建正常

CI/CD gate — MANDATORY before marking IMPLEMENTED. The spec CANNOT be marked IMPLEMENTED unless the CI/CD build is confirmed GREEN (no failures). Follow this procedure:
1. Check if the project has a
```
buildgit
```
  skill installed (look for a
```
SKILL.md
```
  in a
```
skill/buildgit/
```
  directory) and a configured build job (e.g.
```
JENKINS_URL
```
  is set, or a Jenkinsfile exists).
2. If buildgit is available and a build job is configured: Run
```
buildgit status
```
  (or equivalent) and verify the latest build result is SUCCESS with no test failures. If the build is failing, fix the issues and push again. Repeat until the build is GREEN. Do NOT proceed to mark the spec IMPLEMENTED while the build is broken.
3. If buildgit is NOT installed or no build job is configured: This is acceptable — note it in the implementation review report under the
```
## CI/CD Verification
```
  section (see Implementation Review Report template). Proceed to the next step.

CI/CD关卡 — 标记为IMPLEMENTED前的强制要求 除非CI/CD构建确认是GREEN（无失败），否则spec不能标记为IMPLEMENTED。遵循以下流程：
1. 检查项目是否安装了
```
buildgit
```
  技能（查找
```
skill/buildgit/
```
  目录下的
```
SKILL.md
```
  ）和配置好的构建任务（例如设置了
```
JENKINS_URL
```
  ，或者存在Jenkinsfile）。
2. 如果已安装buildgit且配置了构建任务： 运行
```
buildgit status
```
  （或等效命令），验证最新构建结果为SUCCESS，无测试失败。如果构建失败，修复问题后重新推送，重复直到构建为GREEN。构建失败时绝对不要继续将spec标记为IMPLEMENTED。
3. 如果未安装buildgit或未配置构建任务： 这种情况是可接受的，在实现审核报告的
```
## CI/CD Verification
```
  部分注明即可（见实现审核报告模板），继续下一步。

4e Update documentation and metadata

4e 更新文档和元数据

Update the spec file: Change its
```
State:
```
field to
```
IMPLEMENTED
```
and add it to the spec index in
```
specs/README.md
```
.
Handle referenced files: If the spec lists files in its
```
References:
```
header, move those files to
```
specs/done-reports/
```
and update the reference paths in the spec accordingly.
Run any additional project-specific finalize steps as specified in the project's
```
CLAUDE.md
```
or
```
specs/CLAUDE.md
```
. This is the extension point where project-specific documentation updates, skill file updates, and custom push/CI commands are executed.

更新spec文件： 将
```
State:
```
字段改为
```
IMPLEMENTED
```
，并将其添加到
```
specs/README.md
```
的spec索引中。
处理引用文件： 如果spec的
```
References:
```
头部列出了相关文件，将这些文件移动到
```
specs/done-reports/
```
目录下，并对应更新spec中的引用路径。
执行项目特定的额外收尾步骤 按照项目的
```
CLAUDE.md
```
或
```
specs/CLAUDE.md
```
中的说明执行。这是扩展点，可以执行项目特定的文档更新、技能文件更新、自定义推送/CI命令等操作。

Spec State Machine

Spec状态机

DRAFT: Spec written, not yet implemented.
IMPLEMENTED: Code written, tests passing, docs updated. This is the normal post-implementation resting state and it is acceptable for a spec or its chunks to remain here indefinitely until a human validation pass happens.
VALIDATED: Human has manually verified the implementation. Validation is a separate later step from implementation.

DRAFT: Spec已编写，尚未实现。
IMPLEMENTED: 代码已编写，测试通过，文档已更新。这是实现后的常规稳定状态，在人工验证之前，spec或其分块可以无限期保持该状态。
VALIDATED: 人工已手动验证实现。验证是实现之后的独立步骤。

IMPLEMENTED → VALIDATED

Perform all manual testing to make sure the change does what it claims (human does this)
Mark the
```
State:
```
of the spec to
```
VALIDATED
```
For chunked work, it is valid to move every completed chunk from
```
IMPLEMENTED
```
to
```
VALIDATED
```
in one later pass after the human verifies the integrated feature end-to-end. Do not require each chunk to be validated immediately after its implementation.

执行所有手动测试，确认改动符合预期（由人工完成）
将spec的
```
State:
```
标记为
```
VALIDATED
```
对于分块实现的工作，人工端到端验证集成后的功能后，可以一次性将所有已完成的分块从
```
IMPLEMENTED
```
改为
```
VALIDATED
```
，不需要每个分块实现后立即验证。

Multi-chunk plan workflow tiers

多分块计划工作流层级

When implementing a spec via a chunk plan, the workflow is split into tiers as documented in

references/taskcreator.md

Initialize workflow (runs before any chunks are implemented)

Run all unit tests before starting

Per-chunk workflow (each chunk does these):

Finalize workflow (runs once after all chunks complete):

Update CHANGELOG.md, README.md, and any other project documentation
Generate the implementation review report (see below)
Run any additional project-specific finalize steps (per project's CLAUDE.md)
Push and verify CI
CI/CD gate: confirm the build is GREEN before marking the spec IMPLEMENTED (see Workflow 4d)
Human validation may later move the completed chunks and/or parent spec from
```
IMPLEMENTED
```
to
```
VALIDATED
```
in a single follow-up pass

Single-spec implementation (without a plan) continues to do everything in one pass as described above.

使用分块计划实现spec时，工作流按照

references/taskcreator.md

中的文档分为不同层级：

初始化工作流（在实现任何分块前运行）

开始前运行所有单元测试

分块工作流（每个分块都执行这些步骤）：

收尾工作流（所有分块完成后运行一次）：

更新CHANGELOG.md、README.md和所有其他项目文档
生成实现审核报告（见下文）
执行所有项目特定的额外收尾步骤（遵循项目的CLAUDE.md）
推送并验证CI
CI/CD关卡：将spec标记为IMPLEMENTED前确认构建为GREEN（见工作流4d）
后续人工验证可以在一次跟进操作中，将已完成的分块和/或父spec从
```
IMPLEMENTED
```
批量改为
```
VALIDATED
```

无分块计划的单spec实现按照上文描述一次性完成所有步骤。

Implementation Review Report

实现审核报告

Every spec implementation — whether via chunk plan, single-pass, or follow-up bug fix — MUST produce a review report at finalize time.

每个spec实现，无论是通过分块计划、单阶段实现还是后续bug修复，都必须在收尾阶段生成审核报告。

File location and naming

文件位置和命名

specs/done-reports/{spec-basename}-review.md

Example:

specs/claim-domain-spec.md

→

specs/done-reports/claim-domain-spec-review.md

specs/done-reports/{spec-basename}-review.md

示例：

specs/claim-domain-spec.md

→

specs/done-reports/claim-domain-spec-review.md

Report template

报告模板

markdown

undefined

markdown

undefined

Implementation Review: {spec title}

Spec:

specs/{spec-file}.md

Implemented: {date} Implementer: {agent or human}

Spec:

specs/{spec-file}.md

Implemented: {date} Implementer: {agent or human}

Existing Test Modifications

Test File	Change	Spec Backing	Rationale

If no existing tests were modified, write: "No existing tests were modified."

Test File	Change	Spec Backing	Rationale

如果没有修改现有测试，填写："No existing tests were modified."

CI/CD Verification

Record the CI/CD build status at finalize time. One of:

Build GREEN:
```
<build tool> status
```
confirmed SUCCESS (build #N, date)
No CI/CD configured: project does not have a buildgit skill installed or no build job is configured. Spec marked IMPLEMENTED without CI/CD verification.

记录收尾阶段的CI/CD构建状态，选填其中一项：

Build GREEN:
```
<build tool> status
```
confirmed SUCCESS (build #N, date)
No CI/CD configured: project does not have a buildgit skill installed or no build job is configured. Spec marked IMPLEMENTED without CI/CD verification.

Flagged Decisions

Any entry above with Spec Backing = "None" must be repeated here with additional context about why the agent proceeded without spec backing. These are the items that most need reviewer attention.

所有

Spec Backing = "None"

的条目都需要在这里重复，补充Agent在无spec支撑的情况下继续推进的上下文。这些是最需要审核者关注的内容。

Files Changed (alphabetical)

```
path/to/modified-file.ext
```

List only project files that were modified (not created) by this implementation. Exclude temporary files, build artifacts, and generated output.

```
path/to/modified-file.ext
```

仅列出本次实现修改的项目文件，不包含临时文件、构建产物和生成的输出。

Files Created (alphabetical)

```
path/to/new-file.ext
```

List only new project files added by this implementation. Exclude temporary files, build artifacts, and generated output.

```
path/to/new-file.ext
```

仅列出本次实现新增的项目文件，不包含临时文件、构建产物和生成的输出。

Key Implementation Decisions

{notable design decisions, trade-offs, or deviations from the spec, one per bullet}

{值得注意的设计决策、权衡、或与spec的偏差，每条一个项目符号}

Consolidation

If a chunk plan was used, summarize each chunk's Implementation Log entry here (one bullet per chunk). This provides a single-file view of the entire implementation.

undefined

如果使用了分块计划，在这里总结每个分块的实现日志条目（每个分块一个项目符号），提供整个实现的单文件视图。

undefined

How the report is built

报告构建方式

During implementation: Each time you modify an existing test, immediately append a row to a scratch log (the chunk's
```
#### Implementation Log
```
if using a chunk plan, or a temporary
```
## Implementation Review Notes
```
section at the bottom of the spec file if not). Do not defer this — log it when you make the change.
At finalize time: Consolidate all logged entries into the review report file. Remove any temporary scratch sections from the spec file.

实现期间： 每次修改现有测试时，立即在临时日志中添加一行（如果使用分块计划，记录在分块的
```
#### Implementation Log
```
中；如果未使用分块计划，记录在spec文件底部临时的
```
## Implementation Review Notes
```
部分）。不要延后记录，改动时就记录。
收尾阶段： 将所有日志条目合并到审核报告文件中，删除spec文件中的所有临时记录部分。

specmgr

Original

Translation

Spec-Driven Development Workflow Manager

Spec驱动开发工作流管理器

Workflow 1: Create DRAFT Spec

工作流1：创建DRAFT Spec

Before writing the spec

编写spec之前

STOP: Ask clarifying questions

暂停：询问澄清问题

Naming convention

命名规范

Spec template

Spec模板

Title

Title

Setting the Chunked: field

设置Chunked:字段

Root cause analysis

根因分析

Companion agent test plan

配套Agent测试计划

Agent test plan guidelines

Agent测试计划指南

SPEC workflow section

SPEC工作流部分

SPEC workflow

SPEC workflow

Superseded specs

被替代的spec

Workflow 2: Create Chunk Plan

工作流2：生成分块计划

Instructions

操作说明

Plan file naming

计划文件命名

SPEC Workflow in plans

计划中的SPEC工作流

Workflow 3: Implement DRAFT Spec (DRAFT → IMPLEMENTED)

工作流3：实现DRAFT Spec（DRAFT → IMPLEMENTED）

3a Before writing code

3a 编写代码前

3b Implement the feature or fix

3b 实现功能或修复

Existing test modification policy

现有测试修改规则

3c Run agent test plan (if present)

3c 运行Agent测试计划（如果存在）

3d Verify CI/CD build is green

3d 验证CI/CD构建正常

3e Update documentation and metadata

3e 更新文档和元数据

Workflow 4: Implement DRAFT Spec using chunk plan (DRAFT → IMPLEMENTED)

工作流4：使用分块计划实现DRAFT Spec（DRAFT → IMPLEMENTED）

4a Before writing code

4a 编写代码前

4b Per-Chunk Workflow (every chunk must follow these steps)

4b 分块工作流（每个分块都必须遵循以下步骤）

4c Run agent test plan (if present)

4c 运行Agent测试计划（如果存在）

4d Verify CI/CD build is green

4d 验证CI/CD构建正常

4e Update documentation and metadata

4e 更新文档和元数据

Spec State Machine

Spec状态机

IMPLEMENTED → VALIDATED

IMPLEMENTED → VALIDATED

Multi-chunk plan workflow tiers

多分块计划工作流层级

Implementation Review Report

实现审核报告

File location and naming

文件位置和命名

Report template

报告模板

Implementation Review: {spec title}

Implementation Review: {spec title}

Existing Test Modifications

Setting the
`Chunked:`
field

设置
`Chunked:`
字段