bobs-workshop 0.3.3 → 3.1.1

package/src/tools/manual/manual-update.ts

@@ -0,0 +1,197 @@
+import { tool, type ToolDefinition } from "@opencode-ai/plugin/tool";
+
+const MANUAL_TEMPLATE = `# 📘 MANUAL: [Feature Name]
+
+> Created: MAN-YYMMDD-[feature-name].md
+
+## 📊 Executive Summary
+
+High-level overview of what we're building and why.
+
+**Example:**
+- What problem does this solve?
+- Who are the users?
+- What's the success criteria?
+- What are the core features?
+
+---
+
+## 📝 Product Specifications
+
+Detailed requirements and acceptance criteria.
+
+**Example:**
+- User stories / Use cases
+- Functional requirements
+- Non-functional requirements (performance, security, etc.)
+- Edge cases and error handling
+- Success metrics
+
+---
+
+## 🏗️ Architecture Analysis
+
+Technical design decisions and system architecture.
+
+**Example:**
+- System diagram / architecture overview
+- Data models and schemas
+- API endpoints and contracts
+- Database design (indexes, relationships)
+- Authentication/authorization approach
+- Technology choices and trade-offs
+- Security considerations
+
+---
+
+## 🚀 Implementation Plan
+
+Breakdown of tasks with dependencies.
+
+**Example:**
+1. Setup and scaffolding
+2. Database schema migrations
+3. Core business logic
+4. API endpoint implementation
+5. Frontend components
+6. Integration testing
+7. Documentation
+
+Mark completed tasks with ✅, in-progress with 🔄, blocked with 🚫
+
+---
+
+## 📈 Execution Logs
+
+Chronological progress as tasks are completed.
+
+**Format:**
+\`\`\`
+[YYYY-MM-DD HH:MM] - Agent: task description
+  - Output: results / artifacts
+  - Files modified: list of files
+  - Dependencies: what blocked this or what it enables
+\`\`\`
+
+---
+
+## 🔍 Review Notes
+
+Findings from code reviews, architectural reviews, or peer reviews.
+
+**Example:**
+- Code quality observations
+- Performance concerns
+- Security vulnerabilities
+- Suggestions for improvements
+- Action items from reviews
+
+---
+
+## 🐛 Debug Logs
+
+Troubleshooting sessions and root cause analysis.
+
+**Format:**
+\`\`\`
+[YYYY-MM-DD HH:MM] - Issue description
+  - Symptoms: what went wrong
+  - Investigation: steps taken
+  - Root cause: underlying problem
+  - Resolution: fix applied
+  - Prevention: how to avoid recurrence
+\`\`\`
+
+---
+
+## ✅ Verification Logs
+
+Test results and quality assurance checks.
+
+**Example:**
+- Unit test results
+- Integration test results
+- E2E test results
+- Performance benchmarks
+- Security scan results
+- Manual QA checklists
+
+Each verification should include:
+- PASS/FAIL status
+- Evidence (screenshots, logs, metrics)
+- Coverage percentage
+- Blockers for release
+
+---
+
+## 🤝 Agent Handoffs
+
+Context transfers between different agents.
+
+**Format:**
+\`\`\`
+[YYYY-MM-DD HH:MM] - alice → bob
+  - Context: architectural decisions, design docs
+  - Artifacts: MAN-xxx.md, schema.sql
+  - Next steps: implement authentication flow
+\`\`\`
+
+This ensures smooth handoffs between agents and maintains continuity across sessions.
+`;
+
+const ManualUpdateTool: ToolDefinition = tool({
+  description: "Update a specific section in a MANUAL file. Creates file/section if missing.",
+  args: {
+    manual_path: tool.schema.string().describe("Path to MANUAL file (e.g., manuals/MAN-260127-auth.md)"),
+    section: tool.schema.string().describe("Section header to update (e.g., '📊 Executive Summary', '📈 Execution Logs')"),
+    content: tool.schema.string().describe("Content to append to the section"),
+    create_if_missing: tool.schema.boolean().default(true)
+      .describe("Create section if it doesn't exist (default: true)"),
+  },
+  async execute(args) {
+    const { readFileSync, writeFileSync, existsSync, mkdirSync } = await import("node:fs");
+    const { dirname } = await import("node:path");
+    
+    const manualPath = args.manual_path;
+    
+    if (!manualPath.match(/^manuals\/MAN-\d{6}-.+\.md$/)) {
+      return `❌ Invalid path. Expected format: manuals/MAN-YYMMDD-<feature>.md`;
+    }
+    
+    const manualsDir = dirname(manualPath);
+    if (!existsSync(manualsDir)) {
+      mkdirSync(manualsDir, { recursive: true });
+    }
+    
+    let content = "";
+    if (existsSync(manualPath)) {
+      content = readFileSync(manualPath, "utf8");
+    } else {
+      content = MANUAL_TEMPLATE;
+      writeFileSync(manualPath, content, "utf8");
+    }
+    
+    const lines = content.split('\n');
+    let sectionIndex = lines.findIndex(l => l.trim() === args.section);
+    
+    if (sectionIndex === -1) {
+      if (!args.create_if_missing) {
+        return `❌ Section '${args.section}' not found in ${manualPath}`;
+      }
+      content = `${content}\n${args.section}\n${args.content}\n`;
+    } else {
+      const insertPosition = sectionIndex + 1;
+      if (lines[insertPosition] && !lines[insertPosition].startsWith('##')) {
+        lines[insertPosition] = `${lines[insertPosition]}\n${args.content}`;
+      } else {
+        lines.splice(insertPosition, 0, args.content);
+      }
+      content = lines.join('\n');
+    }
+    
+    writeFileSync(manualPath, content, "utf8");
+    return `✅ Updated section '${args.section}' in ${manualPath}`;
+  },
+});
+
+export default ManualUpdateTool;

package/src/tools/manual/verify-manual.ts

@@ -0,0 +1,60 @@
+import { tool, type ToolDefinition } from "@opencode-ai/plugin/tool";
+
+const VerifyManualTool: ToolDefinition = tool({
+  description: "Run bob-rev verification in background for a MANUAL",
+  args: {
+    manual_path: tool.schema.string().describe("Path to MANUAL file (e.g., manuals/MAN-260127-auth.md)"),
+  },
+  async execute(args, context) {
+    const { client, directory, sessionID } = context as unknown as { client: unknown; directory: string; sessionID: string };
+    
+    const createResult = await (client as { session: { create: (args: unknown) => Promise<unknown> } }).session.create({
+      body: {
+        parentID: sessionID,
+        title: `Verification: ${args.manual_path.split('/').pop()}`,
+      },
+      query: { directory },
+    });
+    
+    const createData = createResult as { data: { id: string }; error?: string };
+    if (createData.error) {
+      throw new Error(`Failed to create verification session: ${createData.error}`);
+    }
+    
+    const { readFileSync, existsSync } = await import("node:fs");
+    const { join } = await import("node:path");
+    
+    let manualContent = "";
+    if (existsSync(args.manual_path)) {
+      manualContent = readFileSync(args.manual_path, "utf8");
+      // Sanitize content to prevent JSON parsing issues with kimi model
+      manualContent = manualContent
+        .replace(/[\x00-\x08\x0B-\x0C\x0E-\x1F]/g, '') // Remove control chars except \n, \r, \t
+        .replace(/\u2028/g, '\n') // Replace line separator with newline
+        .replace(/\u2029/g, '\n'); // Replace paragraph separator with newline
+    }
+    
+    const skillPath = join(directory, ".opencode", "agent", "bobs-workshop", "bob-rev.md");
+    let agentPrompt = "You are bob-rev, a reviewer agent that verifies implementation against MANUAL requirements.";
+    if (existsSync(skillPath)) {
+      agentPrompt = readFileSync(skillPath, "utf8");
+    }
+    
+    await (client as { session: { prompt: (args: unknown) => Promise<unknown> } }).session.prompt({
+      path: { id: createData.data.id },
+      body: {
+        agent: "bob-rev",
+        system: `${agentPrompt}\n\n## MANUAL to Verify:\n${manualContent}`,
+        tools: {
+          task: false,
+          delegate_task: false,
+        },
+        parts: [{ type: "text", text: "Verify this MANUAL and provide PASS/FAIL decision with reasoning." }],
+      },
+    });
+    
+    return `✅ Started verification for ${args.manual_path} in session ${createData.data.id}`;
+  },
+});
+
+export default VerifyManualTool;

package/uninstall.js

@@ -0,0 +1,64 @@
+import { readFileSync, writeFileSync, existsSync, rmSync } from 'fs';
+import { join } from 'path';
+import jsonc, { parse } from 'jsonc-parser';
+
+function uninstall() {
+  const projectRoot = process.cwd();
+  const opencodeDir = join(projectRoot, '.opencode');
+
+  console.log('🗑️  Uninstalling bobs-workshop...');
+
+  const skillNames = ['architecture', 'exploration', 'api-patterns',
+    'brainstorming', 'clean-code', 'code-review-checklist',
+    'database-design', 'frontend-ui-ux', 'git-master',
+    'performance', 'plan-writing', 'security', 'simplification',
+    'systematic-debugging', 'testing-patterns', 'verification'];
+
+  const dirsToRemove = [
+    join(opencodeDir, 'plugins/bobs-workshop'),
+    join(opencodeDir, 'tools/bobs-workshop'),
+    ...skillNames.map(s => join(opencodeDir, 'skills', s))
+  ];
+
+  dirsToRemove.forEach(dir => {
+    if (existsSync(dir)) {
+      rmSync(dir, { recursive: true, force: true });
+      console.log(`🗑️  Removed: ${dir}`);
+    }
+  });
+
+  const configPath = join(opencodeDir, 'opencode.jsonc');
+  if (existsSync(configPath)) {
+    try {
+      const config = parse(readFileSync(configPath, 'utf8'));
+      const agentNames = ['alice', 'bob', 'bob-eng', 'bob-rev', 'trace', 'bob-send'];
+
+      if (config.agent) {
+        let removedCount = 0;
+        agentNames.forEach(name => {
+          if (config.agent[name]) {
+            delete config.agent[name];
+            console.log(`🗑️  Removed agent config: ${name}`);
+            removedCount++;
+          }
+        });
+
+        if (removedCount > 0) {
+          const newConfig = JSON.stringify(config, null, 2);
+          writeFileSync(configPath, newConfig);
+        }
+      }
+    } catch (err) {
+      console.warn(`⚠️  Could not update opencode.jsonc: ${err.message}`);
+    }
+  }
+
+  console.log('✅ bobs-workshop uninstalled successfully!');
+}
+
+try {
+  uninstall();
+} catch (error) {
+  console.error('❌ Uninstallation failed:', error.message);
+  process.exit(1);
+}

package/Claude.md

@@ -1,162 +0,0 @@
-# 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 (default: 30 ranked results)
-bob.code.search({
-  query: "pattern",
-  phase: "engineer",  // architect | engineer | debugger | reviewer
-  mode: "auto"        // auto | semantic | lexical | structural
-})
-
-// ✅ STRUCTURAL SEARCH - AST-based symbol analysis (TypeScript/JavaScript)
-bob.code.search({
-  query: "find references to UserService",  // Auto-routes to structural mode
-  phase: "engineer",
-  mode: "auto"
-})
-
-bob.code.search({
-  query: "show dependencies for src/api/auth.ts",  // Dependency analysis
-  phase: "architect",
-  mode: "auto"
-})
-
-bob.code.search({
-  query: "find circular dependencies",  // Architecture health check
-  phase: "architect",
-  mode: "auto"
-})
-
-bob.code.search({
-  query: "find unused exports",  // Code cleanup
-  phase: "engineer",
-  mode: "auto"
-})
-
-// ✅ SEMANTIC SEARCH - Multi-word conceptual queries
-bob.code.search({
-  query: "authentication user session management",  // 3+ words auto-routes to semantic
-  phase: "architect",
-  mode: "auto"
-})
-
-// ✅ FOR DEBUGGING - Verbose mode includes full result arrays
-bob.code.search({
-  query: "pattern",
-  phase: "engineer",
-  verbose: true  // Increases token usage but useful for debugging
-})
-```
-
-**Search Configuration:**
-- **Default limits**: 30 results, 5 matches per file (optimized for token efficiency)
-- **Relevance ranking**: Results sorted by file priority (src/ > lib/ > test/), semantic boost, git recency
-- **Token efficiency**: ~70-80% reduction vs previous version (3-5k tokens vs 15-20k)
-- **Output format**: Scored `results` array with relevance scores
-
-**Query Pattern Notes:**
-- **Structural queries**: Patterns like "find references to X", "show dependencies", "find circular dependencies" auto-route to AST-based analysis (TypeScript/JavaScript only)
-- **Single/two words**: Treated as lexical patterns (exact match or regex)
-- **Three or more words**: Automatically routed to semantic search in auto mode for architect/debugger/reviewer phases
-- **Semantic search unavailable**: Falls back to lexical OR search (matches any word)
-- **Force modes**: Use `mode: "lexical"`, `mode: "semantic"`, or `mode: "structural"` for explicit routing
-
-**Advanced Options:**
-- `maxHits`: Override default 30 (e.g., maxHits: 50 for broader search)
-- `perFileLimit`: Override default 5 per-file limit
-- `verbose`: Include full lexicalHits/semanticHits arrays (debugging only)
-
-### 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/bin/bobs-mcp-server.js

@@ -1,11 +0,0 @@
-#!/usr/bin/env node
-
-// MCP Server entry point for Bob's Workshop
-import { fileURLToPath } from 'url';
-import { dirname, join } from 'path';
-
-const __filename = fileURLToPath(import.meta.url);
-const __dirname = dirname(__filename);
-
-// Load and start the MCP server
-const serverModule = await import('../dist/index.js');

package/bin/bobs-mcp.js

@@ -1,130 +0,0 @@
-#!/usr/bin/env node
-
-import { fileURLToPath } from 'url';
-import { dirname, join } from 'path';
-import { readFile } from 'fs/promises';
-
-const __filename = fileURLToPath(import.meta.url);
-const __dirname = dirname(__filename);
-
-// Import CLI modules
-async function loadCliModule(modulePath) {
-  try {
-    const module = await import(modulePath);
-    return module;
-  } catch (error) {
-    console.error(`Failed to load CLI module: ${error.message}`);
-    process.exit(1);
-  }
-}
-
-async function showHelp() {
-  console.log(`
-🔧 Bob's Workshop - Agentic Development Helper
-
-Usage:
-  bobs [command] [options]
-
-Commands:
-  workshop        Launch Bob's Workshop dashboard
-  health          Check system health and component status
-  cleanup         Perform system cleanup and maintenance
-  debug           Show debug information and system state
-  --check, -c     Check installation and system requirements
-  --setup, -s     Generate MCP configuration for Claude Code
-  --help, -h      Show this help message
-  --version, -v   Show version information
-
-Examples:
-  bobs workshop       # Launch Bob's Workshop dashboard
-  bobs health         # Check system health
-  bobs cleanup        # Clean up stale resources
-  bobs cleanup --stats # Show cleanup statistics
-  bobs debug          # Show debug information
-  bobs --check        # Check if everything is working
-  bobs --setup        # Generate Claude Code MCP configuration
-  bobs                # Run installation check (default)
-
-For more information, visit: https://github.com/your-org/bobs-workshop
-  `);
-}
-
-async function showVersion() {
-  try {
-    const packagePath = join(__dirname, '../package.json');
-    const packageData = JSON.parse(await readFile(packagePath, 'utf8'));
-    console.log(`Bob's MCP v${packageData.version}`);
-  } catch (error) {
-    console.log('Bob\'s MCP (version unavailable)');
-  }
-}
-
-async function main() {
-  const args = process.argv.slice(2);
-
-  // Parse command line arguments
-  const command = args[0];
-
-  switch (command) {
-    case 'workshop':
-      console.log('🔧 Launching Bob\'s Workshop dashboard...\n');
-      const workshopModule = await loadCliModule('../dist/cli/workshop.js');
-      await workshopModule.runWorkshop();
-      break;
-
-    case 'health':
-      console.log('🔧 Running Bob\'s Workshop health check...\n');
-      const healthModule = await loadCliModule('../dist/cli/health.js');
-      await healthModule.runHealthCheck();
-      break;
-
-    case 'cleanup':
-      console.log('🔧 Running Bob\'s Workshop cleanup...\n');
-      const cleanupModule = await loadCliModule('../dist/cli/cleanup.js');
-      const cleanupOptions = cleanupModule.parseCleanupArgs(args.slice(1));
-      await cleanupModule.runCleanup(cleanupOptions);
-      break;
-
-    case 'debug':
-      console.log('🔧 Collecting Bob\'s Workshop debug information...\n');
-      const debugModule = await loadCliModule('../dist/cli/debug.js');
-      await debugModule.runDebug();
-      break;
-
-    case '--help':
-    case '-h':
-      await showHelp();
-      break;
-
-    case '--version':
-    case '-v':
-      await showVersion();
-      break;
-
-    case '--setup':
-    case '-s':
-      console.log('🔧 Starting Bob\'s MCP setup wizard...\n');
-      const setupModule = await loadCliModule('../dist/cli/setup.js');
-      await setupModule.runSetup();
-      break;
-
-    case '--check':
-    case '-c':
-    case undefined:
-      // Default action is to run installation check
-      console.log('🔧 Checking Bob\'s MCP installation...\n');
-      const checkerModule = await loadCliModule('../dist/cli/checker.js');
-      await checkerModule.runInstallationCheck();
-      break;
-
-    default:
-      console.error(`Unknown command: ${command}`);
-      console.error('Run "bobs --help" for usage information.');
-      process.exit(1);
-  }
-}
-
-main().catch(error => {
-  console.error('❌ Error:', error.message);
-  process.exit(1);
-});