feature-dev-loop

Feature Dev Loop

通过组合本地开发技能，而不是重写这些技能，编排完整的软件功能开发循环：需求基线、计划拆解、多视角计划审查、安全的串行实现、动态验收审查，以及 HTML PR 摘要。

这是一个控制器技能。它负责决定何时进入下一阶段、如何分类反馈、何时退出循环、将哪些内容写入磁盘，以及何时让用户参与。若有可用的现有本地技能，应调用或遵循这些技能来完成底层工作，尤其是：

• superpowers:writing-plans 用于制定实施计划
• superpowers:subagent-driven-development 用于通过实施者／审查者 Agent 执行任务
• superpowers:test-driven-development 用于功能和 Bug 修复的实施
• superpowers:requesting-code-review 用于发起代码审查
• superpowers:verification-before-completion 用于在宣告完成之前进行验证
• UI 行为发生变化时使用前端／浏览器验证技能

Operating Defaults

• 将此技能用于非简单的功能开发、多步骤改动、适合 PR 规模的任务，或用户明确要求计划审查、子 Agent 审查、验收测试、代码审查或生成 PR 摘要的情况。
• 对于微小改动，使用轻量流程，除非用户明确要求完整流程。
• 默认采用安全的串行实现。只有在文件／模块的归属互不重叠，且共享契约已确定时，才并行运行实施工作者。
• 默认在人类审查计划结束后以及最终发布前设置人工关卡。如果用户要求全自动模式，则在满足退出标准时自动继续，并记录所有假设。
• 将流程产物保存在目标仓库的 docs/dev-loop-runs/YYYY-MM-DD-feature-slug/ 下。
• 注意 Git 状态，但除非用户明确要求，否则不要提交、推送或创建 PR。
• 切勿无限循环。每个审查循环默认最多进行 3 轮。
• 遵循当前生效的子 Agent 工具策略。如果用户明确要求使用子 Agent、委派任务、由 Agent 审查计划、完整的 feature-dev-loop，或按名称指定此技能，则在可用时发起子 Agent 调度。如果不可用，应在首次调度子 Agent 前询问，或直接进行审查并记录这一限制。

Dependency Gate

开始完整流程前，检查当前会话中是否提供了本地前置技能。此技能依赖 Superpowers 风格的开发工作流；如果这些技能缺失，不应悄悄退化为临时拼凑的流程。

当可获取当前生效的技能列表时，请从中检查依赖。如果无法获取该列表，请检查可能的本地技能／插件位置，例如 .agents/skills/superpowers、.codex/superpowers/skills 或运行环境的插件列表。不要仅仅因为此技能提到了某项依赖，就假定该依赖存在。

Required skills

以下技能是预期工作流所必需的：

• superpowers:writing-plans - 拆解实施计划
• superpowers:subagent-driven-development - 使用实施者／审查者 Agent 串行执行任务
• superpowers:test-driven-development - 对行为改动遵循红／绿／重构纪律
• superpowers:requesting-code-review - 发起结构化代码审查
• superpowers:verification-before-completion - 在宣告完成前提供证据

Recommended skills

以下技能并非始终必需，但在相关情况下应使用：

• superpowers:brainstorming - 请求仍较粗略，或产品／设计意图尚不明确时
• superpowers:systematic-debugging - 实施或测试过程中发现 Bug 时
• superpowers:receiving-code-review - 应用审查者反馈时
• superpowers:finishing-a-development-branch - 用户需要合并／PR／分支清理方面的指导时
• superpowers:using-git-worktrees - 用户希望在隔离的分支／工作树中执行时
• 前端／浏览器自动化技能 - 必须通过视觉方式验证 UI 行为时

缺少依赖时的处理方式

如果缺少任何必需技能：

1. 在创建完整运行目录或开始实施之前停止。
2. 明确告知用户缺少哪些前置技能。
3. 建议安装 Superpowers，因为这些必需技能由 Superpowers 工作流提供。
4. 如果当前运行环境提供 Superpowers 插件安装工具，请根据当前生效的工具政策使用该工具，或征求用户批准。否则，在已知运行环境时提供相应的安装提示：
   • Codex App：在侧边栏中打开 Plugins，在 Coding 部分找到 Superpowers，点击 +，然后按照提示操作。
   • Codex CLI：运行 /plugins，搜索 superpowers，然后选择 Install Plugin。
   • Claude Code：运行 /plugin install superpowers@claude-plugins-official，或通过 /plugin marketplace add obra/superpowers-marketplace 注册 Superpowers marketplace，然后运行 /plugin install superpowers@superpowers-marketplace。
5. 用户安装后，重新检查依赖，再继续操作。

如果当前运行环境无法安装，请明确说明这一限制之后，再提供精简内联模式。精简内联模式仍必须创建运行产物，并记录子 Agent / Superpowers 依赖不可用。

安装和工作流名称参考：https://github.com/obra/superpowers。

反馈严重级别

所有审查意见都必须使用以下严重级别：

• BLOCKER：必须解决后才能退出循环。
• IMPORTANT：应在退出前解决。控制器只能在提供书面理由后裁定并关闭此项。
• QUESTION：必须得到答复，或转化为具体更改后才能退出。
• NIT：不阻塞进度的小改进。记录下来，但不得因此阻碍进度。

仅当没有未解决的 BLOCKER、IMPORTANT 或 QUESTION 项时，阶段才能退出。剩余的 NIT 项作为后续事项处理。

运行目录

每次运行开始时：

1. 如果可用，使用 git rev-parse --show-toplevel 定位仓库根目录。
2. 检查 git status -sb。
3. 记录 base_sha、当前分支、脏状态摘要、用户请求和模式。
4. 创建：

docs/dev-loop-runs/YYYY-MM-DD-feature-slug/
  00-requirements.md
  01-plan.md
  02-plan-review-rounds.md
  03-implementation-log.md
  04-acceptance-report.md
  05-pr-summary.html
  artifacts/
    screenshots/
    test-outputs/

如果工作树存在未提交更改，不要还原任何内容。判断现有更改是否与所请求的任务相关。如果情况不明确且存在风险，请在编辑前询问用户。

阶段 1：需求基准

在制定计划之前创建 00-requirements.md。

使用以下结构：

# Requirements Baseline

## Goal
## Non-goals
## User-visible Behavior
## Acceptance Criteria
## Constraints
## Assumptions
## Open Questions
## Source Request
## Repo Context

仅当未解决的问题会实质影响架构、数据模型、安全性、用户体验、兼容性或测试策略时，才向用户提问。普通实现细节根据仓库惯例推断，并记录为假设。

存在会阻塞进度的未解决问题时，不得开始拆分计划。

阶段 2：计划拆分

编写计划前先探索代码库。优先使用 rg 和现有项目文档 / 测试，让仓库的现有风格指导实现方式。

创建 01-plan.md。如有条件，请遵循 superpowers:writing-plans。

计划必须包含：

• 明确目标和架构概要
• 预计变更的文件 / 模块
• 任务顺序及依赖关系
• 测试策略和准确的验证命令
• 工作子 Agent 的职责边界
• 与 00-requirements.md 对应的验收标准
• 已知风险和假设

任务应足够精简，便于独立实施和审查。如果需要共享契约，应将其安排在依赖它的任务之前。

阶段 3：多视角计划审查循环

在有可用且获准使用子 Agent 时，从不同视角派遣多个计划审查子 Agent。为每位审查者提供明确的上下文：需求文件、计划文件、相关仓库规范，以及要求的输出格式。不要把完整对话历史交给他们。

默认审查视角：

• 架构审查者：拆分方式、边界、依赖顺序、可扩展性、集成风险
• 测试策略审查者：验收标准、回归覆盖、失败路径、验证命令
• 产品／规范审查者：用户可见行为、需求缺口、非目标、语义模糊之处
• 风险／复杂度审查者：隐藏复杂度、迁移风险、上线顾虑、可维护性陷阱

每位审查者都必须返回：

## Verdict
APPROVED | COMMENTS

## Comments
- id:
  severity: BLOCKER | IMPORTANT | QUESTION | NIT
  area:
  target:
  comment:
  required_change:

## Approval Conditions

将所有反馈汇总到 02-plan-review-rounds.md。

每轮审查：

1. 针对所有有效的 BLOCKER、IMPORTANT 和 QUESTION 反馈修订计划。
2. 如拒绝某条意见，写明裁定和理由。
3. 让审查者重新审查完整的修订计划，而不只是差异。
4. 最多进行 3 轮；若仍有未解决的阻塞性分歧，则向用户升级并给出具体建议。

当所有审查者均批准，或只剩 NIT 项时，计划审查结束。

计划关卡

除非用户要求自动模式，否则在开始实施前，简要展示计划摘要并征求批准：

• 目标
• 主要文件／模块
• 任务顺序
• 主要风险
• 验证策略

阶段 4：安全串行实施

按照计划顺序，一次实施一个任务。当计划已明确且适合使用工作子 Agent 时，使用 superpowers:subagent-driven-development。对于行为变更，使用 superpowers:test-driven-development。

对于每项任务：

1. 明确分配文件／模块的所有权。
2. 告知工作者，代码库中还有其他人；不得撤销他人的编辑，并且必须适应现有变更。
3. 尽可能优先采用 TDD：在实施前编写并验证失败的测试。
4. 运行针对任务的验证命令。
5. 在 03-implementation-log.md 中记录变更、命令、结果和顾虑。
6. 若任务涉及重要行为或风险，则进行任务级规范符合性和代码质量审查。
7. 按照统一的严重性规则处理审查发现。

默认采用串行实施。仅当满足以下条件时，才允许并行实施：

• 任务涉及互不重叠的文件／模块
• 共享契约已经提交或以其他方式保持稳定
• 每位工作者都有明确的所有权
• 控制者能够安全地整合并审查输出

除非用户明确要求提交变更或采用 PR 模式，否则不要创建检查点提交。

阶段 5：动态验收矩阵

实施完成后，根据实际变更范围选择审查者。

始终运行：

• 需求验收审查者：根据 00-requirements.md 和 01-plan.md 验证交付的行为
• 测试覆盖审查者：检查测试、遗漏的用例、回归风险，以及验证命令是否可信
• 代码质量审查者：检查正确性、可维护性、集成、边缘情况和隐蔽回归

按需运行：

• 前端 UX 审查者：针对 UI、交互、布局、无障碍或视觉变更；要求提供浏览器/截图证据
• 安全审查者：针对身份验证、权限、机密、上传、外部输入、支付或数据暴露
• 性能审查者：针对查询、渲染循环、并发、缓存、批处理或大型数据路径
• 文档/迁移审查者：针对配置、迁移、API 行为、设置说明或面向用户的行为变更
• 兼容性审查者：针对公共 API、架构、序列化数据、插件或集成契约

每位验收审查者都会收到：

• 需求基线
• 最终计划
• 实施日志
• base_sha 和当前 HEAD 或工作树差异
• 相关测试输出和截图
• 其具体审查任务

每位审查者返回：

## Verdict
PASS | PASS_WITH_NOTES | FAIL

## Scope Checked
## Evidence
## Findings
- id:
  severity: BLOCKER | IMPORTANT | MINOR
  target:
  finding:
  suggested_fix:
  evidence:

## Residual Risks

将结果汇总到 04-acceptance-report.md：

# Acceptance Report

## Verdict
PASS | PASS_WITH_NOTES | FAIL

## Scope Checked
## Reviewers Run
## Tests Run
## Requirement Coverage
## Findings
## Fixes Applied
## Residual Risks
## Follow-ups

仅当满足以下条件时，验收才结束：

• 不再存在 BLOCKER
• 不再存在未解决的 IMPORTANT
• 验证命令均通过，或已清楚说明哪些命令不可用及其原因
• 控制器可以如实给出 PASS 或 PASS_WITH_NOTES

如果验收失败，请修复问题并重新运行相关审查者。最多进行 3 轮，然后提交包含阻塞问题的报告并升级处理。

阶段 6：HTML PR 摘要

生成 05-pr-summary.html，作为自包含、摘要优先的 HTML 报告。报告应帮助 PR 审查者快速了解变更，同时保留可展开的审计详情。

首屏应说明：

• 此 PR 解决的问题
• 变更内容
• 面向用户的行为变更
• 验证和验收结论
• 剩余风险及后续事项

包含以下可展开的详情部分：

• 需求基线
• 计划审查摘要
• 实施日志
• 验收矩阵
• 已运行的测试及关键输出
• 代码审查发现
• 截图或产物（如适用）
• 主要差异或变更文件摘要

使用简洁易读的 HTML 和 CSS，且不依赖外部网络。尽可能使用相对路径链接本地文件。

Git 策略

• 始终检查并记录当前分支和 base_sha。
• 切勿运行具有破坏性的 git 命令。
• 除非用户明确要求，否则切勿还原用户的更改。
• 除非用户明确要求，否则不要提交、推送或创建 PR。
• 如果用户要求提交，请使用非交互式 git 命令，并确保每次提交仅包含已完成且已验证的工作单元。
• 如果没有提交，则根据 git diff 和 git status 生成摘要。

用户升级处理规则

仅在以下情况询问用户：

• 需求歧义会影响架构、UX、数据模型、安全、兼容性或验收标准
• 工作区中已有的更改导致无法明确安全的编辑方式
• 审查循环达到 3 轮上限，仍存在未解决的阻塞性分歧
• 请求的行为与仓库约束或安全要求冲突

提出问题时，一次只问一个具体问题，并提供推荐答案。

完成清单

最终回复前：

• 00-requirements.md 已存在
• 01-plan.md 已通过计划审查，或已记录裁定结果
• 03-implementation-log.md 记录了任务、变更文件和验证证据
• 04-acceptance-report.md 给出了明确结论
• 05-pr-summary.html 已存在
• 已运行所需测试或检查；若无法运行，则已记录原因
• 不存在未解决的 BLOCKER、IMPORTANT 或 QUESTION

然后向用户简要总结结果，包括报告路径和验证状态。