# opencode-remi

[![npm version](https://badge.fury.io/js/opencode-remi.svg)](https://www.npmjs.com/package/opencode-remi)

**Remi v3** - The Full WZRD.dev Agentic Framework for OpenCode

A complete AI engineering platform with 75+ specialized skills, 8 operating modes, and the Gold Standard methodology. Install once, use everywhere.

## What Makes Remi Different

Remi is NOT "Claude with skills" or "an agent using a framework." **Remi IS the WZRD.dev framework itself** - a complete agentic engineering platform with:

- **75+ Skills** - Auto-loaded on demand for any task
- **8 Operating Modes** - CHAT, PLANNING, CODING, TESTING, RESEARCH, DEBUG, DOCUMENTATION, REVIEW
- **Gold Standard** - Read-back verification, executable proof, max 3 attempts rule
- **PIV Orchestration** - Plan → Implement → Validate for complex tasks
- **Role-Shifting** - Shift modes instead of spawning agents (preserves context)

## Installation

```bash
# 1. Install OpenCode (required first)
npm install -g @opencode/cli

# 2. Install Remi
npm install -g opencode-remi

# 3. Initialize agents
remi-init

# 4. Verify
remi-doctor
```

## Quick Start

```bash
# Start OpenCode with Remi (default agent)
opencode

# Use a specific agent
opencode --agent remi-coder

# Or switch agents mid-session
/agent remi-architect
```

## Agents

| Agent | Purpose | Best For |
|-------|---------|----------|
| `remi` | General purpose | Most tasks, default. Full access to all 75+ skills |
| `remi-coder` | Implementation | Writing code, debugging, code review |
| `remi-architect` | System design | Architecture, planning, technology selection |
| `remi-debug` | Troubleshooting | Finding/fixing bugs, root cause analysis |

## Skills (75+)

Skills are loaded on-demand using the `skill` tool. Core skills are always available, extended skills load automatically when needed.

### Core Skills (Always Available)

- **coding** - Implementation patterns, TDD, code standards
- **testing** - Unit, integration, E2E testing
- **planning** - Task decomposition, dependency mapping
- **debugging** - Bug finding and fixing
- **architecture** - System design, patterns
- **gold-standard** - Quality enforcement rules
- **research** - Deep investigation, web search
- **context** - Token management, compression

### Extended Skills (Load on Demand)

#### UI/UX & Frontend (10 skills)
- `react-ui-master` - React with shadcn/ui, Tailwind, Playwright
- `shadcn-generator` - Generate shadcn/ui components
- `theme-generator` - Tailwind themes from design tokens
- `ui-ux-master` - Master-level UI/UX design
- `ui-vision` - AI-powered UI understanding
- `ui-screenshot` - Screenshot capture and comparison
- `visual-validator` - Visual validation with agent-browser
- `design-mode` - Unified design mode (greenfield/brownfield)
- `excalidraw` - Diagram generation
- `opentui` - Terminal UI development

#### Backend & Infrastructure (12 skills)
- `api` - REST, GraphQL, HTTP standards
- `sql` - Database queries, schema design
- `git` - Version control workflow
- `github` - GitHub search, repository navigation
- `cli` - Command line operations
- `automation` - Task automation, cron jobs
- `heartbeat` - Cron job scheduling
- `system-health` - Health monitoring
- `system-audit` - System auditing
- `security` - Security auditing, best practices
- `validation` - Input validation, sanitization
- `mcp` - Model Context Protocol

#### Code Transformation & Analysis (10 skills)
- `code-transformation` - General code transformation
- `code-transformation-v31` - V31 transformation
- `transform-model-a` - Column-based filtering patterns
- `transform-model-b` - Row-iteration patterns
- `transform-model-c` - Multi-pass scanner patterns
- `classify-transformation` - Classify and route transformations
- `v31-transformation-base` - Shared V31 utilities
- `v31-generator` - V31 code generation
- `code-analysis` - Codebase analysis
- `scan-build` - Build scanning

#### Testing & Quality (8 skills)
- `e2e-test` - End-to-end testing with browser automation
- `code-run-validator` - Validate code execution
- `testing` - Comprehensive testing strategies
- `validation` - Input validation patterns
- `security` - Security testing
- `performance` - Performance testing
- `browser-automation` - Browser automation
- `platform-integration` - Edge.dev platform integration

#### Data & Research (10 skills)
- `data-formats` - JSON, YAML, CSV, XML, TOML
- `data-analysis` - Data analysis, statistics, visualization
- `web-search` - Advanced web searching
- `research` - Deep investigation
- `twitter-knowledge` - Extract insights from tweets
- `transcribe` - Audio/video transcription
- `sec-filings` - SEC filing analysis
- `file-ops` - File operations
- `regex` - Regular expressions
- `github` - Repository research

#### Platform & Integration (8 skills)
- `platform-integration` - Edge.dev platform
- `browser-automation` - Browser automation
- `mcp` - Model Context Protocol
- `discord-file-upload` - Discord file uploads
- `opentui` - Terminal UI
- `wzrd-framework` - WZRD framework integration
- `wzrdclaw-patterns` - WZRD patterns
- `wzrdclaw-tui-integration` - TUI integration

#### Advanced Features (12 skills)
- `background-agents` - Parallel agent delegation
- `orchestration` - Task coordination
- `memory-curation` - Memory management
- `auto-memory` - Automatic memory injection
- `ralph-loop` - Self-referential development
- `jcodemunch` - Token-efficient code retrieval
- `skills-builder` - Create new skills
- `agent-onboarding` - Agent transformation
- `topic-switcher` - Topic switching
- `learning-loop` - Continuous learning
- `framework-loader` - Framework loading
- `framework-integration` - Framework integration

## CLI Commands

```bash
remi-init      # Install agents into OpenCode (run once)
remi-doctor    # Check installation health
remi-update    # Update to latest version
```

## Gold Standard Rules

Every Remi agent follows these principles:

1. **Read-Back Verification**: After EVERY file write, read it back
2. **Executable Proof**: Never claim something works without showing it
3. **Max 3 Attempts**: After 3 failures, escalate
4. **Context Monitoring**: Auto-summarize at 40%, 65%, 75% thresholds

## 8 Operating Modes

Remi automatically detects the right mode:

- **CHAT MODE**: Casual conversation
- **PLANNING MODE**: Task breakdown, architecture
- **CODER MODE**: Code generation, implementation
- **TESTING MODE**: QA, validation, verification
- **RESEARCH MODE**: Deep investigation, learning
- **DEBUG MODE**: Error fixing, troubleshooting
- **DOCUMENTATION MODE**: Docs, guides, README
- **REVIEW MODE**: Code review, quality checks

## Role-Shifting

Instead of spawning multiple agents, Remi shifts roles:

```
"Shifting to planning mode..."
"Shifting to coding mode..."
"Shifting to QA mode..."
```

This preserves context and is more efficient.

## PIV Orchestration

For complex tasks (>3 components):

### Phase 1: PLAN
- Launch research pool (parallel agents)
- Gather information 3x faster
- Aggregate findings

### Phase 2: IMPLEMENT
- Single build agent with research context
- Focused implementation
- Incremental progress

### Phase 3: VALIDATE
- Systematic testing
- Quality gates
- Documentation

## Commands

Use these pre-made command workflows:

| Command | Purpose | Time |
|---------|---------|------|
| `/fix-bug` | Fix bugs systematically | 15-45 min |
| `/add-feature` | Add new features | 1-4 hours |
| `/refactor` | Clean up existing code | 30 min - 2 hrs |
| `/test-and-deploy` | Test and deploy | 10-30 min |
| `/quick-help` | Get quick answers | 5-10 min |
| `/topic-chapter "name"` | Mark new chapter | Save summary, fresh start |
| `/topic-archive` | Archive current work | Save to archive, clear context |

## Configuration

Agents are installed to:

```
~/.opencode/agents/
├── remi.json           # Full framework with all skills
├── remi-coder.json     # Implementation focused
├── remi-architect.json # System design focused
├── remi-debug.json     # Troubleshooting focused
└── default-agent.json  # Points to remi
```

## Requirements

- Node.js >= 18.0.0
- OpenCode CLI (`npm install -g @opencode/cli`)

## Uninstall

```bash
npm uninstall -g opencode-remi
```

This removes the CLI tools. To remove agents:

```bash
rm ~/.opencode/agents/remi*.json
```

## License

MIT

---

**Made with 💜 by WZRD.dev**