rpiv-loop-biubiubiu

> `<rpiv-loop-root>` 解析顺序：环境变量 `RPIV_LOOP_ROOT` -> `CLAUDE_PLUGIN_ROOT` -> 当前插件根目录；均不存在时停止并请用户配置 `RPIV_LOOP_ROOT` 或 `CLAUDE_PLUGIN_ROOT`。 # Biubiubiu: 全自主 RPIV 团队执行 > **`{RPIV_SKILLS}` 路径约定**：指当前运行面可发现的 rpiv-loop skills 集合。优先按已安装 skill frontmatter `name: rpiv-loop:<name>` 精确匹配；其次按同级目录 `rpiv-loop-<name>/SKILL.md` 或源树 `skills/<name>/SKILL.md` 查找。只有显式处于插件开发模式时，才扫描 `plugins/rpiv-loop/skills/<name>/SKILL.md`。 ## 前置初始化 首次执行前调用（幂等，已存在则静默跳过）： ```bash uv run --no-project python <rpiv-loop-root>/tools/ensure_project_dod.py ``` 该脚本在缺失时从 `<rpiv-loop-root>/tools/dod_template.yaml` 创建项目根目录的 `rpiv/dod.yaml`；已存在则静默跳过。该文件是 validate 阶段项目级质量门的数据源（validate SKILL「第 0 步」逐条执行其 gates），delivery-report 前置条件亦对账其 blocking gates。 从对话上下文中提取需求，启动 agent 团队自主完成完整 RPIV 开发流程（PRD → Plan → Execute → Validate），全程无需用户介入。 ## 团队架构 | 角色 | 职责 | 活跃阶段 | |------|------|----------| | **Leader**（你自己） | 协调、任务分配、阶段门禁、决策 | 全程 | | **Architect** | PRD + Plan + 实现对齐审查 | 阶段 1-2, 4 | | **Research** | 技术可行性调研（临时） | 阶段 1-2 | | **QA** | 测试策略/用例/执行 + 代码审查 | 全程 | | **Dev-1 / Dev-2** | 代码实现 | 阶段 3-4 | ## 执行流程 ### 步骤 1：提取需求上下文 确定功能名称（从 `$ARGUMENTS` 或对话推断，kebab-case 格式）。 **如果 `$ARGUMENTS` 是已存在的文件路径**（PRD 或需求文档），直接使用该文件作为需求输入，跳到步骤 2。 **否则**，从对话上下文和 `$ARGUMENTS` 提取需求，保存到 `rpiv/brainstorm-summary-{feature-name}.md`： ```markdown --- description: "需求摘要: {feature-name}" status: pending created_at: {YYYY-MM-DDTHH:MM:SS} updated_at: {YYYY-MM-DDTHH:MM:SS} --- # 需求摘要：{feature-name} ## 产品愿景 - 核心问题：... - 价值主张：... - 目标用户：... - 产品形态：... ## 核心场景（按优先级） 1. ... ## 产品边界 - MVP 范围内：... - 明确不做：... ## 约束条件 - ... ## 各场景功能要点 ### 场景 1：... ``` ### 步骤 2：团队机制说明（无需显式创建团队） 当前 Claude Code harness **没有 `TeamCreate`/`TeamDelete` 工具**。团队是**单一 implicit flat team**：你（main 会话）即 Leader，用 `Agent` 工具 spawn 的每个 named agent 自动加入该 implicit team，可被 `SendMessage` 按 name 寻址。因此本步骤无需任何操作，直接进入步骤 3。 若当前运行面没有 `Agent` / `TaskCreate` / `TaskUpdate` / `SendMessage` / `TaskStop` 等团队工具，进入 **single-agent sequential mode**：Leader 按同一阶段顺序在本会话内依次扮演 Architect、Research、QA、Dev，使用 checklist 记录任务状态，不调用缺失工具，不承诺并行执行。核心交付链仍是 PRD → Plan → Execute → Validate → Delivery Report，只有调度方式降级。 ### 步骤 3：创建任务结构 若当前运行面提供任务协作工具，使用 TaskCreate 创建以下任务并设置 blockedBy 依赖。若没有任务协作工具，不调用任何缺失工具；在主会话中创建同等 checklist，按 blockedBy 顺序逐项推进并在每项完成时记录状态。 ``` 阶段 1：需求与调研 T1 create-prd → Architect 基于需求摘要创建 PRD T2 tech-research → Research 关键技术可行性调研 T3 test-strategy → QA 制定测试策略 阶段 2：架构规划 T4 create-plan → Architect 创建实施计划 [blockedBy: T1, T2] T5 test-specs → QA 编写测试规格 [blockedBy: T1] 阶段 3：实现 T6 implement → Dev 代码实现 [blockedBy: T4] T7 write-tests → QA 编写测试代码 [blockedBy: T4, T5] 阶段 4：验证 T8 run-tests → QA 运行测试 [blockedBy: T6, T7] T9 code-review → QA 代码审查 [blockedBy: T6] T10 plan-alignment → Architect 实现对齐审查 [blockedBy: T6] T11 delivery-report → Leader 生成交付报告 [blockedBy: T8, T9, T10] ``` ### 步骤 4：启动团队 仅当当前运行面提供可用的 Agent 工具时执行本步骤。若处于 single-agent sequential mode，跳过 spawn；Leader 直接按步骤 3 checklist 依次完成 Architect / Research / QA / Dev 职责，并在每个阶段结束时自检同一门禁。 **第一批（并行启动 3 个 agent）：** 用 `Agent` 工具 spawn 以下每个角色，参数：`name` = 角色名（如 `architect`）、`subagent_type` = `general-purpose`、`run_in_background` = `true`（不阻塞 Leader 协调）。**不要传 `team_name`**（已废弃且被忽略）。spawn 出的 named agent 自动加入 implicit team，后续用 `SendMessage`（`to` = 角色名）双向通信；spawn 返回的 `agent_id`（形如 `architect@session-xxxx`）可用于 `TaskStop` 兜底。 > 若 spawn named teammate 报错（roster / 身份类错误），不要反复重试 spawn，按「规模自适应 → 降级路径」处理。 #### Architect Agent 名称：`architect` 提示词要点： - 你是 RPIV 团队的架构师，负责产品设计和技术架构 - **首要步骤**：开始任何文档编写前，先读取项目 CLAUDE.md 获取部署平台、技术栈、架构等基础设施信息。PRD/Plan 中涉及部署、环境、技术栈的内容必须以 CLAUDE.md 为准，禁止自行推断 - **事实承接（强制）**：PRD/Plan 中**任何含具体事实声明的语句**（文件名 / 行号 / 类名 / 函数签名 / 字段名 / 调用次数 / 批量计数 / 模块依赖），实施前必须先 `Grep` 或 `Read` 实际代码 verify 事实存在且精确。grep 出"所有命中行"后还要**人工区分"必须改 vs 中性可保留"**，给每行打 `MUST_CHANGE / OPTIONAL / KEEP` 标记，再写入 Plan，禁止整段未分级倒入。verify 与 brainstorm/PRD 描述不符时，立刻 SendMessage 透明披露给 Leader，禁止默默按错描述继续（此机制多次 catch PRD/Plan 中的事实漏洞，每次节省数轮下游 fix loop） - **阶段 1**：读取需求摘要文件 `{brainstorm-summary-path}`，将其 `status` 更新为 `in-progress`。按照 RPIV create-prd 规范创建 PRD → `rpiv/requirements/prd-{feature-name}.md`。PRD 创建完成后，将需求摘要的 `status` 更新为 `completed`。PRD 规范参考读取 `{RPIV_SKILLS}/create-prd/SKILL.md` - **阶段 2**：等待 tech-research 任务完成（通过 TaskList 检查），然后按照 RPIV plan-feature 规范创建实施计划 → `rpiv/plans/plan-{feature-name}.md`。计划规范参考读取 `{RPIV_SKILLS}/plan-feature/SKILL.md`。代码库分析要做充分，计划要足够详细，让 Dev agent 无需额外调研就能实现 - **阶段 4**：对比实现代码与计划，检查是否有偏离或遗漏，将审查结果通过 SendMessage 发给 team leader - **完成任务的固定顺序**：标记 TaskUpdate completed 之前，必须先 Edit 对应的 `rpiv/` 文件，将 frontmatter `status` 更新为 `completed`、`updated_at` 更新为当前时间戳。顺序：Edit frontmatter → TaskUpdate completed，不可颠倒 - 完成每个任务后 TaskList 找下一个任务 - 遇到需要决策时自主决定，在文档中记录理由 - 全程使用中文 #### Research Agent 名称：`researcher` 提示词要点： - 你是 RPIV 团队的技术调研员，负责关键技术的可行性分析 - 读取需求摘要 `{brainstorm-summary-path}`，识别关键技术点 - 调研内容：核心依赖库 API 兼容性和版本、框架特性支持（如 Streamlit）、性能约束、潜在技术风险 - **框架内置方案优先（硬性要求）**：对每个核心依赖库，必须检查是否有内置的抽象类/Provider/Handler 可直接使用。具体做法：读取依赖库源码中的 abstract class 和示例代码，而非仅搜索文档。调研结论必须明确回答"框架是否已提供此能力"，并附源码路径作为证据。只有在证明框架不支持后，才评估自研方案 - 调研结果保存到 `rpiv/research-{feature-name}.md`，文件必须包含 frontmatter：`status: pending`、`created_at`、`updated_at` - 调研完成后，将 research 文件的 `status` 更新为 `completed`，更新 `updated_at` - 通过 SendMessage 将关键发现告知 architect - 你是临时角色，tech-research 任务完成后你的工作就结束了。标记任务完成，然后等待 shutdown - 全程使用中文 #### QA Agent 名称：`qa` 提示词要点： - 你是 RPIV 团队的质量保证工程师，贯穿全流程 - **事实承接（强制）**：PRD/brainstorm 中**任何具体断言**(如"新增测试 pass:断言 trait_subtype 不恒为 'behavior'"、"行 184 应改 dict"），编写 test-strategy/test-specs 前必须先 `Read` 实际代码验证该断言**可达**(grep 字段定义 / 看代码硬编码默认值 / 看 callsite)。**verification_method self-test(强制)**：写 `acceptance.yaml` 时,每条 `verification_method` 的 shell 命令(`grep` / `bash` / `pytest` 流程)在标 `status=passed` 前**必须先用最小 case 自验**该命令真能产出预期结果——典型陷阱:`grep -A2 pattern file` 在签名跨 4 行时会截断,`grep -rn token` 会撞 `__pycache__` 假阳性（此类自检多次 catch 断言不可达 / 命令假阳性问题，避免 AC gate 空转卡死） - **阶段 1**：分析需求，制定测试策略文档 `rpiv/validation/test-strategy-{feature-name}.md`（frontmatter status: `pending`） - **阶段 2**：基于 PRD 编写测试规格 `rpiv/validation/test-specs-{feature-name}.md`（frontmatter status: `pending`）和验收标准（等 PRD 完成后开始） - **阶段 3**：基于实施计划编写测试用例代码（与 Dev 并行） - **阶段 4**：运行测试 + 代码审查。测试全部通过后，将 test-strategy 和 test-specs 的 status 更新为 `completed`。代码审查规范参考读取 `{RPIV_SKILLS}/code-review/SKILL.md`。审查报告保存到 `rpiv/validation/code-review-{feature-name}.md` - 审查标准要苛刻：安全问题标记为 CRITICAL，每个问题精确到文件和行号 - 如果发现 critical/high 问题，通过 SendMessage 立即告知 team leader - **完成任务的固定顺序**：标记 TaskUpdate completed 之前，必须先 Edit 对应的 `rpiv/` 文件，将 frontmatter `status` 更新为 `completed`、`updated_at` 更新为当前时间戳。顺序：Edit frontmatter → TaskUpdate completed，不可颠倒 - 全程使用中文 **第二批（阶段 3 开始时启动）：** 当 create-plan 任务完成后（门禁 2 通过），根据 Plan 内容决定 Dev agent 数量： 判断标准： - 任务可按模块明确分割（前后端、不同工具模块）且文件不重叠 → 2 个 Dev agent - 任务主要顺序依赖或规模较小 → 1 个 Dev agent - 确保 Dev agents 操作不同的文件集，避免冲突 #### Dev Agent 名称：`dev-1`（如有第二个则 `dev-2`） 提示词要点： - 你是 RPIV 团队的开发工程师 - 读取实施计划 `rpiv/plans/plan-{feature-name}.md` - 按照计划中的逐步任务实现代码。执行规范参考读取 `{RPIV_SKILLS}/execute/SKILL.md` - 你负责的范围：{Leader 根据 Plan 指定的具体模块/文件列表} - 严格按计划实现，不擅自扩展范围 - 遵循项目 CLAUDE.md 中的编码规范 - 每完成一个子任务运行基本语法验证 - **事实承接 + 透明披露（强制）**：Plan 中含具体事实声明（行号 / 字段名 / 函数签名）时，实施前先 `Read` 该位置 verify。**发现 Plan 跟实际代码冲突时（如 "PRD §7 line 262 说改字符串,但 line 184 实际是 dict 断言"），不要默默调和——立刻 SendMessage 透明披露给 Leader,等指示再继续**。判定 baseline vs 新引入回退时,**禁止凭 `.pytest_cache/lastfailed` 单文件判断**(它是多次 partial run 累积),必须 `git stash -u && pytest <files>` 跑改动前 baseline 对比 diff。**每完成一个 Plan 子任务立即 SendMessage 通知 Leader 进度**,不要静默 idle 等大批工作完才汇报（透明披露与 baseline diff 能防止 Leader 基于失真描述派工） - 遇到计划不明确的地方，通过 SendMessage 询问 team leader - **完成任务的固定顺序**：如果任务涉及 `rpiv/` 目录下的 .md 文件，标记 TaskUpdate completed 之前必须先 Edit 文件将 frontmatter `status` 更新为 `completed`、`updated_at` 更新为当前时间戳。顺序：Edit frontmatter → TaskUpdate completed，不可颠倒 - 全程使用中文 ### 步骤 5：阶段协调 作为 Team Leader，你的核心工作是让并行最大化、阻塞最小化。 #### 门禁 1：PRD 就绪 Architect 完成 create-prd 后： - 快速读取 PRD，检查是否覆盖需求摘要中的所有核心场景 - **Frontmatter 校验（grep 验证）**：用 `grep ^status:` 检查 PRD 文件和 brainstorm-summary 文件的 frontmatter status。如果 status 未更新为 `completed`，Leader 直接 Edit 修复（不要 SendMessage 要求 agent 补充，减少往返） - 重大遗漏 → SendMessage 要求 Architect 补充 - 通过 → Architect 可进入 Plan 阶段 #### 门禁 2：Plan 就绪 Architect 完成 create-plan 后： - 检查计划包含：上下文参考、逐步任务、测试策略、验证命令 - **Frontmatter 校验（grep 验证）**：用 `grep ^status:` 检查 Plan 文件和 research 文件的 frontmatter status。如果 status 未更新为 `completed`，Leader 直接 Edit 修复 - **框架方案检查**：确认计划中是否优先使用了框架内置能力（而非自研）。如果计划选择自研而调研报告未充分证明框架不支持，要求 Architect 补充论证 - 确定 Dev agent 数量和文件分工 - **多人协作检查**：如果项目有多个贡献者，先 `git fetch` 检查远程是否已有相关变更，避免重复实现 - 通过 → 启动 Dev agent(s) #### 实现阶段：逐任务快速验证 在阶段 3 实现过程中，不要等所有实现完成后才审查。采用**滚动验证**模式： - Dev 每完成一个子任务（Plan 中的一个 Task），通过 SendMessage 通知 Leader - Leader 立即让 QA 对该子任务做**快速合规检查**（≤5 分钟）：语法验证、导入检查、与计划是否一致 - 快速检查发现 critical 问题 → 立即要求 Dev 修复再继续下一个任务 - 快速检查通过或仅有 low/medium 问题 → Dev 继续下一个任务，问题记录待最终审查处理 这确保了早期任务的错误不会传播到后续任务，同时不阻塞 Dev 的工作节奏。 #### 门禁 3：实现完成 + AC gate 循环 所有子任务的快速检查通过后，进入 **AC gate 循环**（参考 runbook：`<rpiv-loop-root>/tools/run_acceptance_fix_loop.py`）： **循环入口**（一次性工作）： 1. QA 运行完整测试套件 + 全面代码审查 2. Architect 做计划对齐审查 3. QA 按 `validate` SKILL 的「AC 逐条证据采集」章节，逐条翻 `rpiv/validation/<feature>/acceptance.yaml` 的 `status` 与 `evidence` **循环体**（每一轮按序执行）： ``` while round < 10: 1. 运行 check_acceptance.py <feature> 2. 退出码 0 → break（全部 passed，进入步骤 6 交付） 3. 退出码 1/2 → 收集 failing AC 清单（AC-id + 失败原因） 4. SendMessage 分配给 Dev-X：精确指出哪条 AC / 哪个文件 / 期望行为 5. Dev 修复实现代码 6. QA 重跑该 AC 对应的 verification_method → 更新 evidence/status 7. round += 1 ``` **护栏规则**： - **同一 AC 连续 2 轮同一 failure**（错误消息或 failing 行号完全相同）→ 提前 escalate 到 AskUserQuestion，不等满 10 轮 - **10 轮上限**：第 11 轮强制触发 AskUserQuestion，三选项如下： ``` AskUserQuestion: question: "AC gate 10 轮修复未通过，如何继续？" options: - label: "继续 10 轮" description: "延长一次循环配额，Leader 继续分配修复任务" - label: "查看失败清单" description: "中断循环，输出当前所有 failing AC 的详细清单与根因假设" - label: "放弃交付" description: "中止本次 biubiubiu，输出部分完成报告，未通过的 AC 记入 rpiv/todo/" ``` **有 critical/high 代码审查问题**（与 AC 无关的代码质量问题）→ SendMessage 要求 Dev 修复（最多 3 轮），与 AC gate 循环并行处理。 **全部通过**（check_acceptance 退出码 0 且 code-review 无 critical/high）→ 进入交付。 #### 硬规则：架构声明必须 Grep 验证 Leader 在派工 / 仲裁 / 任务依赖判定中，**禁止仅凭 SendMessage 信息**对以下"架构性声明"做出决策： | 声明类型 | 示例 | |---|---| | **字段增删** | Pydantic / dataclass / TypedDict 字段的增加、删除、重命名 | | **接口改动** | 函数签名、CLI 参数、API 路径、事件名变化 | | **数据流变** | 数据来源切换、模块拆分合并、依赖关系反转 | | **配置 schema 变化** | YAML/TOML/JSON 配置字段语义变化 | **强制动作**：收到上述任一类型的 agent 汇报后，Leader **必须** Read 或 Grep 实际代码（类定义文件 / 函数签名 / 配置文件）至少 1 次，确认与汇报一致后才能基于此派工或进入下一阶段。 **反例（禁止）**： - ✗ Dev-1 汇报"SlideSpec 已加 variant 字段"，Leader 直接 SendMessage Dev-2 按新字段实现 layouts.yaml 适配 - ✗ QA 汇报"test_xxx.py 第 127 行断言已更新"，Leader 直接进入交付门禁 **正例（要求）**： - ✓ Dev-1 汇报后，Leader Read `core/spec.py` 或 `Grep "class SlideSpec"` 验证 variant 字段确实存在 + 类型符合预期 → 再 SendMessage Dev-2 - ✓ QA 汇报后，Leader Read `tests/test_xxx.py:120-135` 范围确认断言改动 → 再判断是否进入交付 **为什么**：SendMessage 是异步队列，agent 汇报常因消息间撤销 / 反转产生信息损耗。Read/Grep 单次约 1-2 秒，相对错误派工导致的 2+ 轮 Dev 来回成本可忽略。 **与门禁 1/2 的 frontmatter grep 区别**：那两处 grep 是校验 RPIV 文档元数据（status 字段），本节是校验 agent 汇报的实际代码状态。两者协同覆盖"流程纪律"与"内容纪律"。 #### 硬规则：Spawn 多 agent 前必须 cross-check 分工措辞 Leader **同一时刻 spawn 多个 agent**（如 Dev-1 + Architect + QA 同步启动）前，**必须**对所有 agent 的 prompt 中"任务范围 / ownership"措辞做交叉一致性检查。 **场景**：spawn 两个或更多 agent 时,prompt 中对同一组资源（文件 / 模块 / 测试类 / 任务子项）描述了 ownership。 **错误模式**： - ✗ Dev-1 prompt 写"你负责 D3: `test_reflection.py` rm + D4: `TestDigestCompat` 删" - ✗ Architect prompt 同时写"QA T6 删 `test_reflection.py` + `TestDigestCompat`" - ✗ 两个 prompt 对**同一组文件 ownership 矛盾**,spawn 后两个 agent 会按各自 prompt race condition 推进,产生 ownership 错乱 **修复模式（强制 SOP）**： 1. spawn 前用 `Read` 工具读每个 agent prompt 的"任务范围"段（或写好的 draft） 2. `Grep` 关键资源名（文件名 / 模块名 / 测试类名）跨 prompt 检查 3. 同一资源名出现在多个 prompt 时,**确认 ownership 唯一**(只能一个 agent 主负责,其他至多 verify-only 或下游消费) 4. 有冲突先修后 spawn,**禁止 spawn 后用 SendMessage 纠正**——SendMessage 是异步队列,agent 已按旧 prompt 推进时 race condition 难恢复 **触发关键词**：spawn 多 agent / 同时启动 / Agent 工具 spawn 多个 named teammate / Architect + QA + Dev 并行启动 / 多 agent 任务分配 **为什么**：spawn 多 agent 是 RPIV 流程中**最易产生 race condition 的关键节点**,cross-check 单次约 2-3 秒,相对错误 ownership 导致的 1-2 轮 agent 工作浪费成本可忽略。 #### 决策原则 遇到需要决策时，按以下优先级： 1. 项目 CLAUDE.md 中的规范 2. 需求摘要中的明确约束 3. 业界最佳实践 4. 最简方案（避免过度工程） ### 步骤 6：完成交付 所有验证通过后，**先输出以下 checklist，然后逐项执行并勾选**（防止中间步骤被团队关闭等交互流程冲断）： ``` 交付 checklist： - [ ] 6.1 生成交付报告 - [ ] 6.2 关闭团队 - [ ] 6.3 归档过程文件 - [ ] 6.4 向用户报告 ``` 1. **生成交付报告**：按 `{RPIV_SKILLS}/delivery-report/SKILL.md` 的规范与「输出格式」模板生成（含第 0 步 AC gate 硬校验），保存到 `rpiv/validation/delivery-report-{feature-name}.md`。frontmatter `related_files` 按本次流程实际产物填写；「关键决策」章节除计划偏离外，一并纳入团队自主做出的重大决策及理由。 2. **关闭团队**：仅当本轮实际启动了 named teammate 时执行。对每个仍活跃的 teammate 用当前运行面支持的团队通信工具发送 `{"type": "shutdown_request", "reason": "..."}`，收到确认后结束；某 teammate 无响应且当前运行面支持 `TaskStop` 时，才用 `TaskStop`（task_id = spawn 返回的 agent_id）强制终止兜底。若处于 single-agent sequential mode，本步骤标记为已跳过。 3. **归档过程文件**：将本次流程产生的所有 `rpiv/` 过程文件归档到 `rpiv/archive/`。具体操作： - 创建 `rpiv/archive/` 目录（如不存在） - 遍历以下文件（如存在）： - `rpiv/todo/*{feature-name}*.md` - `rpiv/brainstorm-summary-{feature-name}.md` - `rpiv/research-{feature-name}.md` - `rpiv/requirements/prd-{feature-name}.md` - `rpiv/plans/plan-{feature-name}.md` - `rpiv/validation/test-strategy-{feature-name}.md` - `rpiv/validation/test-specs-{feature-name}.md` - `rpiv/validation/code-review-{feature-name}.md` - `rpiv/validation/delivery-report-{feature-name}.md` - **新增**：归档 `rpiv/validation/{feature-name}/` 整个子目录（含 `acceptance.yaml` 及该特性下所有同目录文件） - 目标路径：`rpiv/archive/validation/{feature-name}/`（保持子目录结构完整，不扁平化） - 子目录内每个 YAML/MD 文件仍需补 `archived_at`（如文件本身有 frontmatter） - 对每个文件：Edit frontmatter 将 `status` 改为 `archived`，添加 `archived_at` 时间戳，更新 `updated_at` - 移动文件到 `rpiv/archive/`（如有同名文件则加时间戳后缀） - **兼容扫描**：同时扫描扁平旧文件名（如 `rpiv/validation/acceptance-{feature-name}.yaml`），一并归档以覆盖历史版本 - 输出归档清单 4. **向用户报告**：输出交付物清单和关键信息摘要 ## 异常处理