opencodekit 0.0.1

package/README.md

@@ -0,0 +1,258 @@
+# OpenCodeKit - 10-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:
+
+- **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)
+
+```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: 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)
+
+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
+  • 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:
+
+```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?
+  ✓ → @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)
+- ✅ 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 + 6 MCP services + 24 skills system + semantic memory search  
+**Ready for**: Daily production use
+
+Enjoy your streamlined agent system with clean phase transitions! 🚀