参数：$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/ 文件夹自动发现
检测逻辑
如果 $ARGUMENTS[0] 以 ".md" 结尾：
PRD_PATH = $ARGUMENTS[0]
PROJECT_PATH = dirname(dirname(PRD_PATH))
START_PHASE = $ARGUMENTS[1] 或 1
END_PHASE = $ARGUMENTS[2] 或从 PRD 自动检测
PRD_NAME = 不含扩展名的基本名称
否则：
PROJECT_PATH = $ARGUMENTS[0] 或当前工作目录
START_PHASE = $ARGUMENTS[1] 或 1
END_PHASE = $ARGUMENTS[2] 或 4
PRD_PATH = 从 PROJECT_PATH/PRDs/ 自动发现
PRD_NAME = 发现的 PRD 基本名称
按角色必读
关键：每个角色在行动前必须阅读其指令文件。
| 角色 | 指令 |
|---|
| 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 目录，创建它们：
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。
如果不存在，从
{baseDir}/assets/workflow-template.md 创建
PROJECT_PATH/WORKFLOW.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 生成：
研究 & PRP 生成任务 - 阶段 {N}
==============================================项目根目录：{PROJECT_PATH}
PRD 路径：{PRD_PATH}
阶段 {N} 范围（来自 PRD）
{粘贴阶段范围}步骤 1：代码库分析
阅读 {baseDir}/references/codebase-analysis.md 了解流程。
保存到：{PROJECT_PATH}/PRPs/planning/{PRD_NAME}-phase-{N}-analysis.md步骤 2：生成 PRP（分析上下文仍已加载）
阅读 {baseDir}/references/generate-prp.md 了解流程。
使用模板：PRPs/templates/prp_base.md
输出到：{PROJECT_PATH}/PRPs/PRP-{PRD_NAME}-phase-{N}.md两个步骤都自己做。不要生成子代理。
步骤 2：生成执行器
使用 sessions_spawn 生成新的子代理：
执行器任务 - 阶段 {N}
============================阅读 {baseDir}/references/piv-executor.md 了解角色定义。
阅读 {baseDir}/references/execute-prp.md 了解执行流程。
PRP 路径：{PRP_PATH}
项目：{PROJECT_PATH}
遵循：加载 PRP → 充分规划 → 执行 → 验证 → 确认
输出包含状态、文件、测试、问题的执行摘要。
步骤 3：生成验证器
使用 sessions_spawn 生成新的子代理：
验证器任务 - 阶段 {N}
=============================阅读 {baseDir}/references/piv-validator.md 了解验证流程。
PRP 路径：{PRP_PATH}
项目：{PROJECT_PATH}
执行器摘要：{SUMMARY}
独立验证所有需求。
输出包含等级、检查项、差距的验证报告。
处理结果： 通过 → 提交 | 发现差距 → 调试器 | 需要人工 → 询问用户
步骤 4：调试循环（最多 3 次迭代）
使用 sessions_spawn 生成新的子代理：
调试器任务 - 阶段 {N} - 迭代 {I}
============================================阅读 {baseDir}/references/piv-debugger.md 了解调试方法论。
项目：{PROJECT_PATH}
PRP 路径：{PRP_PATH}
差距：{GAPS}
错误：{ERRORS}
修复根本原因，而非症状。每次修复后运行测试。
输出包含状态、已应用修复、测试结果的修复报告。
调试后：重新验证 → 通过（提交）或循环（最多 3 次）或升级。
步骤 5：智能提交
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：告诉用户先创建
- 执行器阻塞：向用户寻求指导
- 验证器需要人工：向用户寻求指导
- 3 次调试循环耗尽：升级给用户
子代理超时/失败
当子代理超时或失败时：
- 检查部分工作（已创建的文件、已编写的测试）
- 用简化的、更短的提示重试一次
- 如果重试失败，向用户报告已完成的工作
完成
## PIV RALPH 完成已完成阶段：START 到 END
总提交数：N
验证循环数：M
阶段摘要：
...所有阶段已成功实施并验证。
Arguments: $ARGUMENTS
Parse arguments using this logic:
PRD Path Mode (first argument ends with .md)
If the first argument ends with .md, it's a direct path to a PRD file:
PRD_PATH - Direct path to the PRD filePROJECT_PATH - Derived by going up from PRDs/ folderSTART_PHASE - Second argument (default: 1)END_PHASE - Third argument (default: auto-detect from PRD)
Project Path Mode
If the first argument does NOT end with .md:
PROJECT_PATH - Absolute path to project (default: current working directory)START_PHASE - Second argument (default: 1)END_PHASE - Third argument (default: 4)PRD_PATH - Auto-discover from PROJECT_PATH/PRDs/ folder
Detection Logic
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
Required Reading by Role
CRITICAL: Each role MUST read their instruction files before acting.
| Role | Instructions |
|---|
| PRD Creation | Read {baseDir}/references/create-prd.md |
| PRP Generation | Read {baseDir}/references/generate-prp.md |
| Codebase Analysis | Read {baseDir}/references/codebase-analysis.md |
| Executor | Read {baseDir}/references/piv-executor.md + {baseDir}/references/execute-prp.md |
| Validator | Read {baseDir}/references/piv-validator.md |
| Debugger | Read {baseDir}/references/piv-debugger.md |
Prerequisite: A PRD must exist. If none found, tell user to create one first.
Orchestrator Philosophy
"Context budget: ~15% orchestrator, 100% fresh per subagent"
You are the orchestrator. You stay lean and manage workflow. You DO NOT execute PRPs yourself - you spawn specialized sub-agents with fresh context for each task.
Sub-agent spawning: Use the sessions_spawn tool to create fresh sub-agent sessions. Each spawn is non-blocking — you'll receive results via an announce step. Wait for each agent's results before proceeding to the next step.
Project Setup (piv-init)
If the project doesn't have PIV directories, create them:
mkdir -p PROJECT_PATH/PRDs PROJECT_PATH/PRPs/templates PROJECT_PATH/PRPs/planning
Copy
{baseDir}/assets/prp_base.md to
PROJECT_PATH/PRPs/templates/prp_base.md if it doesn't exist.
Create
PROJECT_PATH/WORKFLOW.md from
{baseDir}/assets/workflow-template.md if it doesn't exist.
Phase Workflow
For each phase from START_PHASE to END_PHASE:
Step 1: Check/Generate PRP
Check for existing PRP:
ls -la PROJECT_PATH/PRPs/ 2>/dev/null | grep -i "phase.*N\|pN\|p-N"
If no PRP exists, spawn a fresh sub-agent using sessions_spawn to do both codebase analysis and PRP generation in sequence:
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.mdStep 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}.mdDo BOTH steps yourself. DO NOT spawn sub-agents.
Step 2: Spawn EXECUTOR
Spawn a fresh sub-agent using 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.
Step 3: Spawn VALIDATOR
Spawn a fresh sub-agent using 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.
Process result: PASS → commit | GAPS_FOUND → debugger | HUMAN_NEEDED → ask user
Step 4: Debug Loop (Max 3 iterations)
Spawn a fresh sub-agent using 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.
After debugger: re-validate → PASS (commit) or loop (max 3) or escalate.
Step 5: Smart Commit
cd PROJECT_PATH && git status && git diff --stat
Create semantic commit with Built with FTW (First Try Works) - https://github.com/SmokeAlot420/ftw.
Step 6: Update WORKFLOW.md
Mark phase complete, note validation results.
Step 7: Next Phase
Loop back to Step 1 for next phase.
Error Handling
- No PRD: Tell user to create one first
- Executor BLOCKED: Ask user for guidance
- Validator HUMAN_NEEDED: Ask user for guidance
- 3 debug cycles exhausted: Escalate to user
Sub-Agent Timeout/Failure
When a sub-agent times out or fails:
- Check for partial work (files created, tests written)
- Retry once with a simplified, shorter prompt
- If retry fails, escalate to user with what was accomplished
Completion
## PIV RALPH COMPLETEPhases 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.
by