speckit-converge

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

User Input

用户输入

text

$ARGUMENTS

You MUST consider the user input before proceeding (if not empty).

text

$ARGUMENTS

你必须在执行前考虑用户输入（如果输入不为空）。

Pre-Execution Checks

执行前检查

Check for extension hooks (before convergence):

Check if
```
.specify/extensions.yml
```
exists in the project root.
If it exists, read it and look for entries under the
```
hooks.before_converge
```
key
If the YAML cannot be parsed or is invalid, skip hook checking silently and continue normally
Filter out hooks where
```
enabled
```
is explicitly
```
false
```
. Treat hooks without an
```
enabled
```
field as enabled by default.
For each remaining hook, do not attempt to interpret or evaluate hook
```
condition
```
expressions:
- If the hook has no
```
condition
```
  field, or it is null/empty, treat the hook as executable
- If the hook defines a non-empty
```
condition
```
  , skip the hook and leave condition evaluation to the HookExecutor implementation
When constructing command invocations from hook command names, replace dots (
```
.
```
) with hyphens (
```
-
```
). For example,
```
speckit.git.commit
```
→
```
/speckit-git-commit
```
.
For each executable hook, output the following based on its
```
optional
```
flag:
- Optional hook (
```
optional: true
```
  ):
  text
```
## Extension Hooks

**Optional Pre-Hook**: {extension}
Command: `/{command}`
Description: {description}

Prompt: {prompt}
To execute: `/{command}`
```
- Mandatory hook (
```
optional: false
```
  ):
  text
```
## Extension Hooks

**Automatic Pre-Hook**: {extension}
Executing: `/{command}`
EXECUTE_COMMAND: {command}

Wait for the result of the hook command before proceeding to the Goal.
```
  After emitting the block above you MUST actually invoke the hook and wait for it to finish before continuing. Run it the same way you would run the command yourself in this agent/session (the invocation may differ from the literal
```
{command}
```
  id shown above, e.g. a skills-mode agent runs it as
```
/skill:speckit-...
```
  or
```
$speckit-...
```
  ). Emitting the block alone does not run the hook.
If no hooks are registered or
```
.specify/extensions.yml
```
does not exist, skip silently

检查扩展钩子（收敛前）：

检查项目根目录下是否存在
```
.specify/extensions.yml
```
文件。
如果存在，读取该文件并查找
```
hooks.before_converge
```
键下的条目
如果YAML文件无法解析或无效，静默跳过钩子检查并正常继续执行
过滤掉
```
enabled
```
字段明确设为
```
false
```
的钩子。未设置
```
enabled
```
字段的钩子默认视为启用状态。
对于剩余的每个钩子，不要尝试解释或评估钩子的
```
condition
```
表达式：
- 如果钩子没有
```
condition
```
  字段，或者该字段为null/空值，则视为可执行钩子
- 如果钩子定义了非空的
```
condition
```
  字段，跳过该钩子，将条件评估留给HookExecutor实现处理
从钩子命令名称构造命令调用时，将点号（
```
.
```
）替换为连字符（
```
-
```
）。例如，
```
speckit.git.commit
```
→
```
/speckit-git-commit
```
。
对于每个可执行钩子，根据其
```
optional
```
标志输出以下内容：
- 可选钩子（
```
optional: true
```
  ）：
  text
```
## 扩展钩子

**可选前置钩子**：{extension}
命令：`/{command}`
描述：{description}

提示：{prompt}
执行方式：`/{command}`
```
- 强制钩子（
```
optional: false
```
  ）：
  text
```
## 扩展钩子

**自动前置钩子**：{extension}
正在执行：`/{command}`
EXECUTE_COMMAND: {command}

在继续执行目标任务前，请等待钩子命令执行完成。
```
  输出上述代码块后，你必须实际调用该钩子并等待其执行完成后再继续。按照你在当前agent/会话中运行命令的方式执行它（调用方式可能与上面显示的字面
```
{command}
```
  ID不同，例如技能模式的agent会以
```
/skill:speckit-...
```
  或
```
$speckit-...
```
  的方式运行）。仅输出代码块并不会运行钩子。
如果没有注册钩子或
```
.specify/extensions.yml
```
不存在，静默跳过

Goal

目标

Close the gap between what a feature's specification, plan, and tasks call for and what the codebase currently implements. Read

spec.md

plan.md

, and

tasks.md

as the sole source of intent (with the constitution as governing constraints), assess the current state of the code, determine which requirements, acceptance criteria, plan decisions, and existing tasks are unmet, incomplete, or only partially satisfied, and append each piece of remaining work as a new, traceable task at the bottom of

tasks.md

so that

/speckit-implement

can complete it. This command MUST run only after

/speckit-implement

has run on the current

tasks.md

, and after

/speckit-tasks

has produced a complete

tasks.md

This is not a diff tool and does not track changes. It assesses the present state of the code relative to the feature's artifacts — no git, no branch comparison, no history.

缩小功能规格说明、计划、任务要求与代码库当前实现之间的差距。将

spec.md

、

plan.md

和

tasks.md

作为唯一的意图来源（以项目章程为约束），评估代码的当前状态，确定哪些需求、验收标准、计划决策和现有任务未满足、未完成或仅部分满足，并将每一项剩余工作作为可追溯的新任务追加到tasks.md的末尾，以便

/speckit-implement

命令完成这些任务。该命令必须在

/speckit-implement

已针对当前

tasks.md

运行，且

/speckit-tasks

已生成完整的

tasks.md

之后才能执行。

这不是差异工具，也不跟踪变更。它仅评估代码当前状态与功能工件之间的差距——不涉及git、分支对比或历史记录。

Operating Constraints

操作约束

APPEND-ONLY, NEVER REWRITE: The command's only write is appending a new

## Phase N: Convergence

section to

tasks.md

. It MUST NOT:

modify
```
spec.md
```
or
```
plan.md
```
in any way;
rewrite, renumber, reorder, or delete any existing task (including tasks from a prior Convergence phase);
modify, create, or delete any application code — completing the appended tasks is the job of
```
/speckit-implement
```
.

When the codebase already satisfies everything, the command MUST leave

tasks.md

byte-for-byte unchanged (no empty Convergence header) and report a clean result.

Constitution Authority: The project constitution (

.specify/memory/constitution.md

) is non-negotiable. Code that violates a MUST principle is the highest-severity finding and produces a corresponding remediation task. If the constitution is an unfilled template, skip constitution checks gracefully rather than failing.

仅追加，绝不重写：该命令唯一的写入操作是向

tasks.md

追加一个新的

## Phase N: Convergence

章节。它不得：

以任何方式修改
```
spec.md
```
或
```
plan.md
```
；
重写、重新编号、重新排序或删除任何现有任务（包括之前收敛阶段的任务）；
修改、创建或删除任何应用代码——完成追加任务是
```
/speckit-implement
```
的工作。

当代码库已完全满足所有要求时，该命令必须保持

tasks.md

字节级不变（不添加空的收敛标题）并报告结果符合要求。

章程权威性：项目章程（

.specify/memory/constitution.md

）是不可协商的。违反MUST原则的代码是最高严重级别的问题，需生成对应的修复任务。如果章程是未填充的模板，则优雅地跳过章程检查，而非执行失败。

Execution Steps

执行步骤

1. Initialize Convergence Context

1. 初始化收敛上下文

Run

.specify/scripts/bash/check-prerequisites.sh --json --require-tasks --include-tasks

once from repo root and parse JSON for FEATURE_DIR and AVAILABLE_DOCS. Derive absolute paths:

SPEC = FEATURE_DIR/spec.md
PLAN = FEATURE_DIR/plan.md
TASKS = FEATURE_DIR/tasks.md
CONSTITUTION =
```
.specify/memory/constitution.md
```
(if present) If
```
spec.md
```
,
```
plan.md
```
, or
```
tasks.md
```
is missing, STOP with a clear, actionable message naming the prerequisite command to run (
```
/speckit-specify
```
for a missing spec,
```
/speckit-plan
```
for a missing plan,
```
/speckit-tasks
```
for missing tasks). Do not produce partial output. For single quotes in args like "I'm Groot", use escape syntax: e.g 'I'''m Groot' (or double-quote if possible: "I'm Groot").

从仓库根目录运行一次

.specify/scripts/bash/check-prerequisites.sh --json --require-tasks --include-tasks

，并解析JSON以获取FEATURE_DIR和AVAILABLE_DOCS。推导绝对路径：

SPEC = FEATURE_DIR/spec.md
PLAN = FEATURE_DIR/plan.md
TASKS = FEATURE_DIR/tasks.md
CONSTITUTION =
```
.specify/memory/constitution.md
```
（如果存在）如果
```
spec.md
```
、
```
plan.md
```
或
```
tasks.md
```
缺失，停止执行并输出清晰、可操作的消息，指明需要运行的前置命令（缺失规格说明时运行
```
/speckit-specify
```
，缺失计划时运行
```
/speckit-plan
```
，缺失任务时运行
```
/speckit-tasks
```
）。不得生成部分输出。对于参数中的单引号，例如"I'm Groot"，使用转义语法：例如'I'''m Groot'（或尽可能使用双引号："I'm Groot"）。

2. Load Artifacts (Progressive Disclosure)

2. 加载工件（渐进式披露）

Load only the minimal necessary context from each artifact:

From spec.md:

Functional Requirements (FR-###)
Success Criteria (SC-###) — include only items requiring buildable work; exclude post-launch outcome metrics and business KPIs
User Stories and their Acceptance Scenarios
Edge Cases (if present)

From plan.md:

Architecture/stack choices and technical decisions
Data Model references
Phases and named touch-points (files/components the plan says will be created or edited)
Technical constraints

From tasks.md:

Task IDs (to compute the next ID and next phase number)
Descriptions, phase grouping, and referenced file paths

From constitution (if not an unfilled template):

Principle names and MUST/SHOULD normative statements

仅从每个工件加载必要的最小上下文：

从spec.md中加载：

功能需求（FR-###）
成功标准（SC-###）——仅包含需要可构建工作的条目；排除发布后的结果指标和业务KPI
用户故事及其验收场景
边缘情况（如果存在）

从plan.md中加载：

架构/技术栈选择和技术决策
数据模型引用
阶段和命名接触点（计划中说明将创建或编辑的文件/组件）
技术约束

从tasks.md中加载：

任务ID（用于计算下一个ID和下一个阶段编号）
描述、阶段分组和引用的文件路径

从章程中加载（如果不是未填充的模板）：

原则名称和MUST/SHOULD规范性声明

3. Build the Intent Inventory

3. 构建意图清单

Create an internal model (do not echo raw artifacts):

Requirements inventory: one stable key per FR-### / SC-### / user-story acceptance scenario (e.g.
```
US1/AC2
```
), plus the plan decisions and constitution principles that impose buildable obligations.
Code-scope map: from the file paths named in
```
plan.md
```
and
```
tasks.md
```
, plus a keyword search for the concepts each requirement describes, derive the set of source files and components in scope for assessment. Bound the assessment to these — do not infer scope beyond what the artifacts define.

创建内部模型（不要回显原始工件）：

需求清单：每个FR-### / SC-### / 用户故事验收场景对应一个稳定键（例如
```
US1/AC2
```
），加上计划决策和章程原则中施加的可构建义务。
代码范围映射：从
```
plan.md
```
和
```
tasks.md
```
中指定的文件路径，加上对每个需求描述概念的关键词搜索，推导评估范围内的源文件和组件集合。评估仅限于这些范围——不得推断超出工件定义的范围。

4. Assess the Codebase and Classify Findings

4. 评估代码库并分类问题

For each item in the intent inventory, inspect the current code in scope and produce a

Finding

only where there is a gap. Classify every finding by gap type:

missing
: the required work is absent from the code entirely.
partial
: the work exists but does not yet fully satisfy the requirement / acceptance criterion / plan decision.
contradicts
: the code does something that conflicts with stated intent or a constitution MUST principle.
unrequested
: the code contains work not called for by the spec, plan, or tasks (surfaced for awareness — converge does not delete code, it only appends a task to review/justify or remove it).

Each

Finding

records: a stable id, the

source-ref

it traces to, the

gap-type

, a severity, and a short human-readable description with the evidence (the file/area observed).

Edge cases:

Little or no code yet: treat the entire specified scope as
```
missing
```
remaining work rather than failing.
Nothing remains: produce zero findings and follow the converged branch in Step 7.

对于意图清单中的每个条目，检查范围内的当前代码，仅在存在差距时生成

Finding

（问题记录）。按差距类型对每个问题进行分类：

missing
（缺失）：所需工作完全未在代码中实现。
partial
（部分实现）：工作已存在，但尚未完全满足需求/验收标准/计划决策。
contradicts
（冲突）：代码的行为与既定意图或章程MUST原则相冲突。
unrequested
（未请求）：代码包含规格说明、计划或任务中未要求的工作（仅用于告知——收敛命令不删除代码，仅追加任务以审查/证明合理性或移除该工作）。

每个

Finding

记录：一个稳定ID、追溯来源的

source-ref

、

gap-type

（差距类型）、严重程度，以及包含证据（观察到的文件/区域）的简短可读描述。

边缘情况：

几乎没有或完全没有代码：将指定范围内的所有工作视为
```
missing
```
（缺失）的剩余工作，而非执行失败。
无剩余工作：生成零个问题记录，然后执行步骤7中的收敛分支流程。

5. Assign Severity

5. 分配严重程度

CRITICAL: violates a constitution MUST principle, or a
```
missing
```
/
```
contradicts
```
gap that blocks baseline functionality of a P1 user story.
HIGH: a
```
missing
```
or
```
partial
```
gap on a core functional requirement or acceptance criterion.
MEDIUM: a
```
partial
```
gap on a secondary requirement, or an
```
unrequested
```
addition with unclear justification.
LOW: minor partial gaps, polish, or low-risk
```
unrequested
```
additions.

CRITICAL（严重）：违反章程MUST原则，或
```
missing
```
/
```
contradicts
```
类型的差距，且阻碍P1用户故事的基线功能。
HIGH（高）：核心功能需求或验收标准存在
```
missing
```
或
```
partial
```
类型的差距。
MEDIUM（中）：次要需求存在
```
partial
```
类型的差距，或
```
unrequested
```
类型的新增工作且合理性不明确。
LOW（低）：轻微的部分实现差距、优化工作，或低风险的
```
unrequested
```
类型新增工作。

6. Present the In-Session Findings Summary

6. 展示会话内问题记录摘要

Before appending anything, output a compact, severity-graded summary (no file writes yet):

在追加任何内容之前，输出一个紧凑的、按严重程度分级的摘要（暂不写入文件）：

Convergence Findings

收敛问题记录

ID	Gap Type	Severity	Source	Evidence	Remaining Work
F1	missing	HIGH	FR-008	Example: no append-only guard detected in path/to/module.py when writing tasks.md	Add append-only enforcement

Summary metrics:

Requirements / acceptance criteria checked
Plan decisions checked
Constitution principles checked (or "skipped — template")
Findings by gap type (missing / partial / contradicts / unrequested)
Findings by severity

ID	差距类型	严重程度	来源	证据	剩余工作
F1	missing	HIGH	FR-008	示例：在写入tasks.md时，path/to/module.py中未检测到仅追加保护机制	添加仅追加执行限制

汇总指标：

已检查的需求/验收标准数量
已检查的计划决策数量
已检查的章程原则数量（或“已跳过——模板”）
按差距类型统计的问题记录数量（missing / partial / contradicts / unrequested）
按严重程度统计的问题记录数量

7. Append Convergence Tasks (or report converged)

7. 追加收敛任务（或报告已收敛）

If there are one or more actionable findings (

tasks_appended

outcome):

Append to the end of

tasks.md

, per the append contract:

Scan all existing task IDs; let
```
M
```
be the maximum. Determine the next phase number
```
N
```
(highest existing phase + 1).
Write a single new section header
```
## Phase N: Convergence
```
.
Emit one checklist item per actionable finding, ordered CRITICAL/HIGH first, assigning zero-padded IDs
```
T{M+1:03d}, T{M+2:03d}, …
```
:
markdown
```
- [ ] T042 <imperative description> per <source-ref> (<gap-type>)
```
```
<source-ref>
```
traces the task to its origin: e.g.
```
FR-003
```
,
```
SC-002
```
,
```
US1/AC2
```
,
```
plan: storage decision
```
,
```
Constitution II
```
.
```
<gap-type>
```
is one of
```
missing
```
,
```
partial
```
,
```
contradicts
```
,
```
unrequested
```
.
Constitution-violation tasks MUST be emitted first and described as
```
CRITICAL
```
.
Never reuse or renumber existing IDs. If a prior Convergence phase exists, add a new, separately-numbered one below it — do not touch the old one.

If there are no actionable findings (

converged

outcome):

Do not modify
```
tasks.md
```
at all — no empty phase header.
Report: "✅ Converged — the implementation satisfies the spec, plan, and tasks."
Include the summary counts of what was checked.

如果存在一个或多个可操作的问题记录（

tasks_appended

结果）：

按照追加规则，将内容追加到

tasks.md

的末尾：

扫描所有现有任务ID；设
```
M
```
为最大ID值。确定下一个阶段编号
```
N
```
（现有最高阶段编号 + 1）。
写入一个新的章节标题
```
## Phase N: Convergence
```
。
为每个可操作的问题记录生成一个清单项，按CRITICAL/HIGH优先级排序，分配零填充ID
```
T{M+1:03d}, T{M+2:03d}, …
```
：
markdown
```
- [ ] T042 <命令式描述> 依据 <source-ref> (<gap-type>)
```
```
<source-ref>
```
追溯任务的来源：例如
```
FR-003
```
、
```
SC-002
```
、
```
US1/AC2
```
、
```
plan: storage decision
```
、
```
Constitution II
```
。
```
<gap-type>
```
为
```
missing
```
、
```
partial
```
、
```
contradicts
```
、
```
unrequested
```
中的一种。
违反章程的任务必须优先输出，并标记为
```
CRITICAL
```
。
绝不重用或重新编号现有ID。如果之前存在收敛阶段，在其下方添加一个新的、独立编号的阶段——不要修改旧阶段。

如果没有可操作的问题记录（

converged

结果）：

完全不修改
```
tasks.md
```
——不添加空的阶段标题。
报告："✅ 已收敛——实现满足规格说明、计划和任务要求。"
包含已检查内容的汇总统计。

8. Provide Next Actions (Handoff)

8. 提供后续操作（交接）

On
```
tasks_appended
```
: state how many tasks were appended under which phase, and recommend running
```
/speckit-implement
```
to complete them; note that a follow-up converge run will find fewer or no remaining items.
On
```
converged
```
: recommend proceeding to review / opening a PR. No further implement pass is needed for this feature's specified scope.

当结果为
```
tasks_appended
```
时：说明在哪个阶段追加了多少任务，并建议运行
```
/speckit-implement
```
来完成这些任务；注意后续运行收敛命令会发现更少或没有剩余项。
当结果为
```
converged
```
时：建议进入评审环节/发起PR。该功能的指定范围内无需再执行实现环节。

9. Check for extension hooks

9. 检查扩展钩子

After producing the result, check if

.specify/extensions.yml

exists in the project root.

If it exists, read it and look for entries under the
```
hooks.after_converge
```
key
If the YAML cannot be parsed or is invalid, skip hook checking silently and continue normally
Filter out hooks where
```
enabled
```
is explicitly
```
false
```
. Treat hooks without an
```
enabled
```
field as enabled by default.
For each remaining hook, do not attempt to interpret or evaluate hook
```
condition
```
expressions:
- If the hook has no
```
condition
```
  field, or it is null/empty, treat the hook as executable
- If the hook defines a non-empty
```
condition
```
  , skip the hook and leave condition evaluation to the HookExecutor implementation
Report the convergence outcome (
```
converged
```
or
```
tasks_appended
```
) in-session before listing any hooks, so users can decide whether to run optional follow-up commands.
When constructing command invocations from hook command names, replace dots (
```
.
```
) with hyphens (
```
-
```
). For example,
```
speckit.git.commit
```
→
```
/speckit-git-commit
```
.
For each executable hook, output the following based on its
```
optional
```
flag:
- Optional hook (
```
optional: true
```
  ):
  text
```
## Extension Hooks

**Optional Hook**: {extension}
Command: `/{command}`
Description: {description}

Prompt: {prompt}
To execute: `/{command}`
```
- Mandatory hook (
```
optional: false
```
  ):
  text
```
## Extension Hooks

**Automatic Hook**: {extension}
Executing: `/{command}`
EXECUTE_COMMAND: {command}
```
  After emitting the block above you MUST actually invoke the hook and wait for it to finish before continuing. Run it the same way you would run the command yourself in this agent/session (the invocation may differ from the literal
```
{command}
```
  id shown above, e.g. a skills-mode agent runs it as
```
/skill:speckit-...
```
  or
```
$speckit-...
```
  ). Emitting the block alone does not run the hook.
If no hooks are registered or
```
.specify/extensions.yml
```
does not exist, skip silently

生成结果后，检查项目根目录下是否存在

.specify/extensions.yml

文件。

如果存在，读取该文件并查找
```
hooks.after_converge
```
键下的条目
如果YAML文件无法解析或无效，静默跳过钩子检查并正常继续执行
过滤掉
```
enabled
```
字段明确设为
```
false
```
的钩子。未设置
```
enabled
```
字段的钩子默认视为启用状态。
对于剩余的每个钩子，不要尝试解释或评估钩子的
```
condition
```
表达式：
- 如果钩子没有
```
condition
```
  字段，或者该字段为null/空值，则视为可执行钩子
- 如果钩子定义了非空的
```
condition
```
  字段，跳过该钩子，将条件评估留给HookExecutor实现处理
在列出任何钩子之前，先在会话中报告收敛结果（
```
converged
```
或
```
tasks_appended
```
），以便用户决定是否运行可选的后续命令。
从钩子命令名称构造命令调用时，将点号（
```
.
```
）替换为连字符（
```
-
```
）。例如，
```
speckit.git.commit
```
→
```
/speckit-git-commit
```
。
对于每个可执行钩子，根据其
```
optional
```
标志输出以下内容：
- 可选钩子（
```
optional: true
```
  ）：
  text
```
## 扩展钩子

**可选钩子**：{extension}
命令：`/{command}`
描述：{description}

提示：{prompt}
执行方式：`/{command}`
```
- 强制钩子（
```
optional: false
```
  ）：
  text
```
## 扩展钩子

**自动钩子**：{extension}
正在执行：`/{command}`
EXECUTE_COMMAND: {command}
```
  输出上述代码块后，你必须实际调用该钩子并等待其执行完成后再继续。按照你在当前agent/会话中运行命令的方式执行它（调用方式可能与上面显示的字面
```
{command}
```
  ID不同，例如技能模式的agent会以
```
/skill:speckit-...
```
  或
```
$speckit-...
```
  的方式运行）。仅输出代码块并不会运行钩子。
如果没有注册钩子或
```
.specify/extensions.yml
```
不存在，静默跳过