bobs-workshop 0.3.3 → 3.1.0

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2025 Bob's Workshop - Pawan Raviee
+Copyright (c) 2026 Bob's Workshop Contributors
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal
@@ -18,4 +18,4 @@ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+SOFTWARE.

package/README.md

@@ -1,299 +1,288 @@
-# 🧭 Bob's Workshop MCP — AI-Orchestrated Development that Builds with You
+# bobs workshop - agentic dev harness for OpenCode
 
-*Manual-driven AI development. Intelligent orchestration. Real-time insight.*
+*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*
 
-*From "hey bob, build this" to production-ready code — all in one seamless flow.*
+![Bob's Workshop Banner](assets/bobs-workshop-banner.png)
 
-<img src="assets/web-banner.jpg" alt="Banner" width="60%" />
-
-**Finally, AI development that feels like teamwork.**
-Bob's Workshop MCP turns complex coding workflows into clear, auditable phases — from **architecture planning**, to **implementation**, **debugging**, and **review** — all captured inside a living manual that evolves as you build.
 
 ---
 
-## The problem
-
-Modern AI coding assistants are fast, but not reliable. You've seen it before:
-
-* The model forgets what it planned five minutes ago
-* Code gets out of sync with documentation
-* You have to re-explain context every time
-* Debugs and reviews happen… somewhere, off-record
+## Problem statement
 
-**What if your AI actually worked like a disciplined engineer — asking questions, documenting decisions, and never skipping review?**
+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
 
-That's what Bob's Workshop does.
-
----
+**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
 
-- [🧭 Bob's Workshop MCP — AI-Orchestrated Development that Builds with You](#-bobs-workshop-mcp--ai-orchestrated-development-that-builds-with-you)
-  - [The problem](#the-problem)
-  - [Table of contents](#table-of-contents)
-  - [What makes this different](#what-makes-this-different)
-  - [🧠 How Bob Works](#-how-bob-works)
-  - [📊 Dashboard](#-dashboard)
-  - [🚀 Get started in 2 minutes](#-get-started-in-2-minutes)
-    - [The easiest way](#the-easiest-way)
-    - [Manual installation](#manual-installation)
-  - [🧩 Core Workflows](#-core-workflows)
-  - [⚙️ Tools Overview](#️-tools-overview)
-  - [🏗️ Architecture](#️-architecture)
-  - [🎯 Use cases](#-use-cases)
-  - [📦 Repository structure](#-repository-structure)
-  - [🤝 Contributing](#-contributing)
-  - [📄 License](#-license)
-
----
+- [What makes this different](#what-makes-this-different)
+- [🌟 Showcase](#-showcase)
+- [📊 Project statistics](#-project-statistics)
+- [🚀 Get started in 2 minutes](#-get-started-in-2-minutes)
+- [🔧 Solution overview](#-solution-overview)
+- [🎯 Use cases](#-use-cases)
+- [🏗️ Architecture](#️-architecture)
+- [📦 Components](#-components)
 
 ## What makes this different
 
-🧭 **Manual-first Development** — every task begins with a living manual (JSON file), so plans and code stay in sync
-🔄 **Mode Switching Execution** — Claude Code switches modes (orchestrator → architect → engineer → debugger → reviewer) within a single conversation - no agent delegation
-🧱 **Role-based Intelligence** — Each mode has specialized prompts and tools for architecture, implementation, debugging, or review
-🧠 **Human-in-the-loop Questions** — Bob never assumes; he clarifies until 95% confident
-🔍 **Hybrid Search (3 Engines)** — Intelligent search combining lexical (ripgrep), semantic (semgrep), and structural (AST-based) analysis with phase-aware routing
-📝 **Traceable Workflows** — Every action logged within the manual using bob.manual.update (single source of truth)
-📊 **Visual Dashboard** — Real-time progress, manual state, logs, and diffs — dashboard reads SPEC files directly
-🔧 **Reliable Git Operations** — Industry-standard practices for handling complex filenames and repository states
+📝 **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
 
-## 🧠 How Bob Works
+### 🎮 Connections Game
 
-> "Hey Bob, build me a new onboarding flow."
+**Location**: [`showcase/connections-game`](showcase/connections-game)
 
-When you say "hey bob", **Claude Code switches to orchestrator mode** and builds a full lifecycle around your request:
+A daily word puzzle game inspired by NYT Connections where players group 4 words that share a common theme.
 
-**🔄 Mode Switching Model**
-Bob's Workshop uses a **mode switching** approach — Claude Code is a single conversation that transitions between modes:
+![Connections Game](assets/connections-game.png)
+*Daily puzzle interface with 16 words to group into 4 categories*
 
-1. **Orchestrator Mode** — classifies your problem using `bob.workshop`
-2. **Architect Mode** — Claude switches to architect, drafts the plan, identifies edge cases, asks clarifying questions
-3. **Engineer Mode** — Claude switches to engineer, implements step-by-step, runs tests, and records progress
-4. **Debugger Mode** — Claude switches to debugger, investigates errors using hybrid search before proposing fixes
-5. **Reviewer Mode** — Claude switches to reviewer, audits security, quality, and architecture before final approval
+**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
 
-> **Important:** There is no agent delegation. Claude Code **IS** the orchestrator/architect/engineer/debugger/reviewer. It switches modes and executes directly.
+---
 
-All changes are tracked in a **Manual** (JSON file stored in `.bob/specs/SPEC-*.json`), which serves as the single source of truth — capturing specifications, execution logs, and debug findings.
+### 🔮 Cyber Wordle
 
----
+**Location**: [`showcase/cyber-wordle`](showcase/cyber-wordle)
 
-## 📊 Dashboard
+A cyberpunk-themed Wordle clone with daily puzzles, archive mode, and statistics tracking.
 
-![Bob's MCP Dashboard](assets/bobs-dashboard.jpg)
-*A real-time view of your manuals, worktrees, and logs.*
+![Cyber Wordle](assets/cyber-wordle.png)
+*Cyberpunk interface with neon aesthetics and full game controls*
 
-* 🧾 **Manual List** — track every task from draft to deployed
-* 🔄 **Live Sync** — see updates appear as Bob works
-* 🧠 **Role Insights** — understand what each agent is doing
-* 🧩 **Diff Viewer** — inspect file changes and LOC stats
-* 🧪 **Test Status** — know when your work passes validation
+**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
 
-Ask Claude Code:
+```bash
+npm install bobs-workshop
+```
 
-> **"Install Bob's Workshop MCP for me from npm"**
+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
 
-Claude will:
+### See it working
 
-* Install and configure Bob's Workshop MCP
-* Register tools & prompts
-* Launch the dashboard
+Once installed, try your first workflow:
 
-Then just type:
+**Workflow diagram**:
 
-```bash
-hey bob, create an API for project management
+```
+┌─────────────┐     ┌────────────────────┐     ┌────────────────────┐     ┌────────────────────┐     ┌────────────────────-┐     ┌──────────────────┐     ┌──────────────┐
+│    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                                                   
 ```
 
-And watch the magic unfold:
+## 🔧 Solution overview
 
-* Architect asks clarifying questions
-* Engineer implements with logs
-* Reviewer checks quality
-* Dashboard tracks everything in real-time
+**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.
 
-### Manual installation
+**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.
 
-```bash
-# 1. Install search tool dependencies (REQUIRED)
-# macOS:
-brew install semgrep ripgrep
+**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.
 
-# Linux:
-pip3 install semgrep && apt install ripgrep  # Debian/Ubuntu
-pip3 install semgrep && yum install ripgrep  # RHEL/CentOS
+**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.
 
-# 2. Install bobs-workshop globally
-npm install -g bobs-workshop
+## 🎯 Use cases
 
-# 3. Register with Claude Code (project scope recommended)
-claude mcp add bobs-workshop bobs-mcp --scope project
+- **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
 
-# Or register globally
-claude mcp add bobs-workshop bobs-mcp --scope global
+## 🏗️ Architecture
 
-# 4. Launch dashboard
-bobs workshop
-```
+Bob's Workshop integrates with OpenCode through:
 
-**Important:** Search tools (semgrep & ripgrep) must be installed **before** using Bob's MCP. The package will attempt to auto-install semgrep during `npm install`, but manual installation is more reliable.
+- **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
 
-After installation, the `bobs` command will be available globally. The package will automatically:
-- Initialize the workspace structure
-- Verify search tools are available
+## 📦 Components
 
-### Verify Installation
+### Core agents (5 total)
 
-Check that everything is properly configured:
-```bash
-# 1. Verify search tools
-semgrep --version  # Should show semgrep version
-rg --version       # Should show ripgrep version
+**Specialized AI agents for different development phases**
 
-# 2. Check MCP server connection in Claude Code
-/mcp
-# You should see "bobs-workshop" as ✔ connected
+- **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
 
-# 3. Verify manifest is loaded (in Claude Code)
-# The manifest provides critical LLM guidance for tool usage
-# Ask Claude: "Can you read the bobs-workshop manifest?"
-```
+### Core skills (16 total)
 
-**Troubleshooting:** If Claude Code doesn't follow Bob's workflow patterns religiously:
-1. Ensure search tools are installed: `semgrep --version && rg --version`
-2. Restart Claude Code to reload the MCP server
-3. Verify manifest resource is accessible: Ask Claude to read `mcp://bobs-workshop/manifest`
-4. Check `.mcp.json` uses `bobs-mcp` command (not local path)
+**Specialized skills that agents can invoke**
 
-The manifest with LLM guidance is available at resource URI `mcp://bobs-workshop/manifest` and provides tool selection optimization and workflow instructions.
+- **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
 
-See the documentation for advanced setup and configuration options.
+### Core tools (6 total)
 
----
+**Custom tools for background task and MANUAL management**
 
-## 🧩 Core Workflows
+- **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
 
-| Workflow                      | Description                                          |
-| ----------------------------- | ---------------------------------------------------- |
-| **bob.workshop**              | Classifies problem and returns mode to switch to (architect/engineer/debugger/reviewer) |
-| **bob.workflow.start**        | Creates new manual + worktree + dashboard session    |
-| **bob.workflow.deploy**       | Commits changes, merges to main, cleans up worktree  |
-| **bob.code.search**           | Phase-aware hybrid search (ripgrep + semgrep)        |
-| **bob.manual.update**         | Updates manual sections with execution/debug logs (single source of truth for activity logging) |
-| **bob.validate.changes**      | Diff validation and spec compliance                  |
-| **bob.summarize.implementation** | Generate implementation summaries                 |
-| **bob.dashboard.launch**      | Launch web dashboard (port 4577) - reads SPEC files directly |
+### File structure after install
 
----
+```
+.opencode/
+├── agents/              # Flat structure (per OpenCode docs)
+│   ├── alice.md
+│   ├── bob.md
+│   ├── bob-rev.md
+│   ├── trace.md
+│   └── bob-send.md
+├── skills/              # Flat structure (per OpenCode docs)
+│   ├── architecture/SKILL.md
+│   ├── exploration/SKILL.md
+│   ├── api-patterns/SKILL.md
+│   └── ... (16 total skills)
+├── tools/bobs-workshop/  # Namespaced tools
+│   ├── background-agent/
+│   ├── manual/
+│   └── index.js
+├── plugins/bobs-workshop/ # Namespaced plugin
+│   └── plugin.js
+└── opencode.jsonc        # Merged agent configs
+```
 
-## ⚙️ Tools Overview
-
-| Tool                              | Description                                     |
-| --------------------------------- | ----------------------------------------------- |
-| 🧭 `bob.workshop`                 | Problem classifier — analyzes request and returns which mode to switch to |
-| 🧱 `bob.manual.create` / `update` / `get` / `list` | Manage manual JSON files (create, update sections, retrieve, list all) |
-| 🔍 `bob.code.search`              | 3-engine hybrid search: lexical (ripgrep), semantic (semgrep), structural (AST-based). Auto-routes based on query type and phase (architect/engineer/debugger/reviewer) |
-| ✅ `bob.validate.changes`          | Verify changes match manual expectations        |
-| 📊 `bob.dashboard.launch`         | Launch web dashboard on port 4577 (reads SPEC files directly) |
-| 🌳 `bob.worktree.debug`           | Advanced worktree maintenance (repair, cleanup, validate, status) |
-| 🚀 `bob.workflow.start`           | Bootstrap workflow: create manual + worktree + launch dashboard |
-| 🎯 `bob.workflow.deploy`          | Complete feature: commit + merge to main + cleanup worktree |
-| 📝 `bob.summarize.implementation` | Generate comprehensive implementation summaries |
-| 🐛 `bob.debug`                    | Debug server state and troubleshoot issues      |
 
----
+## CLI (Optional)
 
-## 🏗️ Architecture
+The CLI provides diagnostic and manual control:
 
-![Bob's MCP Architecture](assets/bobs-architecture.jpg)
-*A simple, composable structure built on MCP principles.*
+```bash
+# Diagnostics - check installation status
+bobs-workshop doctor
 
-* **MCP Server** — exposes tools & prompts via Model Context Protocol
-* **Mode Switching** — Claude Code switches between orchestrator/architect/engineer/debugger/reviewer modes within a single conversation
-* **CLI Interface** — `bobs` command for workflows, health checks, and maintenance
-* **Worktrees** — isolated git branches per manual for parallel development
-* **Dashboard** — visual orchestration view that reads SPEC files directly from `.bob/specs/`
-* **Prompts** — mode-specific instructions that Claude executes directly (ORCHESTRATOR_PROMPT, ARCHITECT_PROMPT, ENGINEER_PROMPT, DEBUGGER_PROMPT, REVIEWER_PROMPT)
-* **Manuals** — JSON files (`.bob/specs/SPEC-*.json`) capturing full context, decisions, execution logs, and debug findings as single source of truth
+# Note: Installation is fully automatic via `npm install bobs-workshop`
+# The CLI is primarily for diagnostics and troubleshooting
+```
 
----
+## Uninstallation
 
-## 🎯 Use cases
+```bash
+npm uninstall bobs-workshop
+```
 
-* 🧠 **Feature planning** — plan & clarify complex features before coding
-* 🧱 **Implementation** — build with discipline & step-by-step logs
-* 🔍 **Debugging** — research & resolve issues transparently
-* 🔒 **Code review** — security, performance, and quality audits
-* 🧾 **Documentation** — living specs that evolve as you code
-* 🧰 **Tool orchestration** — unify AI, search, and validation tools under one flow
+All files and configs are removed automatically.
 
----
+## Development
+
+```bash
+# Build tools
+npm run build
 
-## 📦 Repository structure
+# Run tests
+npm test
 
-```
-bobs-workshop/
-├── README.md                # You're here
-├── src/
-│   ├── index.ts            # MCP server bootstrap
-│   ├── tools/              # MCP tool implementations
-│   ├── cli/                # CLI command modules
-│   ├── dashboard/          # Web dashboard server
-│   ├── services/           # Core services (logging, validation, etc.)
-│   ├── utils/              # Utility functions and helpers
-│   └── prompts/            # Role prompts (Architect, Engineer, Reviewer, Debugger)
-├── bin/
-│   └── bobs-mcp.js         # CLI entry point
-├── scripts/                # Installation and setup scripts
-├── dist/                   # Compiled JavaScript output
-├── public/                 # Dashboard frontend assets
-├── tests/                  # Test suites
-└── .bob/                   # Workshop data storage
-    ├── specs/              # Manual JSON files
-    └── worktrees/          # Worktree metadata
+# Prepare for publish
+npm run prepublishOnly
+npm publish
 ```
 
----
+## 👨‍💻 Author's Stack
 
-## 🤝 Contributing
+**Core Infrastructure**
+- **[OpenCode](https://opencode.ai)** - CLI coding interface that makes this workflow possible
+- **[OpenChamber](https://github.com/pwnk77/openchamber)** - Multi-agent coordination and orchestration platform
+- **[Tailscale](https://tailscale.com)** - Seamless phone/laptop interoperability across devices
 
-1. Fork the repository
-2. Create a feature branch (`git checkout -b feat/improvement`)
-3. Add / enhance tools, prompts, or workflows
-4. Test via Claude Code or MCP CLI
-5. Submit a pull request with a clear changelog
+**AI Models**
+- **GLM-4.7** - 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](./LICENSE)
+MIT License - see [LICENSE](./LICENSE) for details.
 
 ---
 
-**Tired of re-explaining your project every session?**
-Just say: **"Hey Bob, build this feature for me."**
-
-Bob will architect it, engineer it, test it, review it —
-and keep your documentation up to date. ✨
+**Ready to stop explaining your project over and over?**
 
----
+```bash
+npm install bobs-workshop
+```
 
-*Built with ♥️ for developers who value clarity, traceability, and craftsmanship.*
-*Powered by [Model Context Protocol](https://modelcontextprotocol.io/) and [Claude Code](https://claude.ai/code)*
+Then create your first MANUAL and watch Alice, Bob, and Trace work their magic. ✨
 
 ---
 
-[![npm version](https://badge.fury.io/js/bobs-workshop.svg)](https://badge.fury.io/js/bobs-workshop)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+*Powered by [OpenCode](https://opencode.ai) and MANUAL-driven development*

package/bin/bobs-workshop.js

@@ -0,0 +1,109 @@
+#!/usr/bin/env node
+
+import { readFileSync, writeFileSync, existsSync, rmSync } from 'fs';
+import { join } from 'path';
+import { parse, print } from 'jsonc-parser';
+
+const commands = ['install', 'uninstall', 'doctor'];
+const args = process.argv.slice(2);
+const command = args[0];
+
+if (!command || !commands.includes(command)) {
+  console.log('bobs-workshop CLI');
+  console.log('');
+  console.log('Usage:');
+  console.log('  bobs-workshop install [--force-merge] [--no-config]');
+  console.log('  bobs-workshop uninstall [--clean]');
+  console.log('  bobs-workshop doctor');
+  console.log('');
+  process.exit(0);
+}
+
+function install(opts = {}) {
+  console.log('🔧 Installing bobs-workshop (manual)...');
+
+  const projectRoot = process.cwd();
+  const opencodeDir = join(projectRoot, '.opencode');
+  const configPath = join(opencodeDir, 'opencode.jsonc');
+
+  if (!existsSync(configPath)) {
+    console.log('ℹ️  No opencode.jsonc found. Run npm install bobs-workshop first.');
+    return;
+  }
+
+  if (opts.forceMerge) {
+    console.log('⚠️  Force merging agent configs (will overwrite existing)');
+  }
+
+  if (opts.noConfig) {
+    console.log('⏭️  Skipping config merge');
+    return;
+  }
+
+  console.log('✅ Manual install complete');
+}
+
+function uninstall(opts = {}) {
+  console.log('🗑️  Uninstalling bobs-workshop (manual)...');
+
+  if (opts.clean) {
+    console.log('🗑️  Removing all bobs-workshop files and configs');
+
+    const projectRoot = process.cwd();
+    const opencodeDir = join(projectRoot, '.opencode');
+
+    const dirsToRemove = [
+      join(opencodeDir, 'plugins/bobs-workshop'),
+      join(opencodeDir, 'agent/bobs-workshop'),
+      join(opencodeDir, 'skill/bobs-workshop')
+    ];
+
+    dirsToRemove.forEach(dir => {
+      if (existsSync(dir)) {
+        rmSync(dir, { recursive: true, force: true });
+        console.log(`🗑️  Removed: ${dir}`);
+      }
+    });
+  }
+
+  console.log('✅ Manual uninstall complete');
+}
+
+function doctor() {
+  console.log('🏥 Running bobs-workshop diagnostics...');
+
+  const projectRoot = process.cwd();
+  const opencodeDir = join(projectRoot, '.opencode');
+
+  const checks = [
+    { path: opencodeDir, name: '.opencode directory' },
+    { path: join(opencodeDir, 'opencode.jsonc'), name: 'Config file' },
+    { path: join(opencodeDir, 'plugins/bobs-workshop'), name: 'Plugin directory' },
+    { path: join(opencodeDir, 'agent/bobs-workshop'), name: 'Agent directory' },
+    { path: join(opencodeDir, 'skill/bobs-workshop'), name: 'Skill directory' },
+  ];
+
+  checks.forEach(check => {
+    const exists = existsSync(check.path);
+    console.log(`${exists ? '✅' : '❌'} ${check.name}`);
+  });
+}
+
+const flags = args.slice(1);
+const opts = {
+  forceMerge: flags.includes('--force-merge'),
+  noConfig: flags.includes('--no-config'),
+  clean: flags.includes('--clean')
+};
+
+switch (command) {
+  case 'install':
+    install(opts);
+    break;
+  case 'uninstall':
+    uninstall(opts);
+    break;
+  case 'doctor':
+    doctor();
+    break;
+}