Rpi Workflow

RPI Workflow: Research -> Plan -> Implement

A structured workflow for complex engineering tasks with Codex architectural review.

When to Invoke

• User says /rpi or "start RPI"
• User wants structured research before implementation
• User wants Codex to review a plan
• User needs to create research docs or implementation plans

File Structure

All artifacts go in docs/ at the project root:

docs/
├── research/
│   └── YYYY-MM-DD-topic.md        # Research findings
└── plans/
    ├── PLAN-<repo>-<task>.md      # Claude creates
    ├── FEEDBACK-<repo>-<task>.md  # Codex creates
    ├── IMPL-<repo>-<task>.md      # Claude creates after implementation
    └── VALIDATION-<repo>-<task>.md # Codex creates (optional)

Workflow Steps

Step 1: Research Phase

Launch parallel Explore agents to gather codebase understanding:

Task(subagent_type="Explore", prompt="Research how X works...")
Task(subagent_type="Explore", prompt="Research how Y connects to Z...")

Save findings to docs/research/YYYY-MM-DD-topic.md using the research template. For the template structure, see TEMPLATES.md.

Step 2: Plan Phase

Create docs/plans/PLAN-<repo>-<task>.md with:

• Goal (1-2 sentences)
• Key Files (path:line references)
• Problem (what's broken/missing)
• Proposed Solution (phased, with file-level changes)
• Success Criteria (checkboxes)
• Risks (numbered)
• Questions for Review (for Codex)

Step 3: Codex Review

Run from the project root:

codex exec --skip-git-repo-check "Read docs/plans/PLAN-<repo>-<task>.md and provide architectural feedback. Review the proposed solution, identify risks, suggest improvements. Write your feedback to docs/plans/FEEDBACK-<repo>-<task>.md"

Notes:

• Always use --skip-git-repo-check for non-git repos
• No --quiet flag exists
• Codex writes feedback autonomously to the FEEDBACK file

Step 4: Read & Incorporate Feedback

Read docs/plans/FEEDBACK-<repo>-<task>.md and present key findings to the user:

• Executive assessment
• Missing edge cases
• Better abstractions suggested
• Risks not identified
• Phase reordering suggestions
• Actionable recommendations

Step 5: Implement

Make the changes. Create docs/plans/IMPL-<repo>-<task>.md documenting:

• What was actually changed (with path:line refs)
• Deviations from plan and why
• Test results
• Remaining work

Step 6: Validate (Optional)

codex exec --skip-git-repo-check "Read docs/plans/IMPL-<repo>-<task>.md and validate the implementation. Check if success criteria are met, identify any issues. Write your validation to docs/plans/VALIDATION-<repo>-<task>.md"

Guidelines

• Research first: Never plan without understanding the codebase
• Parallel agents: Use multiple Explore agents simultaneously
• Compact findings: Use file:line references, not full code dumps
• Questions for Codex: Always include 3-5 specific architectural questions
• Parity checks: Before deleting old code, run side-by-side comparisons
• Phase boundaries: Each phase should be independently mergeable