# Claude + OpenCode Orchestration Guide
**How Claude and OpenCode work together for high-velocity full-stack development.**
---
## The Core Pattern
```
┌─────────────────────────────────────────────────────────────────┐
│ User Request │
│ ↓ │
│ Claude: Break into focused steps │
│ ↓ │
│ For each step: │
│ ┌──────────────────────────────────────────────────────────┐ │
│ │ 1. Call OpenCode MCP tool with focused prompt │ │
│ │ 2. OpenCode generates code at 2000-3000 tok/sec │ │
│ │ 3. Claude reads result │ │
│ │ 4. Claude verifies (syntax, logic, security) │ │
│ │ 5. Fix issues or proceed to next step │ │
│ └──────────────────────────────────────────────────────────┘ │
│ ↓ │
│ Final verification → Report to user │
└─────────────────────────────────────────────────────────────────┘
```
---
## Role Division
| Role | Responsibility | Speed |
|------|----------------|-------|
| **Claude** | Orchestration, verification, judgment, user communication | Thoughtful |
| **OpenCode** | Code generation, file operations, implementation | 2000-3000 tok/sec |
**Claude's strengths**: Superior reasoning, verification, security awareness, context understanding
**OpenCode's strengths**: Raw speed, focused execution, pattern matching
---
## MCP Tool Invocation
```typescript
mcp__fullstack-mcp__[manager]-manager(
prompt="TASK: [Clear, focused instruction]",
cwd="/path/to/project" // Required for file access
)
```
### Available Managers
| Manager | Domain | Use When |
|---------|--------|----------|
| `frontend-manager` | React, Vue, Svelte, CSS | Building UI components, styling, client logic |
| `backend-manager` | Node, Express, FastAPI | Server routes, middleware, services |
| `database-manager` | PostgreSQL, Prisma, MongoDB | Schema, migrations, queries |
| `api-manager` | REST, GraphQL, WebSocket | Endpoints, auth, API design |
| `devops-manager` | Docker, CI/CD, deployment | Containers, pipelines, infra |
| `testing-manager` | Jest, Playwright, pytest | Unit, integration, E2E tests |
| `security-manager` | Auth, OWASP, validation | Security hardening, auth flows |
| `performance-manager` | Caching, optimization | Speed improvements, profiling |
---
## Prompt Engineering for OpenCode
### Good Prompts
```
TASK: Add a Button component with primary/secondary variants
CONTEXT:
- File: src/components/Button.tsx
- Pattern: Look at existing Input component for styling approach
REQUIREMENTS:
- TypeScript with proper props interface
- Tailwind CSS for styling
- Support disabled and loading states
AFTER: Read the file back to verify
```
### Bad Prompts
```
Make a button that looks nice and works well
```
### The Formula
1. **TASK**: Clear, specific goal (WHAT not HOW)
2. **CONTEXT**: File location, patterns to follow
3. **REQUIREMENTS**: Constraints, must-haves
4. **AFTER**: Verification step
---
## Plan-Implement-Reflect Cycle
For each feature or fix:
### 1. PLAN
- Break the task into focused steps
- Identify which managers to use
- Define success criteria
### 2. IMPLEMENT
- Call OpenCode MCP for each step
- One step at a time
- Read files back after generation
### 3. REFLECT
- Verify syntax: `npx tsc --noEmit`
- Run tests: `npm test`
- Check security implications
- Review logic for edge cases
### If Issues Found
- Create targeted fix prompt with EXACT error
- Call OpenCode again
- Re-verify
---
## Graduated Escalation
When OpenCode struggles with a task:
| Cycle | Implementer | Reviewer |
|-------|-------------|----------|
| 1 | OpenCode | OpenCode (same tool) |
| 2 | OpenCode | Claude (reads guide, reviews) |
| 3 | Claude | Claude |
**Cycle 1**: Let OpenCode try and self-correct
**Cycle 2**: Claude reads the relevant manager guide, provides detailed critique
**Cycle 3**: Claude takes over implementation directly
---
## Verification Checklist
After each OpenCode response:
```
□ File was created/modified correctly
□ TypeScript compiles (npx tsc --noEmit)
□ No obvious bugs or logic errors
□ Security: No injection vulnerabilities, proper validation
□ Follows existing patterns in codebase
□ Tests pass (if applicable)
```
---
## Bug Fixing Pattern
When OpenCode introduces a bug:
```
FILE: [exact path]
BUG: Line [X] in function [name]
PROBLEM: [exact error message or description]
FIX:
1. READ the current file
2. CHANGE [specific thing] to [new value]
3. READ back to verify
```
Be specific. "Fix the bug" doesn't work. "Change line 42 from `user.id` to `user?.id`" works.
---
## Common Patterns
### Creating a New Feature
```
1. mcp__fullstack-mcp__database-manager → Add schema/migration
2. mcp__fullstack-mcp__backend-manager → Add service + routes
3. mcp__fullstack-mcp__api-manager → Review endpoint design
4. mcp__fullstack-mcp__frontend-manager → Add UI component
5. mcp__fullstack-mcp__testing-manager → Add tests
```
### Adding Authentication
```
1. mcp__fullstack-mcp__security-manager → Design auth flow
2. mcp__fullstack-mcp__database-manager → User schema
3. mcp__fullstack-mcp__backend-manager → Auth middleware
4. mcp__fullstack-mcp__api-manager → Auth endpoints
5. mcp__fullstack-mcp__frontend-manager → Login/signup forms
```
### Optimizing Performance
```
1. mcp__fullstack-mcp__performance-manager → Profile and identify bottlenecks
2. mcp__fullstack-mcp__database-manager → Query optimization
3. mcp__fullstack-mcp__backend-manager → Add caching
4. mcp__fullstack-mcp__frontend-manager → Code splitting, lazy loading
```
---
## Anti-Patterns
| Don't | Why | Instead |
|-------|-----|---------|
| "Build entire feature" in one prompt | Too vague, can't verify | Break into steps |
| Skip verification | Bugs compound | Always read back |
| Micromanage code | Wastes Claude's judgment | Tell WHAT not HOW |
| Ignore errors | They get worse | Fix immediately |
| Use wrong manager | Suboptimal results | Match task to specialty |
---
## Speed Expectations
- OpenCode generation: 0.5-2 seconds per step
- Claude verification: 30-60 seconds per step
- **Bottleneck is verification, not generation** (this is correct)
Don't rush verification to "save time" - that's where bugs get caught.
---
## Project Setup
Before using MCP tools on a project:
```bash
# Initialize the project with agents
./init-project.sh /path/to/your/project
# This creates:
# - opencode.json (permissions)
# - .opencode/agent/ (specialist agents)
```
Without this, OpenCode will prompt for permissions and timeout.
---
## Quick Reference
```bash
# Full-stack managers
mcp__fullstack-mcp__frontend-manager(prompt, cwd)
mcp__fullstack-mcp__backend-manager(prompt, cwd)
mcp__fullstack-mcp__database-manager(prompt, cwd)
mcp__fullstack-mcp__api-manager(prompt, cwd)
mcp__fullstack-mcp__devops-manager(prompt, cwd)
mcp__fullstack-mcp__testing-manager(prompt, cwd)
mcp__fullstack-mcp__security-manager(prompt, cwd)
mcp__fullstack-mcp__performance-manager(prompt, cwd)
# Quality checks
npx tsc --noEmit # TypeScript
npx eslint . --ext .ts # Linting
npm test # Tests
npm run build # Build
```
---
## Remember
1. **One step at a time** - Verify before proceeding
2. **Be specific** - Vague prompts get vague results
3. **Trust but verify** - OpenCode is fast, not infallible
4. **Match the manager** - Use the right specialist
5. **Security first** - Check every change for vulnerabilities
---
*This guide complements CLAUDE.md with practical workflow patterns.*