Skip to content

feat(sdd): 同步上游 v6 子智能体驱动开发重写(合并审查者 + scripts/) - #108

Merged
jnMetaCode merged 1 commit into
mainfrom
sync/v6-sdd-rewrite
Jul 17, 2026
Merged

feat(sdd): 同步上游 v6 子智能体驱动开发重写(合并审查者 + scripts/)#108
jnMetaCode merged 1 commit into
mainfrom
sync/v6-sdd-rewrite

Conversation

@jnMetaCode

Copy link
Copy Markdown
Owner

你要解决什么问题?

用户在 #89、以及同步追踪 #19 中反馈:superpowers-zh 的 subagent-driven-development 仍停留在上游 v5 的双审查者架构,没有跟上上游 v6.0.0 起对该 skill 的重写(当前上游 v6.1.1)。

具体表现:本地 SKILL.md 还画着「先分派规格审查子智能体 → 再分派代码质量审查子智能体」的旧流程;目录里是 spec-reviewer-prompt.md + code-quality-reviewer-prompt.md 两个模板;缺少上游 v6 新增的 scripts/(review-package / sdd-workspace / task-brief)与「文件交接、持久化进度账本、构造审查者提示词」等章节。即中文用户拿到的是过时一个大版本的 SDD 工作流。

这个 PR 做了什么改变?

subagent-driven-development 对齐到上游 v6.1.1:双审查者合并为单个 task-reviewer-prompt.md,新增 scripts/ 三件套,SKILL.md/implementer-prompt.md 补齐 v6 新增契约(简报文件 + 报告文件、model 必填、TDD RED/GREEN 证据、进度账本),删除 v5 遗留的两个 reviewer 模板。

这个改变适合放在核心库中吗?

适合。这是对上游 core skill 的中文同步翻译,通用、与项目类型无关,属于本 fork「完整翻译上游 skill」的既定范围。未引入任何第三方依赖。

你考虑了哪些替代方案?

  • 逐字照抄上游脚本task-brief 的 awk 只认英文 ## Task N 标题,而本 fork 的 writing-plans 产出的是 ### 任务 N:…,照抄会导致中文计划抽取不到任务。故对 task-brief 的正则做了最小适配,同时匹配 Task任务review-package / sdd-workspace 无语言依赖,与上游逐字节一致)。
  • 拆成多个小 PR(先脚本、后 SKILL):这些改动是同一次 skill 重写的整体,拆开会留下自引用悬空(SKILL 引用尚不存在的 task-reviewer / scripts),故作为一个原子 PR。

这个 PR 是否包含多个不相关的改变?

否。全部围绕 subagent-driven-development 一个 skill 的 v6 同步。

已有的 PR

测试环境

工具 工具版本 模型 模型版本/ID
Claude Code 本地 Opus claude-opus-4-8

评估

如实说明:本 PR 是对上游「已经过上游校准」的 v6 内容做中文翻译,不是新的行为设计。 已完成的验证:

  • 三个 script 端到端功能测试通过:sdd-workspace 正确建自忽略工作区(git status 干净);review-package 正确按 BASE..HEAD 生成含提交列表/stat/带上下文 diff 的审查包(验证多提交场景不被 HEAD~1 截断);task-brief 对中文「任务 N」、英文「Task N」两类计划均正确抽取,且「任务 1」不会误吞「任务 10」,缺失任务正确以退出码 3 报错。
  • bash scripts/audit.sh:106 PASS / 0 FAIL;SDD 的 SKILL.md 标题结构与上游对齐(未触发结构漂移告警)。
  • 全仓库无对已删除文件名的悬空引用。

尚未做: 未跑 tests/subagent-driven-dev/run-test.sh 的真实多智能体集成 eval(该 eval 需实拉 agent 会话、有 API 成本)。建议合并前由维护者补跑一次 go-fractals / svelte-todo 集成 eval 作为把关。

严格性

  • 如果这是 skills 改变:完成了对抗性压力测试 —— 未做(见「评估」,本次为上游 v6 内容的翻译同步,非新行为设计)
  • 这个改变经过了功能/结构测试(脚本端到端 + audit + 引用完整性)
  • 我没有改动精心调优的行为塑造内容的「设计」——仅将上游 v6 的措辞翻译为中文,保留其红线表/合理化列表/「人类伙伴」用语的结构与语义

人工审核

  • 提交前已有人工审核过完整的 diff —— 待维护者审核:本 PR 由 AI 完成翻译与脚本适配,diff 完整、可复核,请在合并前过一遍完整 diff(尤其 task-brief 的中文正则适配与三个 prompt 译文)。

对齐 obra/superpowers v6.0.0+(当前 v6.1.1)对 subagent-driven-development 的重写:

- 双审查者(规格 + 代码质量)合并为单个 task-reviewer-prompt.md,一次读 diff 出两个结论
- 新增 scripts/:review-package(生成审查包)、sdd-workspace(工作树临时区)、task-brief(抽取单任务简报)
- SKILL.md 补齐 v6 新增章节:起飞前计划审查、处理审查者 ⚠️ 事项、构造审查者提示词、文件交接、持久化进度(ledger)
- implementer-prompt.md 改为简报文件 + 报告文件契约、model 必填、TDD RED/GREEN 证据
- 删除 v5 遗留的 spec-reviewer-prompt.md / code-quality-reviewer-prompt.md

中文 fork 适配:task-brief 的 awk 同时匹配英文 "Task N" 与中文 "任务 N" 标题,
使 writing-plans 产出的中文计划也能抽取任务。review-package / sdd-workspace 与上游逐字节一致。

关联 #89 #19
@jnMetaCode
jnMetaCode merged commit d7885ca into main Jul 17, 2026
2 checks passed
@jnMetaCode
jnMetaCode deleted the sync/v6-sdd-rewrite branch July 17, 2026 13:04
jnMetaCode added a commit that referenced this pull request Jul 17, 2026
npm 1.7.0 发布在 SDD v6 合并(#108)之前,tarball 不含新内容,故 bump patch 发版:
- 双审查者合并为 task-reviewer-prompt.md、新增 scripts/(review-package/sdd-workspace/task-brief)
- SKILL/implementer 补 v6 契约、删 v5 双 reviewer
- 7 个清单版本同步至 1.7.1

关联 #89 #19
jnMetaCode added a commit that referenced this pull request Aug 7, 2026
对齐上游 v6.1.1 -> v6.2.0 中 subagent-driven-development 的 6 个 commit
(6df8ba1 / b8a2d84 / 2dbbaed / 87e4050 / ebdd4ec / 28882fc)。

这是 #19 拆分后的 A 块。注意 v1.7.1 刚对齐过 SDD,本次是那之后的新增量。

## 为什么必须整块一起改

我们的 SKILL.md 里写的是旧脚本签名(review-package BASE HEAD)。脚本换成
plan 作用域签名后若不同步改文档,agent 会照旧签名调用直接吃 usage 错误 ——
比不同步更糟。所以脚本 + 文档 + 模板同批落地。

## plan 作用域工作区(结构性修复)

原先所有计划共用 .superpowers/sdd/ 一个目录,一份过期账本被误读成当前进度,
会让控制者跳过整段任务序列 —— 上游称这是观察到的最昂贵失败。现在每个计划
一个 .superpowers/sdd/<计划文件名>/,从结构上消除这种误读。

- scripts/sdd-workspace 改为接收 PLAN_FILE,自忽略 .gitignore 上移到
  .superpowers/sdd/;scripts/review-package 前置 PLAN_FILE 参数
- 两个脚本在我们这边与上游 v6.1.1 字节一致(从未汉化),直接取上游版
- scripts/task-brief 只手工应用上游那两处改动,保留我们的 fork 适配
  (awk 同时匹配 "Task N" 与 "任务 N",因为本仓库 writing-plans 产出中文标题)
- 账本新增身份行 `# SDD ledger — plan: <路径>`,并明确「第一行点名别的计划、
  或旧扁平路径下的游离账本」都不是你的进度

实测(临时 git 仓库):两个计划各得独立目录;往 A 计划写 ledger 后 B 计划
目录仍为空(关键回归);.gitignore 落在 .superpowers/sdd/ 且 git status 干净;
中文「任务 2」经新路径抽取成功;review-package 旧签名正确报 usage 错误。

## SKILL.md 全面重写(14 章 -> 生命周期结构)

上游把平铺的 14 节重组为「任务循环」五步 + 熔断机制,Red Flags / Advantages /
Integration / File Handoffs / Durable Progress 等并入使用现场。逐节重译:

- 修复循环:一轮 = 一次修复分派 + 一次定向复审,每任务上限五轮
  第 1-3 轮唤回原实现者(context 完整),第 4-5 轮换全新实现者 + 高一档模型
- 熔断:第 5 轮仍有未解决发现则停止分派,逐条裁定 —— 搁置(附裁定)或在
  承重项上 BLOCKED。只在上限处裁定,提早裁定等于换名字的预先定性
- Minor 发现与「计划要求的」发现两条路在循环外
- 新增「常见的合理化借口」表取代原「红线」清单

新增 re-review-prompt.md(106 行全文翻译):定向复审只核实发现是否解决 +
只看修复 diff 的新破坏,范围外观察进账本不延长循环。

implementer-prompt.md「审查发现之后」改写为基于唤回的修复轮次;
task-reviewer-prompt.md 更新脚本签名并删除被 re-review-prompt.md 取代的结尾两句。

## 顺手修掉一个既有缺陷

三个 SDD 文件末尾都残留着 `</content>` —— v1.7.1 那次重写(PR #108, d7885ca)
留下的生成产物,上游没有。这些文件会整体进 agent 的 prompt,属于污染。已全部清除,
并全仓扫描确认无同类残留。

## 验证

- 章节结构与上游 14 节一一对应;superpowers: 引用集与上游完全一致
- 26 项关键技术记号(脚本签名、账本行格式、四种状态、ADDRESSED/NOT ADDRESSED、
  数值门槛)逐一确认存在,无漏译
- 两个 dot 图节点/边数与上游精确一致(6/6 与 23/28),且无幽灵节点、无孤立节点
  (手工翻译 dot 标签最易在边里写错,会静默产生幽灵节点)
- audit.sh 150 pass / 0 fail;verify-release.sh 82 pass / 0 fail
- SDD 已从 audit 的上游漂移警告里消失(结构层级现已对齐)

注:audit PASS 由 153 降至 150,是上游有意删除 Integration 一节
(原列 executing-plans / test-driven-development / writing-plans 三个引用)
导致 Category 4b 少 3 项引用检查,非静默跳过 —— 已核对我们的引用集与上游一致。
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant