介绍
# 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 创建 | 阅读 {baseDir}/references/create-prd.md | | PRP 生成 | 阅读 {baseDir}/references/generate-prp.md | | 代码库分析 | 阅读 {baseDir}/references/codebase-analysis.md | | 执行器 | 阅读 {baseDir}/references/piv-executor.md + {baseDir}/references/execute-prp.md | | 验证器 | 阅读 {baseDir}/references/piv-validator.md | | 调试器 | 阅读 {baseDir}/references/piv-debugger.md |
**前置条件：** 必须存在一个 PRD。如果未找到，请告知用户先创建一个。
---
## 编排器理念
> “上下文预算：编排器约占 15%，每个子代理 100% 全新”
你是 **编排器**。你保持精简并管理工作流程。你**不**亲自执行 PRP——你为每个任务生成带有全新上下文的专业子代理。
**子代理生成：** 使用 `sessions_spawn` 工具创建全新的子代理会话。每次生成都是非阻塞的——你将通过公告步骤接收结果。在进入下一步之前等待每个代理的结果。
---
## 项目设置 (piv-init)
如果项目没有 PIV 目录，请创建它们： ```bash mkdir -p PROJECT_PATH/PRDs PROJECT_PATH/PRPs/templates PROJECT_PATH/PRPs/planning ``` 如果 `PROJECT_PATH/PRPs/templates/prp_base.md` 不存在，请将 `{baseDir}/assets/prp_base.md` 复制到该处。 如果 `PROJECT_PATH/WORKFLOW.md` 不存在，请从 `{baseDir}/assets/workflow-template.md` 创建它。
---
## 阶段工作流
对于从 START_PHASE 到 END_PHASE 的每个阶段：
### 步骤 1：检查/生成 PRP
检查现有的 PRP： ```bash 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 → 调试器 | 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. ```
调试器运行后：重新验证 → PASS（提交）或 循环（最多 3 次）或 升级处理。
### 步骤 5：智能提交
```bash cd PROJECT_PATH && git status && git diff --stat ```
使用 `Built with FTW (First Try Works) - https://github.com/SmokeAlot420/ftw` 创建语义化提交。
### 步骤 6：更新 WORKFLOW.md
标记阶段完成，记录验证结果。
### 步骤 7：下一阶段
循环回步骤 1 进入下一阶段。
---
## 错误处理
- **没有 PRD**：告知用户先创建一个 - **执行器被阻塞 (Executor BLOCKED)**：向用户寻求指导 - **验证器需要人工 (Validator HUMAN_NEEDED)**：向用户寻求指导 - **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. ```