# OpenCodeKit - 7-Agent Multi-Agent Observability

**Architecture**: Multi-Agent Observability Pattern  
**Inspiration**: [disler/opencode-hooks-multi-agent-observability](https://github.com/disler/opencode-hooks-multi-agent-observability)

---

## 🎯 What is OpenCodeKit?

A pre-configured OpenCode distribution featuring:

- **7 core agents** with clear delegation
- **24 skills** (domain expertise loaded via commands)
- **45+ workflow commands** (including `/handoff`)
- **Multi-agent observability** (all work visible in build session)
- **Manual handoffs** for clean phase transitions

**For**: Solo developers who want low maintenance + high productivity

---

## 🚀 Quick Start (5 minutes)

### Option 1: Using CLI (Recommended)

```bash
# 1. Install CLI
bun install -g opencodekit-cli
# or use local version
bun install
bun run dev init

# 2. Create new project
ock init
cd my-opencode-project

# 3. Configure OpenCodeKit
ock setup

# 4. Explore
ock agent list
ock skill list
```

**See [CLI.md](./CLI.md) for complete CLI documentation**

### Option 2: Manual Setup

```bash
# 1. Verify setup
ls -1 ~/.config/opencode/agent/*.md | wc -l  # Should be: 6

# 2. Start OpenCode
opencode

# 3. Try simple task (build handles)
create test.txt with "Hello OpenCodeKit"

# 4. Try command
/commit

# 5. Try delegation
@plan Build auth system with 4 phases

# 6. Try handoff workflow
/handoff "implement phase 1 of the plan"
# Creates portable handoff bundle in .opencode/memory/handoffs/
```

---

## 🏗️ Architecture

```
build (Primary Orchestrator - 70% of work)
  ├→ @plan (Complex planning ≥3 phases)
  ├→ @code-auditor (Review + security + testing)
  ├→ @researcher (Deep research)
  ├→ @orchestrator (Multi-agent coordination)
  └→ @general (Fallback)

Supporting:
  • 24 Skills (loaded via commands: 8 core, 7 stack, 9 specialized)
  • 45+ Commands (workflow shortcuts, includes /handoff)
  • 7 MCP Services (context7, exa, gkg, gh_grep, backlog, code-mode*, figma*)
  • Manual Handoffs (clean phase transitions)
```

### Manual Handoffs (Recommended)

**We use manual `/handoff` command for clean phase transitions** - no automatic session plugin needed.

### Custom `/handoff` Command

Creates portable handoff bundles for phase transitions:

```bash
# Create handoff bundle
/handoff "design the rate limiting system based on research"

# Creates: .opencode/memory/handoffs/2025-11-18-rate-limiting-design.md
# Contains: summary, @file-mentions, key decisions, next-phase prompt
```

**Use handoff bundle:**

```bash
# Option 1: Manual reference
@.opencode/memory/handoffs/2025-11-18-planning.md

# Option 2: With sessions plugin
session({
  mode: "new",
  agent: "plan",
  text: "@.opencode/memory/handoffs/2025-11-18-planning.md"
})
```

**Complete Workflow Example:**

```bash
# Phase 1: Research
/research "API rate limiting patterns"
# ... research happens ...

# Create handoff → Planning
/handoff "design system based on research"
# Creates: .opencode/memory/handoffs/2025-11-20-planning.md

# Phase 2: Planning (new thread with @plan)
@plan @.opencode/memory/handoffs/2025-11-20-planning.md
# ... planning happens ...

# Create handoff → Implementation
/handoff "implement phase 1 of the plan"
# Creates: .opencode/memory/handoffs/2025-11-20-implementation.md

# Phase 3: Implementation (new thread)
@.opencode/memory/handoffs/2025-11-20-implementation.md
# ... implementation happens ...

# Create handoff → Review
/handoff "review the completed feature for security"
# Creates: .opencode/memory/handoffs/2025-11-20-review.md

# Phase 4: Review (new thread with @code-auditor)
@code-auditor @.opencode/memory/handoffs/2025-11-20-review.md
```

**Key Benefits:**

- ✅ Clean context per phase (no conversation pollution)
- ✅ Portable bundles (share across workspaces)
- ✅ Git-tracked handoffs (audit trail)
- ✅ Simple workflow (just /handoff + new thread)

---

## 🎓 Learning Path

**Week 1**: Use daily, document patterns  
**Week 2**: Refine, create custom commands if needed

---

## 🔍 Decision Tree

**"Which agent should I use?"**

```
Is it a simple task?
  ✓ → Use build directly (70% of work)

Complex task (≥3 phases)?
  ✓ → @plan (creates task ledger)

Need research?
  ✓ → @researcher (multi-source validation)

Quality gate before deployment?
  ✓ → @code-auditor (security + review + test)

5+ phases + 3+ agents?
  ✓ → @orchestrator (progress tracking)

Everything else?
  ✓ → @general (fallback)
```

---

## 🛠️ Troubleshooting

**"Skills not loading"**  
→ Skills load via commands, NOT file types  
→ Use `/design/good` to load frontend-design skill  
→ Use `/fix/hard` to load debugging skills  
→ Check: `ls .opencode/skills/` for all available skills

**"/handoff command not available"**  
→ Verify: `ls .opencode/command/handoff.md`  
→ Check frontmatter has: `description`, `agent: build`  
→ Restart OpenCode if just added

**"MCP services not working"**  
→ Check `.opencode/.env` for API keys (CONTEXT7_API_KEY, EXA_API_KEY)  
→ Verify enabled in `.opencode/opencode.json`  
→ See `.opencode/README.md` for complete setup guide

---

## 🎉 Success Criteria

You've successfully set up OpenCodeKit when:

- ✅ 7 agent files (.opencode/agent/\*.md)
- ✅ Build handles 70%+ directly
- ✅ Commands work (45+ total, including `/handoff`)
- ✅ Skills load via commands (24 skills: 8 core, 7 stack, 9 specialized)
- ✅ Delegation is clear (build → specialized subagents)
- ✅ `/handoff` creates portable bundles (.opencode/memory/handoffs/)
- ✅ MCP services configured (7 total: 5 enabled, 2 optional)
- ✅ Environment variables set (.opencode/.env with API keys)

---

## 🔗 Resources

- [OpenCode Docs](https://opencode.ai/docs/)
- [Multi-Agent Pattern](https://github.com/disler/opencode-hooks-multi-agent-observability)
- [Handoff Workflow Guide](.opencode/INTEGRATION_OVERVIEW.md)
- [MCP Services Setup](.opencode/README.md)

## 📚 Documentation

- **CLI Tool**: [CLI.md](./CLI.md) - `ock` command reference (init, setup, agent, skill)
- **Architecture Guide**: `.opencode/INTEGRATION_OVERVIEW.md` - Two-layer system (Memory + Backlog + Git)
- **MCP Services Setup**: `.opencode/README.md` - Complete environment setup
- **Handoff Bundles**: `.opencode/command/handoff.md` - Clean phase transitions
- **Custom Commands**: `.opencode/command/` - All 45+ workflow commands
- **Skills System**: `.opencode/skills/` - 24 skills (8 core, 7 stack, 9 specialized)
- **Memory System**: `.opencode/memory/` - Persistent cross-session knowledge

---

**OpenCodeKit v2.0**  
**Architecture**: Two-layer (Memory + Backlog + Git)  
**New**: Manual handoff workflow + 7 MCP services + 24 skills system  
**Ready for**: Daily production use

Enjoy your streamlined agent system with clean phase transitions! 🚀
