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。

前置初始化

首次执行前调用（幂等，已存在则静默跳过）：

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），全程无需用户介入。

团队架构

执行流程

步骤 1：提取需求上下文

确定功能名称（从 $ARGUMENTS 或对话推断，kebab-case 格式）。

如果 $ARGUMENTS 是已存在的文件路径（PRD 或需求文档），直接使用该文件作为需求输入，跳到步骤 2。

否则，从对话上下文和 $ARGUMENTS 提取需求，保存到 rpiv/brainstorm-summary-{feature-name}.md：

---
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 信息对以下"架构性声明"做出决策：

强制动作：收到上述任一类型的 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. 向用户报告：输出交付物清单和关键信息摘要

异常处理

规模自适应

根据项目规模调整团队配置：

• 小型（预估 ≤3 文件变更）：3 agent — Leader + Architect(兼 Dev) + QA
• 中型（4-10 文件）：4 agent — Leader + Architect + Dev-1 + QA
• 大型（>10 文件或多模块）：5-6 agent — 完整团队配置

在步骤 1 完成后，根据需求复杂度判断规模，选择合适的团队配置。

降级路径（named spawn 受限时）：若遇到 named spawn 受限，按以下顺序降级——① Leader 兼任 Dev：plan 已机械化到代码片段级时，中大型也可由 Leader 直接实现 + named Architect/QA 审查；② Dev/Research 改用 omit-name background subagent：Agent 不传 name、run_in_background: true，完成即返回结果，不中途双向通信。named teammate 仅保留给需要全程双向协作的 Architect/QA。

备注

• 全程使用中文进行文档和沟通
• 所有产出文件遵循 RPIV 的 frontmatter 规范（status/created_at/updated_at/archived_at）
• agent 之间关键指令单独发送短消息，不要混在长文本中
• Research agent 是临时角色，Plan 完成后关闭以节省资源
• 如果项目已有 PRD 或 Plan，可跳过对应阶段，从现有文件继续