OpenCodeKit - 10-Agent Multi-Agent Observability

Architecture: Multi-Agent Observability Pattern
Inspiration: disler/opencode-hooks-multi-agent-observability

🎯 What is OpenCodeKit?

A pre-configured OpenCode distribution featuring:

• 10 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)

# 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 for complete CLI documentation

Option 2: Manual Setup

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

# 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)
  ├→ @oracle (Deep analysis, debugging, architecture review)
  ├→ @librarian (Cross-repo GitHub search, framework internals)
  ├→ @docs (Quick API documentation)
  ├→ @finder (Fast codebase search)
  ├→ @orchestrator (Multi-agent coordination)
  └→ @general (Fallback)

Background Plugins:
  • enforcer (TODO completion enforcement)
  • compactor (Context usage warnings at 70/85/95%)
  • truncator (Dynamic output truncation)

Supporting:
  • 24 Skills (loaded via commands: 8 core, 7 stack, 9 specialized)
  • 45+ Commands (workflow shortcuts, includes /handoff)
  • 5 MCP Services (context7, exa, gkg, gh_grep, figma*) + augment-context-engine
  • Custom Tools (memory-*, observation, ast-grep)
  • Beads task tracking (`bd` CLI for multi-session workflows)
  • 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:

# 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:

# 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:

# 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?
  ✓ → @oracle (complex debugging/architecture)
  ✓ → @librarian (cross-repo GitHub search)
  ✓ → @docs (quick API reference)
  ✓ → @finder (codebase search)

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:

• ✅ 10 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 (6 total: 5 enabled, 1 optional)
• ✅ Background plugins active (enforcer, compactor, truncator)
• ✅ Custom tools available (memory-*, observation, ast-grep)
• ✅ Environment variables set (.opencode/.env with API keys)

🔗 Resources

• OpenCode Docs
• Multi-Agent Pattern
• Handoff Workflow Guide
• MCP Services Setup

📚 Documentation

• CLI Tool: CLI.md - ock command reference (init, setup, agent, skill)
• Architecture Guide: .opencode/AGENTS.md - Global rules and tool priority
• 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
• Templates: .opencode/memory/_templates/ - PRD, observation, and session-summary templates
• Memory Tools: .opencode/tool/ - memory-read, memory-update, memory-search, observation

OpenCodeKit v0.3.0
Architecture: Two-layer (Memory + Beads + Git)
New in v0.3.0: Background plugins (enforcer, compactor, truncator) + ast-grep semantic code tool
Ready for: Daily production use

Enjoy your streamlined agent system with clean phase transitions! 🚀