rpiv-loop-plan-feature

name	rpiv-loop:plan-feature
description	通过深入的代码库分析和研究创建全面的功能计划
argument-hint	<功能描述或 PRD 路径>
allowed-tools	Read, Write, Edit, Bash, Glob, Grep, Agent, AskUserQuestion, WebSearch, WebFetch
version	2.17.5

<rpiv-loop-root> 解析顺序：环境变量 RPIV_LOOP_ROOT -> CLAUDE_PLUGIN_ROOT -> 当前插件根目录；均不存在时停止并请用户配置 RPIV_LOOP_ROOT 或 CLAUDE_PLUGIN_ROOT。

规划新任务

功能：$ARGUMENTS

使命

通过系统的代码库分析、外部研究和战略规划，将功能请求转换为全面的实施计划。

核心原则：在此阶段我们不编写代码。我们的目标是创建一个上下文丰富的实施计划，使 AI 代理能够一次性成功实施。

关键理念：上下文为王。计划必须包含实施所需的所有信息——模式、必读内容、文档、验证命令——以便执行代理在第一次尝试时就能成功。

规划流程

阶段 0：前置检查

在开始规划前执行状态管理：

1. 检查是否存在相关的 PRD 文件：rpiv/requirements/prd-*.md
2. 如果存在相关 PRD：
   • 读取该 PRD 文件内容
   • 检查是否有 YAML frontmatter
   • 根据 PRD 当前 status 处理：
     • pending → 更新为 in-progress，更新 updated_at
     • in-progress → 可能是上次会话中断。提示用户但继续执行（Plan 创建完成后仍会将 PRD 标记为 completed）
     • completed → PRD 已完成，正常继续
     • superseded → 警告用户此 PRD 已被取代，询问是否仍要基于它创建 Plan
   • 记录 PRD 文件路径，用于后续 related_files
3. 如果没有 frontmatter（旧文件），跳过状态更新
4. 版本替代检查：检查是否存在同名特性的旧版本文件（如当前要创建 plan-{name}-v2.md，而 plan-{name}.md 已存在；或新建的 feature-{name}-complete.md 取代旧 todo todo-{name}-refine.md）。如果存在旧版本且状态不是 superseded / archived，按文件类型分别处理：
   • 流程文件（PRD/Plan/validation 各类）：使用 AskUserQuestion 询问用户是否将旧版本标记为 superseded。确认后更新旧文件 frontmatter：status: superseded，追加 superseded_by: {新文件路径}，更新 updated_at；同时建议在新文件反向加 supersedes: {旧文件路径} 形成双向闭环。
   • todo 文件：todo 不支持 superseded（hook 会拒）。使用 AskUserQuestion 询问用户是否将被取代的旧 todo 直接归档：确认后更新旧文件 frontmatter status: archived，追加 superseded_by: {新文件路径} 作为追溯笔记，更新 updated_at。这与 flow_status 对误标 superseded 的 todo 的自动归一化产出一致——就地 status: archived 即逻辑终态；archive 技能只归档 completed/superseded，不会再搬已 archived 的文件，故 archived_at 可不补、物理位置不强制。

阶段 1：功能理解

深入功能分析：

• 提取要解决的核心问题
• 识别用户价值和业务影响
• 确定功能类型：新功能/增强/重构/错误修复
• 评估复杂度：低/中/高
• 映射受影响的系统和组件

创建用户故事格式或完善用户提供的故事：

作为 <用户类型>
我想要 <行动/目标>
以便 <收益/价值>

阶段 2：代码库情报收集

使用专门的代理和并行分析：

1. 项目结构分析

• 检测主要语言、框架和运行时版本
• 映射目录结构和架构模式
• 识别服务/组件边界和集成点
• 定位配置文件（pyproject.toml、package.json 等）
• 查找环境设置和构建流程

2. 模式识别（在有益时使用专门的子代理）

• 在代码库中搜索类似的实现
• 识别编码约定：
  • 命名模式（CamelCase、snake_case、kebab-case）
  • 文件组织和模块结构
  • 错误处理方法
  • 日志记录模式和标准
• 提取功能领域的常见模式
• 记录要避免的反模式
• 检查 CLAUDE.md 以了解项目特定的规则和约定

3. 依赖分析

• 编录与功能相关的外部库
• 了解库的集成方式（检查导入、配置）
• 在 docs/、ai_docs/、rpiv/reference 或 ai-wiki（如果可用）中查找相关文档
• 注意库版本和兼容性要求

4. 测试模式

• 识别测试框架和结构（pytest、jest 等）
• 查找类似的测试示例作为参考
• 了解测试组织（单元测试 vs 集成测试）
• 注意覆盖率要求和测试标准

5. 集成点

• 识别需要更新的现有文件
• 确定需要创建的新文件及其位置
• 映射路由器/API 注册模式
• 如果适用，了解数据库/模型模式
• 如果相关，识别身份验证/授权模式

澄清模糊之处：

• 如果此时需求不清楚，在继续之前询问用户以澄清
• 获取具体的实施偏好（库、方法、模式）
• 在继续之前解决架构决策

阶段 3：外部研究与文档

在有益时使用专门的子代理进行外部研究：

文档收集：

• 研究最新的库版本和最佳实践
• 查找带有特定章节锚点的官方文档
• 定位实施示例和教程
• 识别常见的陷阱和已知问题
• 检查破坏性更改和迁移指南

技术趋势：

• 研究技术栈的当前最佳实践
• 查找相关的博客文章、指南或案例研究
• 识别性能优化模式
• 记录安全考虑

编译研究参考：

## 相关文档

- [库官方文档](https://example.com/docs#section)
  - 特定功能实施指南
  - 原因：需要 X 功能
- [框架指南](https://example.com/guide#integration)
  - 集成模式部分
  - 原因：展示如何连接组件

阶段 4：深度战略思考

深入思考：

• 此功能如何融入现有架构？
• 关键依赖和操作顺序是什么？
• 可能出现什么问题？（边缘情况、竞争条件、错误）
• 如何全面测试？
• 存在哪些性能影响？
• 是否有安全考虑？
• 这种方法的可维护性如何？

设计决策：

• 在替代方法之间选择，并给出明确的理由
• 为可扩展性和未来修改而设计
• 如果需要，规划向后兼容性
• 考虑可扩展性影响

阶段 5：计划结构生成

使用以下结构创建全面的计划：

以下是您为实施代理填写的模板：

# 功能：<功能名称>

以下计划应该是完整的，但在开始实施之前，验证文档和代码库模式以及任务合理性非常重要。

特别注意现有工具、类型和模型的命名。从正确的文件导入等。

## 功能描述

<功能的详细描述、其目的和对用户的价值>

## 用户故事

作为 <用户类型>
我想要 <行动/目标>
以便 <收益/价值>

## 问题陈述

<明确定义此功能要解决的具体问题或机会>

## 解决方案陈述

<描述提议的解决方案方法以及它如何解决问题>

## 功能元数据

**功能类型**：[新功能/增强/重构/错误修复]
**估计复杂度**：[低/中/高]
**主要受影响的系统**：[主要组件/服务列表]
**依赖项**：[所需的外部库或服务]
**隔离开发**：[是/否] — 中大型功能或需要随时切回主分支时选"是"，execute 阶段据此决定是否创建 Git Worktree

---

## 上下文参考

### 相关代码库文件 重要：在实施之前必须阅读这些文件！

<列出文件及其行号和相关性>

- `path/to/file.py` (第 15-45 行) - 原因：包含我们将镜像的 X 模式
- `path/to/model.py` (第 100-120 行) - 原因：要遵循的数据库模型结构
- `path/to/test.py` - 原因：测试模式示例

### 要创建的新文件

- `path/to/new_service.py` - X 功能的服务实现
- `path/to/new_model.py` - Y 资源的数据模型
- `tests/path/to/test_new_service.py` - 新服务的单元测试

### 相关文档 在实施之前应该阅读这些！

- [文档链接 1](https://example.com/doc1#section)
  - 特定部分：身份验证设置
  - 原因：实施安全端点所需
- [文档链接 2](https://example.com/doc2#integration)
  - 特定部分：数据库集成
  - 原因：展示正确的异步数据库模式

### 要遵循的模式

<从代码库中提取的特定模式 - 包括项目中的实际代码示例>

**命名约定：**（例如）

**错误处理：**（例如）

**日志记录模式：**（例如）

**其他相关模式：**（例如）

---

## 实施计划

### 阶段 1：基础

<描述主要实施之前所需的基础工作>

**任务：**

- 设置基础结构（模式、类型、接口）
- 配置必要的依赖项
- 创建基础工具或辅助函数

### 阶段 2：核心实施

<描述主要的实施工作>

**任务：**

- 实施核心业务逻辑
- 创建服务层组件
- 添加 API 端点或接口
- 实施数据模型

### 阶段 3：集成

<描述功能如何与现有功能集成>

**任务：**

- 连接到现有的路由器/处理器
- 注册新组件
- 更新配置文件
- 如果需要，添加中间件或拦截器

### 阶段 4：测试与验证

<描述测试方法>

**任务：**

- 为每个组件实施单元测试
- 创建功能工作流的集成测试
- 添加边缘情况测试
- 根据验收标准进行验证

---

## 逐步任务

默认按顺序从上到下执行。标记了 `DEPENDS_ON` 的任务，无依赖项之间可并行执行（biubiubiu 模式下由 Leader 据此分配 Dev agent）。每个任务都是原子的且可独立验证。

### 任务格式指南

使用信息密集的关键字以提高清晰度：

- **CREATE**：新文件或组件
- **UPDATE**：修改现有文件
- **ADD**：在现有代码中插入新功能
- **REMOVE**：删除已弃用的代码
- **REFACTOR**：在不改变行为的情况下重构
- **MIRROR**：从代码库的其他地方复制模式

### 任务 N：{ACTION} {target_file}

- **DEPENDS_ON**：[前置任务编号，无依赖则留空] — 用于识别可并行的任务
- **IMPLEMENT**：{具体实施细节}
- **PATTERN**：{对现有模式的引用 - 文件:行号}
- **IMPORTS**：{所需的导入和依赖项}
- **GOTCHA**：{要避免的已知问题或约束}
- **PROPAGATE**（可选，仅当存在强传导依赖时填）：{改动本任务 target_file 时必须同步检查/修改的下游文件——典型如配置常量、期望值表、测试断言（如改 `layouts.yaml` 须同步 `EXPECTED_LAYOUT_*` 常量 + 对应 test 断言行）。无强传导依赖则留空}
- **VALIDATE**（必填）：`{该任务完成后的独立验证命令}`

<按依赖顺序继续所有任务...>

---

## 测试策略

<根据项目的测试框架和研究期间发现的模式定义测试方法>

### 单元测试

<基于项目标准的范围和需求>

按照现有测试方法使用 fixtures 和断言设计单元测试

### 集成测试

<基于项目标准的范围和需求>

### 边缘情况

<列出此功能必须测试的特定边缘情况>

---

## 验证命令

<根据阶段 2 中发现的项目工具定义验证命令>

执行每个命令以确保零回归和 100% 功能正确性。

### 级别 1：语法和样式

<项目特定的代码检查和格式化命令>

### 级别 2：单元测试

<项目特定的单元测试命令>

### 级别 3：集成测试

<项目特定的集成测试命令>

### 级别 4：手动验证

<功能特定的手动测试步骤 - API 调用、UI 测试等>

### 级别 5：额外验证（可选）

<MCP 服务器或可用的额外 CLI 工具>

---

## 验收标准

<列出必须满足的特定、可衡量的完成标准>

- [ ] 功能实现了所有指定的功能
- [ ] 所有验证命令通过，零错误
- [ ] 单元测试覆盖率满足要求（80%+）
- [ ] 集成测试验证端到端工作流
- [ ] 代码遵循项目约定和模式
- [ ] 现有功能无回归
- [ ] 文档已更新（如果适用）
- [ ] 性能满足要求（如果适用）
- [ ] 已解决安全考虑（如果适用）

---

## 完成检查清单

- [ ] 所有任务按顺序完成
- [ ] 每个任务验证立即通过
- [ ] 所有验证命令成功执行
- [ ] 完整测试套件通过（单元 + 集成）
- [ ] 无代码检查或类型检查错误
- [ ] 手动测试确认功能有效
- [ ] 所有验收标准均满足
- [ ] 代码已审查质量和可维护性

---

## 备注

<额外的上下文、设计决策、权衡>

阶段 5.6：产出 acceptance.yaml（AC 对账的权威数据源）

目的：与 plan 文件同步生成结构化的 Gherkin 风格验收判据（AC），作为 validate 填写证据、delivery-report 门禁校验的唯一真实源。

文件路径：rpiv/validation/<feature>/acceptance.yaml（若目录不存在需一并创建）。

plan 阶段职责（本 SKILL 只写以下字段）：

• id：全文件唯一，格式 AC-NNN（三位数字），禁止重复
• given / when / then：严格按 Gherkin 三段式书写
• verification_method：具体到命令 / 测试文件路径 / 脚本名，禁止"人工检查"这种泛词
• blocking：true 表示强约束项，交付前必须 passed 或 not_applicable；false 为软性目标
• notes（可选）：额外上下文

validate 阶段后续职责（不要在 plan 阶段预填）：

• evidence：执行 verification_method 后的具体证据（路径:行号 / 日志片段 / 截图文件名）
• status：passed / failed / not_applicable（初始留空，由 QA 翻状态）

delivery-report 阶段职责：只读 acceptance.yaml，禁止修改任何字段。check_acceptance.py 通过 uv run --no-project python <rpiv-loop-root>/tools/check_acceptance.py <feature> 校验后以退出码决定能否出具交付报告。

质量门（plan 阶段自检清单）：

• acceptance.yaml 条目数 ≥ 3
• 所有 id 唯一且连号
• 所有 verification_method 非空且具体
• 每个 blocking: true 项都配了可执行的 verification_method
• given/when/then 用祈使句描述系统行为，禁止"用户应该感觉良好"这种无法验证的措辞

YAML 示例（最小可用模板，复制后替换内容）：

# rpiv/validation/<feature>/acceptance.yaml
# 由 plan-feature 阶段产出骨架；validate 阶段填 evidence/status；delivery-report 只读不改
feature: <feature-name>
prd: prd-<feature-name>
plan: plan-<feature-name>
acceptance_criteria:
  - id: AC-001
    given: 用户已配置 dod.yaml 且首次进入 rpiv-loop 工作流
    when: 执行 /rpiv-loop:prime 命令
    then: ensure_project_dod.py 被调用，rpiv/dod.yaml 已存在则静默跳过
    verification_method: uv run pytest tests/test_ensure_project_dod.py::test_idempotent_on_second_run
    blocking: true
    evidence: ""
    status: ""
    notes: ""
  - id: AC-002
    given: acceptance.yaml 存在一条 blocking AC 且 status 为空
    when: 触发 Write delivery-report-<feature>.md
    then: PostToolUse hook 退出码 2，stderr 提示 "DoD gate 未通过"
    verification_method: bash tests/integration/test_hook_blocks_unverified.sh
    blocking: true
    evidence: ""
    status: ""
    notes: ""
  - id: AC-003
    given: 8 条 AC 全部 passed 且 evidence 非空
    when: 运行 uv run --no-project python <rpiv-loop-root>/tools/check_acceptance.py <feature>
    then: 退出码 0，stdout 含 "ALL PASS"
    verification_method: uv run --no-project python <rpiv-loop-root>/tools/check_acceptance.py <feature>
    blocking: true
    evidence: ""
    status: ""
    notes: ""

产出约束：

• 本章节要求 acceptance.yaml 与 plan.md 同一会话内产出，缺一不可
• plan.md 的「验收标准」章节可保留对 plan 自身的 checklist，但强约束 AC 的唯一权威源是 acceptance.yaml
• 与 delivery-report 的 check_acceptance.py 构成闭环：plan 写骨架 → validate 翻状态 → delivery-report 校验通过才放行

---

输出格式

文件名：rpiv/plans/plan-{kebab-case-feature-name}.md

• 将 {kebab-case-feature-name} 替换为简短、描述性的功能名称
• 示例：plan-user-authentication.md、plan-search-api.md、plan-database-refactor.md

目录：如果不存在，创建 rpiv/plans/

文件格式

文件必须包含 YAML frontmatter 和内容：

---
description: "功能实施计划: {feature-name}"
status: pending
created_at: {YYYY-MM-DDTHH:MM:SS}
updated_at: {YYYY-MM-DDTHH:MM:SS}
archived_at: null
related_files:
  - rpiv/requirements/prd-{feature-name}.md  # 如果存在相关 PRD
---

# {计划内容}

Frontmatter 字段说明：

• description: 文件描述
• status: 文件状态，新创建时固定为 pending
• created_at: 创建时间戳，ISO 8601 格式
• updated_at: 更新时间戳，创建时与 created_at 相同
• archived_at: 归档时间戳，创建时固定为 null
• related_files: 关联文件列表（如果存在相关 PRD 则添加）

完成后续

计划创建完成后：

1. 如果在前置检查中更新了 PRD 的状态，将其 status 从 in-progress 改为 completed
2. 更新 PRD 的 updated_at 时间戳
3. 提示用户："计划已创建。相关 PRD 已标记为完成。"
4. 建议下一步："建议 /clear 后执行 /rpiv-loop:execute rpiv/plans/plan-{feature-name}.md 开始实施。"

质量标准

上下文完整性 ✓

• 所有必要的模式已识别和记录
• 外部库使用已记录并附有链接
• 集成点已清晰映射
• 已捕获陷阱和反模式
• 每个任务都有可执行的验证命令

实施就绪 ✓

• 其他开发者可以在没有额外上下文的情况下执行
• 任务按依赖顺序排列（可以从上到下执行）
• 每个任务都是原子的且可独立测试
• 模式引用包括特定的文件:行号

模式一致性 ✓

• 任务遵循现有代码库约定
• 新模式有明确的理由说明
• 没有重新发明现有的模式或工具
• 测试方法符合项目标准

信息密度 ✓

• 无通用引用（全部具体且可操作）
• URL 在适用时包含章节锚点
• 任务描述使用代码库关键字
• 验证命令是非交互式可执行的

成功指标

一次性实施：执行代理可以在没有额外研究或澄清的情况下完成功能

验证完整：每个任务至少有一个有效的验证命令

上下文丰富：计划通过"无先验知识测试" - 不熟悉代码库的人可以仅使用计划内容进行实施

信心分数：#/10 表示执行将在第一次尝试时成功

报告

创建计划后，提供：

• 功能和方法的摘要
• 创建的计划文件的完整路径
• 复杂度评估
• 关键实施风险或考虑因素
• 一次性成功的估计信心分数