RIPER-5 Advanced Agent Constraint Mode for Cursor

RIPER-5 is a community-created constraint framework that has been proven to drastically reduce AI hallucinations and unauthorized code modifications. Originally designed for Claude 3.7, it works exceptionally well with Cursor's Agent mode. This guide explains the five phases and how to implement them.

What is RIPER-5?

RIPER-5 stands for:

Phase	Name	Purpose
R	Research	Gather information without making changes
I	Identify	Pinpoint the exact problem or requirement
P	Plan	Create a detailed, approved plan
E	Execute	Implement ONLY the approved plan
R	Review	Verify and test the implementation

The Five Phases in Detail

Phase 1: Research (R)

Rule: Read-only. No file modifications allowed.

Actions:

• Read relevant files
• Search codebase with Grep
• Analyze existing patterns
• Understand dependencies

Output: Research summary with findings

## Research Phase Complete

### Files Analyzed
- `src/auth/login.ts` - Current auth flow
- `src/middleware/auth.ts` - JWT verification
- `tests/auth.test.ts` - Existing tests

### Key Findings
1. Auth uses JWT with 15min expiry
2. No refresh token mechanism exists
3. Password reset is not implemented
4. Tests cover login but not edge cases

### Dependencies
- jsonwebtoken: ^9.0.0
- bcrypt: ^5.1.0

Phase 2: Identify (I)

Rule: Define the exact problem statement.

Actions:

• State the problem clearly
• Define acceptance criteria
• Identify constraints
• Note potential risks

Output: Problem definition document

## Problem Identification

### Problem Statement
Users are logged out after 15 minutes and must re-authenticate.
This creates a poor UX for long-running sessions.

### Root Cause
JWT tokens expire after 15 minutes with no refresh mechanism.

### Acceptance Criteria
- [ ] Users stay logged in for 7 days
- [ ] Refresh tokens rotate on each use
- [ ] Old refresh tokens are invalidated
- [ ] Users can revoke all sessions

### Constraints
- Must maintain backward compatibility
- No breaking changes to existing API
- Must work with existing JWT middleware

### Risks
- Token theft if refresh tokens are compromised
- Database storage for token tracking

Phase 3: Plan (P)

Rule: Create a detailed, step-by-step plan.

Actions:

• List all files to modify
• Specify exact changes per file
• Define test strategy
• Plan rollback procedure

Output: Detailed implementation plan

## Implementation Plan

### Files to Modify

#### 1. `src/models/refresh-token.ts` (NEW)
```typescript
// Schema for refresh tokens
// Fields: id, userId, token, createdAt, expiresAt, revoked

2. src/services/auth.ts (MODIFY)

• Add createRefreshToken() function
• Add rotateRefreshToken() function
• Add revokeAllUserTokens() function

3. src/routes/auth.ts (MODIFY)

• Add POST /refresh endpoint
• Add POST /revoke endpoint

4. src/middleware/auth.ts (MODIFY)

• Update JWT verification to support longer sessions

Testing Plan

1. Unit tests for token rotation
2. Integration tests for refresh flow
3. Security tests for token revocation

Rollback Plan

1. Remove refresh token model
2. Revert auth service changes
3. Remove new endpoints

### Phase 4: Execute (E)

**Rule**: Implement ONLY what was planned.

**Actions**:
- Make planned changes
- Follow the plan exactly
- Report progress after each file
- Stop if plan needs revision

**Output**: Implementation with progress tracking

```markdown
## Execution Phase

### Progress
- [x] Created `src/models/refresh-token.ts`
- [x] Modified `src/services/auth.ts`
- [ ] Modify `src/routes/auth.ts` (in progress)
- [ ] Update `src/middleware/auth.ts`

### Changes Made
1. Added RefreshToken model with fields
2. Implemented token rotation logic
3. Added revocation support

### Next
- Add refresh endpoint
- Update middleware

Phase 5: Review (R)

Rule: Verify everything works as planned.

Actions:

• Run all tests
• Check for regressions
• Verify acceptance criteria
• Document any deviations

Output: Review report

## Review Phase

### Tests
- [x] Unit tests pass (15/15)
- [x] Integration tests pass (8/8)
- [x] Security tests pass (5/5)

### Acceptance Criteria
- [x] Users stay logged in for 7 days
- [x] Refresh tokens rotate on each use
- [x] Old refresh tokens are invalidated
- [x] Users can revoke all sessions

### Regressions
- None detected

### Deviations from Plan
- Added token cleanup cron job (not in original plan)
- Reason: Prevents database bloat from expired tokens

Setting Up RIPER-5 in Cursor

Step 1: Create the Rule File

Create .cursor/rules/riper5-mode.mdc:

---
description: 'RIPER-5 advanced constraint mode'
globs: ['**/*']
alwaysApply: true
---

# RIPER-5 Mode

You MUST follow the RIPER-5 workflow for ALL tasks.

## Phase Sequence
1. **Research** - Read and analyze only
2. **Identify** - Define the problem
3. **Plan** - Create detailed plan
4. **Execute** - Implement plan only
5. **Review** - Verify and test

## Phase Rules

### Research Phase
- Use only Read, Grep, Search tools
- NO file modifications
- NO code generation
- Present findings in structured format

### Identify Phase
- State problem clearly
- Define acceptance criteria
- List constraints
- Identify risks

### Plan Phase
- List ALL files to modify
- Show exact changes for each file
- Include testing strategy
- Include rollback plan
- WAIT for user approval

### Execute Phase
- Implement ONLY planned changes
- Report after each file
- Ask for clarification if stuck
- NO unplanned modifications

### Review Phase
- Run all tests
- Verify acceptance criteria
- Check for regressions
- Document deviations

## CRITICAL
- NEVER skip phases
- NEVER modify files in Research phase
- NEVER add unplanned changes in Execute phase
- ALWAYS get approval before Execute phase

Step 2: Add to System Prompt

In Cursor Settings:

## RIPER-5 Workflow

For every task, you MUST follow these 5 phases:

1. **Research**: Read and analyze without changes
2. **Identify**: Define the exact problem
3. **Plan**: Create detailed implementation plan
4. **Execute**: Implement ONLY the approved plan
5. **Review**: Verify everything works

You cannot proceed to the next phase without completing the current one.
You cannot modify files during Research or Identify phases.
You cannot add unplanned changes during Execute phase.

Step 3: Practice with a Simple Task

Start with a small task to get familiar:

[Task] Add a utility function to format dates.

Follow RIPER-5:
1. Research existing date handling
2. Identify what's needed
3. Plan the implementation
4. Execute after my approval
5. Review the result

Advanced: RIPER-5 with Checkpoints

Git Integration

# Before starting (Research phase)
git checkout -b feature/riper5-task
git commit -m "checkpoint: before RIPER-5 implementation"

# After Research phase
git add research-notes.md
git commit -m "riper5: research complete"

# After Plan phase (before approval)
git add plan.md
git commit -m "riper5: plan created, awaiting approval"

# After Execute phase
git add -A
git commit -m "riper5: implementation complete"

# After Review phase
git commit -m "riper5: review passed, tests green"

Measuring Effectiveness

Track these metrics:

Metric	Before RIPER-5	After RIPER-5
Unauthorized changes	High	Near zero
Plan approval rate	N/A	>90%
Test pass rate after changes	60%	95%
Rollback frequency	High	Low
User satisfaction	Mixed	High

Common Challenges

Challenge	Solution
Agent skips phases	Enforce with strict rules
Plans are too broad	Require file-level specificity
Review is superficial	Mandate test execution
Slows down simple tasks	Allow shortcuts for trivial changes

Quick Reference

[RIPER-5 START]

Phase 1/5: Research
[Agent reads and analyzes]

Phase 2/5: Identify
[Agent defines problem]

Phase 3/5: Plan
[Agent creates plan]
[User: APPROVE or MODIFY]

Phase 4/5: Execute
[Agent implements]

Phase 5/5: Review
[Agent verifies]

[RIPER-5 COMPLETE]

Related Resources

• Cursor Agent Mode Masterclass
• Plan vs Act Dual-Mode Workflow
• Cursor Self-Review Hooks Guide