piv

# PIV Ralph Orchestrator ## 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 file - `PROJECT_PATH` - Derived by going up from PRDs/ folder - `START_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 references/create-prd.md | | PRP Generation | Read references/generate-prp.md | | Codebase Analysis | Read references/codebase-analysis.md | | Executor | Read references/piv-executor.md + references/execute-prp.md | | Validator | Read references/piv-validator.md | | Debugger | Read 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: ```bash mkdir -p PROJECT_PATH/PRDs PROJECT_PATH/PRPs/templates PROJECT_PATH/PRPs/planning ``` Copy `assets/prp_base.md` to `PROJECT_PATH/PRPs/templates/prp_base.md` if it doesn't exist. Create `PROJECT_PATH/WORKFLOW.md` from `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: ```bash 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 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 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. ``` ### Step 2: Spawn EXECUTOR Spawn a fresh sub-agent using `sessions_spawn`: ``` EXECUTOR MISSION - Phase {N} ============================ Read references/piv-executor.md for your role definition. Read references/execute-prp.md for the execution process. PRP Path: {PRP_PATH} Project: {PROJECT_PATH} Follow: Load PRP → ULTRATHINK → 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 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 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 ```bash cd PROJECT_PATH && git status && git diff --stat ``` Create semantic commit with `Co-Authored-By: Claude <noreply@anthropic.com>`. ### 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 --- ## Completion ``` ## 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. ```