RIPER Workflow for OpenCode

Research • Innovate • Plan • Execute • Review

Structured AI-assisted development workflow for OpenCode with phase-specific agents for research, planning, and execution.

🎯 Overview

RIPER creates a controlled, guided flow that enforces separation between research, planning, and execution phases. This helps:

• Reduce context usage through specialized agents
• Prevent premature implementation before understanding
• Maintain clear documentation of decisions
• Enable reproducible development processes

🚀 Quick Start

Installation

1. Copy the .opencode directory to your project root:

cp -r .opencode /path/to/your/project/

2. OpenCode will automatically detect and load the configuration

3. Optional: Add .opencode/memory-bank/ to .gitignore to keep plans and reviews private:

   echo ".opencode/memory-bank/" >> .gitignore

   Or selectively ignore just plans and reviews while keeping memory bank structure:

   echo ".opencode/memory-bank/*/plans/" >> .gitignore
   echo ".opencode/memory-bank/*/reviews/" >> .gitignore

   Note: If you accidentally commit these, remove them before merging:

   git rebase -i HEAD~n  # where n is number of commits to review

Basic Usage

RIPER uses a coordinator-based workflow with 5 specialized subagents.

Option 1: Guided Workflow (Recommended)

Use the riper coordinator for full feature implementation with checkpoints:

# Full 5-phase workflow
@riper add user authentication

# Partial workflow
@riper research and innovate for caching strategy

The coordinator will:

• Guide you through each phase
• Ask for approval at checkpoints
• Pass context between phases automatically
• Create plan file with all workflow history

Option 2: Direct Subagent Usage (Ad-hoc)

Use subagents directly for one-off tasks:

# Just research something
@riper-research how is error handling implemented?

# Just brainstorm approaches
@riper-innovate different caching strategies

# Create a plan (if you have context)
@riper-plan implement Redis caching

# Execute a plan
@riper-execute the add-auth plan
# or: @riper-execute /path/to/plan.md

# Review implementation
@riper-review the add-auth plan

When to Use Which

Use Coordinator (@riper) for:

• Complex multi-step features end-to-end
• Refactoring critical code
• Implementing architectural changes
• Tasks requiring careful planning with checkpoints
• Strict enforcement of phase boundaries

Use Direct Subagents for:

• Simple bug fixes or minor changes
• Quick information gathering
• One-off tasks (research only, review only, etc.)
• Exploratory coding with flexible workflow

📚 Agent Reference

RIPER Agents in OpenCode

Agent	Mode	Description	Permissions
riper	primary	Orchestrates 5-phase workflow (strict mode)	Minimal (coordinator)
riper-research	subagent	Research phase - gather context	Read-only, web access
riper-innovate	subagent	Innovation phase - explore approaches	Read-only, web access
riper-plan	subagent	Planning phase - create specifications	Memory-bank writes only
riper-execute	subagent	Execution phase - implement plan	Full edit/bash access
riper-review	subagent	Review phase - validate implementation	Read-only + test execution

Strict Enforcement: Only when using the coordinator. Direct subagents are flexible.

Accessing Agents

• Tab to select riper or @riper [goal] for coordinator
• Use @riper-research, @riper-innovate, @riper-plan, @riper-execute, @riper-review for direct subagent access

🏗️ Architecture

RIPER uses a coordinator pattern with 6 total agents.

Memory Bank Structure

.opencode/memory-bank/
├── main/                     # Main branch
│   └── plans/               # Plan files (YYYY-MM-DD-HH-mm-description.md)
└── [feature-branch]/        # Feature branch
    └── plans/               # Branch-specific plans

Plan Files: Single source of truth containing:

• Research findings
• Approaches considered
• Technical specification
• Implementation progress (checked off steps)
• Review results (OK/BAD/DEFER marks)

Phase Capabilities

Phase	Read	Write	Execute	Plan	Validate
RESEARCH	✅	❌	❌	❌	❌
INNOVATE	✅	❌	❌	❌	❌
PLAN	✅	📄*	❌	✅	❌
EXECUTE	✅	✅	✅	❌	❌
REVIEW	✅	📄*	✅**	❌	✅

* Only to memory bank
** Only test execution

Workflow Flow

Research (gather context)
    ↓
Innovate (explore approaches) → [Select approach]
    ↓
Plan (create spec) → [Review plan]
    ↓
Execute (implement) → [Track progress in plan]
    ↓
Review (validate) → [Mark tasks OK/BAD/DEFER]

Coordinator enforces this flow strictly. Direct subagents are flexible.

🔧 Configuration

.opencode/opencode.json

Main configuration file:

• Global permission settings
• Agent definitions with custom permissions
• Model selection (Claude Sonnet 4.5)

Agent Prompts

Each agent has a markdown file in .opencode/agent/:

• riper.md - Coordinator (mode: primary)
• riper-research.md - Research subagent
• riper-innovate.md - Innovation subagent
• riper-plan.md - Planning subagent
• riper-execute.md - Execution subagent
• riper-review.md - Review subagent

These define agent behavior, permissions (in frontmatter), and output templates.

Customization

To customize RIPER for your project:

• Edit agent markdown files in .opencode/agent/ to adjust behavior
• Modify permissions in frontmatter of agent files
• Update .opencode/opencode.json for global settings

💡 Tips & Best Practices

Workflow Tips

1. Always start with research - Understanding before coding prevents wasted effort
2. Use memory bank - Save important context for future sessions
3. Be specific in plans - Detailed specs lead to accurate implementation
4. Review ruthlessly - Catch deviations early

Context Efficiency

• Research phase uses cheaper, focused tools
• Plans are saved to memory, reducing repetition
• Execute phase has full context from approved plan
• Review validates without reimplementing

🤝 Contributing

Improvements welcome! Key areas:

• Additional workflow commands
• Better memory management
• Enhanced agent capabilities
• Integration examples

📜 Credits

Based on claude-code-riper-5.

📄 License

MIT - Use freely in your projects

---

Example Session

Complete RIPER Workflow in OpenCode

Using the Coordinator (Recommended)

@riper implement two-factor authentication with TOTP

The coordinator will:

1. Research Phase - Gather context about existing auth implementation
2. Innovate Phase - Explore approaches (SMS vs TOTP vs WebAuthn)
3. Plan Phase - Create detailed specification (asks for approval)
4. Execute Phase - Implement the approved plan (tracks progress)
5. Review Phase - Validate implementation against plan

Each phase asks for approval before proceeding. Plan is saved to .opencode/memory-bank/main/plans/.

Using Direct Subagents (Ad-hoc)

# Just research
@riper-research how is authentication currently implemented?

# Just explore approaches
@riper-innovate different strategies for 2FA

# Just create a plan
@riper-plan implement TOTP-based 2FA

# Just execute a plan
@riper-execute the 2FA plan

# Just review implementation
@riper-review the 2FA implementation

Troubleshooting

Q: Agents not appearing in OpenCode?
A: Ensure .opencode directory is in project root and OpenCode has loaded the config

Q: Permission denied errors?
A: This is expected! riper-research and riper-review cannot edit files by design

Q: Memory bank not saving?
A: Check write permissions on .opencode/memory-bank/ and verify you're using correct repository root

Q: Agent configuration errors?
A: Validate .opencode/opencode.json with cat .opencode/opencode.json | jq empty