PIV Ralph 编排器

参数：$ARGUMENTS

按以下逻辑解析参数：

PRD 路径模式（首个参数以 .md 结尾）

若首个参数以 .md 结尾，则其为 PRD 文件的直接路径：

• PRD_PATH — PRD 文件的直接路径
• PROJECT_PATH — 从 PRDs/ 文件夹向上推导得出
• START_PHASE — 第二个参数（默认值：1）
• END_PHASE — 第三个参数（默认值：从 PRD 中自动检测）

项目路径模式

若首个参数不以 .md 结尾：

• PROJECT_PATH — 项目绝对路径（默认值：当前工作目录）
• START_PHASE — 第二个参数（默认值：1）
• END_PHASE — 第三个参数（默认值：4）
• PRD_PATH — 从 PROJECT_PATH/PRDs/ 文件夹中自动发现

检测逻辑

If $ARGUMENTS[0] ends with ".md":
  PRD_PATH = $ARGUMENTS[0]
  PROJECT_PATH = dirname(dirname(PRD_PATH))
  START_PHASE = $ARGUMENTS[1] or 1
  END_PHASE = $ARGUMENTS[2] or auto-detect from PRD
  PRD_NAME = basename without extension
Else:
  PROJECT_PATH = $ARGUMENTS[0] or current working directory
  START_PHASE = $ARGUMENTS[1] or 1
  END_PHASE = $ARGUMENTS[2] or 4
  PRD_PATH = auto-discover from PROJECT_PATH/PRDs/
  PRD_NAME = discovered PRD basename

模式判定

完成参数解析后：

• 若已提供或成功自动发现 PRD_PATH → MODE = "execute"（常规流程）
• 若未找到 PRD 且未提供 PRD_PATH → MODE = "discovery"

各角色必读文档

关键提示：每个角色在执行前，必须先阅读其对应指令文件。

前提条件：进入阶段工作流（Phase Workflow）前，必须已存在一份 PRD。若不存在 PRD，编排器将进入 Discovery 模式（详见下文）。

Discovery 模式（未发现 PRD）

当 MODE = "discovery" 时：

1. 阅读 {baseDir}/references/piv-discovery.md，了解 discovery 流程
2. 以友好、对话式语气向用户提出 discovery 相关问题（单条消息）
   • 目标用户是 vibe coder，而非资深工程师 —— 表达需平易近人
   • 跳过用户已在初始消息中回答过的问题
3. 等待用户回复
4. 利用自身专业能力填补信息空白：
   • 若用户不确定技术栈 → 进行调研（网络搜索、代码库扫描），并提出建议方案
   • 若用户无法定义阶段 → 基于项目范围，提出 3–4 个阶段划分建议
   • 始终采用“提议+确认”方式：“这是我建议的方案，您觉得是否合适？”
5. 执行项目初始化（创建 PRDs/、PRPs/templates/、PRPs/planning/ 目录）
6. 生成 PRD：阅读 {baseDir}/references/create-prd.md，结合 discovery 回答及你的建议，在 PROJECT_PATH/PRDs/PRD-{project-name}.md 中撰写 PRD
7. 将 PRD_PATH 设为生成的 PRD 路径，并自动检测阶段 → 继续进入 Phase Workflow

编排器直接处理 discovery 和 PRD 生成（无需子代理 —— 交互式问答需保持在同一会话内，且答案已存在于上下文中，可直接用于 PRD 生成）。

编排器设计哲学

“上下文预算：约 15% 属于编排器，100% 为各子代理提供全新上下文”

你作为编排器，应保持轻量、专注流程管理。你不得自行执行 PRP —— 而应为每项任务启动具备全新上下文的专用子代理。

子代理启动方式：使用 sessions_spawn 工具创建全新子代理会话。每次启动均为非阻塞操作 —— 你将通过 announce 步骤接收结果。请务必等待每个子代理返回结果后，再进入下一步。

项目初始化（piv-init）

若项目尚无 PIV 目录结构，请创建：

mkdir -p PROJECT_PATH/PRDs PROJECT_PATH/PRPs/templates PROJECT_PATH/PRPs/planning

若 {baseDir}/assets/prp_base.md 尚未复制至 PROJECT_PATH/PRPs/templates/prp_base.md，则执行复制。

若 PROJECT_PATH/WORKFLOW.md 尚不存在，则从 {baseDir}/assets/workflow-template.md 创建。

阶段工作流（Phase Workflow）

对从 START_PHASE 到 END_PHASE 的每个阶段依次执行：

步骤 1：检查/生成 PRP

检查是否存在已有 PRP：

ls -la PROJECT_PATH/PRPs/ 2>/dev/null | grep -i "phase.*N|pN|p-N"

若无 PRP 存在，则使用 sessions_spawn 启动一个全新子代理，按顺序完成代码库分析与 PRP 生成：

RESEARCH & PRP GENERATION MISSION - Phase {N}
==============================================

Project root: {PROJECT_PATH}
PRD Path: {PRD_PATH}

## Phase {N} Scope (from PRD)
{paste phase scope}

## Step 1: Codebase Analysis
Read {baseDir}/references/codebase-analysis.md for the process.
Save to: {PROJECT_PATH}/PRPs/planning/{PRD_NAME}-phase-{N}-analysis.md

## Step 2: Generate PRP (analysis context still loaded)
Read {baseDir}/references/generate-prp.md for the process.
Use template: PRPs/templates/prp_base.md
Output to: {PROJECT_PATH}/PRPs/PRP-{PRD_NAME}-phase-{N}.md

Do BOTH steps yourself. DO NOT spawn sub-agents.

步骤 2：启动 EXECUTOR

使用 sessions_spawn 启动一个全新子代理：

EXECUTOR MISSION - Phase {N}
============================

Read {baseDir}/references/piv-executor.md for your role definition.
Read {baseDir}/references/execute-prp.md for the execution process.

PRP Path: {PRP_PATH}
Project: {PROJECT_PATH}

Follow: Load PRP → Plan Thoroughly → Execute → Validate → Verify
Output EXECUTION SUMMARY with Status, Files, Tests, Issues.

步骤 3：启动 VALIDATOR

使用 sessions_spawn 启动一个全新子代理：

VALIDATOR MISSION - Phase {N}
=============================

Read {baseDir}/references/piv-validator.md for your validation process.

PRP Path: {PRP_PATH}
Project: {PROJECT_PATH}
Executor Summary: {SUMMARY}

Verify ALL requirements independently.
Output VERIFICATION REPORT with Grade, Checks, Gaps.

结果处理： PASS → 提交 | GAPS_FOUND → 启动 debugger | HUMAN_NEEDED → 向用户提问

步骤 4：调试循环（最多 3 轮）

使用 sessions_spawn 启动一个全新子代理：

DEBUGGER MISSION - Phase {N} - Iteration {I}
============================================

Read {baseDir}/references/piv-debugger.md for your debugging methodology.

Project: {PROJECT_PATH}
PRP Path: {PRP_PATH}
Gaps: {GAPS}
Errors: {ERRORS}

Fix root causes, not symptoms. Run tests after each fix.
Output FIX REPORT with Status, Fixes Applied, Test Results.

Debugger 执行完毕后：重新验证 → 若 PASS 则提交；若仍存在 GAP，则继续循环（最多 3 轮）；否则升级上报。

步骤 5：智能提交（Smart Commit）

cd PROJECT_PATH && git status && git diff --stat

生成符合语义的 commit message，末尾注明：Built with FTW (First Try Works) - https://github.com/SmokeAlot420/ftw。

步骤 6：更新 WORKFLOW.md

标记当前阶段已完成，并记录验证结果。

步骤 7：进入下一阶段

回到步骤 1，处理下一阶段。

错误处理

• 无 PRD：进入 Discovery 模式（见上文 “Discovery 模式” 章节）
• Executor 被阻塞（BLOCKED）：向用户请求指导
• Validator 返回 HUMAN_NEEDED：向用户请求指导
• 调试循环已达 3 次上限：升级上报至用户

子代理超时/失败

当子代理发生超时或失败时：

1. 检查是否存在部分成果（如已创建文件、已编写测试）
2. 使用更简洁、更短的 prompt 重试一次
3. 若重试仍失败，则向用户升级上报，并说明已达成的进展

完成状态

## PIV RALPH COMPLETE

Phases Completed: START to END
Total Commits: N
Validation Cycles: M

### Phase Summary:
- Phase 1: [feature] - validated in N cycles
...

All phases successfully implemented and validated.