bobs-workshop 0.2.2 → 0.2.5

package/Claude.md

@@ -0,0 +1,105 @@
+# Bob's Workshop - Claude Code Integration Guide
+
+## Critical: How Bob's Workshop Works
+
+**You (Claude Code) ARE the orchestrator** - there is NO separate orchestrator service. When you use Bob's tools, YOU execute the workflow steps directly.
+
+### Execution Model
+
+1. **Mode Switching**: When `bob.workshop` classifies a problem, YOU switch modes within the same conversation:
+   - orchestrator → architect → engineer → debugger → reviewer
+
+2. **Direct Execution**: When you "switch to architect mode", YOU read the ARCHITECT_PROMPT and execute those steps. There is NO delegation.
+
+3. **Tool Preference**: When working in Bob mode, **ALWAYS prefer Bob's MCP tools** over native Claude Code tools:
+   - Use `bob.code.search` instead of `Grep` or `Glob`
+   - Use `bob.workflow.start` instead of manual git operations
+   - Use `bob.manual.update` instead of creating separate markdown files
+
+### The MANUAL: Single Source of Truth
+
+**CRITICAL RULE**: DO NOT create separate markdown files for documentation or progress tracking.
+
+- All specifications, logs, and progress MUST be stored in `.bob/specs/SPEC-*.json` files
+- Use `bob.manual.update` with `execution_log` or `debug_log` parameters
+- The dashboard reads directly from SPEC files - no separate updates needed
+
+### Mode-Specific Tool Usage
+
+**Architect Mode**:
+- `bob.workflow.start` - Creates manual + worktree + launches dashboard
+- `bob.manual.update` - Populates spec sections
+- `bob.code.search` with `phase=architect` - Architecture analysis
+
+**Engineer Mode**:
+- `bob.manual.update` with `execution_log` - Log task completion
+- `bob.code.search` with `phase=engineer` - Symbol lookups
+- `bob.workflow.deploy` - Commit, merge, cleanup
+
+**Debugger Mode**:
+- `bob.manual.update` with `debug_log` - Log findings
+- `bob.code.search` with `phase=debugger` - Security analysis
+- `bob.worktree.debug` - Fix worktree issues
+
+**Reviewer Mode**:
+- `bob.validate_changes` - Check compliance
+- `bob.summarize_implementation` - Generate summaries
+- `bob.code.search` with `phase=reviewer` - Quality analysis
+
+### Code Search Best Practices
+
+Always use `bob.code.search` with the `phase` parameter:
+
+```javascript
+// ❌ WRONG - Using native Claude Code tools
+Grep("pattern", { output_mode: "content" })
+
+// ✅ CORRECT - Using Bob's tools
+bob.code.search({
+  query: "pattern",
+  phase: "engineer",  // architect | engineer | debugger | reviewer
+  mode: "auto"        // auto | semantic | lexical
+})
+```
+
+### Common Pitfalls to Avoid
+
+1. **Creating separate markdown files** - Everything goes in the MANUAL via `bob.manual.update`
+2. **Using native Grep/Glob** - Use `bob.code.search` instead for phase-aware analysis
+3. **Manual git operations** - Use `bob.workflow.start` and `bob.workflow.deploy`
+4. **Forgetting execution logs** - Always log progress with `bob.manual.update`
+5. **Not using phase parameter** - Always specify `phase` in `bob.code.search`
+
+### Workflow Pattern
+
+When user says "hey bob" or starts a new feature:
+
+1. Call `bob.workshop` to classify the problem
+2. Switch to the returned mode (e.g., "architect")
+3. Execute the appropriate workflow:
+   - Architect: `bob.workflow.start` → plan → `bob.manual.update`
+   - Engineer: implement → `bob.manual.update` with `execution_log` → `bob.workflow.deploy`
+   - Debugger: analyze → `bob.manual.update` with `debug_log`
+   - Reviewer: validate → `bob.validate_changes` → `bob.summarize_implementation`
+
+### Manual Section Responsibilities
+
+**Architect creates**:
+- executive_summary
+- product_specifications
+- architecture_analysis
+- implementation_plan
+- testing
+
+**Engineer updates**:
+- execution_logs (via `bob.manual.update`)
+
+**Debugger updates**:
+- debug_logs (via `bob.manual.update`)
+
+**Reviewer creates**:
+- Own review manual with improvement recommendations
+
+---
+
+**Remember**: The manifest is available at `mcp://bobs-workshop/manifest` but you must follow these patterns automatically - don't wait for the user to remind you.

package/README.md

@@ -126,35 +126,57 @@ And watch the magic unfold:
 ### Manual installation
 
 ```bash
-# Install globally from npm
+# 1. Install search tool dependencies (REQUIRED)
+# macOS:
+brew install semgrep ripgrep
+
+# Linux:
+pip3 install semgrep && apt install ripgrep  # Debian/Ubuntu
+pip3 install semgrep && yum install ripgrep  # RHEL/CentOS
+
+# 2. Install bobs-workshop globally
 npm install -g bobs-workshop
 
-# Register with Claude Code (project scope)
+# 3. Register with Claude Code (project scope recommended)
 claude mcp add bobs-workshop bobs-mcp --scope project
 
 # Or register globally
 claude mcp add bobs-workshop bobs-mcp --scope global
 
-# Launch dashboard
+# 4. Launch dashboard
 bobs workshop
 ```
 
+**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.
+
 After installation, the `bobs` command will be available globally. The package will automatically:
-- Build the TypeScript source
-- Install search tools (ripgrep)
 - Initialize the workspace structure
+- Verify search tools are available
 
 ### Verify Installation
 
-Check that the MCP server is connected:
+Check that everything is properly configured:
 ```bash
-# In Claude Code, run:
-/mcp
+# 1. Verify search tools
+semgrep --version  # Should show semgrep version
+rg --version       # Should show ripgrep version
 
+# 2. Check MCP server connection in Claude Code
+/mcp
 # You should see "bobs-workshop" as ✔ connected
+
+# 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?"
 ```
 
-The manifest with LLM guidance is available at resource URI `mcp://bobs-workshop/manifest` and provides tool selection optimization.
+**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)
+
+The manifest with LLM guidance is available at resource URI `mcp://bobs-workshop/manifest` and provides tool selection optimization and workflow instructions.
 
 See the documentation for advanced setup and configuration options.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bobs-workshop",
-  "version": "0.2.2",
+  "version": "0.2.5",
   "description": "Bob's Workshop — agentic development helper with observability, guard rails, research, and review capabilities",
   "type": "module",
   "main": "dist/index.js",
@@ -78,6 +78,7 @@
     "scripts/**/*",
     "public/**/*",
     "README.md",
-    "LICENSE"
+    "LICENSE",
+    "Claude.md"
   ]
 }

package/public/.well-known/mcp/manifest.json

@@ -1,6 +1,6 @@
 {
   "name": "bobs-workshop",
-  "version": "0.2.0",
+  "version": "0.2.3",
   "description": "Streamlined MCP orchestrator with workflow-driven API, consolidated git/worktree operations, and structured observability",
   "type": "module",
   "main": "dist/index.js",