spec-impl

/spec-impl — 已批准规格的实施者

会话上下文

当前仓库状态： !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)"

---

说明

严格按顺序执行以下四个阶段。如果前一阶段未正确完成，请勿进入下一阶段。

---

阶段 1 — 确定规格

收到的参数为：$ARGUMENTS

如果 $ARGUMENTS 为空：

• 列出 specs/ 中的可用文件（上方已列出）。
• 请用户指定规格的准确名称。
• 停止并等待回答。不要继续。

如果 $ARGUMENTS 有值：

• 在 specs/ 中查找文件。用户可能输入了完整名称（01-mvp-arkanoid）、仅输入编号（01），或仅输入 slug（mvp-arkanoid）。请尝试在这些情况下找到正确的文件。
• 如果找不到文件，请显示可用规格并请用户更正名称。
• 如果找到文件，请继续阶段 2。

---

阶段 2 — 验证规格状态

使用 Read 工具或 cat 读取阶段 1 中找到的规格文件。

在文件内容中，查找包含规格状态的行。标题标签通常为 **Status:**（英语）或 **Estado:**（西班牙语），但也可能使用任何语言。请根据位置（规格开头附近的状态行）以及周围的状态机判断，而不要只看标签本身。

**绝对规则：只有当状态表示“已批准”**时，才能继续，不论使用何种语言。

以下状态（以及其他语言中含义相同的状态）均视为已批准，可以继续：

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

任何其他状态（Draft / Borrador、In review / En revisión、Implemented / Implementado、Obsolete / Obsoleto，或任何无法识别的值）都表示停止，并显示以下错误消息。

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

如果不确定某个值是否表示“已批准”，请勿自行假定。停止并请用户澄清，或将规格更新为规范用语。

状态不表示“已批准”时的标准错误消息：

❌ 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.

不要提供其他选项，也不要建议“如果你愿意，我仍然可以开始”。此处的限制是有意设置的。

---

阶段 3 — 创建 git 分支并切换到该分支

确认状态为 Approved 后：

0. 先检查工作树。查看上方会话上下文中的 git status --short 输出。如果不为空，请停止并展示待处理的更改，然后询问：

   ⚠️ There are uncommitted changes in the working tree.
   Switching branches would carry them over. What do you want to do?
     1. Commit or stash them yourself, then re-run this command  (recommended)
     2. Continue anyway — the changes travel to the new branch
   

   等待用户回答。除非用户明确要求，否则不要代替用户暂存或提交更改。如果工作树干净，则直接跳到步骤 1，不必提及此事。

1. 根据规格文件的完整文件名（不含扩展名）推导分支名称。格式：spec-NN-slug。例如：

   • 01-mvp-arkanoid.md → 分支 spec-01-mvp-arkanoid
   • 02-powerups.md → 分支 spec-02-powerups

2. 从上方会话上下文中显示的分支创建配置读取 AutoCreateBranch 标志。

   • 如果配置文件不存在、缺少该值，或该值无法识别 → 将其视为 true（默认值）。
   • 只有明确设置为 false（不区分大小写）时，才会禁用自动创建分支。

   **如果 AutoCreateBranch 为 true（默认值）：**直接继续，无需询问。

   • 如果分支不存在：使用 git checkout -b spec-NN-slug 创建分支。
   • 如果分支已存在：这表示正在恢复之前的工作。切换到该分支，在该分支上读取 git log --oneline，并告知用户计划中哪些步骤看起来已经完成，以及你打算从哪一步继续。开始实施前，等待用户确认恢复的步骤。
   • 两种情况下都要：使用 git checkout spec-NN-slug 切换到该分支，并确认切换成功后再继续。

   **如果 AutoCreateBranch 为 false：**操作 git 前先询问。展示：

   AutoCreateBranch is set to false.
   Create and switch to the branch spec-NN-slug? [y/N]
   

   • 如果用户回答是：按照上文 true 情况中的方式创建/切换到分支。
   • 如果用户回答否或未作回答：**不要创建任何分支。**告知用户你将在当前分支（上方会话上下文中显示的分支）上实施，并询问是否明确确认继续在该分支上操作。不要擅自决定——等待用户回答。

3. 向用户直观确认规格已就绪，并说明当前激活的分支：

   ✅ 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)
   

4. **暂时不要开始实施。**先向用户展示规格摘要，帮助他们回顾内容。提取并展示：

   • 目标（**Objective:** / **Objetivo:** / 等效标签之后的行）。
   • 范围（## Scope / ## Alcance / 等效章节）。
   • 实施计划（包含编号步骤的章节——## Implementation plan / ## Plan de implementación / 等效章节）。
   • 验收标准（清单——## Acceptance criteria / ## Criterios de aceptación / 等效章节）。

根据含义而非确切措辞匹配章节标题——规格可能使用任何语言编写。

---

阶段 4 — 逐步实现

展示规格摘要后，告诉用户：

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?

等待用户明确确认（“yes”“go ahead”“go” 或同等意思）。未经确认，不要开始。

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

绝不自动提交。 无论每个步骤结束时还是最后，都不要提交。你负责编写代码并展示差异；是否提交由用户决定，且必须由用户执行命令。只有用户明确要求时才提交。

最重要的一条：按照规格实现。 如果你认为规格中的某些内容不够理想，可以指出，但仍须实现已达成一致的内容。规格的变更应写入规格，不要擅自改动代码。

工作节奏：

• 实现计划中的一个步骤。
• 总结你修改了哪些文件以及做了什么。
• 说：Step N completed. Could you review the diff and let me know if I continue with Step N+1?
• 等待确认后再继续。

如果实现过程中发现规格未解决的歧义：

• 停止。
• 准确描述歧义。
• 提出两到三个具体选项。
• 等待用户决定。
• 不要自行发挥。

如果用户要求的内容超出规格范围：

• 提醒用户该内容不在本规格范围内。
• 建议将其记录下来，留待下一份规格处理。
• 不要在此分支上实现。

完成最后一个步骤时：

✅ 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.

---

预期行为摘要

/spec-impl 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

/spec-impl 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

分支创建由 specs/.spec-config.yml 中的 AutoCreateBranch 标志控制。 默认值为 true（自动创建分支，如上所示）。将其设为 false，即可让阶段 3 在创建分支前询问 [y/N]。