implement-task

name	implement-task
description	根据技术方案实施任务并输出报告

实施任务

根据已批准的技术方案实施任务，并产出 implementation.md 或 implementation-r{N}.md。

行为边界 / 关键规则

• 严格遵循最新方案产物：plan.md 或 plan-r{N}.md
• 绝不自动执行 git add 或 git commit
• 每轮实现都创建新的实现产物，不覆盖旧文件
• 执行本技能后，你必须立即更新 task.md

版本戳规则：创建或更新 task.md frontmatter 时，先读取 .agents/rules/version-stamp.md，并写入或刷新 agent_infra_version。

常见违规借口与反驳

动手实现前，若冒出以下念头，先停下——它们都是违规借口：

借口	反驳
「代码太简单，不需要测试」	简单代码也会回归；没有"失败→通过"的用例就没有完成标志，先写验证业务行为的测试。
「先写代码再补测试更高效」	后补测试常沦为对实现的镜像；目标驱动应先定义可验证用例再让它通过。
「方案这里不合理，顺手改更好」	偏离 {plan-artifact} 必须在报告中记录原因；有异议先停下确认，不擅自改方向。
「测试过了，顺便提交一下」	本技能绝不执行 git add/git commit，提交是用户显式发起的独立步骤。

第 0 步：状态核对（执行前硬约束）

在加载 workflow / skill / rules 指令之后、做任何任务状态判断或用户可见结论之前，必须先执行状态核对。指令类文件读取不算对外动作或结论。

运行以下命令，并把原文粘贴到回复正文和本轮产物的 ## 状态核对 段：

git status -s
ls -la .agents/workspace/active/{task-id}/
tail .agents/workspace/active/{task-id}/task.md

状态核对完成前，禁止任何关于外部状态的断言（例如“代码没变”“测试已通过”“没有其他引用”），包括思考阶段。本门禁只提供结构下限；逐条证据配对和真实性仍需按报告模板与审查要求核对。

执行步骤

1. 验证前置条件

先检查：

• .agents/workspace/active/{task-id}/task.md
• 至少一个技术方案产物：plan.md 或 plan-r{N}.md

如果缺少任一文件，立即停止并提示用户先完成前置步骤。

2. 确保任务分支

先读取 task.md 中 ## 上下文 的分支字段，并检查当前 Git 分支是否匹配。

• 已记录任务分支：当前分支不匹配时切换到该分支
• 未记录任务分支：判断当前分支是否符合命名规范且属于当前任务
  • 符合：记录当前分支并继续
  • 不符合：按规范创建并切换到新的任务分支

完成后，把最终使用的分支名回写到 task.md。

分支命名规则、Git 命令和边界处理见 reference/branch-management.md。执行此步骤前，先读取 reference/branch-management.md。

3. 收窄里程碑

如果 task.md 中存在有效的 issue_number，执行前先读取 .agents/rules/issue-sync.md，完成 upstream 仓库检测和权限检测；再读取 .agents/rules/milestone-inference.md，按其中的「阶段 2：implement-task」收窄 Issue milestone；如果 has_triage=false，则保持原 milestone 不变。

4. 确定输入方案与实现轮次

扫描 .agents/workspace/active/{task-id}/ 并记录：

• 最高轮次的方案文件为 {plan-artifact}
• 本轮实现产物为 implementation.md 或 implementation-r{N}.md
• {implementation-round} 与 {implementation-artifact}

如果存在 plan-r{N}.md，读取最高轮次的方案文件；否则读取 plan.md。

5. 阅读技术方案

仔细阅读 {plan-artifact}，提取：

• 实施步骤
• 需要创建或修改的文件
• 测试策略
• 约束、风险与已批准的取舍

6. 执行代码实现

按照 .agents/workflows/feature-development.yaml 和方案顺序实施。

详细实现规则、测试执行循环和偏离处理见 reference/implementation-rules.md。执行此步骤前，先读取 reference/implementation-rules.md。 测试编写纪律（RED-GREEN-REFACTOR 与反模式）见 .agents/rules/testing-discipline.md；新增或调整测试前先读取该文件。

7. 运行测试验证

使用 test 技能中的项目测试命令，直到所有必需测试通过。

如果测试失败，先尝试修复并重新运行测试。只有在确认存在外部阻塞、环境缺失或需求不明确且超出任务范围时，才可以停止。

8. 编写实现报告

创建 .agents/workspace/active/{task-id}/{implementation-artifact}。

报告结构、必填章节和完整模板见 reference/report-template.md。写报告前先读取 reference/report-template.md。

9. 更新任务状态

获取当前时间：

date "+%Y-%m-%d %H:%M:%S%:z"

更新 .agents/workspace/active/{task-id}/task.md：

• current_step：implementation
• assigned_to：{当前代理}
• updated_at：{当前时间}
• agent_infra_version：按 .agents/rules/version-stamp.md 取值
• 审查 ## 需求 段落，仅把本轮已由代码实现且有测试通过支撑的条目从 - [ ] 勾为 - [x]
• 记录 Round {implementation-round} 的 {implementation-artifact}
• 追加： - {YYYY-MM-DD HH:mm:ss±HH:MM} — **Implementation (Round {N})** by {agent} — Code implemented, {n} files modified, {n} tests passed → {implementation-artifact}

如果 task.md 中存在有效的 issue_number，执行以下同步操作（任一失败则跳过并继续；执行前先读取 .agents/rules/issue-sync.md，完成 upstream 仓库检测和权限检测）：

• 按 issue-sync.md 设置 status: in-progress
• 创建或更新 .agents/rules/issue-sync.md 中定义的 task 评论标记（按 issue-sync.md 的 task.md 评论同步规则）
• 发布 {implementation-artifact} 评论

10. 完成校验

运行完成校验，确认任务产物和同步状态符合规范：

node .agents/scripts/validate-artifact.js gate implement-task .agents/workspace/active/{task-id} {implementation-artifact} --format text

处理结果：

• 退出码 0（全部通过）-> 继续到「告知用户」步骤
• 退出码 1（校验失败）-> 根据输出修复问题后重新运行校验
• 退出码 2（网络中断）-> 停止执行并告知用户需要人工介入

将校验输出保留在回复中作为当次验证输出。没有当次校验输出，不得声明完成。

11. 告知用户

仅在校验通过后执行本步骤。

重要：以下「下一步」中列出的所有 TUI 命令格式必须完整输出，不要只展示当前 AI 代理对应的格式。如果 .agents/.airc.json 中配置了自定义 TUI（customTUIs），读取每个工具的 name 和 invoke，按同样格式补充对应命令行（${skillName} 替换为技能名，${projectName} 替换为项目名）。输出格式见 reference/output-template.md。

完成检查清单

• 已完成批准范围内的代码实现
• 已创建 {implementation-artifact}
• 所有必需测试通过
• 已更新 task.md 并追加 Activity Log
• 已向用户展示所有 TUI 格式的下一步命令（含自定义 TUI）

停止

完成检查清单后立即停止。不要自动提交。

注意事项

• 首轮实现使用 implementation.md，后续轮次使用 implementation-r{N}.md
• 如偏离 {plan-artifact}，必须在报告中记录原因
• 新测试必须验证有意义的业务行为，而不是机械透传

错误处理

• 任务未找到：Task {task-id} not found
• 缺少方案：Technical plan not found, please run the plan-task skill first
• 本地修复后仍无法通过测试：说明外部阻塞并停止，且不要创建实现产物