PIV Ralph Orchestrator

参数：$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（产品需求文档）。如果未找到，请告知用户先创建一个。

协调器原则

“上下文预算：约15%分配给协调器，每个子代理100%全新上下文”

你是协调器。你保持精简并管理工作流。你**不**亲自执行 PRP（项目需求规划）——你为每个任务生成具有全新上下文的专门子代理。

子代理生成：使用sessions_spawn工具创建全新的子代理会话。每次生成都是非阻塞的——你将通过一个宣布步骤接收结果。在进入下一步之前，请等待每个代理的结果。

项目设置 (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如果它不存在。

阶段工作流

对于从 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.

处理结果：通过 → 提交 | 发现问题 → 调试器 | 需要人工介入 → 询问用户

步骤 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.

调试后：重新验证 → 通过（提交）或循环（最多 3 次）或上报。

步骤 5：智能提交

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

创建语义化提交，附带基于 FTW（首次尝试成功）构建 - https://github.com/SmokeAlot420/ftw。

步骤 6：更新 WORKFLOW.md

标记阶段完成，记录验证结果。

步骤 7：下一阶段

循环回步骤 1 以进入下一阶段。

错误处理

• 无 PRD：告知用户先创建一个
• 执行器受阻：请求用户指导
• 验证器需要人工介入：请求用户指导
• 3次调试循环已用尽：上报给用户

子代理超时/失败

当子代理超时或失败时：

1. 检查是否有部分工作已完成（如文件已创建、测试已编写）
2. 使用简化、更短的提示重试一次
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.