Skip to content
This repository was archived by the owner on Sep 2, 2026. It is now read-only.

chore: 清理已弃用 superpowers 插件的遗留文档 - #84

Merged
HyxiaoGe merged 2 commits into
masterfrom
claude/cleanup-superpowers
Aug 31, 2026
Merged

chore: 清理已弃用 superpowers 插件的遗留文档#84
HyxiaoGe merged 2 commits into
masterfrom
claude/cleanup-superpowers

Conversation

@HyxiaoGe

@HyxiaoGe HyxiaoGe commented Aug 31, 2026 •
edited
Loading

Copy link
Copy Markdown
Owner

背景

superpowers 插件已弃用。它遗留的实施计划文档不再维护,而且 43 份在头部写着:

> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development

会把任何读到它们的 agent 指向一个不存在的插件。这些文档不只是"占地方",是在下达错误指令。

本描述为评审后修订版。第一轮评审提出两个 P1,均已受理,见 评审回复。

删除范围

内容 数量
docs/superpowers/plans/(全部,目录清空) 53 份
.superpowers/(插件自身的 sdd 状态目录) 2 个跟踪文件

合计 55 个文件删除,4 个文件修改,-10600 行。

删除前的入边核查

按完整路径(而非文件名,避免 plans/specs 同名碰撞)搜索全仓,53 份 plan 中仅 2 份有入边,且均为"假引用":

文件 入边 性质
2026-08-22-trajectory-ledger-p0.md .gitignore 白名单规则本身,随文件一并删除
2026-08-27-run-capability-router.md .superpowers/sdd/.../progress.md 死插件的状态目录,本次一并清理

另有 4 处按文件名初查命中,逐一核实后确认均指向别处,无断链:

  • 2026-07-11-admin-audit-center-v1 → 台账实际指向 docs/acceptance/(另一目录,未删)
  • 2026-08-26-system-prompt-assembly / 2026-08-27-prompt-runtime-v2 / 2026-08-27-run-capability-router → 均指向 superpowers/specs/

评审修正:2026-08-31-run-skills-mvp.md 已一并删除

初版保留了这份,判据是"台账无完成条目 → 可能仍在进行中"。该判据错误。

核实 master 历史后确认工作早已完成:

64049e5  Merge PR #76  feat: 引入Run级Skills运行时
3ba19f9  Merge PR #77  fix: skills CRLF 与 release hash
22f8625  Merge PR #79  fix: fresh release intent 路由

64049e5 与该 plan 逐项对应:app/ai/skills/registry.py、verified-research/1.0.0 skill、Run capability 路由、Trajectory API、agent loop wiring、previous_run_skill_release.py,含配套测试。

保留它会恰好留下唯一一份"已完成却显示未开始、且仍强制调用已弃用插件"的文档,与本 PR 目标相反。

同时在执行台账补上 Run 级 Skills 运行时的已完成记录 —— 台账缺这条正是上述错误判据的成因。

保留项

docs/superpowers/specs/ 全部 23 份。其中三份是承重契约:

引用方 指向
EXECUTION_LEDGER.md:72 specs/2026-08-26-system-prompt-assembly.md
EXECUTION_LEDGER.md:81 specs/2026-08-27-prompt-runtime-v2.md
EXECUTION_LEDGER.md:89 specs/2026-08-27-run-capability-router.md
TRAJECTORY_DESIGN.md:131 specs/2026-08-26-system-prompt-assembly.md

且 specs/ 无一份带已弃用插件头(plans 是 43/53)。

确立插件无关的落位目录

新增 docs/implementation-plans/ 作为实施计划的稳定落位,与已弃用插件解耦。全部发现入口改为同时覆盖该目录与 docs/superpowers/specs:

  • AGENTS.md 第 11 条(下一步建议必须查执行记录)
  • docs/EXECUTION_LEDGER.md 开头说明
  • docs/EXECUTION_LEDGER.md 检查清单第 3 条
  • .agents/skills/fusion-next-step/SKILL.md

.gitignore 相应调整:移除已空的 plans/ 白名单,新增 !docs/implementation-plans/。

漏改发现入口会比留着旧文档更糟 —— agent 会被指去查一个不存在的目录;而入口与实际落位不一致,则会让新计划落在无人扫描的位置(这正是第二个 P1 指出的问题)。

验证

在 #84 + #83 的合并树上(而非单分支)验证:

docs/implementation-plans/   1 份
docs/superpowers/plans/      0 份
docs/superpowers/specs/      23 份

指向已删 plans 的活引用            →  无
发现入口 vs 实际落位               →  两目录各 4 处提及,一一对应
specs 承重链接(台账 ×3 + 设计 ×1)  →  全部可解析
新目录下新文件可否添加              →  可以

另:test/ 与 scripts/ 中无任何读取 docs/superpowers 的代码。

找回方式

删除内容全部保留在 git 历史中:

git log --diff-filter=D --name-only -- 'docs/superpowers/plans/*'
git show <sha>^:docs/superpowers/plans/<file>.md

与 #83 的关系

#83(monorepo 合并计划)已配套调整(7df9b1c):文档移入 docs/implementation-plans/,并修正三处对本 PR 所删文件的引用。

docs/implementation-plans/ 的 .gitignore 白名单只在本 PR 中。#83 的文档文件本身已被 git 跟踪不受影响,但若 #83 先合,该目录下后续新增的文件会被 docs/* 静默忽略。建议本 PR 先合。

⚠️ 合并会触发一次真实发布

deploy.yml 为 on.push.branches: [master] 且无 paths 过滤,合并会触发 publish(构建推 ACR)+ deploy-dev(alembic 迁移 + 容器重启)。请按一次正式发布处理。

🤖 Generated with Claude Code

https://claude.ai/code/session_01QR4stz9sbfVRS6xgriQ9kQ

Claude @claude
chore: 清理已弃用 superpowers 插件的遗留文档
d1d7a0c 
superpowers 插件已弃用，其遗留的实施计划文档不再维护，且 43 份在
头部写着 REQUIRED SUB-SKILL superpowers:subagent-driven-development，
会把读到它们的 agent 指向一个不存在的插件。

删除范围：

- docs/superpowers/plans/ 52 份。删除前逐份核查入边，全部无活引用：
  按完整路径搜索全仓，仅 2 份有入边，一份来自 .gitignore 白名单
  规则本身，一份来自 .superpowers 状态目录，两者随本次一并清理。
- .superpowers/ 2 个被跟踪文件，是插件自身的 sdd 状态目录。
- .gitignore 中专为已删文件写的一条白名单。

保留 docs/superpowers/plans/2026-08-31-run-skills-mvp.md。判据是
台账完成记录：另三份近期 plan 在 EXECUTION_LEDGER L72 L81 L89 均有
已完成条目，而该份没有，可能仍在进行中，不纳入本次清理。

保留 docs/superpowers/specs/ 全部 23 份。其中三份是承重契约，被
EXECUTION_LEDGER 与 TRAJECTORY_DESIGN.md 作为权威协议引用，且
specs 无一份带已弃用插件头。

同步修正四处会指向已删目录的引用，改为指向 docs/superpowers/specs：
AGENTS.md 第 11 条、EXECUTION_LEDGER.md 开头说明与检查清单第 3 条、
.agents/skills/fusion-next-step/SKILL.md。

删除内容全部保留在 git 历史中，可用 git log --diff-filter=D
--name-only 定位、git show <sha>^:<path> 取回。

Co-Authored-By: Claude <noreply@anthropic.com>
@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Aug 31, 2026

Copy link
Copy Markdown

Codex usage limits have been reached for code reviews. Please check with the admins of this repo to increase the limits by adding credits.
Credits must be used to enable repository wide code reviews.

@HyxiaoGe

HyxiaoGe commented Aug 31, 2026

Copy link
Copy Markdown
Owner Author

我按当前 head d1d7a0c 复核了删除清单、4 处引用修改、保留文件、当前 master 历史，以及与仍开放的 #83 的叠加结果。PR container validation 已通过，但当前还有 2 个 P1，建议先修再合并。

[P1] 唯一保留的 plan 正是本 PR 要清掉的错误入口，而且该工作其实已经完成

docs/superpowers/plans/2026-08-31-run-skills-mvp.md 的第 3 行仍然是：

REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development ...

并且 5 个 Task 仍全部显示为未勾选。PR 用“台账里没有完成条目，因此可能仍在进行中”作为保留依据，但当前 master 已有 64049e5（Merge PR #76），其变更与这份计划逐项对应：Skill registry、verified-research、Run capability、Trajectory API、前端协议所需后端接口和完整测试都已合入，后续 #77/#79 还继续做了发布修正。

因此合并 #84 后，仓库会恰好留下一个“已完成但显示未开始、且仍强制调用被声明为已弃用插件”的 plan。任何按目录枚举或链接进入它的 agent 仍可能重复实施已完成工作，这与本 PR 的清理目标相反。

最小安全修正：把这份 plan 也纳入删除；如果确实需要保留历史，则至少移到明确的 archive，并移除 REQUIRED 指令、把完成状态与 64049e5 / #76 写实，同时在执行台账补上 Skills MVP 已完成记录。

[P1] #84 → #83 的建议合并顺序会静默生成一个“发现不到且含断链”的新计划

#83 当前 head 会新增 docs/superpowers/plans/2026-08-31-monorepo-merge.md，而 #84 把 AGENTS.md、fusion-next-step 和执行台账的检索范围全部收窄到 docs/superpowers/specs。两条分支不会产生文本冲突，所以按 PR 描述建议的顺序先合 #84、再合 #83 后：

  1. monorepo 实施计划仍落在 plans/，但所有“下一步”发现入口都只扫描 specs/，当前最高风险的迁移工作反而不会被发现；
  2. docs: 新增 fusion-api 与 fusion-ui 合并为 monorepo 的实施计划 #83 的“依据”仍按完整路径引用本 PR 删除的 docs/superpowers/plans/2026-06-28-agent-run-continuation.md，会立即形成断链。

PR 描述里写“#83 再据此调整”不能阻止当前 #83 被无冲突合并。请在本 PR 合并前把落位规则闭环：要么把未来 implementation plan 迁到与插件无关的稳定目录（例如 docs/implementation-plans/），并同步更新 #83 和所有发现入口；要么让发现入口继续覆盖 plans + specs，同时先修改 #83 的落位和被删除证据引用。修完后建议用 #84 与 #83 合并后的最终树再跑一次残留引用检查，而不是只检查 #84 单分支。

除此之外，本轮未发现代码运行时回归；但该 PR 合入 master 仍会触发完整 API 发布，不能把 CI 绿等同于文档迁移闭环或发布验收。

Claude @claude
chore: 按评审补删已完成的 plan 并确立插件无关的落位目录
d996450 
回应 PR #84 第一轮评审的两个 P1。

P1 之一：补删 docs/superpowers/plans/2026-08-31-run-skills-mvp.md。
原先以「台账无完成条目」为由保留，该判据错误。核实 master 历史，
64049e5（PR #76 引入 Run 级 Skills 运行时）已逐项实现该计划：
app/ai/skills/registry.py、verified-research/1.0.0 skill、Run
capability 路由、Trajectory API 与 skills 详情端点、agent loop
wiring、previous run skill release 及配套测试；3ba19f9（PR #77）
与 22f8625（PR #79）为后续修正。保留它会恰好留下唯一一份
「已完成却显示未开始、且仍强制调用已弃用插件」的文档，与本 PR
目标相反。docs/superpowers/plans 至此为空，同步移除其 gitignore
白名单。

同时在执行台账补上 Run 级 Skills 运行时的已完成记录。台账缺这条
正是上述错误判据的成因。

P1 之二：确立与插件无关的稳定落位目录 docs/implementation-plans，
并将全部发现入口改为同时覆盖该目录与 docs/superpowers/specs：
AGENTS.md 第 11 条、执行台账开头说明与检查清单第 3 条、
fusion-next-step skill。gitignore 增加对应白名单。

此前仅把发现入口收窄到 specs，会使 PR #83 的 monorepo 实施计划
合入后落在无人扫描的目录中。#83 需配套把文档移入新目录并修正
其对已删文件的引用，两者合并后需在最终树上重跑残留引用检查。

Co-Authored-By: Claude <noreply@anthropic.com>
HyxiaoGe pushed a commit that referenced this pull request Aug 31, 2026
Claude @claude
docs: 迁入插件无关目录并修正对已删文件的引用
7df9b1c 
回应 PR #84 评审的第二个 P1：#84 把发现入口收窄后，本计划若仍落在
docs/superpowers/plans 会落在无人扫描的目录，且其对已删文件的完整
路径引用会立即断链。

- 文件迁至 docs/implementation-plans/2026-08-31-monorepo-merge.md，
  该目录由 #84 确立为与已弃用插件无关的稳定落位，并已纳入全部发现
  入口。本分支不改 gitignore，其白名单随 #84 提供，因此本 PR 需在
  #84 之后合并。
- 依据章节：对 2026-06-28-agent-run-continuation.md 的引用改为标注
  该文件已由 #84 清理、原文存于 git 历史，并说明结论不受影响。
- 路径清单 C 类：含 ../fusion-ui/ 的唯一存量文件已随 #84 删除，本项
  在新树上归零，只需对两个保留目录复查一次。
- Task 5 第 2 步重写：fusion-api 侧文档结构已由 #84 简化，本步改为
  迁移 implementation-plans 与 specs，并指出 fusion-ui 侧尚未做过
  同一轮清理、需先按同样口径核查再决定删除或迁移；同时要求 specs
  脱离 superpowers 这一废弃插件名，且落位与发现入口必须一一对应、
  在合并后的最终树上验证。

Co-Authored-By: Claude <noreply@anthropic.com>
@HyxiaoGe Claude

HyxiaoGe commented Aug 31, 2026

Copy link
Copy Markdown
Owner Author

两个 P1 都成立,已修:本 PR 推送 d996450,配套的 #83 推送 7df9b1c。

P1-1 保留那份 plan 是错的 — 判据本身就错

我用的判据是"台账无完成条目 → 可能在飞"。核实 master 历史后确认这条判据不成立:

64049e5  Merge PR #76  feat: 引入Run级Skills运行时
3ba19f9  Merge PR #77  fix: skills CRLF 与 release hash
22f8625  Merge PR #79  fix: fresh release intent 路由

64049e5 的变更与那份 plan 逐项对应:app/ai/skills/registry.py(322 行新增)、app/ai/skills/verified-research/1.0.0/SKILL.md、app/api/trajectory.py、app/services/stream/agent_loop_wiring.py、previous_run_skill_release.py,含配套测试。工作确实已完成,台账只是没更新。

你的推论也对:保留它会恰好留下唯一一份"已完成却显示未开始、且仍强制调用已弃用插件"的文档,与本 PR 目标相反。

已处理:

  • 补删该文件。docs/superpowers/plans/ 至此为空,同步移除其 .gitignore 白名单
  • 在台账补上 Run 级 Skills 运行时的已完成记录(附三个 merge SHA 与实现范围)—— 台账缺这条正是我判据出错的成因,不补的话下一个人会犯同样的错

P1-2 落位与发现入口未闭环 — 采纳方案 (a)

你说得对:PR 描述里写"#83 再据此调整"拦不住 #83 被无冲突合并。而且断链有两处,不止一处:

#83 中的位置 引用 #84 后
依据 L24 plans/2026-06-28-agent-run-continuation.md 断链
路径清单 C 类 2026-06-30-search-read-planner-ledger.md 断链
Task 5 第 2 步 「合并 plans(54) 与 specs(23)」 数字与前提均失效

我此前只在 #84 单分支上跑残留检查,没查合并后的树 —— 这是实打实的疏漏。

采纳你的方案 (a),确立与插件无关的稳定目录 docs/implementation-plans/:

本 PR(d996450)

  • .gitignore 新增 !docs/implementation-plans/ 白名单
  • 发现入口全部改为同时覆盖 docs/implementation-plans 与 docs/superpowers/specs:AGENTS.md 第 11 条、台账开头说明、台账检查清单第 3 条、fusion-next-step skill

#83(7df9b1c)

  • 文档 git mv 到 docs/implementation-plans/2026-08-31-monorepo-merge.md
  • 依据 L24 改为标注该文件已由 chore: 清理已弃用 superpowers 插件的遗留文档 #84 清理、原文存于 git 历史,并说明结论不受影响(跨仓协同要一个工作分支却只能按子仓分别提交,这条约束本身就是双仓成本的证据)
  • C 类改为「chore: 清理已弃用 superpowers 插件的遗留文档 #84 后存量归零」
  • Task 5 第 2 步重写:改为迁移 implementation-plans + specs;指出 fusion-ui 侧尚未做过同一轮清理,需先按同样口径核查再决定;要求 specs 脱离 superpowers 这个废弃插件名;并把「落位与发现入口必须一一对应、须在合并后的最终树上验证」写成 Task 要求

在合并树上重跑了检查

按你的要求,本地构造 #84 + #83 的合并树(无冲突)后验证:

docs/implementation-plans/   1 份 (monorepo-merge.md)
docs/superpowers/plans/      0 份
docs/superpowers/specs/      23 份

指向已删 plans 的活引用          →  无
发现入口 vs 实际落位             →  两个目录各 4 处提及,一一对应
specs 承重链接(台账 ×3 + 设计 ×1) →  全部可解析
新目录下的新文件可否添加          →  可以

⚠️ 合并顺序现在是硬依赖,不是建议

docs/implementation-plans/ 的 .gitignore 白名单只在本 PR 里。#83 的文档文件本身已被 git 跟踪(不受 ignore 影响),但若 #83 先合,该目录下后续新增的文件会被 docs/* 静默忽略。

所以:#84 必须先合,再合 #83。 我没在 #83 里重复加白名单,以免和本 PR 的 .gitignore 改动冲突。

另外同意你最后一句 —— CI 绿只说明容器校验没被破坏,不等于文档迁移闭环或发布验收;两个 PR 合入 master 都会触发完整 API 发布。

Generated by Claude Code

@HyxiaoGe
HyxiaoGe merged commit 7a2c7d2 into master Aug 31, 2026
1 check passed
@HyxiaoGe
HyxiaoGe deleted the claude/cleanup-superpowers branch August 31, 2026 11:31
@HyxiaoGe HyxiaoGe mentioned this pull request Aug 31, 2026
Merged
HyxiaoGe pushed a commit that referenced this pull request Aug 31, 2026
Claude @claude
chore: 并入 master(#84 已合并)
5dbe51a 
Co-Authored-By: Claude <noreply@anthropic.com>
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@HyxiaoGe