--- disable-model-invocation: true name: spec-end description: > 当一个完整 Spec 的计划、实现、测试阶段都已完成，且角色 spec-ender 进入阶段五收尾时使用： 收集角色经验、触发 exp-reflect、审查项目规范、询问归档，并完成提交、推送、创建 PR。 不要用于功能实现中途、测试未完成时，或 spec-update 的小迭代收尾。 --- # Spec End ## 运行契约 > 进入核心原则前先对齐这张表。它把本 Skill 当成一个有边界的循环单元：明确读什么、能动什么、怎么算完成、什么时候停、什么时候交还给人。 | 项 | 本 Skill 的约定 | |----|----------------| | 输入 | 当前 Spec 全部角色产物、`lead/team-context.md`（含 Git 元数据）、TeamLead 转回的各角色经验素材 | | 权限 | 写 `ender/end-report.html`、调用 exp-reflect 分流、归档目录、git commit/push/创建 PR（`autopilot` 下可自主执行这些可逆动作）；维护 AGENTS.md/rules 属永远门禁，任何模式下都必须先经用户确认；合并、改动远程默认分支不在本 Skill 权限内；force push **仅豁免**收尾时对自己刚推送的 Spec 分支做 amend（`git commit --amend` + `git push --force-with-lease`，让 PR URL 等收尾写回并入同一次提交），其余 force push 不在权限内 | | 验证 | 各阶段已完成、经验已分流沉淀、规范审查有结论；归档前必须在当前工作树上跑一次全量测试并观察输出（新鲜验证，引用历史测试结论、「刚才是绿的」都不算）；合并完成后必须在**合并结果**上再跑一次全量测试——合并可能引入语义冲突，两个分支各自绿不代表合并后绿；归档前当前分支等于 `git_branch`，且不等于远程默认分支（用 `git symbolic-ref refs/remotes/origin/HEAD` 读出，不假定分支名） | | 停止 | 收尾确认方式随模式（见核心原则 4）；两项永远门禁——合并分支、直接改动远程默认分支——任何模式下都必须停下等用户，`autopilot` 遇到时就地降级为门禁模式；丢弃改动、删除分支必须拿到用户键入的精确确认词才执行；force push 仅收尾 amend 场景豁免（对刚推送的 Spec 分支 `--amend` + `--force-with-lease`），其余 force push 仍是门禁并需精确确认词；用户选"暂不归档"则只产出报告即停止 | | 升级 | 阶段未真正完成、全量测试未绿、规范变更影响面大、或 Git 状态异常（分支不符、在远程默认分支上提交）时，停止并交回用户决策 | ## 核心原则 1. **多角色视角**：通过 TeamLead 收集各角色视角的经验素材，不只是 spec-ender 的独角戏 2. **分流沉淀**：调用 exp-reflect 按权重分流（重大经验 → exp-write，轻量 → Auto Memory） 3. **规范维护审查**：判断本次 Spec 是否产生需要长期遵守的项目规范，必要时更新 AGENTS.md 或 .agents/rules/ 4. **确认方式随模式**：`gated` 模式下归档、提交、推送、创建 PR 前都必须用当前运行环境的确认方式询问用户；`autopilot` 模式下可自主 push 工作分支并创建 PR（两者可逆，且 PR 本身就是给人审的入口），但合并分支、直接改动远程默认分支这两项是永远门禁，任何模式下都必须停下等人；force push 仅收尾 amend 场景豁免（对刚推送的 Spec 分支做 `git commit --amend` + `git push --force-with-lease`，这是让收尾只提交一次的既定动作），其余 force push 仍是门禁 5. **GitHub Flow 收尾**：先跑全量测试，绿了之后才出收尾菜单——测试还红着的时候不要问用户「要不要归档」；放行后调用 git-work 提交、推送当前 Spec 分支并创建 PR 6. **报告用 HTML，记忆用 Markdown**：`ender/end-report.html` 遵循 html-report 契约（`rk:*` meta + `.rk-meta` 双轨元信息、`rk-links` / `rk-backlinks` 双向关联、`data-rev` 修订标记）；`spec/context/experience/*.md`、`knowledge/*.md` 保持 Markdown 不变；账本 `.md` / `.html` 皆可 ## 工作流程 ### 步骤 1：接收任务 从 TeamLead 的启动指令中获取： - 当前 Spec 的目录路径 - 确认所有阶段（计划/实现/测试）已完成 - 当前工作分支（应与 `lead/team-context.md` 的 `git_branch` 一致） - base 分支（用 `git symbolic-ref refs/remotes/origin/HEAD` 读远程默认分支，不要假定分支名；`lead/team-context.md` 的 `base_branch` 与之不符时以远程为准并向用户说明） ### 步骤 2：扫描 Spec 目录 读取当前 spec 目录下的所有角色产物： - `lead/team-context.md`：团队运行上下文（Markdown 运行账本） - `explorer/exploration-report.html`：探索阶段发现 - `writer/plan.html`：设计方案 - `tester/test-plan.html`：测试策略 - `executor/summary.html`：实现细节 - `tester/test-report.html`：测试过程和结果 - `reviewer/review.html` / `reviewer/update-xxx-review.html`：审查报告（如有） - `updater/update-xxx.html` / `updater/update-xxx-summary.html`：更新方案和总结（如有） - `debugger/debug-xxx.html` / `debugger/debug-xxx-fix.html`：问题和修复（如有） 同时读取 `lead/team-context.md` 的运行账本： - frontmatter 的 `git_branch` / `base_branch` / `pr_url` - 「决策记录」：本次所有实质取舍及理由——end-report 的「关键决策」小结直接来自此表，无需重新回忆；用 `rk-cal key` 承载 - 「问题闭环记录」：本次遇到并解决的 bug 与过程性问题，供 exp-reflect 分流沉淀 如果 `git_branch` 为空或为 `none`，说明本 Spec 没有使用 GitHub Flow 分支；收尾时仍可归档文档，但提交/PR 步骤需要先询问用户。 ### 步骤 3：通过 TeamLead 收集团队成员素材 向 TeamLead 请求恢复或转询相关角色，收集本次开发的经验素材： ```text 询问 spec-writer：本次撰写 writer/plan.html 时遇到的困难、踩过的坑、值得记录的发现？ 询问 spec-tester：本次测试过程中的发现、边界情况、改进建议？ 询问 spec-executor：本次实现过程中遇到的技术挑战、解决方案、值得复用的模式？ 询问 spec-debugger：本次调试的根因分析、修复思路、预防建议？（如有 debug 文档） 询问 spec-reviewer：本次审查中发现的完成度风险、测试缺口或规范建议？（如有 review 文档） ``` 等待 TeamLead 转回各角色回复，汇总讨论结果。若运行环境无法恢复角色线程，则基于当前 Spec 目录文档补足对应视角。 ### 步骤 4：调用 exp-reflect 分流沉淀 以当前 Spec 目录文档为素材（exp-reflect 会直接读取文档，无需手动整理素材），调用 `/exp-reflect` 并传递目录路径： ```bash /exp-reflect spec/当前任务目录路径 ``` exp-reflect 会根据经验的重要性分流： - 重大经验（解决了重要问题、有高复用价值）→ `exp-write` 写入正式经验文件 - 轻量知识（小技巧、上下文记忆）→ Auto Memory - 项目规范、项目偏好或规则变化 → 建议更新 `AGENTS.md` / `.agents/rules/`（这些文件保持 Markdown） ### 步骤 5：项目规范维护审查 归档前轻量审查本次 Spec 是否产生长期规则或长期项目偏好。`AGENTS.md` 保持入口清单定位；只在命中明确、长期有效的变化时更新，不为了“有动作”而改规范。 | 发现内容 | 维护位置 | |----------|----------| | 项目名称/一句话身份、核心技术栈摘要、AGENTS 路由或 import 变化 | `AGENTS.md` | | 启动/部署方式、开发流程细则、长期编码约定、安全规则、日志/审计要求、测试约束、目录/命名规范、产品/前端偏好 | `.agents/rules/*.md` | | 可复用操作流程（部署、发布、迁移等） | `.agents/skills/sop-xxx/SKILL.md` | | 项目架构、数据流、模块理解 | `spec/context/knowledge/`（保持 `.md`，被 exp-search 检索） | | 困境-策略、踩坑经验 | `spec/context/experience/`（保持 `.md`，被 exp-search 检索） | 审查问题： - 本次是否形成了以后都要遵守的编码/安全/测试/日志/审计规则？ - 本次是否改变了项目身份摘要、AGENTS 入口路由、目录结构、模块边界、启动或部署方式？ - 本次是否形成了长期产品体验、前端样式或协作偏好，需要写入 `.agents/rules/project-preferences.md` 或相关 rules？ - 本次是否暴露了反复出现的问题，需要写入 rules 防止复发？ - 本次是否形成了可机械复用的 SOP，应创建或更新 Skill？ 如需更新，先向用户说明将修改哪些规范文件，得到确认后再编辑。 ### 步骤 6：创建 ender/end-report.html 并按模式确认归档创建 PR 在当前 Spec 目录下创建 `ender/end-report.html`，按 html-report skill 的固定骨架承载： - `` 写全 `rk:*` meta（`rk:type=end-report`、`rk:spec-dir`、`rk:role=spec-ender`、`rk:created`、`rk:updated`、`rk:revision`、`rk:mode`、`rk:git-branch`、`rk:base-branch`、`rk:pr-url`、`rk:tags`），并用 `` 声明关联；`.rk-meta` 人可读镜像同样字段（含运行模式、基准分支与 PR） - `rk-verdict`（`is-pass` / `is-fail`）一句话给出本次 Spec 的完成结论 - 「修订历史」表固定 5 列（修订/日期/修改人/改了什么/原因），不新增列；后续补 PR URL 等修改时修订号 +1、追加修订历史行、正文用 `data-rev` 标记，不静默改写；「原因」列源于实质取舍时引用账本「决策记录」的决策编号（如 `按 D-003（…）`），纯笔误/措辞/补充直接写清，不编造编号 - 正文章节：完成状态、本轮全量测试的命令与退出码（新鲜验证证据）、已扫描的角色产物路径、经验沉淀结果或无需沉淀的说明、规范维护结果或无需维护的说明、归档/提交/推送/PR 的确认状态（写明按哪种模式放行）、待用户处理的永远门禁项（合并/默认分支改动；force push 仅收尾 amend 场景豁免） - 关键决策用 `rk-cal key` 小结（取自账本「决策记录」，只写结论与一句话理由并标注 `D-xxx`，决策过程正文不复制进报告），遗留风险用 `rk-cal risk`，需后续观察项用 `rk-cal warn` - 末尾「关联产物」拆两个 `h3`：「本报告引用」用 `