MANUAL-driven development with background agents for OpenCode
npm install bobs-workshopusing well-stitched OpenCode features for MANUAL-driven development with background agents, to stop juggling between sequential agent calls, scattered context, and endless context switching
---
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)?
- What makes this different
- š Showcase
- š Project statistics
- š Get started in 2 minutes
- š§ Solution overview
- šÆ Use cases
- šļø Architecture
- š¦ Components
š 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
Location: showcase/connections-game
A daily word puzzle game inspired by NYT Connections where players group 4 words that share a common theme.
!Connections Game
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
---
Location: showcase/cyber-wordle
A cyberpunk-themed Wordle clone with daily puzzles, archive mode, and statistics tracking.
!Cyber Wordle
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!
``bash`
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
Add bobs-workshop to your opencode.jsonc plugins list:
`json`
{
"$schema": "https://opencode.ai/config.json",
"plugin": ["bobs-workshop"]
}
Both npm and scoped packages are supported (e.g., @my-org/bobs-workshop).
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
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.
- 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
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
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
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
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
``
.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.
The CLI provides diagnostic and manual control:
`bashDiagnostics - check installation status
bobs-workshop doctor
Uninstallation
`bash
npm uninstall bobs-workshop
`Development
`bash
Build tools
npm run buildRun tests
npm testPrepare 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?
`bash
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