opencodekit 0.16.17 → 0.16.18

package/README.md

@@ -1,260 +1,95 @@
-# OpenCodeKit - 10-Agent Multi-Agent Observability
+# OpenCodeKit
 
-**Architecture**: Multi-Agent Observability Pattern  
-**Inspiration**: [disler/opencode-hooks-multi-agent-observability](https://github.com/disler/opencode-hooks-multi-agent-observability)
+OpenCodeKit is a Bun + TypeScript CLI and template for running OpenCode with an opinionated multi-agent workflow.
 
----
+## What This Template Includes
 
-## 🎯 What is OpenCodeKit?
+- Beads-first lifecycle: `/create` -> `/start` -> `/ship`
+- Custom agents in `.opencode/agent/` (9 in this template)
+- Slash commands in `.opencode/command/` (14 workflows)
+- Skills in `.opencode/skill/` (large curated library)
+- Custom tools in `.opencode/tool/` (memory tools, `observation`, `swarm`, `context7`, `grepsearch`, etc.)
+- Plugins in `.opencode/plugin/` for memory, session continuity, swarm workflow enforcement, and skill MCP
 
-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. Create new project with npx
-npx opencodekit init my-project
-cd my-project
-
-# 2. Or install globally
-npm install -g opencodekit
-ock init my-project
-```
-
-**See [CLI.md](./CLI.md) for complete CLI documentation**
-
-### Option 2: Manual Setup
+## Quick Start
 
 ```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
+# Scaffold or initialize
+npx opencodekit init
 
-# 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/
+# Or in this repository during development
+bun install
+bun run src/index.ts --help
 ```
 
----
-
-## 🏗️ Architecture
-
+## Core Slash Command Workflow
+
+Use these inside OpenCode:
+
+1. `/create <description>` - create bead and PRD
+2. `/start <bead-id>` - claim bead and prepare branch/workspace
+3. `/ship <bead-id>` - implement, verify, review, close
+
+## Available Slash Commands (Template)
+
+- `/create`
+- `/start`
+- `/ship`
+- `/plan`
+- `/status`
+- `/pr`
+- `/resume`
+- `/handoff`
+- `/research`
+- `/review-codebase`
+- `/verify`
+- `/design`
+- `/ui-review`
+- `/init`
+
+## CLI Command Surface (`ock`)
+
+The packaged CLI commands are:
+
+- `ock init`
+- `ock agent <list|create|view|remove>`
+- `ock command <list|create|show|delete>`
+- `ock config [action]`
+- `ock doctor`
+- `ock status`
+- `ock upgrade`
+- `ock completion [shell]`
+- `ock tui`
+
+See `CLI.md` for command usage details.
+
+## Repository Layout
+
+```text
+src/                  # CLI implementation
+.opencode/            # Agents, commands, skills, tools, plugins
+.beads/               # Task tracking database and artifacts
+build.ts              # Build pipeline (bundles .opencode template)
+dist/                 # Build output (generated)
 ```
-build (Primary Orchestrator - 70% of work)
-  ├→ @rush (Fast agent for simple tasks)
-  ├→ @plan (Complex planning ≥3 phases)
-  ├→ @review (Code review + security + debugging)
-  ├→ @scout (External research, library docs, GitHub patterns)
-  ├→ @explore (Fast codebase search)
-  ├→ @vision (UI/UX, mockups, visual analysis)
-  └→ @general (Fallback)
 
-Background Plugins:
-  • enforcer (TODO completion enforcement)
-  • compactor (Context usage warnings at 70/85/95%)
-  • truncator (Dynamic output truncation)
-
-Supporting:
-  • 30+ Skills (domain expertise loaded on-demand)
-  • 26+ Commands (workflow shortcuts)
-  • 3 MCP Services (context7, exa) + grepsearch tool + skill-embedded MCPs
-  • Custom Tools (memory-*, observation, grepsearch, lsp-*)
-  • 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:
+## Development
 
 ```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
+npm run typecheck
+npm run lint
+npm run test
+npm run build
 ```
 
-**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)
-
-Need speed over depth?
-  ✓ → @rush (fast agent, same capabilities)
-
-Complex task (≥3 phases)?
-  ✓ → @plan (creates implementation plan)
-
-Need research?
-  ✓ → @scout (library docs + GitHub patterns)
-  ✓ → @explore (codebase search)
-
-Quality gate before deployment?
-  ✓ → @review (security + code review + debugging)
-
-UI/UX work?
-  ✓ → @vision (mockups, visual analysis, accessibility)
-
-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:
-
-- ✅ Agent files in place (.opencode/agent/\*.md)
-- ✅ Build handles 70%+ directly
-- ✅ Commands work (/commit, /pr, /design, /fix, /implement)
-- ✅ Skills load on-demand (30+ skills)
-- ✅ Delegation is clear (build → specialized subagents)
-- ✅ `/handoff` creates portable bundles (.opencode/memory/handoffs/)
-- ✅ Tools configured (context7, grepsearch + skill-embedded MCP)
-- ✅ Background plugins active (enforcer, compactor, truncator)
-- ✅ Custom tools available (memory-_, observation, grepsearch, lsp-_)
-- ✅ 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/command/handoff.md)
-- [MCP Services Setup](.opencode/README.md)
-
-## 📚 Documentation
-
-- **CLI Tool**: [CLI.md](./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
+## Documentation
 
----
+- `CLI.md` - `ock` command reference
+- `.opencode/README.md` - project OpenCode configuration guide
+- `.opencode/AGENTS.md` - global agent rules and operating constraints
+- `.opencode/plugin/README.md` - plugin architecture and tooling
 
-**OpenCodeKit v0.13.2**  
-**Architecture**: Two-layer (Memory + Beads + Git)  
-**Package**: `npx opencodekit` to scaffold new projects  
-**New in v0.13.2**: Multimodal support for gemini-claude models (image, PDF input)  
-**Ready for**: Daily production use
+## Notes
 
-Enjoy your streamlined agent system with clean phase transitions!
+- Do not edit `dist/` directly; it is generated by `npm run build`.
+- This repository targets Bun runtime compatibility (`engines.bun >= 1.3.2`).

package/dist/index.js

@@ -759,9 +759,16 @@ var cac = (name = "") => new CAC(name);
 // package.json
 var package_default = {
   name: "opencodekit",
-  version: "0.16.17",
+  version: "0.16.18",
   description: "CLI tool for bootstrapping and managing OpenCodeKit projects",
-  keywords: ["agents", "cli", "mcp", "opencode", "opencodekit", "template"],
+  keywords: [
+    "agents",
+    "cli",
+    "mcp",
+    "opencode",
+    "opencodekit",
+    "template"
+  ],
   license: "MIT",
   author: "OpenCodeKit",
   repository: {
@@ -771,7 +778,10 @@ var package_default = {
   bin: {
     ock: "dist/index.js"
   },
-  files: ["dist", "README.md"],
+  files: [
+    "dist",
+    "README.md"
+  ],
   type: "module",
   publishConfig: {
     access: "public",
@@ -785,6 +795,9 @@ var package_default = {
     typecheck: "tsc --noEmit",
     test: "bun test",
     "test:watch": "bun test --watch",
+    "validate:command-doc": "bun run src/validation/command-doc.ts --check",
+    "validate:docs-drift": "bun run src/validation/docs-drift.ts --check",
+    "validate:governance": "npm run validate:command-doc && npm run validate:docs-drift",
     lint: "oxlint .",
     "lint:fix": "oxlint --fix .",
     format: "oxfmt",
@@ -9258,10 +9271,10 @@ var MODEL_PRESETS = {
     model: "opencode/kimi-k2.5-free",
     agents: {
       build: "github-copilot/claude-opus-4.6",
-      plan: "github-copilot/gpt-5.2-codex",
-      review: "github-copilot/gpt-5.2-codex",
+      plan: "openai/gpt-5.3-codex",
+      review: "openai/gpt-5.3-codex",
       explore: "proxypal/gemini-3-flash-preview",
-      general: "opencode/minimax-m2.1-free",
+      general: "github-copilot/gpt-5.2-codex",
       looker: "proxypal/gemini-3-flash-preview",
       vision: "proxypal/gemini-3-pro-preview",
       scout: "proxypal/gemini-3-flash-preview",