diff --git a/.claude/results/comment_19_20260422_022859.json b/.claude/results/comment_19_20260422_022859.json new file mode 100644 index 0000000..1e2a551 --- /dev/null +++ b/.claude/results/comment_19_20260422_022859.json @@ -0,0 +1,10 @@ +{ + "type": "issue-comment", + "issue_number": 19, + "body": "**Agent**: product-manager\n**Date**: 2026-04-22T02:28:59Z\n**Source**: [Issue #19 Comment]()\n---\n\nproject_id: alpha-86-AgentDevFlow\nissue_id: #19\n当前阶段: Gate 1: PRD Review\nowner: Product Manager\n\n## 问题理解\n\n#19 当前处理的是 AgentDevFlow 安装脚本的路径问题：当 AgentDevFlow 被安装在 `~/.claude/` 目录下时，skill 中的\"必读文档\"路径（如 `prompts/002_develop_pipeline.md`）无法被正确读取，因为安装目录与项目开发目录不同。\n\n## 当前范围\n\n1. 明确安装到 `~/.claude/` 后的文档路径映射规则\n2. 确保 skill 中引用的文档路径在安装后仍然有效\n3. 定义安装脚本与文档路径的统一规范\n\n## 当前非目标\n\n- 不在本 PRD 中直接修改安装脚本实现\n- 不扩展到与文档路径无关的其他安装问题\n- 不把历史安装经验直接作为当前有效交付物\n\n## 下一步\n\n1. 起草 #19 当前有效 PRD\n2. 以 PRD 作为 Gate 1 输入发起三方评审\n3. Gate 1 通过后再进入 Tech / QA / HR#1 正式链路", + "agent": "product-manager", + "source_comment_url": "", + "created_at": "2026-04-22T02:28:59Z", + "status": "sent", + "http_code": 201 +} \ No newline at end of file diff --git a/.claude/results/comment_21_20260422_022908.json b/.claude/results/comment_21_20260422_022908.json new file mode 100644 index 0000000..e59de2d --- /dev/null +++ b/.claude/results/comment_21_20260422_022908.json @@ -0,0 +1,10 @@ +{ + "type": "issue-comment", + "issue_number": 21, + "body": "**Agent**: product-manager\n**Date**: 2026-04-22T02:29:08Z\n**Source**: [Issue #21 Comment]()\n---\n\nproject_id: alpha-86-AgentDevFlow\nissue_id: #21\n当前阶段: Gate 1: PRD Review\nowner: Product Manager\n\n## 问题理解\n\n#21 当前处理的是 AgentDevFlow 中 prompts 的描述规范问题：禁止仅使用单一 pattern 式描述（如\"读取你的 skill 文件：`.claude/skills/adf-{role}/SKILL.md`\"），要求采用\"pattern + 枚举\"组合方式，即 pattern 作为说明，下方必须放枚举式具体映射内容（如表格）。\n\n## 当前范围\n\n1. 在 CLAUDE.md 中沉淀\"pattern + 枚举\"原则\n2. 修改所有 skills 中的单一 pattern 式描述\n3. 确保所有 skill 调用、文档引用都遵循该规范\n\n## 当前非目标\n\n- 不在本 PRD 中直接修改所有 skill 文件\n- 不扩展到与描述规范无关的其他流程改造\n- 不把历史讨论直接作为当前有效交付物\n\n## 下一步\n\n1. 起草 #21 当前有效 PRD\n2. 以 PRD 作为 Gate 1 输入发起三方评审\n3. Gate 1 通过后再进入 Tech / QA / HR#1 正式链路", + "agent": "product-manager", + "source_comment_url": "", + "created_at": "2026-04-22T02:29:08Z", + "status": "sent", + "http_code": 201 +} \ No newline at end of file diff --git a/.claude/results/comment_5_20260416_074755.json b/.claude/results/comment_5_20260416_074755.json index 1b5ebfe..756e35f 100644 --- a/.claude/results/comment_5_20260416_074755.json +++ b/.claude/results/comment_5_20260416_074755.json @@ -5,5 +5,6 @@ "agent": "github-actions[sync]", "source_comment_url": "", "created_at": "2026-04-16T07:47:55Z", - "status": "pending" + "status": "sent", + "http_code": 201 } \ No newline at end of file diff --git a/.claude/results/comment_8_20260416_074749.json b/.claude/results/comment_8_20260416_074749.json index b5c6888..853b3fe 100644 --- a/.claude/results/comment_8_20260416_074749.json +++ b/.claude/results/comment_8_20260416_074749.json @@ -5,5 +5,6 @@ "agent": "github-actions[sync]", "source_comment_url": "", "created_at": "2026-04-16T07:47:49Z", - "status": "pending" + "status": "sent", + "http_code": 201 } \ No newline at end of file diff --git a/.claude/skills/adf-start-agent-team/SKILL.md b/.claude/skills/adf-start-agent-team/SKILL.md index 46e410a..4632a70 100644 --- a/.claude/skills/adf-start-agent-team/SKILL.md +++ b/.claude/skills/adf-start-agent-team/SKILL.md @@ -40,6 +40,13 @@ 3. **Team 创建完成后，继续步骤 1** +**⚠️ 路径陷阱：Claude Code Team 系统 vs 项目本地配置是两套路径系统**： +- TeamCreate tooling 读取全局注册表：`~/.claude/teams/{team_name}/config.json`（home 目录，不是项目目录） +- 项目本地配置：`.claude/teams/{project_id}/config.json`（项目目录） +- **正确顺序**：先用 TeamCreate 在全局注册 Team → 再在项目目录建立本地 mirror +- **禁止跳过全局注册直接用本地配置**，否则 Agent tool 报"Team 不存在" +- 验证方法：`ls ~/.claude/teams/{team_name}/config.json` 确认全局注册存在 + **禁止行为**： - 在 Team 未建立的情况下直接创建多个 Agent - 将 `team-lead` 作为需要创建的 Agent（team-lead 是当前 Claude Code 窗口本身，不是需要创建的 Agent） diff --git a/docs/guides/enhancement-guide.md b/docs/guides/enhancement-guide.md index 0740ee5..1ea73ac 100644 --- a/docs/guides/enhancement-guide.md +++ b/docs/guides/enhancement-guide.md @@ -6,10 +6,12 @@ ## 默认状态 -**增强层默认关闭**。 +**增强层默认关闭**（未安装 gstack/superpower 时）。 AgentDevFlow 本体保持可独立运行，不安装 gstack / superpower 时，所有流程正常运行。 +**开关打开 = 强制依赖**：当用户安装 gstack / superpower 后，AgentDevFlow 在适用 Gate 阶段**强制使用**增强能力，不支持选择性关闭。 + ## 启用增强层 ### 前提条件 @@ -99,7 +101,7 @@ AgentDevFlow 本体保持可独立运行，不安装 gstack / superpower 时， ### 不能做的 -- 不能让 AgentDevFlow 强依赖 gstack / superpower +- 不能在安装增强层后选择性关闭某个增强能力（开关打开 = 强制依赖） - 不能把 skill 输出当作正式 Gate 结论 - 不能让 skill 替代正式角色职责 - 不能为了接 skill 而改造出 AgentDevFlow 之外的新流程能力边界 diff --git a/docs/platforms/enhancement-layer.md b/docs/platforms/enhancement-layer.md index a9fc340..a979443 100644 --- a/docs/platforms/enhancement-layer.md +++ b/docs/platforms/enhancement-layer.md @@ -30,14 +30,16 @@ AgentDevFlow 的"能力增强层"由 `gstack` 和 `superpower` 提供，用于 ## 角色增强映射 -| 角色 | 可选增强 skill | 适用阶段 | 来源 | -|------|--------------|---------|------| +| 角色 | 增强 skill | 适用阶段 | 来源 | +|------|----------|---------|------| | Product Manager | brainstorming, plan-ceo-review | 需求澄清、PRD 起草前 | superpower / gstack | | Architect | plan-eng-review, brainstorming | Tech Spec 起草前、技术方案评审前 | gstack / superpower | | QA Engineer | qa-only, qa | QA Case Design 后、QA 验证阶段 | gstack | | Engineer | review, investigate | 开发前、修 Bug、代码 PR 前 | gstack | | Team Lead / PMO | brainstorming, plan-design-review, document-release | 流程改进、接入文档优化、发布后文档同步 | superpower / gstack | +> **强制增强语义**：安装 gstack/superpower 后，增强能力在适用 Gate 阶段**强制使用**，不支持选择性关闭。详见 [增强层使用指南](../guides/enhancement-guide.md)。 +> > **注**：`plan-devex-review` 已在 gstack/superpower 中验证为 `plan-design-review`。 ## 安装前置条件 @@ -52,6 +54,6 @@ AgentDevFlow 的"能力增强层"由 `gstack` 和 `superpower` 提供，用于 ## 相关文档 -- [PRD #003 — AgentDevFlow gstack/superpower 能力增强层接入](../prd/003_adf_enhancement_layer_2026-04-15.md) +- [PRD #003 — AgentDevFlow gstack/superpower 能力增强层接入](../prd/003_adf_enhancement_layer_2026-04-17.md) - [讨论文档 #028 — gstack 与 superpower 增强层接入方案](../prompts/discuss/028_2026-04-14_gstack与superpower增强层接入方案.md) - [增强层使用指南](../guides/enhancement-guide.md) diff --git a/docs/prd/003_adf_enhancement_layer_2026-04-17.md b/docs/prd/003_adf_enhancement_layer_2026-04-17.md new file mode 100644 index 0000000..387ca64 --- /dev/null +++ b/docs/prd/003_adf_enhancement_layer_2026-04-17.md @@ -0,0 +1,228 @@ +--- +name: AgentDevFlow gstack/superpower 增强层接入 +description: 明确 gstack / superpower 作为 AgentDevFlow 能力增强层的接入方式、角色映射和边界约束 +status: In Review +owner: Product Manager +date: 2026-04-17 +update_date: 2026-04-21 +issue: "#3" +--- + +# PRD #003 v4.3 — AgentDevFlow gstack/superpower 能力增强层接入 + +> **当前状态说明**：Issue #3 已按用户要求从暂停恢复，并正式回退到 **Gate 1: PRD Review**。本版本为 GOV-011 后、结合 Human 最新确认的返工修订版本；旧 Gate 2 / QA Case 状态仅作为历史记录，不再作为当前有效前提。 + +## 0. 本轮 Gate 1 当前确认口径 + +### D1. 增强层依赖语义 + +本轮 Gate 1 的当前唯一口径如下： + +- **安装增强层后 = 强制依赖** + - 一旦用户安装增强层，即默认开启并在适用 Gate 强制使用 gstack / superpower + - 不存在“安装后仍按场景选择是否启用”的可选分支 +- **未安装增强层时 = 回落 AgentDevFlow 原生机制** + - 未安装时不阻断主流程 + - 仍按 AgentDevFlow 原生机制运行 + +### D2. 角色增强映射执行强度 + +本轮 Gate 1 的当前唯一口径如下： + +- 在适用 Gate 中，已安装增强层的相关角色按 **强制执行** 处理 +- 不再保留“推荐使用”分支作为当前需求口径 + +> 在新的 Gate 1 评审结论完成前，当前阶段仍仅限 **Gate 1: PRD Review**，不得进入 Gate 2 Tech Review / QA Case Design。 + +## 1. 背景 + +AgentDevFlow 与 gstack、superpower 三个项目解决的问题层级不同： + +- `gstack`：偏工具与任务工作流，增强单个 Agent 的执行能力 +- `superpower`：偏通用方法论与执行模式，增强单个 Agent 的规划、拆解和协作能力 +- `AgentDevFlow`：偏多 Agent 的交付流程层，定义 Issue / PRD / Tech / QA / Gate / Human Review / Release 的正式协作机制 + +当前 README.md 已明确三者差异，但尚未有正式接入规范，来定义 gstack / superpower 作为 AgentDevFlow 能力增强层时的定位、强制语义与边界约束。 + +关联讨论：`prompts/discuss/028_2026-04-14_gstack与superpower增强层接入方案.md` + +## 2. 问题 + +当前 AgentDevFlow 缺少对 gstack / superpower 增强层的正式接入规范，导致： + +- **接入语义不清**：安装后是否必须启用、未安装时如何回落未被正式定义 +- **边界不清晰**：增强层输出与正式交付物的关系未定义 +- **各角色增强路径不明**：哪些角色在哪些阶段必须使用哪些增强能力未梳理 + +## 3. 目标 + +建立 AgentDevFlow 的“gstack/superpower 能力增强层”接入规范，包括定位声明、角色映射、边界约束，并落地到文档。 + +## 4. 范围 + +### 4.1 增强层定位声明 + +在 README.md 或平台接入文档中明确： + +- `gstack / superpower` 作为 AgentDevFlow 的“能力插件层”，不替代 AgentDevFlow 本身的流程约束层 +- 三者定位关系：工具层（gstack）+ 方法层（superpower）+ 流程层（AgentDevFlow） +- **开关语义**：安装增强层后按强制依赖处理；未安装时回落 AgentDevFlow 原生机制 +- 在新的 Gate 1 评审结论完成前，不得据此进入 Gate 2 + +### 4.2 角色增强映射 + +明确各角色在哪些 Gate 阶段使用增强能力；已安装增强层时，在适用 Gate 中按强制执行处理： + +| 角色 | 增强能力范围 | 适用 Gate | 来源 | +|------|------------|---------|------| +| Product Manager | brainstorming、方案评审增强 | Gate 0（启动）/ Gate 1（PRD 评审前）| superpower、gstack | +| Architect | 方案评审增强 | Gate 2（Tech Spec 起草前）/ HR#1（设计评审）| gstack、superpower | +| QA Engineer | 验证覆盖增强 | Gate 4（QA 验证阶段）/ HR#2（实现确认）| gstack | +| Engineer | 代码审查增强、问题定位增强 | Gate 3（开发阶段）/ 修 Bug / 代码 PR 前 | gstack | +| Team Lead | 流程改进增强 | Gate 0（团队启动）/ Gate 5（发布评审）| superpower、gstack | +| PMO | 流程审计增强 | Gate 0 / Gate 5 / 流程合规检查 | superpower、gstack | + +### 4.3 增强层输出边界约束 + +明确增强层输出不能替代正式交付物： + +- 增强能力生成的内容只能作为：分析过程、补充视角、评审建议、质量增强输入 +- 不能替代以下正式交付物：PRD、Tech Spec、QA Case Design、QA Report、Issue Comment、正式评审结论 + +## 5. 非目标 + +- 不改造 AgentDevFlow 核心流程（Issue/Gate/PR/Human Review） +- 不在本 PRD 中描述技术实现细节（技术选型、接口设计、代码方案） +- 不改造 AgentDevFlow 产生 gstack / superpower 之外的新流程能力边界 +- 不引入“安装后可选启用”或“推荐执行”作为本轮已确认需求分支 + +## 6. 用户故事 + +### US-1：增强语义确认者 +> 作为 AgentDevFlow 用户，我希望明确增强层安装后的真实语义是强制依赖 / 强制执行，未安装时才回落原生机制，以避免文档与实际行为不一致。 + +### US-2：无缝回落者 +> 作为 AgentDevFlow 用户，我希望在未安装增强层时自动回落 AgentDevFlow 原生机制，不需要任何配置即可正常运行。 + +### US-3：质量增强者 +> 作为使用 AgentDevFlow 的 QA Engineer，我希望在 QA 阶段获得验证覆盖增强，同时不改变正式 QA 报告的约束。 + +## 7. 验收标准 + +### 7.1 定位声明 + +- [ ] README.md 或平台接入文档中明确增强层定位（三者定位关系已说明） +- [ ] 增强层“增强角色不替代角色”原则已声明 +- [ ] 增强层依赖语义已明确：安装后强制依赖，未安装时回落原生机制，且表达一致 + +### 7.2 角色增强映射 + +- [ ] 各角色增强能力清单已梳理（6 个角色） +- [ ] 各角色增强能力的适用 Gate 阶段已明确 +- [ ] 各角色增强能力的来源（gstack/superpower）已标注 +- [ ] 已明确这些增强能力在已安装增强层时按“强制执行”处理 + +### 7.3 输出边界 + +- [ ] 增强层输出不能替代正式交付物的约束已声明 +- [ ] “增强能力负责增强思考，正式文件负责流程留痕”的口径已明确 + +### 7.4 安装前置 + +- [ ] 增强层安装前置条件（gstack skill 包 + superpower skill 包）已写入平台接入文档 +- [ ] 已说明安装后行为、回落方式与失败场景 +- [ ] 已说明未安装时按原生机制运行，不阻断主流程 + +## 8. 风险 + +| 风险 | 影响 | 缓解 | +|------|------|------| +| 增强层输出被误当作正式交付物 | 高：Gate 检查被绕过 | 文档中明确边界约束，增强能力输出不计入 Gate 签字 | +| 用户误解安装后仍可选择关闭增强层 | 高：安装后行为与预期不符 | 在 Gate 1 明确唯一口径，并同步 README / 平台文档 | +| 文档口径与实际行为不一致 | 高：用户按文档操作后发现行为不符 | 文档变更需走 PRD Review，不允许跳过 Gate 1 | + +## 9. 依赖 + +- `prompts/discuss/028_2026-04-14_gstack与superpower增强层接入方案.md` +- README.md 当前内容（已包含三者差异 FAQ） +- Issue #3 当前讨论上下文与 Human 最新确认 + +## 10. Gate 1 Review Record + +| 日期 | 评审人 | 结论 | 关键意见 | 待办 | +|---|---|---|---|---| +| 2026-04-17 | PM | 起草完成，发起评审 | 符合新约束：禁止技术细节 | 等待 Architect + QA 签字 | +| 2026-04-17 | Architect | **Approved** ✅ | PRD v4 符合新约束：无技术选型/代码/接口/架构；Section 4 范围重构合理 | — | +| 2026-04-17 | QA | **Approved** ✅ | Section 7 验收标准覆盖完整，可测试性明确 | — | +| 2026-04-20 | PM | HR#1 迭代 — v4.1 | 引入 Gate 0~5 增强映射及“强制依赖/强制增强”口径 | 该版本因 GOV-011 回退，不作为当前有效前提 | +| 2026-04-21 | PM | PRD 返工 — v4.2 | 正式回退到 Gate 1；将依赖语义与增强强制性列为本轮核心决策点 | 等待 PM + Architect + QA 重新评审 | +| 2026-04-21 | PM | PRD 最小修订 — v4.3 | 已按 Human 最新确认统一为“安装后强制依赖 / 强制执行，未安装时回落原生机制” | 等待重新发起 Gate 1 三方评审 | + +### 历史 Gate 2 / QA Case 记录（仅留档，不作为当前有效前提） + +| 文档 | 历史状态 | 说明 | +|------|---------|------| +| Tech Spec #003 v4 | Approved（历史） | 因 Issue #3 已回退到 Gate 1，本记录仅保留追溯，不作为当前 Tech Review 准入依据 | +| QA Case #003 | Approved（历史） | 因 Issue #3 已回退到 Gate 1，本记录仅保留追溯，不作为当前 QA Case Design 准入依据 | + +## 11. 评审记录 + +| 日期 | 评审人 | 备注 | 决策 | +|---|---|---|---| +| 2026-04-17 | PM | PRD 起草（符合新约束：禁止技术细节） | Draft | +| 2026-04-17 | Architect | Gate 1 签字：Approved — 符合新约束，无技术选型/代码/接口/架构 | Approved | +| 2026-04-17 | QA | Gate 1 签字：Approved — Section 7 验收标准覆盖完整 | Approved | +| 2026-04-20 | PM | PRD v4.1 迭代（HR#1 反馈）：补 Gate 映射与强制依赖口径 | In Review | +| 2026-04-21 | PM | GOV-011 后返工：Issue #3 正式回退到 Gate 1，重置 PRD Review 输入；旧 Gate 2 / QA Case 仅作历史留档 | In Review | +| 2026-04-21 | PM | Gate 1 Rejected 后最小修订：删除可选增强 / 推荐执行分支，统一为唯一已确认口径 | In Review | + +## 12. 本轮 Gate 1 进入条件 + +- [x] PRD 当前版本已作为本轮正式评审输入回写到 Issue #3 +- [x] PM 已在 Issue #3 评论中声明：当前阶段 = Gate 1: PRD Review +- [x] Human 最新确认已明确：安装后按强制依赖 / 强制执行处理，未安装时回落原生机制 +- [x] 旧 Gate 2 / QA Case 状态已明确不作为当前有效前提 +- [ ] 待重新发起新的 Gate 1 三方评审入口（PM + Architect + QA） + +## 13. 当前阻塞 + +- 缺新的 Gate 1 三方评审结论 +- 在新的 Gate 1 评审结论完成前，不进入 Tech Review / QA Case Design + +## 14. Review Record + +- 2026-04-21：本版本为 Gate 1 返工后的最小修订版本（v4.3），用于重新进入 PRD Review。当前不具备进入 Gate 2 的条件。 + +## 15. 版本历史 + +| 版本 | 日期 | 变更说明 | 变更人 | +|------|------|---------|-------| +| v4.0 | 2026-04-17 | Gate 1 首轮通过版本 | PM | +| v4.1 | 2026-04-20 | HR#1 反馈后迭代，补 Gate 映射与强制依赖口径 | PM | +| v4.2 | 2026-04-21 | 因 GOV-011 回退到 Gate 1，重置为返工评审输入，显式列出核心待决策点 | PM | +| v4.3 | 2026-04-21 | 按 Rejected 意见做最小修订，统一为“安装后强制依赖 / 强制执行，未安装时回落原生机制” | PM | + +前序文档追溯链： +`PRD v4.3 -> Tech Spec（待重置） -> QA Case（待重置）` + +后续 Gate 1 通过后，Tech Spec 与 QA Case 必须基于 v4.3 重新确认，不得直接沿用历史 Approved 结果。 + +## 16. Review Record 表 + +| 日期 | 阶段 | 评审人 | 结论 | 关键意见 | 待办与负责人 | 下次复审时间 | +|------|------|--------|------|---------|-------------|-------------| +| 2026-04-21 | PRD | PM | In Review | 已按拒绝意见完成最小修订，待重新发起 PM+Architect+QA 三方评审 | 组织 Gate 1 重审（Team Lead） | 待定 | + +## 17. 文档状态机记录 + +- 当前有效 PRD 输入版本：v4.3 +- 当前有效阶段：Gate 1: PRD Review +- 旧 Gate 2 / QA Case 结论：历史留档，不得作为当前下游阶段输入 +- 当前禁止进入：Tech Review、QA Case Design、Implementation + +## 18. 本轮待确认问题 + +1. 在当前唯一确认口径下，README / 平台接入文档应如何准确表达安装前置、强制启用与原生回落机制？ +2. 在当前唯一确认口径下，边界约束与正式交付物替代限制是否表达充分，可供 Gate 1 通过后进入下游重置？ + +这些问题仅作为 Gate 1 当前评审关注点；在新的 Gate 1 评审结论完成前，仍不进入下一阶段。 diff --git a/docs/qa/003_adf_enhancement_layer_qa_2026-04-17.md b/docs/qa/003_adf_enhancement_layer_qa_2026-04-17.md new file mode 100644 index 0000000..e7713be --- /dev/null +++ b/docs/qa/003_adf_enhancement_layer_qa_2026-04-17.md @@ -0,0 +1,251 @@ +--- +name: AgentDevFlow 增强层接入 — QA Case Design v3 +description: 基于 PRD v4.3 与 Tech Spec v5.2 的当前有效 QA Case Draft，定义增强层文档交付的测试用例（文档搜索型验收测试 + 脚本执行验证） +status: Draft +owner: QA Engineer +date: 2026-04-17 +update_date: 2026-04-21 +issue: "#3" +prd: docs/prd/003_adf_enhancement_layer_2026-04-17.md (v4.3) +tech: docs/tech/003_adf_enhancement_layer_tech_2026-04-17.md (v5.2) +--- + +# QA Case Design #003 — 增强层文档交付（v3 Draft） + +--- + +## 当前有效状态 + +- **当前有效版本**：v3 Draft +- **当前有效输入**：PRD v4.3 + Tech Spec v5.2 +- **当前阶段**：QA Case Design（等待 PM + Architect + Engineer 三方评审） +- **规则说明**：本文件为 Issue #3 在回退到 Gate 1 / Gate 2 并重新通过后的当前有效 QA Case Draft + +## 历史结论说明（仅留档，不作为本轮有效前提） + +- 2026-04-17 / 2026-04-20 的 QA Case 评审、Architect 补签与 Approved 结论仅用于追溯 +- 这些历史结论基于 PRD v4.1 / Tech v5，不作为本轮 PRD v4.3 / Tech v5.2 的有效前提 +- 本轮进入 QA Case 三方评审时，应仅以本文件当前 Draft 内容为准 + +--- + +## 追溯关系 + +- **PRD**: `docs/prd/003_adf_enhancement_layer_2026-04-17.md` (v4.3, Issue #3) +- **Tech Spec**: `docs/tech/003_adf_enhancement_layer_tech_2026-04-17.md` (v5.2) + +### PRD v4.3 → QA Case 追溯矩阵 + +| PRD v4.3 Section 7 | 对应 TC | 覆盖状态 | +|---------------------|---------|---------| +| 7.1 定位声明 — 三者定位关系 | TC-3-01 | ✅ | +| 7.1 定位声明 — 安装后强制依赖、未安装时回落原生机制 | TC-3-02, TC-3-04 | ✅ | +| 7.2 角色增强映射 — 6角色清单 / 适用 Gate / 来源 | TC-3-05, TC-3-11 | ✅ | +| 7.2 角色增强映射 — 已安装增强层时按强制执行处理 | TC-3-05, TC-3-11 | ✅ | +| 7.3 输出边界 — 不能替代正式交付物 | TC-3-06 | ✅ | +| 7.3 输出边界 — 流程留痕口径 | TC-3-07 | ✅ | +| 7.4 安装前置 — 安装前置条件 | TC-3-08, TC-3-09 | ✅ | +| 7.4 安装前置 — 安装后行为 / 回落方式 / 未安装不阻断主流程 | TC-3-03, TC-3-04, TC-3-09 | ✅ | + +### Tech Spec v5.2 → QA Case 追溯矩阵 + +| Tech Spec v5.2 Section | 对应 TC | 覆盖状态 | +|------------------------|---------|---------| +| 检测机制（统一检测一次、结果共享、强制依赖/回落） | TC-3-02, TC-3-03, TC-3-04 | ✅ | +| Python 检测脚本实现逻辑 | TC-3-10 | ✅ | +| Gate × 角色增强能力映射矩阵 | TC-3-11 | ✅ | +| 输出边界与回落机制说明 | TC-3-06, TC-3-07 | ✅ | + +--- + +## TC-3-01：增强层定位声明验证 + +| 字段 | 内容 | +|------|------| +| 用例 ID | TC-3-01 | +| 标题 | 增强层定位声明验证 | +| 追溯 | PRD #003 v4.3 / 7.1 定位声明 | +| 前置条件 | `docs/platforms/enhancement-layer.md` 存在于当前分支 | +| 测试步骤 | 1. 读取 `docs/platforms/enhancement-layer.md`
2. 搜索关键词“能力插件层”“工具层”“方法层”“流程层” | +| 预期结果 | 文档包含三者定位关系（gstack/工具层、superpower/方法层、AgentDevFlow/流程层），且明确增强层不替代正式流程约束层 | +| 验证方法 | 文档搜索 | +| 优先级 | P1 | + +--- + +## TC-3-02：安装后强制依赖 / 强制执行语义验证 + +| 字段 | 内容 | +|------|------| +| 用例 ID | TC-3-02 | +| 标题 | 安装后强制依赖 / 强制执行语义验证 | +| 追溯 | PRD #003 v4.3 / 7.1 定位声明；7.2 角色增强映射 | +| 前置条件 | `docs/platforms/enhancement-layer.md` 或当前 Tech Spec 存在 | +| 测试步骤 | 搜索“强制依赖”“强制执行”“不支持安装后再选择性关闭”等关键词 | +| 预期结果 | 文档明确说明：安装增强层后按强制依赖 / 强制执行处理，不存在“安装后可选启用”或“推荐执行”分支 | +| 验证方法 | 文档搜索 | +| 优先级 | P1 | + +--- + +## TC-3-03：检测结果共享验证 + +| 字段 | 内容 | +|------|------| +| 用例 ID | TC-3-03 | +| 标题 | 检测结果共享验证 | +| 追溯 | Tech Spec #003 v5.2 / 检测机制、结果共享 | +| 前置条件 | Tech Spec 存在 | +| 测试步骤 | 搜索“统一检测一次”“Team config”“metadata”“共享”等关键词 | +| 预期结果 | 文档明确说明：`start-agent-team` 统一检测一次，结果通过 Team config 持久化并供各 Agent 共享读取 | +| 验证方法 | 文档搜索 | +| 优先级 | P1 | + +--- + +## TC-3-04：未安装时回落原生机制验证 + +| 字段 | 内容 | +|------|------| +| 用例 ID | TC-3-04 | +| 标题 | 未安装时回落原生机制验证 | +| 追溯 | PRD #003 v4.3 / 7.1、7.4；Tech Spec #003 v5.2 / 回落保障 | +| 前置条件 | `docs/platforms/enhancement-layer.md` 或当前 Tech Spec 存在 | +| 测试步骤 | 搜索“回落”“未安装”“不阻断主流程”“建议安装”等关键词 | +| 预期结果 | 文档明确说明：未安装时自动回落 AgentDevFlow 原生机制，不阻断主流程，并给出建议安装提示 | +| 验证方法 | 文档搜索 | +| 优先级 | P1 | + +--- + +## TC-3-05：角色增强映射表验证（6 角色） + +| 字段 | 内容 | +|------|------| +| 用例 ID | TC-3-05 | +| 标题 | 角色增强映射表验证（6 角色） | +| 追溯 | PRD #003 v4.3 / 7.2 角色增强映射 | +| 前置条件 | `docs/platforms/enhancement-layer.md` 或 PRD/Tech 中映射表存在 | +| 测试步骤 | 读取角色增强映射表，检查 6 个角色 | +| 预期结果 | 每个角色（PM/Architect/QA/Engineer/Team Lead/PMO）都有对应增强能力范围、适用 Gate、来源；并明确已安装时按强制执行处理 | +| 验证方法 | 文档内容验证 | +| 优先级 | P1 | + +--- + +## TC-3-06：输出边界验证 + +| 字段 | 内容 | +|------|------| +| 用例 ID | TC-3-06 | +| 标题 | 增强层输出边界验证 | +| 追溯 | PRD #003 v4.3 / 7.3 输出边界；Tech Spec #003 v5.2 / 输出边界 | +| 前置条件 | `docs/platforms/enhancement-layer.md` 或当前 Tech Spec 存在 | +| 测试步骤 | 搜索“不能替代”“正式交付物”“PRD”“Tech Spec”“QA Case Design”“QA Report”“Issue Comment”“正式评审结论”等关键词 | +| 预期结果 | 文档明确说明增强能力输出不能替代正式交付物与正式 Gate 结论 | +| 验证方法 | 文档搜索 | +| 优先级 | P1 | + +--- + +## TC-3-07：流程留痕口径验证 + +| 字段 | 内容 | +|------|------| +| 用例 ID | TC-3-07 | +| 标题 | 流程留痕口径验证 | +| 追溯 | PRD #003 v4.3 / 7.3 输出边界 | +| 前置条件 | `docs/platforms/enhancement-layer.md` 或当前 Tech Spec 存在 | +| 测试步骤 | 搜索“增强能力负责增强思考”“正式文件负责流程留痕”等关键词 | +| 预期结果 | 文档明确说明增强能力仅增强思考与分析，正式文件负责流程留痕 | +| 验证方法 | 文档搜索 | +| 优先级 | P2 | + +--- + +## TC-3-08：角色文档增强 skill 引用验证 + +| 字段 | 内容 | +|------|------| +| 用例 ID | TC-3-08 | +| 标题 | 6 个角色 SKILL.md 包含增强能力说明验证 | +| 追溯 | PRD #003 v4.3 / 7.2 角色增强映射 | +| 前置条件 | `skills/*/SKILL.md` 存在于当前分支 | +| 测试步骤 | 检查每个角色 SKILL.md 中是否包含增强能力说明及来源标注 | +| 预期结果 | 每个角色文档至少有一条增强能力说明，并标注来源（gstack/superpower） | +| 验证方法 | 文件内容验证 | +| 优先级 | P2 | + +--- + +## TC-3-09：安装前置条件说明验证 + +| 字段 | 内容 | +|------|------| +| 用例 ID | TC-3-09 | +| 标题 | 安装前置条件说明验证 | +| 追溯 | PRD #003 v4.3 / 7.4 安装前置 | +| 前置条件 | `docs/guides/enhancement-guide.md` 存在 | +| 测试步骤 | 读取增强层使用指南，确认安装前置说明 | +| 预期结果 | 文档包含 gstack + superpower skill 包的安装前置条件，并说明未安装时按原生机制运行 | +| 验证方法 | 文档内容验证 | +| 优先级 | P2 | + +--- + +## TC-3-10：检测脚本实现验证 + +| 字段 | 内容 | +|------|------| +| 用例 ID | TC-3-10 | +| 标题 | 检测脚本实现验证 | +| 追溯 | Tech Spec #003 v5.2 / Python 检测脚本实现 | +| 前置条件 | `scripts/detect_enhancement_layer.py` 存在且可执行 | +| 测试步骤 | 1. 确认脚本存在于 `scripts/detect_enhancement_layer.py`
2. 运行 `python scripts/detect_enhancement_layer.py`
3. 验证脚本输出（gstack/superpower 安装状态）
4. 对比脚本输出与实际 skill 目录状态 | +| 预期结果 | 脚本正确识别 gstack/superpower 安装状态，返回码正确（0=任一已安装，1=均未安装），输出与实际 skill 目录一致 | +| 验证方法 | 脚本执行验证 | +| 优先级 | P1 | +| 注意事项 | 若 gstack/superpower 均未安装，脚本返回码应为 1 且输出提示建议安装 | + +--- + +## TC-3-11：Gate 增强映射一致性验证 + +| 字段 | 内容 | +|------|------| +| 用例 ID | TC-3-11 | +| 标题 | 各 Gate 增强能力映射一致性验证 | +| 追溯 | PRD #003 v4.3 / 7.2；Tech Spec #003 v5.2 / Gate × 角色增强映射矩阵 | +| 前置条件 | Tech Spec Gate 增强映射矩阵存在 | +| 测试步骤 | 对照 PRD v4.3 与 Tech Spec v5.2，逐一验证：1. 每个 Gate 的增强能力有 PRD 角色映射作为依据
2. 各角色在各 Gate 的增强能力不超出 PRD 范围
3. 空白（不使用增强）的 Gate 阶段与 PRD 一致 | +| 预期结果 | Tech Spec 的 Gate × 角色增强映射有 PRD v4.3 作为依据，无超出 PRD 范围的增强能力定义 | +| 验证方法 | 文档交叉验证 | +| 优先级 | P1 | + +--- + +## 当前评审状态 + +- **当前状态**：Draft +- **下一动作**：进入 QA Case Design 三方评审（PM + Architect + Engineer） +- **评审前提**：以本文件当前 Draft 为准，不沿用历史 Approved 结论 + +## 历史评审记录（仅留档，不作为本轮有效前提） + +| 日期 | 评审人 | 历史结论 | 说明 | +|---|---|---|---| +| 2026-04-17 | PM | 发起评审 | 基于旧版 PRD / Tech 的历史记录，仅留档 | +| 2026-04-17 | Engineer | Approved | 基于历史版本，仅留档 | +| 2026-04-17 | QA | Approved | 基于历史版本，仅留档 | +| 2026-04-20 | QA | Approved（v2迭代） | 基于 PRD v4.1 / Tech v5，仅留档 | +| 2026-04-20 | Architect | Approved（补签） | 基于 PRD v4.1 / Tech v5，仅留档 | + +## v3 Draft 变更说明（2026-04-21） + +| 变更项 | 说明 | +|--------|------| +| 当前有效输入重置 | 从 PRD v4.1 / Tech v5 重置为 PRD v4.3 / Tech v5.2 | +| frontmatter 重置 | 状态改为 Draft，绑定当前有效 PRD / Tech 版本 | +| 追溯矩阵重置 | 清理 PRD v4.1 / Tech v5 旧追溯矩阵，改为 PRD v4.3 / Tech v5.2 | +| 历史结论降格 | 历史 Approved 记录仅保留留档，不作为当前有效前提 | +| 语义对齐 | 所有测试用例统一对齐“安装后强制依赖 / 强制执行，未安装时回落原生机制” | diff --git a/docs/tech/003_adf_enhancement_layer_tech_2026-04-17.md b/docs/tech/003_adf_enhancement_layer_tech_2026-04-17.md new file mode 100644 index 0000000..adbc73a --- /dev/null +++ b/docs/tech/003_adf_enhancement_layer_tech_2026-04-17.md @@ -0,0 +1,355 @@ +--- +name: AgentDevFlow gstack/superpower 增强层接入 — Tech Spec v5.2 +description: 定义增强层接入的文档交付架构、检测机制语义、角色映射、技术风险与研发计划，作为 PRD v4.3 的 Gate 2 重审输入 +status: Draft +owner: Architect +date: 2026-04-17 +update_date: 2026-04-21 +issue: "#3" +prd: docs/prd/003_adf_enhancement_layer_2026-04-17.md (v4.3) +--- + +# Tech Spec #003 — gstack/superpower 增强层接入（v5.2） + +--- + +**ID**: Tech-3_v5.2 +**状态**: Draft +**负责人**: 架构师 +**日期**: 2026-04-17 +**更新日期**: 2026-04-21 +**基于**: PRD #003 v4.3（2026-04-21） +**版本说明**: v4 → v5：新增检测机制实现逻辑（Section 3）、各 Gate 增强能力使用映射（Section 4.3） +**版本说明**: v5 → v5.1：PRD v4.1 强制增强语义对齐、Section 4.3 补充 HR#1/HR#2、清理 Section 3 重复内容 +**版本说明**: v5.1 → v5.2：因 PRD 已回退并重进 Gate 1，当前按 PRD v4.3 最小重置为本轮 Gate 2 重审输入；统一当前有效口径为“安装后强制依赖/强制执行，未安装时回落原生机制” +**当前评审状态**: 待本轮 Gate 2（PM + QA + Engineer）重新评审，历史 Gate 2 结论仅保留追溯，不作为当前有效前提 + +--- + +## 上下文 + +本 Tech Spec 当前对应 Issue #3 PRD #003 v4.3（2026-04-21），PRD v4.3 为当前有效产品输入，不含技术细节。 + +**PRD v4.3 产品层决策**（Tech Spec 技术层需完整承接）： + +1. **增强层定位**：gstack/superpower = 能力插件层，不替代 AgentDevFlow 流程约束层 +2. **依赖与执行语义**：安装增强层后 = 强制依赖 gstack/superpower，且在适用 Gate 阶段按强制执行处理；未安装时 = 回落 AgentDevFlow 原生机制 +3. **角色增强映射**：6 角色 × 增强能力范围 × 适用 Gate × 来源（产品层抽象，不含具体 skill 名称） +4. **输出边界**：增强能力输出不能替代正式交付物 +5. **非目标**：不改造核心流程、不含技术选型/接口设计/架构设计、不支持安装后再选择性关闭 + +**本 Tech Spec 范围**：纯文档交付，**含检测逻辑说明**。Tech Spec 负责填补 PRD v4.3 中产品层未覆盖的技术细节（检测机制实现逻辑、skill 名称映射、各 Gate 增强能力映射），并作为本轮 Gate 2 重审输入。 + +--- + +## 架构 + +### 检测机制（PRD v4.3 的技术承接） + +PRD v4.3 Section 4 未描述技术实现细节，Tech Spec 补充以下技术语义和实现逻辑。 + +**增强层检测机制**： +- **检测时机**：`start-agent-team` 入口统一检测 gstack / superpower 是否已安装（只检测一次） +- **结果共享**：检测结果在各 Agent 间共享，无需重复检测 +- **安装后语义**：只要检测到增强层已安装，即按当前有效产品口径进入强制依赖 / 强制执行模式，不提供“安装后但按场景选择关闭”的分支 +- **回落保障**：未安装时自动回落 AgentDevFlow 原生机制 + 提示建议安装 +- **零配置**：用户无需手动开启或关闭增强层 + +**用户视角**： +> "安装 gstack/superpower → 启动 start-agent-team → 自动检测一次 → 进入强制依赖 / 强制执行模式 → 各 Agent 在适用 Gate 自动获得增强；未安装或卸载 → 自动回落原生机制" + +### 检测机制实现逻辑 + +#### 两种检测方式对比 + +| 检测方式 | 原理 | 优点 | 缺点 | +|---------|------|------|------| +| **Prompts 检测** | 在 `start-agent-team` skill 的 prompt 中写入检测指令，Agent 执行时通过读取 skill 目录判断 | 无需额外脚本，Skill 内可自包含 | 依赖 Agent 执行 prompt，检测结果不可预测，有副作用 | +| **Python 脚本检测** | 在 `start-agent-team` skill 的 prompt 中调用 Python 脚本，脚本通过文件系统检查 skill 包是否已安装 | 结果可预测、无副作用、可独立测试 | 需额外维护脚本文件 | + +#### 推荐方案：Python 脚本检测 + +采用 **Python 脚本检测**，理由： +1. **无副作用**：脚本只读文件系统，不修改任何状态 +2. **结果可预测**：脚本返回确定的布尔值或列表，Skill prompt 无需解析复杂输出 +3. **可独立测试**：脚本可单独运行验证，无需完整执行 start-agent-team +4. **与 prompts 解耦**：Skill prompt 只负责调用脚本和解读结果，检测逻辑独立演进 + +#### 检测脚本实现 + +**脚本路径**：`scripts/detect_enhancement_layer.py` + +```python +#!/usr/bin/env python3 +"""检测 gstack / superpower 增强层是否已安装""" + +import os +import sys + +SKILL_SEARCH_PATHS = [ + os.path.expanduser("~/.claude/skills"), # 全局 skill 目录 + os.path.join(os.getcwd(), ".claude/skills"), # 项目本地 skill 目录 +] + +def detect_skill(skill_name: str) -> bool: + """检测指定 skill 是否存在于任意 search path 中。""" + for base in SKILL_SEARCH_PATHS: + skill_path = os.path.join(base, skill_name) + # 检查 skill 目录或 skill 文件是否存在 + if os.path.isdir(skill_path) or os.path.isfile(f"{skill_path}.md"): + return True + return False + +def main(): + has_gstack = detect_skill("gstack") + has_superpower = detect_skill("superpower") + + print(f"gstack={'installed' if has_gstack else 'not_found'}") + print(f"superpower={'installed' if has_superpower else 'not_found'}") + + # 返回码表示是否有任一增强层安装 + sys.exit(0 if (has_gstack or has_superpower) else 1) + +if __name__ == "__main__": + main() +``` + +**调用方式**（在 `start-agent-team` skill prompt 中）： +``` +执行检测脚本确定增强层状态： +bash python scripts/detect_enhancement_layer.py +根据输出： +- gstack=installed → 在支持 gstack 的 Agent 中启用 gstack 增强 skill +- superpower=installed → 在支持 superpower 的 Agent 中启用 superpower 增强 skill +- 均 not_found → 回落到原生机制，提示建议安装 gstack 和 superpower +``` + +**检测结果共享机制**： +- `start-agent-team` 在 team 创建时执行一次检测 +- 检测结果通过 Team 配置（`~/.claude/teams/{project_id}/config.json`）的 metadata 字段持久化，供各 Agent 读取 +- 各 Agent 初始化时从 Team config 读取增强层状态，无需重复检测 + +**回落行为**： +- 脚本返回码 0（任一已安装）：正常启用增强能力 +- 脚本返回码 1（均未安装）：AgentDevFlow 原生机制运行 + 建议性提示 +- 回落不影响任何核心流程运行 + +#### 整体逻辑关系图 + +```text +start-agent-team 执行 + │ + ▼ +┌──────────────────────────────────────┐ +│ scripts/detect_enhancement_layer.py │ +│ 遍历 ~/.claude/skills + .claude/skills│ +│ 检查 gstack / superpower 是否存在 │ +└──────────────────────────────────────┘ + │ + ├── gstack installed ──┐ + │ ├──→ Team config metadata + ├── superpower installed ─┤ (增强层状态持久化) + │ │ │ + └── 均 not found ──────┘ ▼ + 回落原生机制 各 Agent 读取 Team config + + 提示安装 启用/回落增强能力 +``` + +#### 为什么不采用 Prompts 检测 + +| 维度 | Prompts 检测 | Python 脚本检测 | +|------|------------|----------------| +| 结果确定性 | 依赖 LLM 理解 prompt，结果不确定 | 脚本返回确定布尔值 | +| 副作用 | LLM 可能执行 prompt 以外的操作 | 只读文件系统，无副作用 | +| 可测试性 | 需完整运行 Agent 才能验证 | 脚本可单独运行测试 | +| 可维护性 | 检测逻辑分散在多个 Skill prompt 中 | 检测逻辑集中在单一脚本 | +| 跨 Agent 一致性 | 不同 Agent 对 prompt 理解可能不同 | 脚本结果一致 | + +> **注**：Claude Code 的 Skill 工具本身已具备 skill 发现能力（扫描 `~/.claude/skills/` 和项目 `.claude/skills/` 目录）。增强层检测脚本复用此发现机制，不需要额外的 skill 注册流程。 + +### 交付域分析 + +基于 PRD #003 v4.3，Issue #3 的交付内容分为 4 个文档域： + +| # | 交付域 | 文档位置 | 操作 | +|---|--------|---------|------| +| 1 | 增强层定位总述 + 检测机制语义 | `docs/platforms/enhancement-layer.md` | 新建 | +| 2 | 增强层回落机制 + 边界说明 | `docs/platforms/enhancement-layer.md` | 合并入域1 | +| 3 | 6 角色增强能力映射 | 对应角色文档 | 修改 | +| 4 | 增强层安装与使用指南 | `docs/guides/enhancement-guide.md` | 新建 | + +> **注**：PRD v4.3 将检测机制保持在产品边界之外，Tech Spec 在域1中补充技术语义描述。PRD v4.3 Section 4.2 的角色增强映射为产品层抽象，Tech Spec 在域3中提供具体 skill 名称映射供参考。 + +### 文档结构 + +``` +docs/ +├── platforms/ +│ └── enhancement-layer.md # 新建：增强层定位 + 检测机制语义 + 回落 + 边界 +└── guides/ + └── enhancement-guide.md # 新建：增强层安装与使用指南 +README.md # 修改：补充增强层定位链接 +skills/*/SKILL.md # 修改：各角色文档补充增强能力说明（6 个角色） +``` + +--- + +## 接口 + +### 角色增强能力 — 产品层（来自 PRD v4.3 Section 4.2） + +| 角色 | 增强能力范围 | 适用阶段 | 来源 | +|------|------------|---------|------| +| Product Manager | brainstorming、方案评审增强 | 需求澄清、PRD 起草前 | superpower、gstack | +| Architect | 方案评审增强 | Tech Spec 起草前、技术方案评审前 | gstack、superpower | +| QA Engineer | 验证覆盖增强 | QA Case Design 后、QA 验证阶段 | gstack | +| Engineer | 代码审查增强、问题定位增强 | 开发前、修 Bug、代码 PR 前 | gstack | +| Team Lead | 流程改进增强 | 流程改进 | superpower、gstack | +| PMO | 流程审计增强 | 流程合规检查 | superpower、gstack | + +### 角色增强能力 — 技术层（Tech Spec 补充） + +> **注**：以下为 gstack/superpower 包中已验证存在的 skill 名称对照，仅供参考。具体 skill 调用以 Agent 初始化时 skill 系统的实际发现为准。 + +| 角色 | 增强能力范围（产品层）| 对应 skill 名称（技术层）| 验证状态 | +|------|---------------------|------------------------|----------| +| Product Manager | brainstorming、方案评审增强 | `brainstorming`, `plan-ceo-review` | ✅ 已验证 | +| Architect | 方案评审增强 | `plan-eng-review`, `brainstorming` | ✅ 已验证 | +| QA Engineer | 验证覆盖增强 | `qa-only`, `qa` | ✅ 已验证 | +| Engineer | 代码审查增强、问题定位增强 | `review`, `investigate` | ✅ 已验证 | +| Team Lead | 流程改进增强 | `brainstorming`, `plan-design-review`, `document-release` | ✅ 已验证 | +| PMO | 流程审计增强 | `brainstorming`, `plan-design-review`, `document-release` | ✅ 已验证 | + +> **更新**：经 Engineer 验证，`plan-devex-review` 不存在，已更正为 `plan-design-review`（gstack 中存在）。其余 skill 均已确认。 + +### 各 Gate 增强能力使用映射（PRD v4.3 Section 4.2 技术层展开） + +以下映射基于 PRD v4.3 Section 4.2 角色增强映射，将"适用 Gate"展开为完整 Gate 矩阵，指定各角色在哪些 Gate 强制使用哪些增强能力： + +| Gate | PM | Architect | QA | Engineer | Team Lead | PMO | +|------|----|-----------|----|----------|-----------|-----| +| Gate 0 Startup | — | — | — | — | brainstorming（流程改进规划）| — | +| Gate 1 PRD Review | brainstorming（需求澄清）| plan-eng-review（技术可行性）| — | — | — | — | +| HR#1 设计确认 | — | plan-eng-review + brainstorming | brainstorming（评审视角）| — | — | — | +| Gate 2 Tech Review | brainstorming（方案评审）| plan-eng-review + brainstorming | — | — | — | — | +| Gate 3 Implementation | — | — | — | review（代码 PR 前）| — | — | +| Gate 4 QA Validation | — | — | qa + qa-only | investigate（Bug 定位）| — | — | +| HR#2 实现确认 | — | — | qa + qa-only | — | — | plan-design-review | +| Gate 5 Release | — | — | — | — | document-release | — | + +> **说明**（来自 PRD v4.3 Section 4.2 当前有效口径）： +> - 空白表示该 Gate 该角色不使用增强能力 +> - 已安装增强层 = 强制依赖，增强能力在适用 Gate **强制使用**，不支持安装后再选择性关闭 +> - 未安装增强层 = 回落 AgentDevFlow 原生机制，不阻断主流程 +> - 增强能力由检测脚本确认安装状态后，在对应 Gate 自动触发或自动回落，无需手动配置 +> - 增强能力输出不能替代正式 Gate 结论 + +### 外部依赖验证项 + +| 依赖项 | 状态 | 说明 | +|--------|------|------| +| skill 名称与 gstack/superpower 包实际命名一致 | ✅ 已验证 | Engineer 确认：plan-devex-review → plan-design-review；其余 skill 均已确认 | +| gstack/superpower 包可用性 | 待实施 | 安装前置条件，文档说明安装来源 | + +--- + +## 数据流 + +### 文档交付流程 + +```text +1. 创建 docs/platforms/enhancement-layer.md（增强层定位 + 检测机制语义 + 回落 + 边界） + ↓ +2. 创建 docs/guides/enhancement-guide.md（安装与使用指南） + ↓ +3. 修改各角色文档（6 个角色补充增强能力说明） + ↓ +4. 修改 README.md（补充增强层定位链接） + ↓ +5. Human Review #1（文档 PR） +``` + +--- + +## 可测试性 + +### 文档验收测试 + +| # | 对应 PRD v4.3 | 验证项 | 验证方法 | 预期结果 | +|---|------------|--------|---------|---------| +| TC-1 | 7.1 定位声明 | 增强层定位说明 | 文档搜索"能力插件层"或"增强层" | 文档可找到定位说明 | +| TC-2 | 7.1 定位声明 | 三者定位关系 | 搜索"工具层"、"方法层"、"流程层" | 文档明确说明 gstack/superpower/AgentDevFlow 三者定位关系 | +| TC-3 | 7.2 角色映射 | 6 角色增强能力清单 | 检查 6 个角色文档 | 每个角色文档包含增强能力说明 | +| TC-4 | 7.2 角色映射 | 适用阶段明确 | 检查角色文档 | 各角色增强能力适用阶段已标注 | +| TC-5 | 7.2 角色映射 | 来源标注 | 检查角色文档 | 各角色增强能力来源（gstack/superpower）已标注 | +| TC-6 | 7.3 输出边界 | 增强能力不能替代正式交付物 | 搜索"不能替代"或"边界" | 文档明确说明增强能力输出不能替代 Gate 结论 | +| TC-7 | 7.3 输出边界 | 增强与留痕口径 | 搜索"流程留痕" | 文档明确"增强能力负责增强思考，正式文件负责流程留痕" | +| TC-8 | 7.4 安装前置 | 安装前置条件 | 检查 enhancement-guide.md | 文档包含 gstack + superpower 安装前置说明 | +| TC-9 | — | 检测机制语义 | 搜索"start-agent-team"+"检测" | 文档明确说明 start-agent-team 入口检测语义 | +| TC-10 | — | 检测脚本实现 | 运行 `scripts/detect_enhancement_layer.py`，验证输出与实际 skill 目录状态一致 | 脚本正确识别 gstack/superpower 安装状态，返回码正确 | +| TC-11 | — | 各 Gate 增强能力映射 | 检查 Tech Spec Section 4.3 与 PRD v4.3 Section 4.2 一致性 | 每个 Gate 的增强能力映射有 PRD v4.3 Section 4.2 作为依据 | + +> **注**：TC-1~TC-9 直接映射自 PRD v4.3 Section 7 验收标准（7.1~7.4），TC-10~TC-11 为 Tech Spec 补充的验证项。 + +--- + +## 风险 + +| 风险 | 级别 | 缓解 | +|------|------|------| +| skill 名称与 gstack/superpower 实际命名不一致 | **高** | Engineer 已验证；TC-5 记录验证方法 | +| 文档与 PRD v4.3 当前有效产品层决策描述漂移 | 中 | Tech Spec 直接引用 PRD #003 v4.3 Section 4 作为基准；变更需回链 PRD | +| 检测机制语义与实际 start-agent-team 实现不符 | 低 | 检测机制语义仅作文档描述，不实现代码；实际行为由 start-agent-team skill 定义 | +| 检测脚本路径或权限问题导致脚本无法执行 | 中 | 脚本路径固定为 `scripts/detect_enhancement_layer.py`，在 start-agent-team 执行环境中确保可读可执行；脚本异常时自动回落原生机制 | +| 历史 Gate 2 结论被误当作当前有效前提 | 高 | 在文档头部、上下文与评审记录中显式声明：当前版本仅作为本轮 Gate 2 重审输入，历史结论仅留档 | + +--- + +## 发布推进 + +### 阶段 1：文档创建与修改 + +- `docs/platforms/enhancement-layer.md`：增强层定位 + 检测机制语义 + 回落 + 边界 +- `docs/guides/enhancement-guide.md`：增强层安装与使用指南 +- 各角色文档：补充增强能力说明（6 个角色） +- `README.md`：补充增强层定位链接 + +### 阶段 2：文档 PR + +- 分支：`doc-3-enhancement-layer` +- 包含：所有增强层相关文档修改 + +### 阶段 3：Human Review #1 + +- 评审人：PM + QA + Architect +- 重点：文档是否完整覆盖 PRD v4.3 Section 7 验收标准 + +--- + +## 回滚 + +### 回滚方案 + +文档 PR 回滚：删除或 close `doc-3-enhancement-layer` PR。 + +### 回滚条件 + +- skill 名称与实际包命名不一致且无法在当前 PR 中修正 +- 文档与 PRD v4.3 当前有效产品层决策描述存在冲突 + +--- + +## 评审记录 + +| 日期 | 评审人 | 备注 | 决策 | +|---|---|---|---| +| 2026-04-17 | 架构师 | 基于 PRD v4 起草 Tech Spec v4 | Draft | +| 2026-04-17 | PM | 发起 Gate 2 评审 | In Review | +| 2026-04-17 | Engineer | Gate 2 Approved | 历史记录：skill 名称映射准确，检测机制语义可实现 | +| 2026-04-17 | QA | Gate 2 Approved | 历史记录：TC-1~TC-9 完整覆盖当时 PRD Section 7 | +| 2026-04-20 | 架构师 | HR#1 反馈迭代 v5 | Draft | +| 2026-04-20 | 架构师 | HR#1 反馈迭代 v5.1：PRD v4.1 强制增强语义对齐、Section 4.3 补充 HR#1/HR#2、清理 Section 3 重复内容 | Draft | +| 2026-04-20 | Engineer | 历史 Gate 2 v5.1 补签 Approved | 仅留档：v5.1 三项变更均可在 Gate 3 实现阶段落地，检测脚本已实现 | +| 2026-04-20 | PM | 历史 Gate 2 v5.1 覆盖确认 Approved | 仅留档：Tech Spec v5.1 完整覆盖 PRD v4.1 五项产品层决策 | +| 2026-04-21 | 架构师 | 因 PRD #003 已回退并以 v4.3 重新通过 Gate 1，Tech Spec 最小重置为 v5.2 Draft；历史 Gate 2 结论仅保留追溯，不作为当前有效前提 | Draft | +| 2026-04-21 | PM | 待重新发起本轮 Gate 2 三方评审 | In Review | diff --git a/scripts/detect_enhancement_layer.py b/scripts/detect_enhancement_layer.py new file mode 100644 index 0000000..cbc83a2 --- /dev/null +++ b/scripts/detect_enhancement_layer.py @@ -0,0 +1,40 @@ +#!/usr/bin/env python3 +"""检测 gstack / superpower 增强层是否已安装""" + +import os +import sys + +SKILL_SEARCH_PATHS = [ + os.path.expanduser("~/.claude/skills"), # 全局 skill 目录 + os.path.join(os.getcwd(), ".claude/skills"), # 项目本地 skill 目录 +] + +ENHANCEMENT_SKILLS = ["gstack", "superpower"] + + +def detect_skill(skill_name: str) -> bool: + """检测指定 skill 是否存在于任意 search path 中。""" + for base in SKILL_SEARCH_PATHS: + skill_path = os.path.join(base, skill_name) + # 检查 skill 目录或 skill 文件是否存在 + if os.path.isdir(skill_path) or os.path.isfile(f"{skill_path}.md"): + return True + return False + + +def main(): + installed = {} + for skill in ENHANCEMENT_SKILLS: + status = "installed" if detect_skill(skill) else "not_found" + installed[skill] = status + print(f"{skill}={status}") + + # 返回码表示是否有任一增强层安装 + any_installed = any(v == "installed" for v in installed.values()) + if not any_installed: + print("hint: install gstack and/or superpower to enable enhancement layer") + sys.exit(0 if any_installed else 1) + + +if __name__ == "__main__": + main()