| name | sf-implement |
| description | 根据已批准的 SpecForge tasks 执行实现；用于 implementation ready，且需要按任务边界、技术选型、UI/技术设计、验证计划落地代码并记录实现证据时。 |
sf-implement
运行目录
执行任何 node .specforge/... 命令或读取 .specforge/... 文件前，必须先定位宿主项目根：项目根是“包含 .specforge/ 目录的业务项目目录”，不是 .specforge/ 目录本身。若当前目录是 .specforge/ 或其任意子目录，先 cd .. 回到宿主项目根；若当前目录是 frontend/、backend/ 等子目录，也先向上回到包含 .specforge/ 的项目根。禁止从 .specforge/ 内执行 node .specforge/core/scripts/...，否则会形成 .specforge/.specforge/... 的错误路径。
sf-implement 负责把已批准 tasks 落成真实代码、命令和证据。实现完成的定义是：代码、task 状态、验证记录、changed-files.md 和真实 git diff 五者一致。本技能不批准 code_review gate。
必读
references/implementation-execution-rules.md：任务边界、失败优先验证、脚手架、UI / PC 规范、diff 对账和报告规则。.specforge/skills/sf-implement/stages/implementation/SKILL.md：内部实现母本。.specforge/core/artifacts/templates/implementation-plan.md.specforge/core/artifacts/templates/implementation-report.md.specforge/core/artifacts/templates/changed-files.md.specforge/core/standards/workflow.md.specforge/core/standards/engineering.md.specforge/core/standards/ai-toolkit.md.specforge/core/skills/code-intelligence/SKILL.md：任务边界涉及现有模块、符号定位、调用链或修改后 freshness 检查时读取。- 需要实现 UI 时读取
.specforge/core/standards/design.md、.specforge/core/skills/ui-ux/design-system/references/output-contract.md 和 ui-design.md#Design Contract Summary；若 ui-design.md 声明采用 PC 端业务系统规范，还要读取 .specforge/core/standards/pc-ui-design-spec.md。
- UI 实现涉及 shadcn-vue、project wrapper、token、动效或组件状态时，按需读取
.specforge/core/skills/ui-ux/design-system/components/component-system.md、.specforge/core/skills/ui-ux/design-system/foundations/foundation-system.md 和 .specforge/core/skills/ui-ux/design-system/references/motion-block-library.md。
启动扫描
- 运行：
node .specforge/core/scripts/instructions.mjs apply
- 如果 implementation 不是 ready，停止，上游 artifact 或 gate 尚未就绪。
- 生成实现产物：
node .specforge/core/scripts/create-artifact.mjs implementation
- 读取
work.yaml、01-spec/tasks.md、适用的 requirements.md / gap-report.md / ui-design.md / technical-design.md、02-spec-review/spec-review-v1.md、.specforge/wiki/00-index.md 和任务 / 技术设计引用的相关 wiki。
- 如 tasks / technical design 引用了
graph_facts[]、affected modules 或关键 symbol，先运行 node .specforge/core/scripts/graph-freshness.mjs --json；provider pending / stale 时直接读取当前文件，不只信图谱。
- 运行：
git status --short --untracked-files=all
记录本次开始前已有改动；不要覆盖、回滚或登记无关改动为本次成果。
执行序列
A. 先写实现计划
- 从 tasks 建立任务执行图：task -> batch ->
_Trace:_ -> _Files:_ -> _Boundary:_ -> _Verification:_ -> _Rollback:_ -> risk。
- 如果 tasks 已填写
任务图与执行策略，以其中依赖、并行边界和禁止同时修改文件为准。
- 若实际执行需要改变依赖或并行边界，停止并回到
sf-tasking 更新任务图。
- 从
technical-design.md#0. 影响面与读取计划、#7.1 Architecture Contract、#Implementation Handoff、#12. Operability & Maintenance 和相关 wiki 建立上下文边界：入口路径、关键符号 / 路由、上游 / 下游、测试位置、运行命令、change slices、files/modules、test seams、rollout、rollback、owner 和 revisit trigger。
- 需要定位具体 symbol 时，按
.specforge/core/skills/code-intelligence/references/stage-integration.md#sf-implement 使用 CodeGraph / provider；实现前只沿上述边界读取代码，不得为了“保险”重新全量扫描仓库。
- 若任务边界、验证方式、回滚信息不足以指导实现，停止并退回
sf-tasking 或 sf-spec-review。
- 若存在
[NEEDS TECH DECISION]、[NEEDS DEPENDENCY DECISION]、关键 unknown，停止并退回 sf-tech-design 或 sf-spec-review。
- 写
03-implementation/plan.md。
B. 准备实现基线
- 新项目、新前端、新后端或新模块，优先使用 technical design 选中的脚手架 / 官方 CLI / 模板。
- 跑通依赖安装、构建 / typecheck / dev server / service 启动中的适用项。
- 对行为变更，先写或定位会失败的测试 / 检查 / Playwright 用例，再写生产代码。确实不能失败优先时，先在 report 写原因、风险和替代证据。
- 脚手架、配置初始化、文档记录、删除死代码等不直接表达业务行为的任务，可以先做结构性准备，但必须有对应验证或对账证据。
C. 按任务小步实现
- 每次编辑前确认目标文件在
_Files:_ / _Boundary:_ 或 approved UI / technical design 范围内。
- UI 实现必须追溯到
ui-design.md 的页面地图、状态矩阵、Visual Style Brief、Pencil .pen 和导出截图。
- UI 实现必须追溯到 Design Contract Summary：token source、component strategy、shadcn-vue primitive layer、project wrapper layer、motion source、anti-slop rules 和 verification hooks。
- PC 端业务系统规范被采用时，HTML / CSS / 组件样式必须使用
pc-ui-design-spec.md token，不接受 UI 库默认主题或临时改值。
- 技术实现必须追溯到
technical-design.md 的 API、数据、安全、配置、运行、可观测性、Architecture Contract、Implementation Handoff、Operability & Maintenance 和验证策略。
Implementation Handoff 中的 do-not-touch、rollback seam、open assumptions 必须在实现计划中复述；需要偏离时停止回到 sf-tasking / sf-tech-design。- 每完成一个 task，运行对应快速验证或写明不能运行的原因；task 状态只能是
DONE、DONE_WITH_CONCERNS、BLOCKED、NEEDS_SPEC。
D. 持续维护证据
- 更新
03-implementation/report.md：task 状态、实现策略、验证、偏离、风险、code review 提示。
- 更新
03-implementation/changed-files.md：每个真实变更文件、task、批准边界、风险和验证方式。
- 修改后如使用过 graph provider，运行
node .specforge/core/scripts/graph-freshness.mjs --json，在 report 写明 graph freshness、touched symbols 和 affected area；pending / stale 文件必须直接读取当前文件。
- 收尾时运行：
git status --short --untracked-files=all
git diff --name-only
git diff --stat
- 真实 diff、report、changed-files、tasks 不一致时先修证据或停止，不能进入 code review。
停止条件
| 条件 | Return path |
|---|
| implementation 未 ready 或 spec_review 未批准 | 停止：上游 gate 未通过 |
| tasks 的核心字段不足以指导实现 | 停止：任务边界不足 |
需要修改 _Boundary:_ 外文件 | 停止：超出批准范围 |
| 存量项目任务需要先全仓查找才能知道改哪里 | 停止：退回 sf-tasking / sf-tech-design / sf-steering 补 wiki 和边界 |
technical design 仍有关键 unknown 或未确认技术 / 依赖决策 | 停止：技术决策未确认 |
| Architecture Contract / Implementation Handoff / Operability & Maintenance 为空或与 tasks 边界冲突 | 停止：退回 sf-tech-design / sf-tasking |
| UI 原型、Pencil 截图或 PC 规范 token 缺失但实现依赖它们 | 停止：UI 设计缺失 |
| 快速验证失败且无法在当前 task 范围内修复 | 停止：说明原因，等待用户决策 |
完成标准
03-implementation/plan.md、report.md、changed-files.md 已填写。- tasks 中完成项有代码、验证或可信 N/A、变更文件登记和状态说明。
- tasks 的任务图、实现顺序和真实 diff 一致；未按计划并行或调整顺序时已有说明。
- technical design
yes / no / unknown 影响面对账清楚。
- Architecture Contract、Implementation Handoff、Operability & Maintenance 的实现对账清楚，尤其是 rollback seam、owner、extension point 和 revisit trigger。
- 属于本 work item 的真实 git diff 均已登记；无关已有改动已排除并说明。
- 没有把
DONE_WITH_CONCERNS、BLOCKED、NEEDS_SPEC 描述成已完成。
- 完成后运行
node .specforge/core/scripts/instructions.mjs，将输出展示给用户，让用户知道当前 workflow 的下一步是什么。
不做
- 不批准
code_review gate。
- 不扩大到未写入 tasks、
ui-design.md 或 technical-design.md 的范围。
- 不顺手修无关问题；需要时新开 work item。
- 不自动安装 / 同步外部 Agent 技能副本，除非用户单独明确要求。
- 不在修复 bug 时顺手改动范围外的代码（如把同步调用改成 async、修改无关方法签名）；范围外改动必须新开 work item。
- 编辑 Python 文件后，如果自动格式化工具（Prettier 等）修改了缩进，必须立即检查并还原；Python 缩进有语义，格式化工具可能破坏逻辑结构。
