spec-impl

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

/spec-impl — Implementer of approved specs

/spec-impl — 已获批规范的实现工具

Session context

会话上下文

Current repository state: !

git status --short

Current branch: !

git branch --show-current

Specs available in this folder: !

ls specs/ 2>/dev/null || echo "The specs/ folder does not exist"

Branch-creation config: !

cat specs/.spec-config.yml 2>/dev/null || echo "AutoCreateBranch: true (default, no config file)"

当前仓库状态： !

git status --short

当前分支： !

git branch --show-current

当前目录下可用的规范： !

ls specs/ 2>/dev/null || echo "The specs/ folder does not exist"

分支创建配置： !

cat specs/.spec-config.yml 2>/dev/null || echo "AutoCreateBranch: true (default, no config file)"

Instructions

操作说明

Follow these four phases in strict order. Do not advance to the next phase if the previous one did not complete correctly.

严格按照以下四个阶段顺序执行。若前一阶段未正确完成，不得进入下一阶段。

Phase 1 — Identify the spec

阶段1 — 确定目标规范

The received argument is:

$ARGUMENTS

$ARGUMENTS

is empty:

List the files available in
```
specs/
```
(you already have them above).
Ask the user to specify the exact name of the spec.
Stop and wait for an answer. Do not continue.

$ARGUMENTS

has a value:

Look for the file in
```
specs/
```
. The user may have written the full name (
```
01-mvp-arkanoid
```
), only the number (
```
01
```
), or only the slug (
```
mvp-arkanoid
```
). Try to find the correct file in any of those cases.
If you do not find the file, show the available specs and ask the user to correct the name.
If you do find it, continue to Phase 2.

接收的参数为：

$ARGUMENTS

若

$ARGUMENTS

为空：

列出
```
specs/
```
目录下的所有文件（上述内容已包含该信息）。
请求用户指定规范的准确名称。
停止操作并等待用户回复，不得继续执行。

若

$ARGUMENTS

有值：

在
```
specs/
```
目录中查找对应文件。用户可能输入完整名称（如
```
01-mvp-arkanoid
```
）、仅编号（如
```
01
```
）或仅别名（如
```
mvp-arkanoid
```
），需尝试通过这些方式找到正确的文件。
若未找到文件，显示可用的规范列表并请用户修正名称。
若找到文件，进入阶段2。

Phase 2 — Validate the spec's state

阶段2 — 验证规范状态

Read the spec file you located in Phase 1 using the Read tool or

cat

In the file's contents, look for the line that contains the spec's state. The header label is typically

**Status:**

(English) or

**Estado:**

(Spanish), but it may use any language. Match by position (status line near the top of the spec) and by the surrounding state machine, not by the exact label.

Absolute rule: You can only continue if the state means "Approved" — regardless of the language used.

Treat any of the following (and their equivalents in other languages) as the Approved state and continue:

English:
```
Approved
```
Spanish:
```
Aprobado
```
Portuguese:
```
Aprovado
```
French:
```
Approuvé
```
German:
```
Genehmigt
```
Italian:
```
Approvato
```
…or any other language's word that clearly means "approved"

Anything else (Draft / Borrador, In review / En revisión, Implemented / Implementado, Obsolete / Obsoleto, or any unrecognized value) means stop and show the error message below.

State category	Examples (any language)	Action
Approved	`Approved` , `Aprobado` , `Aprovado` , `Approuvé` , …	Continue to Phase 3.
Draft	`Draft` , `Borrador` , …	Stop. Show the error message below.
In review	`In review` , `En revisión` , …	Stop. Show the error message below.
Implemented	`Implemented` , `Implementado` , …	Stop. Show the error message below.
Obsolete	`Obsolete` , `Obsoleto` , …	Stop. Show the error message below.
State line not found / unrecognized value	—	Stop. The file does not follow the expected format. Tell this to the user.

If you are unsure whether a value means "approved", do not assume. Stop and ask the user to clarify or to update the spec to the canonical wording.

Standard error message when the state does not mean Approved:

❌ I cannot implement this spec.

Current state: [STATE FOUND]
I only work with specs whose state means "Approved" (e.g. `Approved`, `Aprobado`,
or the equivalent in another language).

To continue you have two options:
  1. If the spec is ready to be implemented, open it and change the state
     to "Approved" (or the equivalent term your team uses) manually.
     That change is made by the human, not the agent.
  2. If the spec still needs work, use /spec [name] to resume it.

Do not offer alternatives, do not suggest "I can still start if you want". The block is intentional.

使用Read工具或

cat

命令读取阶段1中定位到的规范文件。

在文件内容中查找包含规范状态的行。状态标题通常为

**Status:**

（英文）或

**Estado:**

（西班牙语），但也可能使用其他语言。请根据位置（状态行通常位于规范顶部附近）和状态流转逻辑匹配，而非依赖确切的标题文本。

绝对规则：仅当状态明确表示“已批准”时，方可继续执行——无论使用何种语言表述。

以下表述（及其他语言的等价表述）均视为“已批准”状态，可继续执行：

英文：
```
Approved
```
西班牙语：
```
Aprobado
```
葡萄牙语：
```
Aprovado
```
法语：
```
Approuvé
```
德语：
```
Genehmigt
```
意大利语：
```
Approvato
```
…或其他语言中明确表示“已批准”的词汇

任何其他状态（草稿/Draft、审核中/In review、已实现/Implemented、已废弃/Obsolete，或无法识别的状态值）均需停止操作并显示下方的错误信息。

状态类别	示例（任意语言）	操作说明
已批准	`Approved` , `Aprobado` , `Aprovado` , `Approuvé` , …	进入阶段3。
草稿	`Draft` , `Borrador` , …	停止操作，显示下方的错误信息。
审核中	`In review` , `En revisión` , …	停止操作，显示下方的错误信息。
已实现	`Implemented` , `Implementado` , …	停止操作，显示下方的错误信息。
已废弃	`Obsolete` , `Obsoleto` , …	停止操作，显示下方的错误信息。
未找到状态行/无法识别的状态值	—	停止操作，告知用户该文件不符合预期格式。

若不确定某个状态值是否表示“已批准”，请勿假设，停止操作并请用户澄清或更新规范至标准表述。

状态非“已批准”时的标准错误信息：

❌ 我无法实现此规范。

当前状态：[检测到的状态]
我仅能处理状态为“已批准”的规范（例如`Approved`、`Aprobado`或其他语言的等价表述）。

如需继续，您有两个选项：
  1. 若该规范已准备好实现，请手动打开文件并将状态修改为“已批准”（或您团队使用的等价术语）。
     此修改需由人工完成，而非Agent执行。
  2. 若该规范仍需完善，请使用/spec [名称]指令继续处理该规范。

不得提供其他替代方案，不得建议“若您需要我仍可开始执行”。此限制为强制要求。

Phase 3 — Create the git branch and switch to it

阶段3 — 创建并切换至Git分支

Once you have confirmed the state means

Approved

Derive the branch name from the spec file's full name, without the extension. Format:
```
spec-NN-slug
```
. Examples:
- ```
01-mvp-arkanoid.md
```
  → branch
```
spec-01-mvp-arkanoid
```
- ```
02-powerups.md
```
  → branch
```
spec-02-powerups
```
Read the
```
AutoCreateBranch
```
flag from the Branch-creation config shown in the session context above.
- If the config file does not exist, the value is missing, or the value is unrecognized → treat it as
```
true
```
  (the default).
- Only an explicit
```
false
```
  (in any capitalization) disables automatic branch creation.
If
AutoCreateBranch
is
true
(default): proceed without asking.
- If the branch does not exist: create it with
```
git checkout -b spec-NN-slug
```
  .
- If it already exists: inform the user that the branch already existed (it may mean previous work is being resumed).
- In both cases: switch to the branch with
```
git checkout spec-NN-slug
```
  and confirm the change was successful before continuing.
If
AutoCreateBranch
is
false
: ask before touching git. Show:
```
AutoCreateBranch is set to false.
Create and switch to the branch spec-NN-slug? [y/N]
```
- If the user answers yes: create/switch to the branch exactly as in the
```
true
```
  case above.
- If the user answers no or leaves it empty: do not create any branch. Tell the user you will implement on the current branch (the one shown in the session context above) and ask for explicit confirmation to continue there. Do not improvise — wait for the answer.

Visually confirm to the user the spec is ready and which branch is active:

✅ Ready to implement.

Spec:   specs/NN-slug.md
Branch: spec-NN-slug  (active)   (← or the current branch, if no new branch was created)
State:  Approved   (← echo back the actual value found in the spec)

Do not start implementing yet. First show the spec summary to the user so they have it fresh. Extract and show:
- The objective (the line after
```
**Objective:**
```
  /
```
**Objetivo:**
```
  / equivalent label).
- The scope (the
```
## Scope
```
  /
```
## Alcance
```
  / equivalent section).
- The implementation plan (the section with the numbered steps —
```
## Implementation plan
```
  /
```
## Plan de implementación
```
  / equivalent).
- The acceptance criteria (the checklist —
```
## Acceptance criteria
```
  /
```
## Criterios de aceptación
```
  / equivalent).

Match section headings by meaning, not by exact wording — the spec may be authored in any language.

确认状态为“已批准”后：

根据规范文件的完整名称（不含扩展名）生成分支名称，格式为
```
spec-NN-slug
```
。示例：
- ```
01-mvp-arkanoid.md
```
  → 分支
```
spec-01-mvp-arkanoid
```
- ```
02-powerups.md
```
  → 分支
```
spec-02-powerups
```
读取上述会话上下文中“分支创建配置”里的
```
AutoCreateBranch
```
标志：
- 若配置文件不存在、该值缺失或无法识别，则视为默认值
```
true
```
  。
- 仅当明确设置为
```
false
```
  （任意大小写）时，才会禁用自动分支创建。
若
AutoCreateBranch
为
true
（默认值）：无需询问直接执行
- 若分支不存在：使用
```
git checkout -b spec-NN-slug
```
  创建分支。
- 若分支已存在：告知用户该分支已存在（意味着可能要恢复之前的工作）。
- 无论哪种情况：使用
```
git checkout spec-NN-slug
```
  切换至该分支，并在继续执行前确认切换成功。
若
AutoCreateBranch
为
false
：操作Git前需询问用户，显示以下内容：
```
AutoCreateBranch已设置为false。
是否创建并切换至分支spec-NN-slug？[y/N]
```
- 若用户回答是：完全按照
```
true
```
  情况下的步骤创建/切换分支。
- 若用户回答否或未回复：不得创建任何分支。告知用户将在当前分支（会话上下文中显示的分支）进行实现，并请求用户明确确认是否继续在此分支执行。不得自行操作，需等待用户回复。

向用户直观确认规范已准备就绪，以及当前激活的分支：

✅ 已准备好开始实现。

规范：specs/NN-slug.md
分支：spec-NN-slug （已激活）（← 若未创建新分支，则显示当前分支）
状态：Approved （← 回显在规范中检测到的实际状态值）

暂不开始实现。先向用户展示规范摘要，以便用户清晰了解内容。需提取并展示：
- 目标（
```
**Objective:**
```
  /
```
**Objetivo:**
```
  或等价标题后的内容）。
- 范围（
```
## Scope
```
  /
```
## Alcance
```
  或等价章节）。
- 实现计划（包含编号步骤的章节，如
```
## Implementation plan
```
  /
```
## Plan de implementación
```
  或等价章节）。
- 验收标准（清单形式的章节，如
```
## Acceptance criteria
```
  /
```
## Criterios de aceptación
```
  或等价章节）。

请根据章节含义匹配，而非依赖确切的表述——规范可能使用任意语言编写。

Phase 4 — Implement step by step

阶段4 — 分步实现

After showing the spec summary, tell the user:

I am going to implement the spec following the implementation plan exactly.
I will pause after each step so you can review the diff.

Shall we start with Step 1?

Wait for explicit confirmation ("yes", "go ahead", "go", or equivalent). Do not start without it.

Once confirmed, follow these rules during the entire implementation:

One rule above all: implement what the spec says. If something in the spec looks suboptimal to you, mention it as an observation but implement what was agreed. Changes to the spec go into the spec, not into the code by surprise.

Work rhythm:

Implement one step of the plan.
Show a summary of which files you touched and what you did.

Say:

Step N completed. Could you review the diff and let me know if I continue with Step N+1?

Wait for confirmation before continuing.

If during the implementation you find an ambiguity the spec does not resolve:

Stop.
Describe the ambiguity exactly.
Present two or three concrete options.
Wait for the user's decision.
Do not improvise.

If the user asks for something that is out of the spec's scope:

Remind them that it is out of this spec's scope.
Suggest noting it down for the next spec.
Do not implement it on this branch.

When finishing the last step:

✅ All steps of the plan are implemented.

Next step: verify the spec's acceptance criteria one by one.
If they all pass, update the spec's state to "Implemented" (or the equivalent
in your repo's language) and make the final commit before merging this branch.

展示规范摘要后，告知用户：

我将严格按照实现计划逐步完成规范的实现。
每完成一步我会暂停，以便您查看差异。

是否开始执行步骤1？

需等待用户明确确认（如“yes”、“开始”、“go”或等价表述），未确认不得开始执行。

确认后，在整个实现过程中需遵循以下规则：

首要规则：严格按照规范内容实现。若您认为规范中的某些内容不够优化，可以提出意见，但仍需按照已达成共识的内容实现。规范的修改需在规范文件中进行，不得擅自修改代码。

工作节奏：

完成计划中的一个步骤。
展示您修改的文件及操作摘要。

告知用户：

步骤N已完成。请查看差异并告知我是否继续执行步骤N+1？

等待用户确认后再继续执行。

若在实现过程中发现规范未明确说明的歧义：

停止操作。
准确描述歧义点。
提供2-3个具体的解决方案选项。
等待用户决策。
不得自行操作。

若用户要求实现超出规范范围的内容：

提醒用户该内容超出当前规范的范围。
建议将其记录下来，用于后续规范的制定。
不得在当前分支实现该内容。

完成最后一步时：

✅ 实现计划中的所有步骤已完成。

下一步：逐一验证规范的验收标准。
若所有标准均通过，请将规范状态更新为“Implemented”（或您仓库使用的等价术语），并在合并分支前完成最终提交。

Summary of expected behavior

预期行为总结

/impl-spec 01-mvp-arkanoid

  Phase 1  →  Finds specs/01-mvp-arkanoid.md
  Phase 2  →  Reads the state → "Approved" (or "Aprobado", etc.) → ✅ continues
  Phase 3  →  git checkout -b spec-01-mvp-arkanoid → git checkout spec-01-mvp-arkanoid
              Shows objective, scope, plan and criteria
  Phase 4  →  Implements step by step with pauses
              Ends by reminding to verify the acceptance criteria

/impl-spec 02-powerups  (state: Draft / Borrador)

  Phase 1  →  Finds specs/02-powerups.md
  Phase 2  →  Reads the state → "Draft" → ❌ stops
              Shows the standard error message
              Does not create branch, does not touch code

Branch creation is controlled by the
AutoCreateBranch
flag in

specs/.spec-config.yml

. It defaults to

true

(create the branch automatically, as shown above). Set it to

false

to make Phase 3 ask

[y/N]

before creating the branch.

/impl-spec 01-mvp-arkanoid

  阶段1 → 找到specs/01-mvp-arkanoid.md
  阶段2 → 读取状态 → "Approved"（或"Aprobado"等）→ ✅ 继续执行
  阶段3 → git checkout -b spec-01-mvp-arkanoid → git checkout spec-01-mvp-arkanoid
          展示目标、范围、实现计划和验收标准
  阶段4 → 分步实现并暂停
          结束时提醒用户验证验收标准

/impl-spec 02-powerups （状态：Draft / Borrador）

  阶段1 → 找到specs/02-powerups.md
  阶段2 → 读取状态 → "Draft" → ❌ 停止操作
          显示标准错误信息
          不创建分支，不修改代码

分支创建由
specs/.spec-config.yml
中的
AutoCreateBranch
标志控制，默认值为

true

（自动创建分支，如上所示）。将其设置为

false

后，阶段3会在创建分支前询问用户

[y/N]

。