spec-implement

spec-implement — 规范驱动实现编排器

协调工作技能（spec-code、spec-review、spec-test），从规范一路推进到拉取请求。此技能不会编写代码或进行审查，而是负责委派。

语言规则

1. 自动检测输入语言 → 使用相同语言输出
2. 输入为日语 → 使用日语输出，并使用 references/implement-guide.ja.md
3. 输入为英语 → 使用英语输出，并使用 references/implement-guide.md
4. 明确指定的语言优先

选项

选项	描述
--resume	从 tasks.md 中最后一个未完成的任务继续
--issue {N}	指定用于上下文的 GitHub Issue 编号
--spec {path}	指定 .specs/ 目录路径（默认：自动检测）
--dry-run	显示执行计划，但不进行任何更改
--roles {map}	按 kind 为每项任务指定负责人。格式：ui=claude,backend=codex,test=codex，或指定一个 pipeline.yml 路径，由其中的 roles.impl_{kind} 键提供映射。省略此选项 → 每项任务都使用 spec-code，每次审查都使用 spec-review（旧版行为，不涉及 agent-delegate）。
--host-runtime {claude|codex}	执行此技能的运行时。与 --roles 一起使用时为必填项；编排器会传递记录的 host_runtime，以分别解析 AI 角色和执行后端。
--review-fallback {block|native-independent}	仅适用于 --roles 路径的审查能力策略。默认值 block 保持独立运行行为。native-independent 允许缺少跨 AI 审查者时，改用全新、只读、由运行时原生提供的审查子 Agent；spec-orchestrate 会显式传递此选项。

角色：仅限编排

🚨 阻断规则 — 此规则优先于以下所有内容。

此技能是一个编排器。它负责协调工作技能，但不会亲自执行工作。

• 不要自行编写实现代码。 始终委派给 spec-code。
• 不要自行进行代码审查。 始终委派给 spec-review。
• 不要自行编写测试。 始终委派给 spec-test。

如果未安装工作技能，请停止并建议安装。绝不要自行代为执行。

关键的第一步

在进行任何实现之前，请按顺序执行以下检查：

1. 验证环境：pwd、git status、gh auth status

2. 解析用户输入：提取 --resume、--issue、--spec、--dry-run、 --roles 和 --host-runtime 选项

3. 检查 cmux 是否可用：

   echo $CMUX_SOCKET_PATH
   

   如果已设置 → 记录 cmux 分派可作为外部窗格选项。

4. 检查运行时原生 Agent 是否可用：

   ls .codex/agents/workflow-*.toml 2>/dev/null
   ls .claude/agents/workflow-*.md 2>/dev/null
   

   如果在 Codex 中运行，且 .codex/agents/workflow-*.toml 存在 → 对工作流角色优先使用运行时原生 Codex 子 Agent，而不是 cmux。Codex 会从 .codex/agents/*.toml 发现自定义 Agent；不要要求提供 [agents.<name>] config_file 条目。 如果在 Claude Code 中运行，且 .claude/agents/workflow-*.md 存在 → 只有在设置了 CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 时，才对工作流角色优先使用 Claude Code Agent 团队，而不是 cmux。如果未设置，则使用常规 Claude Code 子 Agent 或单 Agent 顺序模式。

5. 定位规格目录 🚨 阻塞项：

   • 如果提供了 --spec → 验证路径存在，然后使用该路径
   • 无论 Issue 正文是否包含路径，都始终扫描 .specs/：

     find .specs -maxdepth 2 -name "tasks.md" 2>/dev/null
     

   • 如果找到匹配的规格目录 → 使用该目录并继续
   • 如果未找到 .specs/ → 通过 AskUserQuestion 询问用户：

     question: "No spec directory found. Where are your specifications?" /
               "未找到规格目录。请问规格文件在哪里？"
     options:
       - "Specify path manually" / "手动指定路径"
       - "Generate specs with spec-generator" / "使用 spec-generator 生成规格"
     

     • 如果用户指定路径 → 验证路径存在并使用
     • 如果用户选择 spec-generator → 停止并指示：Run /spec-generator first, then re-run /spec-implement
   • 在确认有效的规格目录之前，不要进入阶段 5（创建分支）。

6. 定位并读取项目文件：

   • 工作流：docs/development/issue-to-pr-workflow.md → docs/ → 查找 → 回退方案
   • 编码规则：docs/development/coding-rules.md → docs/ → 查找 → 回退方案
   • 评审规则：docs/development/review_rules.md → docs/ → 查找 → 可选
   • 项目说明：CLAUDE.md、AGENTS.md
   • 规格文件：requirement.md、design.md、tasks.md

执行流程

阶段 1-3：加载上下文

读取工作流、编码规则和项目说明。搜索和回退逻辑与之前相同，详情请参阅 references/implement-guide.md。

从工作流中提取：

• 基础分支（默认：main）
• 分支命名约定
• 提交消息格式
• 测试／lint／构建命令
• 分派策略和 Agent 定义（如果存在）

阶段 4：Issue 分析

如果提供了 --issue {N}：

gh issue view {N} --json title,body,labels,assignees

阶段 5：创建分支

🚨 阻塞项 — 必须创建功能分支

git checkout {base_branch} && git pull origin {base_branch}
git checkout -b feature/issue-{N}-{brief-description}

创建后验证 — 当前分支绝不能是 main、master 或 develop。

阶段 6：任务循环（编排）

读取 tasks.md，并按角色标签处理各阶段：

如果某个阶段没有角色标签（不含 [code]/[orchestrator] 的旧版规范），则默认将其视为 [code]。这可确保与 v3 之前生成的规范向后兼容。

评审关卡阶段：带有 -R 后缀的阶段（例如 Phase 2-R: Review Gate [orchestrator]）属于评审关卡。处理这些阶段时，对前一个 [code] 阶段中的每项任务运行 spec-review 和 spec-test。

for each phase in tasks.md:
  if phase has [orchestrator] tag AND phase name contains "Review Gate":
    // This is a review gate — run spec-review + spec-test for preceding [code] tasks
    for each task in the preceding [code] phase:
      invoke spec-review --task {task-id} --spec {path}
      read review result → if FAIL, run fix loop (spec-code --feedback → re-review, max 3)
      invoke spec-test --task {task-id} --spec {path}
      read test result → if FAIL, run fix loop (spec-code --feedback → re-test)
      if review PASS AND test PASS: mark review gate task checkbox

  elif phase has [orchestrator] tag:
    execute tasks directly (run commands, check results — do NOT modify files)

  elif phase has [code] tag (or NO tag — legacy fallback):
    for each unchecked task in phase:
      // Implement only — review/test happens in the Review Gate phase
      invoke spec-code --issue {N} --task {task-id} --spec {path}
      mark task checkbox: - [ ] → - [x]
      commit progress

分派模式：

调用工作技能时，调用方式取决于执行模式：

模式	调用方式
单 Agent	在当前会话中直接调用该技能
Codex 子 Agent	使用 Agent 列的值（例如 workflow-implementer）生成工作流自定义 Agent，并指示其为分配的任务运行 /spec-code、/spec-review 或 /spec-test
Claude Code Agent 团队	请 Claude Code 根据 Agent 列的值（例如 workflow-implementer）创建 Agent 团队，并向这些队友分配 /spec-code、/spec-review 或 /spec-test 任务
cmux 分派	明确选择外部窗格或无法使用运行时原生 Agent 时，使用 cmux-delegate --agent {ai} --task "/spec-code --issue {N} --task {id} --spec {path}"

模式优先级：

1. 如果在 Codex 中运行，且 .codex/agents/workflow-*.toml 存在 → 默认使用 Codex 子 Agent
2. 如果在 Claude Code 中运行，且 .claude/agents/workflow-*.md 存在，并且设置了 CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 → 默认使用 Claude Code Agent 团队
3. 如果 cmux 可用，且工作流/用户明确选择了 cmux → 使用 cmux 分派
4. 否则，使用单 Agent 顺序执行

此优先级适用于未启用 --roles 的旧版路径。启用 --roles 时，Phase 6b 中针对宿主环境的能力回退机制优先：向调用方报告原生工作 Agent 不可用，不要静默切换到 cmux 或单 Agent 执行。

对于 Codex 子 Agent：

1. 工作流引用以下文件时，验证 .codex/agents/workflow-implementer.toml、.codex/agents/workflow-reviewer.toml 和 .codex/agents/workflow-tester.toml 存在
2. 将 Agent 列的值用作自定义 Agent 类型
3. 不要将 TOML 内容内联到提示词中；Codex 会从自定义 Agent 文件加载 developer_instructions
4. 仅传递任务专属上下文：问题、规范路径、任务 ID、相关文件和预期产物/结果

对于 Claude Code Agent 团队：

1. 工作流引用以下文件时，验证 .claude/agents/workflow-implementer.md、.claude/agents/workflow-reviewer.md 和 .claude/agents/workflow-tester.md 存在
2. 验证已设置 CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1
3. 请 Claude Code 创建名称可预测的 Agent 团队，并根据 Agent 列的值使用对应的工作流 Agent 定义
4. 如果 Claude Code 可以直接选择该 Agent，则不要将 Markdown Agent 定义内联到提示词中
5. 传递任务专属上下文：问题、规范路径、任务 ID、相关文件、依赖项、预期产物/结果和文件所有权，以避免冲突

对于 cmux 分派：

1. 阅读工作流的分派策略和 Agent 定义文件路径
2. 将角色映射到 Agent（实现者/测试者 → cmux-delegate，评审者 → cmux-second-opinion）
3. 传递技能命令 — 工作 Agent 会自行加载上下文

阶段 6b：按类型路由任务（--roles）

此层构建在阶段 6 循环之上，且仅在提供 --roles 时（编排模式）启用。不提供 --roles 时，每项任务都使用 spec-code，每次审查都使用 spec-review——与旧版行为完全相同，不涉及 agent-delegate。循环的控制流程（逐阶段迭代、最多 3 次迭代的修复循环、门禁评估、勾选复选框、spec-test）保持不变；仅按任务解析每个步骤的执行者。

所有者解析（逐任务）：

1. 从 tasks.md 中任务详情块的 kind: 字段读取任务类型（ui | backend | test）。
2. 如果类型已知且存在于映射中，owner = roles[kind]；否则使用 claude（默认值）。
3. 将 owner 视为实现者 AI 角色，而不是后端。
4. 根据 --host-runtime 解析执行者：
   • owner == host_runtime → 在运行时原生子 Agent中运行 spec-code； 不要启动 agent-delegate。
   • owner != host_runtime → 使用 agent-delegate 脚本并传入 --mode delegate --target <owner> --detach。保留预期运行 ID， 并使用契约规定的 15–30 秒“先报告”状态等待方式。每隔 30 分钟重新评估， 并在 2 小时时按契约执行受控停止。

**审查者反转（审查门禁）：**首选审查者应为与任务实现者相反的 AI 角色，然后通过相同的主机感知矩阵解析该审查者：

实现者 AI 角色	审查者 AI 角色
codex	claude
claude	codex

审查者与主机角色相同时，使用运行时原生 spec-review 子 Agent；角色不同时，使用 agent-delegate --mode review --target <reviewer>（仅在有明确且不超过 5 分钟的依据时同步执行，否则分离执行）。修复任务路由到实现者 AI 角色，并再次通过相同的矩阵解析。agent-delegate 审查文件与 spec-review 兼容（包含严重性分级章节和 Gate: PASS|FAIL），因此现有修复循环可直接使用，无需更改。

如果无法使用跨 AI 审查者，默认的 --review-fallback block 会报告阻塞问题。只有 native-independent 可以改用主机 AI 角色继续审查，而且必须启动一个全新的运行时原生审查子 Agent：该 Agent 不得是实现者实例，不得恢复或接收实现对话，不得拥有写入工具，并且不得更改工作区。如果无法创建此独立原生审查者，则阻塞。每次使用都会记录在编排器状态和 PR 正文中；绝不能将其伪装成跨 AI 审查。为保留状态所有权，spec-implement 每次使用后都会向调用方返回一条结构化回退记录。spec-orchestrate 会将这些记录追加到状态和 PR 中；独立调用方则在完成摘要中显示这些记录，而不写入流水线状态。

agent-delegate 是公共契约依赖：按照 agent-delegate/references/contract.md 调用脚本，并且始终显式传入 --target（契约中的嵌套链注意事项禁止程序化调用方使用自动检测）。有关调用详情、预期运行轮询、沙箱阶段、恢复和不可用对端回退，请参阅 references/implement-guide.md →“按类型路由任务”。

阶段 7：最终质量门禁

所有任务完成后：

1. 运行工作流中的测试命令（或语言默认命令）
2. 运行 lint／类型检查命令（如有指定）
3. 确认 tasks.md 中的所有任务均已勾选
4. 如果任何检查失败 → 通过 spec-code --feedback 修复 → 重新检查

阶段 8：创建 PR

将 PR 正文视为审查索引，而非审计日志、规范或实现日志。撰写前，检查仓库的 PR 模板和 PR 撰写规则。如果项目提供了模板，请保留其标题、顺序、必填字段和复选框。

只选择那些删除后会改变审查者对正确性、风险、范围、验证情况或合并就绪状态判断的事实。总结变更行为、设计理由、影响范围、已知限制、验证情况和审查重点。将完整的审查轮次、所有发现、验收表、证据清单、任务进度和仲裁历史保留在持久化的本地记录中；不要将它们完整复制到 PR 正文中。

如果项目没有模板，请使用以下用途的标题：摘要、背景或原因、变更、验证、已知限制和审查重点。

gh pr create \
  --title "{type}: {description} (closes #{N})" \
  --body "{PR body following workflow template}" \
  --base {base_branch}

安全防护：

• 如果测试失败，切勿创建 PR
• 切勿强制推送，也不要推送到 main/master
• 确认基准分支与工作流一致

延后处理的发现：对于每条带有 fix_before: trial / required_check / follow_up 标记的审查发现，都要创建一个后续 Issue（gh issue create — 发现内容、严重程度、fix_before 阶段、文件/章节、返回 PR 的链接；同类发现可以共用一个 Issue）。在该 Issue 中保留完整发现。PR 正文中只写 Issue 链接、该发现对变更行为的影响，以及当前 PR 为何可以先于后续处理合并。如果创建 Issue 失败或 gh 不可用，请在 PR 正文中保留完整发现内容并附上警告——延后处理的发现绝不能只留在运行记录中。

仅当审查降级会降低审查保障时，才在 PR 中总结降级情况。说明首选和实际审查者角色、发生降级的原因及其对合并判断的影响；不要倾倒所有结构化的降级记录。

错误处理

情况	响应
不是 git 仓库	错误：必须在 git 仓库中
gh CLI 不可用	错误：引导用户安装/完成身份验证
未找到 .specs/	🚨 阻塞：询问用户路径或建议使用 spec-generator
缺少 requirement.md	警告：使用 Issue 正文作为需求
缺少 tasks.md	警告：根据 Issue 生成简单清单
位于受保护分支上	🚨 阻塞：停止，要求切换到功能分支
未安装 Worker 技能	错误：建议运行 npx skills add anyoneanderson/agent-skills --skill {name}
提供了 --roles，但未提供有效的 --host-runtime	向协调器报告配置阻塞。独立运行时：询问用户选择 claude 或 codex；不要猜测
所负责的任务无法使用运行时原生子 Agent	向协调器报告阻塞，由其应用手动/自动角色降级。独立运行时：重新分配 AI 角色前先询问
跨 AI 实现时 agent-delegate 不可用（脚本缺失 / 退出码 2 / tool_unavailable）	向协调器报告阻塞，由其应用手动/自动负责人降级。独立运行时：重新分配给宿主 AI 前先询问
跨 AI 审查时 agent-delegate 不可用	使用默认的 --review-fallback block 时，报告阻塞。使用显式的 native-independent 时，使用全新的只读宿主原生审查子 Agent，并记录审查保障降级情况；如果该子 Agent 不可用，则阻塞
3 轮迭代后审查仍未通过	请用户决定
尝试修复后测试仍未通过	请用户决定

完成后的操作

AskUserQuestion:
  question: "PR created. What's next?" / "PRを作成しました。次は？"
  options:
    - "Monitor CI status" / "CIステータスを監視"
    - "Done" / "完了"