npm package: @riseonalv/opencode-agents
Description: OpenCode plugin with 5 primary agents and 26 subagents for software development
Author: RiseOn
Latest version: 1.0.1

# 🚀 RiseOn.OpenCodeAgents

<div align="center">

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![TypeScript](https://img.shields.io/badge/TypeScript-5.0-blue.svg)](https://www.typescriptlang.org/)
[![Bun](https://img.shields.io/badge/Bun-Runtime-orange.svg)](https://bun.sh/)
[![OpenCode](https://img.shields.io/badge/OpenCode-Plugin-green.svg)](https://opencode.ai/)

**A comprehensive multi-agent plugin for OpenCode with 5 primary agents and 26 specialized subagents**

[Installation](#installation) • [Quick Start](#quick-start) • [Documentation](#documentation) • [Contributing](#contributing)

</div>

---

## 📋 Table of Contents

- [Overview](#overview)
- [Features](#features)
- [Architecture](#architecture)
- [Installation](#installation)
- [Quick Start](#quick-start)
- [Agent Reference](#agent-reference)
- [Configuration](#configuration)
- [Usage Examples](#usage-examples)
- [Contributing](#contributing)
- [License](#license)

---

## 🎯 Overview

RiseOn.OpenCodeAgents is a powerful plugin for [OpenCode](https://opencode.ai) that provides a complete multi-agent architecture for software development. It implements an orchestrator-workers model where primary agents coordinate specialized subagents to accomplish complex tasks.

### Key Principles

- **🎭 Inline Prompts**: No external prompt files - everything is self-contained
- **📦 Embedded Rules**: Rules are part of agent prompts, not separate files
- **🔄 Smart Delegation**: Task-based permissions control agent collaboration
- **⚡ Parallel Delegation**: Independent subagent tasks run in a single turn
- **📋 TODO-First Workflow**: Agents create structured plans before taking action
- **⚙️ User Customization**: Override prompts and config via `.md` files
- **📚 Bundled Skills**: 73+ skills included and easily installed

---

## ✨ Features

### Primary Agents (5)

| Agent | Description | Subagents |
|-------|-------------|-----------|
| 🏗️ **Architect** | System design & architecture | 8 subagents |
| 💻 **Software Engineer** | Development & coding | 6 subagents |
| 🚀 **DevOps Engineer** | Infrastructure & operations | 3 subagents |
| 📊 **Product Owner** | Backlog & agile ceremonies | 4 subagents |
| 🎯 **Product Manager** | Strategy & roadmap | 5 subagents |

### Subagents (26)

**Architecture:**
- `adr-generator` - Architectural Decision Records
- `ddd-specialist` - Domain-Driven Design
- `governance-specialist` - Compliance & quality
- `hlbpa-specialist` - High-level documentation
- `mermaid-diagrammer` - Architecture diagrams
- `microservices-specialist` - Service decomposition
- `system-architecture-reviewer` - Architecture validation
- `technical-writer` - Documentation

**Engineering:**
- `code-reviewer` - Code quality
- `test-writer` - Test automation
- `refactoring-specialist` - Code restructuring
- `dotnet-specialist` - C#/.NET expertise
- `frontend-developer` - React/Vue/Angular
- `api-architect` - API design

**DevOps:**
- `cicd-specialist` - Pipeline automation
- `cloud-architect` - Cloud infrastructure
- `security-auditor` - Security assessment

**Product:**
- `sprint-planner` - Sprint planning
- `backlog-manager` - Backlog prioritization
- `agile-coach` - Process improvement
- `acceptance-criteria-writer` - Testable criteria
- `roadmap-planner` - Strategic planning
- `requirements-analyst` - Requirements gathering
- `product-strategist` - Vision & positioning
- `market-researcher` - User & market research
- `mvp-definer` - MVP scope definition

---

## 🏗️ Architecture

```
┌─────────────────────────────────────────────────────────────┐
│                    OpenCode Runtime                          │
└───────────────────────┬─────────────────────────────────────┘
                        │
┌───────────────────────▼─────────────────────────────────────┐
│              RiseOn.OpenCodeAgents Plugin                    │
│                                                              │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐         │
│  │  Architect  │  │   Software  │  │   DevOps    │         │
│  │             │  │   Engineer  │  │   Engineer  │         │
│  │  8 subs 🏗️  │  │  6 subs 💻  │  │  3 subs 🚀  │         │
│  └─────────────┘  └─────────────┘  └─────────────┘         │
│                                                              │
│  ┌─────────────┐  ┌─────────────┐                           │
│  │   Product   │  │   Product   │                           │
│  │   Owner     │  │   Manager   │                           │
│  │  4 subs 📊  │  │  5 subs 🎯  │                           │
│  └─────────────┘  └─────────────┘                           │
│                                                              │
└─────────────────────────────────────────────────────────────┘
```

### Delegation Model

Primary agents automatically delegate to subagents based on context:

```typescript
// Architect can delegate to architecture subagents
architect: {
  task: {
    "*": "deny",
    "adr-generator": "allow",
    "ddd-specialist": "allow",
    "mermaid-diagrammer": "allow",
    // ... 5 more
  }
}

// Software Engineer cannot delegate to architect subagents
software-engineer: {
  task: {
    "*": "deny",
    "code-reviewer": "allow",
    "test-writer": "allow",
    // ... 4 more (engineering only)
  }
}
```

### Parallel Delegation

Primary agents delegate independent tasks in a **single turn** instead of sequentially. When tasks have no dependencies between their outputs, the agent batches them together for faster execution.

```
You: Design a microservices architecture and document it

🏗️ architect: I'll handle this efficiently.

[Single turn — delegates all independent tasks at once:]
  → adr-generator: Create ADR for key decisions
  → mermaid-diagrammer: Generate architecture diagrams
  → technical-writer: Write architecture documentation

[Then consolidates all results]
```

Tasks with dependencies still execute sequentially (e.g., write code first, then review it).

> **Tip:** For best parallel behavior, enable `experimental.batch_tool: true` in your OpenCode config.

### TODO-First Workflow

All primary agents and visible subagents (`@code-reviewer`, `@test-writer`) follow a **TODO-first** workflow. Before taking any action, the agent creates a structured plan using the `todowrite` tool. Items are marked `in_progress` during execution and `completed` when done.

```
You: Implement user authentication

💻 software-engineer: Let me plan this first.

📋 TODO:
  ✅ Understand auth requirements
  ✅ Design API endpoints
  🔄 Implement JWT token generation
  ⬜ Create login/logout endpoints
  ⬜ Add refresh token mechanism
  ⬜ Write unit tests (delegate to test-writer)
  ⬜ Code review (delegate to code-reviewer)
```

This gives you visibility into what the agent is doing and helps maintain structured progress on complex tasks.

---

## 📦 Installation

### As OpenCode Plugin

```bash
opencode plugin add riseon-opencode-agents
```

Or add to your `opencode.json`:

```json
{
  "plugin": ["riseon-opencode-agents"]
}
```

### Install Skills

```bash
# Core skills only (recommended)
bunx riseon-opencode-agents install --skills core

# All 73+ skills
bunx riseon-opencode-agents install --skills all
```

### Local Installation

For development or when not installing from npm, you can install locally via `bun link`:

```bash
# Clone and build the project
git clone https://github.com/RiseOn/RiseOn.OpencodeAgents.git
cd RiseOn.OpencodeAgents
bun install && bun run build

# Link the package globally
bun link

# Now you can use it as a plugin in your projects
# In your project directory:
bun link riseon-opencode-agents
```

Then add the plugin to your `opencode.json`:

```json
{
  "plugin": ["riseon-opencode-agents"]
}
```
### CLI Commands

Once installed, you can use these commands to manage your RiseOn Opencode Agents setup:

```bash
# Initialize an empty configuration with default agent
riseon-opencode-agents init

# Install skills (default is core skills)
riseon-opencode-agents install --skills core     # core skills only (default)
riseon-opencode-agents install --skills all      # all available skills  
riseon-opencode-agents install --skills <skill>  # specific skill

# List available skills and installation status
riseon-opencode-agents list                    # show all with status
riseon-opencode-agents list --installed        # show only installed
```

---

## 🚀 Quick Start

## 🚀 Quick Start

### 1. Switch Between Primary Agents

Use **Tab** in the TUI to cycle through agents:

```
🏗️ architect ↔ 💻 software-engineer ↔ 🚀 devops-engineer ↔ 📊 product-owner ↔ 🎯 product-manager
```

### 2. Invoke Visible Subagents

Type `@` to see available subagents:

```
@code-reviewer review the authentication module
@test-writer create tests for the user service
@api-architect design the REST API for orders
```

### 3. Automatic Delegation

Primary agents automatically delegate when needed:

```
You: Design a microservices architecture for an e-commerce platform

🏗️ architect: I'll design this architecture for you. Let me start by
analyzing the domain and then create the necessary documentation.

[Delegates to ddd-specialist for domain modeling]
[Delegates to microservices-specialist for service boundaries]
[Delegates to mermaid-diagrammer for diagrams]
[Delegates to adr-generator for decision records]
```

---

## 📖 Agent Reference

### 🏗️ Architect

Your system architecture expert. Handles:
- High-level system design
- Technology selection
- Architecture documentation
- Code reviews at architecture level

**Subagents:**
- `adr-generator` - Creates Architectural Decision Records
- `ddd-specialist` - Domain-Driven Design modeling
- `governance-specialist` - Compliance and standards
- `hlbpa-specialist` - High-level documentation
- `mermaid-diagrammer` - Architecture diagrams
- `microservices-specialist` - Service decomposition
- `system-architecture-reviewer` - Architecture validation
- `technical-writer` - Technical documentation

### 💻 Software Engineer

Your coding companion. Handles:
- Feature implementation
- Code reviews
- Testing
- Refactoring

**Subagents:**
- `code-reviewer` - Code quality review
- `test-writer` - Test automation
- `refactoring-specialist` - Code restructuring
- `dotnet-specialist` - C#/.NET expertise
- `frontend-developer` - Frontend development
- `api-architect` - API design

### 🚀 DevOps Engineer

Your infrastructure expert. Handles:
- CI/CD pipelines
- Cloud infrastructure
- Security auditing
- Deployment automation

**Subagents:**
- `cicd-specialist` - Pipeline automation
- `cloud-architect` - Cloud infrastructure
- `security-auditor` - Security assessment

### 📊 Product Owner

Your agile product expert. Handles:
- Sprint planning
- Backlog management
- Agile ceremonies
- Acceptance criteria

**Subagents:**
- `sprint-planner` - Sprint planning
- `backlog-manager` - Backlog prioritization
- `agile-coach` - Process improvement
- `acceptance-criteria-writer` - Testable criteria

### 🎯 Product Manager

Your strategic product leader. Handles:
- Product strategy
- Roadmap planning
- Market research
- MVP definition

**Subagents:**
- `roadmap-planner` - Strategic planning
- `requirements-analyst` - Requirements gathering
- `product-strategist` - Vision & positioning
- `market-researcher` - User & market research
- `mvp-definer` - MVP scope definition

---

## ⚙️ Configuration

### Global Config

Create `~/.config/opencode/riseon-opencode-agents.jsonc`:

```jsonc
{
  // Default agent for new conversations
  "default_agent": "software-engineer",
  
  // Agent-specific overrides
  "agents": {
    "architect": {
      "temperature": 0.2,
      "steps": 50
    },
    "software-engineer": {
      "steps": 40
    }
  },
  
  // Presets for different scenarios
  "presets": {
    "cost-optimized": {
      "architect": {},
      "software-engineer": {}
    },
    "quality": {
      "architect": { "temperature": 0.1, "steps": 60 },
      "code-reviewer": { "temperature": 0.0 }
    }
  },
  
  // Active preset
  "preset": "quality",
  
  // Skills to disable
  "disabled_skills": []
}
```

### Project Config

Create `.opencode/riseon-opencode-agents.jsonc` in your project:

```jsonc
{
  "default_agent": "architect",
  "agents": {
    "architect": {}
  }
}
```

Project config merges with user config (project takes precedence).

### Prompt Customization

Override agent prompts in `~/.config/opencode/riseon-opencode-agents/`:

**Full replacement:** `architect.md`
```markdown
You are a minimalist architect focused only on cloud-native microservices...
```

**Append to default:** `architect_append.md`
```markdown
Always use Portuguese for all documentation.
Always include performance considerations.
```

**Preset-scoped:** `quality/architect.md`

### Merge Priority

1. `{preset}/{agent}.md` - Preset-scoped replacement
2. `{agent}.md` - Replacement
3. `{agent}_append.md` - Append
4. Default prompt (embedded) - Fallback

---

## 💡 Usage Examples

### Example 1: Architecture Review

```
You: Review our current microservices architecture and suggest improvements

🏗️ architect: I'll conduct a comprehensive review of your architecture. Let me analyze the system using multiple perspectives.

[Analyzing codebase...]
[Delegates to system-architecture-reviewer for detailed analysis]
[Delegates to governance-specialist for compliance check]

📋 Findings:
- Service boundaries are well-defined ✓
- Missing circuit breakers in 3 services ⚠️
- Database per service pattern not followed ❌
- API versioning inconsistent ⚠️

🎯 Recommendations:
1. Implement circuit breaker pattern
2. Separate databases for each service
3. Standardize API versioning strategy
4. Add distributed tracing
```

### Example 2: Feature Development

```
You: Implement user authentication with JWT

💻 software-engineer: I'll implement a complete JWT authentication system. Let me break this down:

[Delegates to api-architect for API design]
[Writing code...]
[Delegates to test-writer for test suite]
[Delegates to code-reviewer for quality check]

✅ Delivered:
- JWT token generation and validation
- Login/logout endpoints
- Password hashing with bcrypt
- Refresh token mechanism
- Unit tests (95% coverage)
- Integration tests
```

### Example 3: CI/CD Setup

```
You: Set up CI/CD for our Node.js project using GitHub Actions

🚀 devops-engineer: I'll create a complete CI/CD pipeline for your Node.js project.

[Delegates to cicd-specialist for pipeline design]
[Creating workflow files...]

✅ Pipeline includes:
- Automated testing on PR
- Code quality checks (lint, format)
- Security scanning
- Docker image building
- Deployment to staging/production
- Notification on failure
```

### Example 4: Sprint Planning

```
You: Help me plan the next sprint

📊 product-owner: I'll help you plan a well-structured sprint. Let me gather the information.

[Delegates to sprint-planner for capacity planning]
[Analyzing backlog...]

📅 Sprint Plan:
Goal: Implement user dashboard and analytics

Capacity: 35 story points
Committed:
- US-101: User dashboard (8 pts)
- US-102: Analytics API (5 pts)
- US-103: Chart components (5 pts)
- US-104: Data export (3 pts)
- Bug fixes (8 pts)
- Tech debt (6 pts)

Risks: Analytics API depends on external service
```

---

## 🏗️ Project Structure

```
riseon-opencode-agents/
├── src/
│   ├── index.ts                    # Plugin entry point
│   ├── config/                     # Configuration system
│   │   ├── constants.ts            # Agent names, rules
│   │   ├── schema.ts               # Zod validation
│   │   ├── loader.ts               # Config loading
│   │   └── index.ts
│   ├── agents/
│   │   ├── index.ts                # Agent factories
│   │   ├── types.ts                # Type definitions
│   │   ├── primary/                # 5 primary agents
│   │   │   ├── architect.ts
│   │   │   ├── software-engineer.ts
│   │   │   ├── devops-engineer.ts
│   │   │   ├── product-owner.ts
│   │   │   └── product-manager.ts
│   │   └── subagents/              # 26 subagents
│   │       ├── adr-generator.ts
│   │       ├── code-reviewer.ts
│   │       └── ... (24 more)
│   ├── cli/
│   │   └── install.ts              # Skills installer
│   └── skills/                     # 73 bundled skills
│       ├── mcp-context-enrichment/
│       ├── documentation-writer/
│       └── ... (71 more)
├── dist/                           # Build output
├── package.json
├── tsconfig.json
└── README.md                       # This file
```

---

## 🤝 Contributing

We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.

### Development Setup

```bash
# Clone the repository
git clone https://github.com/RiseOn/RiseOn.OpencodeAgents.git
cd RiseOn.OpencodeAgents

# Install dependencies
bun install

# Build the project
bun run build

# Type check
bun run typecheck
```

### Adding a New Subagent

1. Create agent factory in `src/agents/subagents/{name}.ts`
2. Add export to `src/agents/index.ts`
3. Add to primary agent's delegation rules
4. Update documentation

---

## 📚 Documentation

- [Full Specification](SPECIFICATION.md) - Detailed architecture and design
- [Agent Reference](#agent-reference) - Complete agent documentation
- [Configuration Guide](#configuration) - How to customize the plugin

---

## 🙏 Acknowledgments

This project is inspired by:
- [OpenCode](https://opencode.ai/) - The platform that makes this possible
- [Anthropic](https://www.anthropic.com/) - For principles on building effective agents

---

## 📄 License

MIT License - see [LICENSE](LICENSE) file for details.

---

<div align="center">

**Made with ❤️ by the RiseOn Team**

[Report Bug](https://github.com/RiseOn/RiseOn.OpencodeAgents/issues) • [Request Feature](https://github.com/RiseOn/RiseOn.OpencodeAgents/issues)

</div>