| name | piv |
| description | Ralph PIV — Plan-Implement-Validate. Solo AI dev workflow with deep analysis, context-rich plans, and independent validation. Spawns specialized sub-agents for execution, validation, and debugging. Triggers on: piv, build, implement, execute. |
| disable-model-invocation | true |
| allowed-tools | Task, TaskCreate, TaskUpdate, TaskList, Read, Write, Bash, Glob, Grep |
| argument-hint | [PRD_PATH|PROJECT_PATH] [START_PHASE] [END_PHASE] |
Ralph PIV Orchestrator
Plan-Implement-Validate
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
Mode Detection
After parsing arguments:
- If PRD_PATH was provided or auto-discovered → MODE = "execute"
- If no PRD found → MODE = "discovery"
Auto-Detect Phases from PRD
When PRD_PATH is specified, scan the PRD for phase sections:
- Look for:
## Phase N:, ### Phase N:, **Phase N:**, Phase N:
- Set END_PHASE to highest phase found (if not specified)
Resolve Ralph PIV Plugin Directory
Before proceeding, determine the absolute path to the Ralph PIV plugin:
find /home -maxdepth 4 -name "plugin.json" -path "*/piv/.claude-plugin/*" 2>/dev/null | head -1 | sed 's|/.claude-plugin/plugin.json||'
Store the result as PIV_DIR. All reference docs and templates are under this directory.
Verify: PIV_DIR/skills/piv/assets/prp_base.md should exist.
Required Reading by Role
CRITICAL: Each role MUST read their instruction files before acting.
| Role | Instructions |
|---|
| Discovery (no PRD) | Read {PIV_DIR}/skills/piv/references/piv-discovery.md |
| PRD Creation | Read {PIV_DIR}/skills/piv/references/create-prd.md |
| PRP Generation | Read {PIV_DIR}/skills/piv/references/generate-prp.md |
| Executor | Read {PIV_DIR}/skills/piv/references/execute-prp.md |
DO NOT wing it. Follow the established processes.
Prerequisite: A PRD must exist before entering the Phase Workflow. If no PRD exists, enter Discovery Mode.
Discovery Mode (No PRD Found)
When MODE = "discovery":
- Read {PIV_DIR}/skills/piv/references/piv-discovery.md for the discovery process
- Present discovery questions to the user in a friendly, conversational tone
- Target audience is vibe coders — keep it approachable
- Skip questions the user already answered
- Wait for user answers
- Fill gaps with your expertise:
- If user doesn't know tech stack → research and PROPOSE one
- If user can't define phases → propose 3-4 phases based on scope
- Always propose-and-confirm: "Here's what I'd suggest — does this sound right?"
- Run project setup:
- Create directories: PRDs/, PRPs/templates/, PRPs/planning/
- Copy PRP template:
cp {PIV_DIR}/skills/piv/assets/prp_base.md {PROJECT_PATH}/PRPs/templates/prp_base.md
- Generate PRD: Read {PIV_DIR}/skills/piv/references/create-prd.md, write to PROJECT_PATH/PRDs/PRD-{project-name}.md
- Set PRD_PATH to the generated PRD, auto-detect phases → continue to Phase Workflow
The orchestrator handles discovery and PRD generation directly (no sub-agent needed).
Orchestrator Philosophy
"Context budget: ~15% orchestrator, 100% fresh per sub-agent"
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.
Phase Workflow
For each phase from START_PHASE to END_PHASE:
Step 1: Check/Generate PRP
Step 1a: Check for existing PRP
ls -la PROJECT_PATH/PRPs/ 2>/dev/null | grep -i "phase.*N\|pN\|p-N"
If a PRP already exists for this phase, skip to Step 2.
Step 1b: Spawn Fresh Research Agent for PRP Generation
CRITICAL: Do NOT generate the PRP yourself. Spawn a FRESH sub-agent.
Before spawning, the orchestrator must:
- Read the PRD at PRD_PATH
- Find the Phase N section
- Extract the phase scope (title, deliverables, validation criteria)
- Pass this extracted scope to the fresh agent
Spawn a general-purpose sub-agent with this prompt:
RESEARCH & PRP GENERATION MISSION - Phase {N}
==============================================
You are generating a PRP for Phase {N}. You have fresh context — use it wisely.
Project root: {PROJECT_PATH}
PRD Path: {PRD_PATH}
## Phase {N} Scope (from PRD)
{paste phase title, deliverables, and validation criteria}
## Step 1: Codebase Analysis
Read the codebase analysis process doc at: {PIV_DIR}/skills/piv/references/codebase-analysis.md
Follow it fully. Run deep codebase analysis for: {phase feature description}
Save analysis to: {PROJECT_PATH}/PRPs/planning/{PRD_NAME}-phase-{N}-analysis.md
## Step 2: Generate PRP (analysis context still loaded)
Read the PRP generation process doc at: {PIV_DIR}/skills/piv/references/generate-prp.md
Read the PRP template at: {PIV_DIR}/skills/piv/assets/prp_base.md
Follow the process doc fully. Use the template structure.
You already have the codebase analysis in your context — use it directly.
DO NOT spawn a sub-agent for this. You do it yourself.
Output PRP to: {PROJECT_PATH}/PRPs/PRP-{PRD_NAME}-phase-{N}.md
## Critical Rules
- Do BOTH steps yourself in sequence
- Your analysis context feeds directly into PRP quality
- Follow the full generate-prp process (template, quality gates, info density)
- The PRP template is at: {PIV_DIR}/skills/piv/assets/prp_base.md
- DO NOT spawn sub-agents for either step
Wait for the research agent to complete before proceeding.
Step 2: Spawn Executor Sub-Agent
Use the Task tool with subagent_type: "piv-executor":
EXECUTOR MISSION - Phase {N}
============================
Read the PRP execution process doc at: {PIV_DIR}/skills/piv/references/execute-prp.md
PRP Path: {PRP_PATH}
Project: {PROJECT_PATH}
Follow: Load PRP → Think Deeply & Plan → Execute → Validate → Verify
Output EXECUTION SUMMARY with Status, Files, Tests, Issues.
Wait for executor to complete before proceeding.
Step 3: Spawn Validator Sub-Agent
Use the Task tool with subagent_type: "piv-validator":
VALIDATOR MISSION - Phase {N}
=============================
PRP Path: {PRP_PATH}
Project: {PROJECT_PATH}
Executor Summary:
{paste EXECUTION SUMMARY here}
Verify ALL requirements independently. Don't trust executor claims.
Check every file, every test, every requirement in the PRP.
Output VERIFICATION REPORT with Grade (PASS/GAPS_FOUND/HUMAN_NEEDED), Checks, Gaps.
Process validator result:
PASS → Proceed to Step 5 (commit)GAPS_FOUND → Proceed to Step 4 (debug)HUMAN_NEEDED → Ask user for guidance
Step 4: Debug Loop (Max 3 iterations)
Spawn debugger sub-agent using subagent_type: "piv-debugger":
DEBUGGER MISSION - Phase {N} - Iteration {I}
============================================
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 fixes:
- Re-run validator
- If PASS → proceed to commit
- If GAPS_FOUND again → debug again (up to 3 total)
- After 3 iterations → escalate to user
Step 5: Smart Commit (Orchestrator does this)
After validation passes:
cd PROJECT_PATH
git status
git diff --stat
Create semantic commit:
- Format:
feat/fix/refactor(scope): description
- Add:
Built with Ralph PIV - https://github.com/SmokeAlot420/ralph-piv
Step 6: Update Progress
Update PROJECT_PATH/WORKFLOW.md:
- Mark phase N as complete
- Note validation results
- Record any issues or observations
Step 7: Next Phase
Increment phase counter. If more phases remain, loop back to Step 1.
Error Handling
No PRD Found
Enter Discovery Mode (see above).
Executor Returns BLOCKED
Ask user: "Executor blocked on phase N. Issue: [description]. How should we proceed?"
Validator Returns HUMAN_NEEDED
Ask user: "Validator needs guidance on phase N. Question: [details]. Please advise."
3 Debug Cycles Exhausted
Ask user: "Phase N failed validation after 3 fix attempts. Persistent issues: [list]. Need your guidance."
Completion
When all phases are complete, output:
## RALPH PIV COMPLETE
Phases Completed: START to END
Total Commits: N
Validation Cycles: M
### Phase Summary:
- Phase 1: [feature] - validated in N cycles
- Phase 2: [feature] - validated in N cycles
...
All phases successfully implemented and validated.
Visual Workflow
┌──────────────────────────────────────────────────────────────┐
│ RALPH PIV ORCHESTRATOR │
│ Plan-Implement-Validate │
├──────────────────────────────────────────────────────────────┤
│ IF NO PRD FOUND: │
│ a. Ask discovery questions (piv-discovery.md) │
│ b. Generate PRD from answers (create-prd.md) │
│ c. Set PRD_PATH, auto-detect phases │
│ │
│ FOR EACH PHASE (START_PHASE to END_PHASE): │
│ a. Check if PRP exists │
│ b. If not → spawn RESEARCH AGENT (analysis + PRP gen) │
│ c. Spawn EXECUTOR → returns EXECUTION SUMMARY │
│ d. Spawn VALIDATOR → returns PASS/GAPS_FOUND/HUMAN_NEEDED │
│ e. If GAPS_FOUND → Spawn DEBUGGER (max 3x) │
│ f. Commit on PASS │
│ g. Update WORKFLOW.md │
│ h. Next phase │
└──────────────────────────────────────────────────────────────┘
