bobs workshop - agentic dev harness for OpenCode

using well-stitched OpenCode features for MANUAL-driven development with background agents, to stop juggling between sequential agent calls, scattered context, and endless context switching

Problem statement

you know that feeling when you're deep in a complex feature or when the codebase gets large after adding a few features, and you have to:

• explain your entire codebase ... again
• switch between architecture planning and implementation
• keep track of decisions made 3 conversations ago
• run agents sequentially when they could work in parallel

What if your AI agents could talk to each other, work in parallel, and build lasting knowledge about your project through shared markdown files (MANUALS)?

Table of contents

• What makes this different
• 🌟 Showcase
• 📊 Project statistics
• 🚀 Get started in 2 minutes
• 🔧 Solution overview
• 🎯 Use cases
• 🏗️ Architecture
• 📦 Components

What makes this different

📝 MANUALs that live: Documentation that updates as you build through shared specifications 🧠 Agents that remember: Your project context persists across conversations via MANUAL files 🔄 Workflows that connect: Alice → Bob → Trace workflow in one flow ⚡ Parallel execution: Multiple background agents work simultaneously on different tasks 🎯 Verification built-in: PASS/FAIL verification with Bob ensures quality

🌟 Showcase

🎮 Connections Game

Location: showcase/connections-game

A daily word puzzle game inspired by NYT Connections where players group 4 words that share a common theme.

Daily puzzle interface with 16 words to group into 4 categories

Features Implemented:

• Daily puzzle selection based on date (50+ levels)
• Drag and drop tile rearrangement
• 4 attempts to solve all connections
• Visual feedback (correct, wrong, "one away" hints)
• 4 difficulty levels (yellow → green → blue → purple)
• Responsive design for desktop and mobile
• Touch support for mobile devices

🔮 Cyber Wordle

Location: showcase/cyber-wordle

A cyberpunk-themed Wordle clone with daily puzzles, archive mode, and statistics tracking.

Cyberpunk interface with neon aesthetics and full game controls

Features Implemented:

• 20 cyberpunk-themed word puzzles
• Daily puzzle rotation based on date
• Full archive mode (access any puzzle)
• Statistics tracking (wins, losses, streaks, best scores)
• localStorage for persistent statistics
• Responsive design with mobile support
• Neon cyberpunk visual theme (dark gradients, holographic effects)

Have a cool project? Share it with the community!

🚀 Get started in 2 minutes

The easiest way

npm install bobs-workshop

That's it. The installer:

• ✅ Automatically installs all components
• ✅ Detects conflicts before installation
• ✅ Shows clear error messages if conflicts exist
• ✅ Follows OpenCode's official directory structure

Configure OpenCode

Add bobs-workshop to your opencode.jsonc plugins list:

{
  "$schema": "https://opencode.ai/config.json",
  "plugin": ["bobs-workshop"]
}

Both npm and scoped packages are supported (e.g., @my-org/bobs-workshop).

See it working

Once installed, try your first workflow:

Workflow diagram:

┌─────────────┐     ┌────────────────────┐     ┌────────────────────┐     ┌────────────────────┐     ┌────────────────────-┐     ┌──────────────────┐     ┌──────────────┐
│    USER     │────►│       ALICE        │────►│        BOB         │────►│      BOB-REV       │────►│      TRACE          │────►│     BOB-SEND     │────►│  PRODUCTION  │
│  Creates    │     │    (Architect)     │     │   (Orchestrator)   │     │     (Reviewer)     │     │    (Debugger)       │     │    (Shipper)     │     │              │
│  MANUAL     │     │  ┌──────────────┐  │     │  ┌──────────────┐  │     │  PASS/FAIL         │     │  Root cause         │     │  Build, lint,    │     │              │
└─────────────┘     │  │ backend-     │  │     │  │ testing-     │  │     │  verification      │     │  analysis           │     │  test, verify    │     │              │
                    │  │ explorer     │  │     │  │ patterns     │  │     │  Quality           │     │  Systematic         │     │                  │     │              │
                    │  │ frontend-    │  │     │  │ clean-code   │  │     │  checks            │     │  debugging          │     │                  │     │              │
                    │  │ explorer     │  │     │  │ security     │  │     │                    │     │                     │     │                  │     │              │
                    │  │ database-    │  │     │  └──────┬───────┘  │     │                    │     │                     │     │                  │     │              │
                    │  │ explorer     │  │     │         │          │     │                    │     │                     │     │                  │     │              │
                    │  └──────┬───────┘  │     │         ▼          │     └─────────┬────────-─┘     └─────────┬───────────┘     └──────────────────┘     └──────────────┘
                    │         │          │     │   (if issues)      │               │                          │                          
                    │         ▼          │     │         │          │               │                          │                                        
                    │  ┌─────────────────┴─┐   │         │          │               │                          │                                        
                    │  │ Findings → MANUAL │   │         │          │               │                          │                                        
                    │  └───────────────────┘   │         │          │               │                          │                                        
                    │                          │         │          │               │                          │                                        
                    └──────────────────────────┘         └──────────┴───────────────┴──────────────────────────┘                                        
                                                                              ↳ back to Bob or Bob-Rev                                                   

🔧 Solution overview

MANUAL-driven development methodology: Every feature begins with a comprehensive MANUAL that serves as the single source of truth. This approach ensures architectural consistency and eliminates the traditional disconnect between planning and implementation.

Background execution architecture: Agents run as background tasks, allowing you to continue working while they complete their work. Multiple agents can run simultaneously, dramatically reducing development time through parallel exploration and implementation.

Context persistence through MANUALs: Project knowledge accumulates across conversations through MANUAL files. Unlike traditional AI interactions that lose context, agents build cumulative understanding of your codebase patterns, architectural decisions, and implementation preferences by reading and updating the same MANUAL.

Multi-agent coordination system: Four specialized AI agents work collaboratively within shared MANUAL documents. Alice (architect) plans and coordinates parallel exploration, Bob (orchestrator) implements with skills-based delegation, Bob-Rev (reviewer) provides PASS/FAIL verification, and Bob-Send (shipper) handles build, lint, test, and verification.

Plugin-based tool integration: Six custom tools provide seamless background task management. background_agent launches parallel tasks, background_output collects results, background_cancel manages cleanup, manual_update appends to MANUAL sections, verify_manual runs automated verification, and list_background_tasks provides observability.

🎯 Use cases

• Feature Development: End-to-end feature planning, implementation, and verification with MANUALs
• Architecture Analysis: Deep codebase exploration with parallel agent coordination
• Code Review: Multi-perspective code analysis with specialized review skills
• Documentation: MANUAL-driven documentation generation and maintenance
• Research: Best practice research and technology evaluation through parallel exploration
• Project Planning: Specification-driven development planning with living MANUALs

🏗️ Architecture

Bob's Workshop integrates with OpenCode through:

• Plugin System: Custom tools extend OpenCode's capabilities
• Agent Framework: Five specialized agents for different development phases
• Skill System: Sixteen specialized skills for specific expertise
• Background Execution: Parallel task management without blocking

📦 Components

Core agents (5 total)

Specialized AI agents for different development phases

• alice (Architect) - Planning & MANUAL authoring with parallel exploration coordination
• bob (Orchestrator) - Executes tasks & routes workflow with skills-based delegation
• bob-rev (Reviewer) - PASS/FAIL verification and quality assurance
• trace (Debugger) - Root cause analysis and systematic debugging
• bob-send (Shipper) - Build, lint, test, and verification for production

Core skills (16 total)

Specialized skills that agents can invoke

• Architecture: Architectural decision-making and requirements analysis
• Exploration: LSP-powered codebase exploration and definition tracing
• API-patterns: API design principles (REST vs GraphQL vs tRPC)
• Database-design: Schema design, indexing, ORM selection
• Security: Advanced vulnerability analysis (OWASP 2025, supply chain)
• Testing-patterns: Testing strategies (unit, integration, mocking)
• Clean-code: Pragmatic coding standards - concise, no over-engineering
• Performance: Performance analysis, bottleneck identification
• Frontend-ui-ux: UI/UX design without mockups
• Git-master: Atomic commits, rebase/squash, history search
• Plan-writing: Structured task planning with clear breakdowns
• Brainstorming: Socratic questioning for complex requirements
• Code-review-checklist: Code quality, security, best practices
• Systematic-debugging: 4-phase debugging with evidence-based verification
• Simplification: Optional polish pass - simplify without changing behavior
• Verification: Evidence-based verification methodology

Core tools (6 total)

Custom tools for background task and MANUAL management

• background_agent: Launch background agents for parallel execution
• background_output: Collect results from specific background tasks
• background_cancel: Cancel running background tasks or all tasks
• manual_update: Append content to specific MANUAL sections
• verify_manual: Run automated verification of MANUAL completion
• list_background_tasks: List all running and completed background tasks

File structure after install

.opencode/
├── agents/              # Agent definitions (alice, bob, bob-rev, trace, bob-send)
│   ├── alice.md
│   ├── bob.md
│   ├── bob-rev.md
│   ├── trace.md
│   └── bob-send.md
├── skills/              # 16 specialized skills for agent invocation
│   ├── architecture/SKILL.md
│   ├── exploration/SKILL.md
│   ├── api-patterns/SKILL.md
│   └── ... (16 total skills)
├── tools/bobs-workshop/ # Plugin tools (loaded from npm package)
│   ├── background-agent/
│   ├── manual/
│   └── index.js
└── opencode.jsonc        # Config with plugin reference

The plugin is loaded from npm, so no local plugin file is needed. Just reference "bobs-workshop" in the plugin array.

CLI (Optional)

The CLI provides diagnostic and manual control:

# Diagnostics - check installation status
bobs-workshop doctor

# Note: Installation is fully automatic via `npm install bobs-workshop`
# The CLI is primarily for diagnostics and troubleshooting

Uninstallation

npm uninstall bobs-workshop

Development

# Build tools
npm run build

# Run tests
npm test

# Prepare for publish
npm run prepublishOnly
npm publish

👨‍💻 Author's Stack

Core Infrastructure

• OpenCode - CLI coding interface that makes this workflow possible
• OpenChamber - Multi-agent coordination and orchestration platform
• Tailscale - Seamless phone/laptop interoperability across devices

AI Models

• Kimi K2.5 - Primary model for planning and architecture (Alice, Trace agents)
• MiniMax M2.1 - Primary model for implementation and verification (Bob, Bob-Rev, Bob-Send agents)
• Break-glass Models (via OpenRouter): GPT 5.1, Gemini 3, or Sonnet 4.5

This stack enables efficient, parallel development workflows with robust fallback options and seamless device integration.

📄 License

MIT License - see LICENSE for details.

Ready to stop explaining your project over and over?

npm install bobs-workshop

Then create your first MANUAL and watch Alice, Bob, and Trace work their magic. ✨

Powered by OpenCode and MANUAL-driven development