RPI Workflow - Claude Code Best Practice

Overview

RPI = Research → Plan → Implement A systematic development workflow with validation gates at each phase. RPI prevents wasted effort on non-viable features by validating product-market fit and technical feasibility before committing to implementation.

This workflow is ideal for new features that require strategic alignment, technical discovery, and phased execution.

Why RPI?

Traditional development often jumps straight to implementation, discovering issues late:

❌ Traditional Approach

Start coding immediately
Discover technical blockers mid-implementation
Realize feature doesn’t align with product vision
Waste significant development time
No clear go/no-go decision point

✅ RPI Workflow

Validate viability first (Research)
Plan architecture and phases (Plan)
Execute with validation gates (Implement)
Clear go/no-go decision at each stage
Constitutional alignment throughout

Workflow Stages

Describe

Goal: Create initial feature descriptionProcess: Use plan mode to generate feature description in rpi/{feature-slug}/REQUEST.mdOutput: REQUEST.md with feature requirements and goals

Research

Goal: GO/NO-GO decision gateCommand: /rpi:research rpi/{feature-slug}/REQUEST.mdAgents Used:

requirement-parser
product-manager
Explore (code discovery)
senior-software-engineer
technical-cto-advisor
documentation-analyst-writer

Output: research/RESEARCH.md with viability assessment and recommendation

Plan

Goal: Create comprehensive planning documentationCommand: /rpi:plan {feature-slug}Agents Used:

senior-software-engineer (architecture)
product-manager (requirements)
ux-designer (user experience)
documentation-analyst-writer (synthesis)

Outputs:

plan/pm.md - Product requirements
plan/ux.md - UX design
plan/eng.md - Technical specification
plan/PLAN.md - Phased implementation roadmap

Implement

Goal: Execute phased implementation with validation gatesCommand: /rpi:implement {feature-slug}Agents Used:

Explore (pre-implementation discovery)
senior-software-engineer (implementation)
code-reviewer (quality gates)
constitutional-validator (compliance)

Output: implement/IMPLEMENT.md with phase validation records

Example: OAuth2 Authentication

Let’s walk through implementing OAuth2 authentication using RPI.

Step 1: Describe

User: "Add OAuth2 authentication with Google and GitHub providers"

Action: Copy plan to rpi/oauth2-authentication/REQUEST.md

Step 2: Research

/rpi:research rpi/oauth2-authentication/REQUEST.md

Research verdict: GO - proceed to planning

Step 3: Plan

/rpi:plan oauth2-authentication

PLAN.md Overview
eng.md Excerpt

# Implementation Plan

## Phase 1: Backend Foundation (5 tasks)
- [ ] Add OAuth provider configs
- [ ] Implement Passport strategies
- [ ] Create token storage
- [ ] Add refresh token logic
- [ ] Write unit tests

## Phase 2: Frontend Integration (6 tasks)
- [ ] Create OAuth login buttons
- [ ] Implement OAuth callback handlers
- [ ] Add provider selection UI
- [ ] Handle OAuth errors
- [ ] Add loading states
- [ ] Write integration tests

## Phase 3: Testing & Polish (4 tasks)
- [ ] End-to-end OAuth flows
- [ ] Security audit
- [ ] Documentation
- [ ] Staging deployment

Step 4: Implement

/rpi:implement oauth2-authentication

Each phase includes a User Validation Gate - you must explicitly approve before proceeding to the next phase.

Complete Feature

After all phases pass validation:

## Implementation Complete

### Summary
- Feature: oauth2-authentication
- Phases: 3 of 3 completed
- Files Modified: 18 files (+1,247 -89 lines)
- Tests Added: 47 unit, 12 integration, 6 e2e
- All phases: PASS ✓

### Next Steps
1. Create PR: [oauth2-authentication] Add Google and GitHub OAuth
2. Deploy to staging
3. QA validation
4. Production deployment

Feature Folder Structure

All RPI work is organized in rpi/{feature-slug}/:

rpi/oauth2-authentication/
├── REQUEST.md              # Step 1: Initial description
├── research/
│   └── RESEARCH.md         # Step 2: GO/NO-GO analysis
├── plan/
│   ├── PLAN.md             # Step 3: Implementation roadmap
│   ├── pm.md               # Product requirements
│   ├── ux.md               # UX design
│   └── eng.md              # Technical spec
└── implement/
    └── IMPLEMENT.md        # Step 4: Phase validation records

This structure creates a complete audit trail from initial idea to shipped feature.

Commands Reference

/rpi:research <feature-slug>

Purpose: Research and validate feature viabilityInput: rpi/{feature-slug}/REQUEST.mdPhases:

Parse requirements (requirement-parser)
Product analysis (product-manager)
Code discovery (Explore)
Technical feasibility (senior-software-engineer)
Strategic assessment (technical-cto-advisor)
Generate report (documentation-analyst-writer)

Output: research/RESEARCH.md with GO/NO-GO recommendationVerdicts:

GO: Proceed to planning
CONDITIONAL GO: Address conditions first
DEFER: Revisit later
NO-GO: Archive or explore alternatives

/rpi:plan <feature-slug>

Purpose: Create comprehensive planning documentationPrerequisites: Research completed with GO recommendationPhases:

Load research findings
Analyze requirements and architecture
Design architecture (senior-software-engineer)
Break down into phases and tasks
Generate documentation

Outputs:

plan/pm.md - Product requirements and user stories
plan/ux.md - User experience design
plan/eng.md - Technical specification
plan/PLAN.md - Phased implementation roadmap

/rpi:implement <feature-slug> [--phase N]

Purpose: Execute phased implementation with validation gatesPrerequisites: Planning completedPer-Phase Flow:

Code discovery (Explore agent)
Implementation (senior-software-engineer)
Self-validation (linting, tests, build)
Code review (code-reviewer agent)
User validation gate ⏸️ STOP for approval
Documentation update

Flags:

--phase N: Execute specific phase
--validate-only: Validate without implementing

Output: implement/IMPLEMENT.md with validation records

Agents Used

RPI orchestrates specialized agents at each stage:

Research Agents

Agent	Role	Model
requirement-parser	Extract structured requirements	sonnet
product-manager	Assess product viability	sonnet
Explore	Discover existing code	inherit
senior-software-engineer	Technical feasibility	opus
technical-cto-advisor	Strategic recommendation	opus
documentation-analyst-writer	Generate report	inherit

Planning Agents

Agent	Role	Model
senior-software-engineer	Architecture design	opus
product-manager	Product requirements	sonnet
ux-designer	User experience design	sonnet
documentation-analyst-writer	Documentation synthesis	inherit

Implementation Agents

Agent	Role	Model
Explore	Pre-implementation discovery	inherit
senior-software-engineer	All implementation tasks	opus
code-reviewer	Quality validation	opus
constitutional-validator	Compliance checking	sonnet

All agents use opus for implementation to maximize quality. Research and planning use sonnet for balanced performance.

Constitutional Alignment

RPI enforces project principles throughout the workflow:

Research Phase

Constitutional Validation:

Does feature align with product vision?
Does it violate any project constraints?
Is it consistent with technical principles?

If constitution exists, product-manager agent checks alignment.

Planning Phase

Constitutional Constraints:

Architecture must respect boundaries
Testing requirements from constitution
Code quality standards

Plans incorporate constitutional requirements.

Implementation Phase

Constitutional Enforcement:

Type safety maintained
Component isolation respected
No breaking changes
Tests required

constitutional-validator agent checks compliance.

Constitution File Locations:

constitution.md
PRINCIPLES.md
.project/constitution.md

Validation Gates

RPI includes multiple validation checkpoints:

Research Gate

GO/NO-GO DecisionPrevents wasted effort on:

Non-viable features
Misaligned initiatives
Technically infeasible ideas

Planning Gate

Architecture ReviewValidates:

Technical approach
Phased breakdown
Resource requirements

Phase Gates

User ValidationEach phase requires approval:

Deliverables completed?
Tests passing?
Code review passed?

Quality Gates

Automated ChecksEvery phase must pass:

Linting
Tests
Build
Code review

When to Use RPI

✅ Use RPI For
❌ Don't Use RPI For

New features requiring strategic alignment
Complex features spanning multiple components
Features with uncertainty (technical or product)
Multi-phase implementations
Team projects requiring coordination
Features needing validation gates

Best Practices

Do complete research before planning - don’t skip the GO/NO-GO gate

Do run /compact after each stage to preserve context

Do review RESEARCH.md and PLAN.md before implementing

Do wait for user validation at each phase gate

Do leverage code discovery from Explore agent

Don’t skip validation gates - they catch issues early

Don’t proceed with NO-GO recommendations without addressing concerns

Don’t implement multiple phases without user approval

Installation

Copy the RPI workflow to your project:

Copy Agent and Command Files

# Copy from claude-code-best-practice repo
cp -r development-workflows/rpi/.claude/agents/* .claude/agents/
cp -r development-workflows/rpi/.claude/commands/rpi .claude/commands/

Create RPI Directory

mkdir -p rpi/plans

Optional: Add Constitution

# Create project principles
touch constitution.md

Define your project’s technical and product principles.

Verify Installation

/rpi:research --help
/rpi:plan --help
/rpi:implement --help

Troubleshooting

Research takes too long

Problem: Research phase consuming significant contextSolutions:

Run /compact before starting research
Provide focused REQUEST.md (avoid too much detail)
Run research in isolated session if needed
Use --phase flag to focus on specific analysis

Agent fails during phase

Problem: Agent times out or errorsSolutions:

Retry the specific phase: /rpi:implement feature --phase N
Check agent configuration in .claude/agents/
Verify required tools are available to agent
Reduce phase scope in PLAN.md if too large

Validation gate unclear

Problem: Don’t know if phase should passSolutions:

Review validation criteria in PLAN.md
Check code review verdict
Run tests manually to verify
Use CONDITIONAL PASS and document concerns

Advanced Usage

Resume Partial Implementation

# Resume from specific phase
/rpi:implement oauth2-authentication --phase 2

Validate Without Implementing

# Check if phase would pass
/rpi:implement oauth2-authentication --phase 3 --validate-only

Custom Phase Breakdown

Edit plan/PLAN.md before implementing:

## Phase 1: Database Layer (2 tasks)
- [ ] Add OAuth schema
- [ ] Create migrations

## Phase 2: Authentication Logic (4 tasks)
- [ ] Implement Passport strategies
- [ ] Add token management
- [ ] Create session handlers
- [ ] Write unit tests

## Phase 3: API Endpoints (3 tasks)
...

Orchestration Workflow

Command → Agent → Skill pattern for complex workflows

Agent Teams

Multiple agents working in parallel

Git Worktrees

Isolated branches for parallel development

Resources

RPI Example

Full RPI workflow implementation

Agents Guide

Learn about agent configuration

Commands Guide

Master command creation

Constitutional AI

Learn about constitutional alignment

Get Started

Core Concepts

Best Practices

Workflows & Patterns

Implementation Examples

​Overview

​Why RPI?

❌ Traditional Approach

✅ RPI Workflow

​Workflow Stages

​Example: OAuth2 Authentication

​Step 1: Describe

​Step 2: Research

​Step 3: Plan

​Step 4: Implement

​Complete Feature

​Feature Folder Structure

​Commands Reference

​Agents Used

​Research Agents

​Planning Agents

​Implementation Agents

​Constitutional Alignment

​Validation Gates

Research Gate

Planning Gate

Phase Gates

Quality Gates

​When to Use RPI

​Best Practices

​Installation

​Troubleshooting

​Advanced Usage

​Resume Partial Implementation

​Validate Without Implementing

​Custom Phase Breakdown

​Related Patterns

Orchestration Workflow

Agent Teams

Git Worktrees

​Resources

RPI Example

Agents Guide

Commands Guide

Constitutional AI

Build docs developers (and LLMs) love

Overview

Why RPI?

Workflow Stages

Example: OAuth2 Authentication

Step 1: Describe

Step 2: Research

Step 3: Plan

Step 4: Implement

Complete Feature

Feature Folder Structure

Commands Reference

Agents Used

Research Agents

Planning Agents

Implementation Agents

Constitutional Alignment

Validation Gates

When to Use RPI

Best Practices

Installation

Troubleshooting

Advanced Usage

Resume Partial Implementation

Validate Without Implementing

Custom Phase Breakdown

Related Patterns

Resources