bobs-workshop 0.1.7 → 0.2.0

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

@@ -0,0 +1,471 @@
+{
+  "name": "bobs-mcp",
+  "version": "0.1.4",
+  "description": "Streamlined MCP orchestrator with workflow-driven API, consolidated git/worktree operations, and structured observability",
+  "type": "module",
+  "main": "dist/index.js",
+  "binary": "./bin/bobs-mcp.js",
+  "node_version": "v20.18.3",
+  "platform": "darwin",
+
+  "metadata": {
+    "schema_version": "v2",
+    "served_at": "/.well-known/mcp/manifest.json",
+    "dynamic_capabilities": false,
+    "reliability_hooks": ["auto_spec_sync", "phase_lock"],
+    "observability_features": ["mode_banner", "structured_logging", "smart_query_routing"],
+    "permissions": { "file_write": true, "git_commit": true, "network_access": false },
+    "rate_limits": { "global_rps": 8, "burst": 16 },
+    "timeouts": { "default_ms": 6000 },
+    "cancellation": { "supported": true },
+    "llm_guidance": {
+      "execution_model": {
+        "identity": "YOU (Claude Code) ARE the orchestrator - there is no separate orchestrator service or agent system",
+        "mode_switching": "When bob.workshop classifies a problem, YOU switch modes (orchestrator → architect → engineer → debugger → reviewer) within the same conversation",
+        "direct_execution": "When you 'switch to architect mode', YOU read the ARCHITECT_PROMPT and execute those steps directly. There is NO delegation to another agent.",
+        "trigger": "When user says 'hey bob', YOU immediately call bob.workshop to classify, then switch to the appropriate mode and execute",
+        "tool_preference": "YOU use Bob's MCP tools (bob.code.search, bob.workflow.start) NOT Claude Code's native tools (Grep, Glob) when in Bob mode"
+      },
+      "manual_definition": {
+        "format": "JSON file stored in .bob/specs/SPEC-*.json",
+        "purpose": "Single source of truth for feature specifications, execution logs, and debug findings",
+        "critical_rule": "DO NOT create separate markdown files for documentation or progress tracking. ALL information must be stored within the MANUAL using bob.manual.update"
+      },
+      "mode_specific_tools": {
+        "architect": ["mcp__bobs-mcp__bob_workflow_start", "mcp__bobs-mcp__bob_manual_update", "mcp__bobs-mcp__bob_code_search"],
+        "engineer": ["mcp__bobs-mcp__bob_manual_update", "mcp__bobs-mcp__bob_code_search", "mcp__bobs-mcp__bob_workflow_deploy"],
+        "debugger": ["mcp__bobs-mcp__bob_manual_update", "mcp__bobs-mcp__bob_code_search", "mcp__bobs-mcp__bob_worktree_debug"],
+        "reviewer": ["mcp__bobs-mcp__bob_validate_changes", "mcp__bobs-mcp__bob_summarize_implementation"]
+      },
+      "verbosity": "summary",
+      "hints": [
+        "Use bob.workflow.start to bootstrap new features (creates manual + worktree + dashboard)",
+        "Use bob.workflow.deploy to complete features (commits + merges + cleanup)",
+        "Individual git/worktree tools are now internal - use workflow tools for end-to-end operations",
+        "Use bob.worktree.debug for advanced worktree troubleshooting",
+        "Always use bob.code.search with phase parameter (architect/engineer/debugger/reviewer) for role-specific analysis",
+        "bob.code.search mode=auto automatically selects semantic or lexical search based on query complexity",
+        "Scope searches with path parameter and limit results with maxHits for better performance",
+        "Architect phase: focus on architecture patterns and module structure",
+        "Engineer phase: exact symbol and function lookups for implementation",
+        "Debugger phase: security analysis and bug detection",
+        "Reviewer phase: quality and performance analysis"
+      ],
+      "manual_section_responsibilities": {
+        "architect": {
+          "creates": ["executive_summary", "product_specifications", "architecture_analysis", "implementation_plan", "testing"],
+          "placeholders": ["execution_logs", "debug_logs"],
+          "description": "Creates comprehensive manual with 4 main sections plus execution_logs and debug_logs placeholders for engineer and debugger to update"
+        },
+        "engineer": {
+          "updates": ["execution_logs"],
+          "description": "Updates execution_logs section with task completion entries for a respective manual"
+        },
+        "debugger": {
+          "creates_or_updates": ["debug_logs"],
+          "manual_type": "debug_manual or existing_manual",
+          "description": "Either creates own debug manual or updates debug_logs section of existing manual"
+        },
+        "reviewer": {
+          "creates": ["executive_summary", "existing_specification_context", "performance_analysis", "quality_analysis", "security_analysis", "implementation_plan", "implementation_strategy"],
+          "manual_type": "review_manual",
+          "description": "Creates own review manual with improvement recommendations"
+        }
+      }
+    }
+  },
+
+  "tools": {
+    "mcp__bobs-mcp__bob_workshop": {
+      "title": "Problem Classifier & Mode Selector",
+      "category": "orchestration",
+      "description": "Classifies user problem and returns which mode (architect/engineer/debugger/reviewer) YOU should switch to. YOU then execute in that mode directly - this is NOT delegation to another agent.",
+      "enhancements": ["phase_lock", "auto_spec_sync"],
+      "permissions": {},
+      "rate_limits": { "rps": 4, "burst": 8 },
+      "timeouts": { "ms": 4000 },
+      "examples": [
+        {
+          "description": "Architect planning for user profile",
+          "input": { "problem": "Add user profile management with avatar upload", "mode": "architect" }
+        },
+        {
+          "description": "Reviewer security pass",
+          "input": { "problem": "Review auth module for vulns", "mode": "reviewer", "spec_id": "SPEC-2025-09-28-auth" }
+        }
+      ]
+    },
+
+    "mcp__bobs-mcp__bob_manual_create": {
+      "title": "Manual Creator",
+      "category": "manual",
+      "description": "Creates a new SPEC manual",
+      "permissions": { "file_write": true },
+      "rate_limits": { "rps": 2, "burst": 4 },
+      "timeouts": { "ms": 4000 },
+      "input_schema": {
+        "title": "string",
+        "author": "string?",
+        "category": "enum(frontend,backend,fullstack,devtools,general)?",
+        "priority": "enum(low,medium,high,critical)?",
+        "tags": "string[]?"
+      },
+      "examples": [
+        {
+          "description": "Create manual for Settings feature",
+          "input": { "title": "User Settings Page", "category": "frontend", "priority": "medium", "tags": ["settings","ui"] }
+        }
+      ]
+    },
+
+    "mcp__bobs-mcp__bob_manual_update": {
+      "title": "Manual Updater",
+      "category": "manual",
+      "description": "Updates manual sections, execution logs, and debug logs. SINGLE SOURCE OF TRUTH for all activity logging to SPEC files.",
+      "enhancements": ["auto_commit_log", "phase_lock_validation"],
+      "permissions": { "file_write": true, "git_commit": true },
+      "rate_limits": { "rps": 4, "burst": 8 },
+      "timeouts": { "ms": 5000 },
+      "idempotency": { "key_param": "idempotency_key", "scope": "spec_id+action" },
+      "input_schema": { "$ref": "./schemas/manual_update.json" },
+      "usage_notes": [
+        "Only tool that writes enhanced_activities to SPEC files",
+        "Creates role-specific activities (architect, engineer, debugger, reviewer, orchestrator)",
+        "Generates intelligent summaries and categorizes file changes",
+        "Dashboard reads activities directly from SPEC files - no separate update needed"
+      ],
+      "examples": [
+        {
+          "description": "Log engineer execution progress",
+          "input": {
+            "spec_id": "SPEC-2025-09-28-user-profile",
+            "execution_log": {
+              "timestamp": "2025-09-28T10:00:00Z",
+              "engineer": "Claude Engineer",
+              "action": "implementation:completed",
+              "task_id": "AVATAR_UPLOAD",
+              "files_changed": ["src/components/ProfileForm.tsx"],
+              "commit_hash": "abc123",
+              "note": "Added avatar upload with image preview"
+            },
+            "idempotency_key": "abc123"
+          },
+          "output": { "summary": "🛠 bob.manual.update | ✅ execution log added" }
+        },
+        {
+          "description": "Log debugger findings",
+          "input": {
+            "spec_id": "SPEC-2025-09-28-user-profile",
+            "debug_log": {
+              "timestamp": "2025-09-28T11:00:00Z",
+              "issue": "Avatar upload fails for files > 5MB",
+              "root_cause": "Missing file size validation before upload",
+              "fix": "Added client-side validation with 5MB limit and user feedback",
+              "confidence": "high"
+            }
+          },
+          "output": { "summary": "🛠 bob.manual.update | ✅ debug log added" }
+        }
+      ]
+    },
+
+    "mcp__bobs-mcp__bob_code_search": {
+      "title": "Code Search",
+      "category": "search",
+      "description": "Phase-aware unified search combining semantic (semgrep) and lexical (ripgrep) search capabilities. Automatically selects best search mode based on query and phase context.",
+      "enhancements": ["mode_banner", "smart_query_routing", "summary_output", "phase_aware_analysis"],
+      "permissions": { "file_read": true },
+      "rate_limits": { "rps": 6, "burst": 12 },
+      "timeouts": { "ms": 6000 },
+      "input_schema": {
+        "query": "string (REQUIRED) - search query or pattern",
+        "mode": "enum(auto,semantic,lexical)? - auto selects best mode based on query",
+        "phase": "enum(architect,engineer,debugger,reviewer)? - role context for specialized analysis rules",
+        "path": "string? - directory to search within (defaults to current directory)",
+        "includeHidden": "boolean? - include hidden files/folders",
+        "followGitIgnore": "boolean? - respect .gitignore rules (default: true)",
+        "fileTypes": "string[]? - filter by file extensions (e.g., ['ts', 'js'])",
+        "maxHits": "number? - maximum number of results to return",
+        "contextLines": "number? - lines of context around matches",
+        "timeoutMs": "number? - search timeout in milliseconds"
+      },
+      "phase_behavior": {
+        "architect": "Focus on architecture analysis, framework patterns, module structure, and high-level design patterns",
+        "engineer": "General implementation search with focus on exact symbols, function names, and variable references",
+        "debugger": "Security-focused search for bugs, anti-patterns, vulnerabilities, and correctness issues",
+        "reviewer": "Quality analysis focused on performance issues, code smells, and best practice violations"
+      },
+      "usage_guidelines": [
+        "Use phase parameter to get specialized analysis relevant to your role",
+        "mode=auto (default) automatically selects semantic or lexical based on query complexity",
+        "Semantic mode: Best for finding patterns, similar code structures, or architectural analysis",
+        "Lexical mode: Best for exact matches, symbol lookups, or simple string searches",
+        "Combine with path parameter to scope searches to specific directories",
+        "Use maxHits to limit results for broad queries"
+      ],
+      "examples": [
+        {
+          "description": "Engineer search for exact function implementation",
+          "input": { "query": "createUserHandler", "mode": "auto", "phase": "engineer", "path": "src/backend/", "maxHits": 20 },
+          "output": {
+            "summary": "🔍 [Hybrid Search] Mode: lexical | Phase: engineer | Query: 'createUserHandler'",
+            "hits": [
+              "src/api/user.ts:45 → function createUserHandler(req,res)",
+              "src/routes/index.ts:22 → router.post('/users', createUserHandler)"
+            ]
+          }
+        },
+        {
+          "description": "Architect analysis of authentication patterns",
+          "input": { "query": "authentication flow", "mode": "semantic", "phase": "architect", "path": "src/" },
+          "output": {
+            "summary": "🔍 [Semantic Search] Phase: architect | Found 8 architecture patterns",
+            "patterns": [
+              "src/auth/middleware.ts - JWT authentication middleware pattern",
+              "src/auth/session.ts - Session management pattern"
+            ]
+          }
+        },
+        {
+          "description": "Debugger security vulnerability scan",
+          "input": { "query": "SQL injection", "mode": "semantic", "phase": "debugger", "path": "src/backend/" },
+          "output": {
+            "summary": "🔍 [Security Scan] Phase: debugger | Analyzing for SQL injection patterns",
+            "vulnerabilities": [
+              "src/db/queries.ts:42 - Potential SQL injection risk in dynamic query"
+            ]
+          }
+        },
+        {
+          "description": "Reviewer performance analysis",
+          "input": { "query": "database query", "phase": "reviewer", "path": "src/" },
+          "output": {
+            "summary": "🔍 [Quality Analysis] Phase: reviewer | Performance issues detected",
+            "issues": [
+              "src/api/users.ts:67 - N+1 query pattern detected",
+              "src/services/data.ts:123 - Missing database index"
+            ]
+          }
+        }
+      ]
+    },
+
+    "mcp__bobs-mcp__bob_workflow_start": {
+      "title": "Workflow Starter",
+      "category": "workflow",
+      "description": "Creates manual + worktree + launches dashboard",
+      "permissions": { "file_write": true, "git_commit": true },
+      "rate_limits": { "rps": 1, "burst": 2 },
+      "timeouts": { "ms": 8000 },
+      "input_schema": { "$ref": "./schemas/workflow_start.json" },
+      "examples": [
+        {
+          "description": "Initialize feature workflow",
+          "input": { "title": "Add User Settings Page", "category": "frontend", "priority": "medium", "branch_name": "feature/user-settings" }
+        }
+      ]
+    },
+
+    "mcp__bobs-mcp__bob_workflow_deploy": {
+      "title": "Workflow Deployer",
+      "category": "workflow",
+      "description": "Commit changes, merge to main, and cleanup worktree",
+      "enhancements": ["summary_output"],
+      "permissions": { "git_commit": true, "file_write": true },
+      "rate_limits": { "rps": 1, "burst": 2 },
+      "timeouts": { "ms": 10000 },
+      "idempotency": { "key_param": "idempotency_key", "scope": "spec_id+target_branch" },
+      "input_schema": { "$ref": "./schemas/workflow_deploy.json" },
+      "examples": [
+        {
+          "description": "Deploy profile feature",
+          "input": {
+            "spec_id": "SPEC-2025-09-28-user-profile",
+            "action_description": "Implemented profile + avatar",
+            "target_branch": "main",
+            "idempotency_key": "deploy-SPEC-2025-09-28-user-profile-main"
+          },
+          "output": { "summary": "🚀 deploy | merged to main, cleaned worktree" }
+        }
+      ]
+    },
+
+    "mcp__bobs-mcp__bob_validate_changes": {
+      "title": "Change Validator",
+      "category": "validation",
+      "description": "Validates diffs against SPEC expectations",
+      "permissions": { "file_read": true },
+      "rate_limits": { "rps": 2, "burst": 4 },
+      "timeouts": { "ms": 6000 },
+      "examples": [
+        { "description": "Compliance check", "input": { "spec_id": "SPEC-2025-09-28-user-profile" } }
+      ]
+    },
+
+    "mcp__bobs-mcp__bob_summarize_implementation": {
+      "title": "Implementation Summarizer",
+      "category": "validation",
+      "description": "Summarizes changes (chokidar)",
+      "permissions": { "file_read": true },
+      "rate_limits": { "rps": 2, "burst": 4 },
+      "timeouts": { "ms": 6000 },
+      "examples": [
+        { "description": "24h summary", "input": { "spec_id": "SPEC-2025-09-28-user-profile", "lookback_hours": 24 } }
+      ]
+    },
+
+    "mcp__bobs-mcp__bob_dashboard_launch": {
+      "title": "Dashboard Launcher",
+      "category": "dashboard",
+      "description": "Opens dashboard on port 4577 to view SPEC files and activity logs",
+      "permissions": {},
+      "rate_limits": { "rps": 0.5, "burst": 1 },
+      "timeouts": { "ms": 4000 },
+      "usage_notes": [
+        "Dashboard reads SPEC files directly from .bob/specs/",
+        "All activity logging is done via bob.manual.update with execution_log or debug_log",
+        "No separate update API - dashboard auto-refreshes from file system"
+      ]
+    },
+
+    "mcp__bobs-mcp__bob_worktree_debug": {
+      "title": "Worktree Debug Tool",
+      "category": "worktree",
+      "description": "Advanced worktree maintenance (repair, cleanup, validate, status)",
+      "permissions": { "file_read": true, "file_write": true, "git_commit": true },
+      "rate_limits": { "rps": 1, "burst": 2 },
+      "timeouts": { "ms": 6000 },
+      "input_schema": {
+        "action": "enum(repair,cleanup,validate,status)",
+        "spec_id": "string?",
+        "max_age_days": "number?"
+      },
+      "examples": [
+        {
+          "description": "Check all worktrees status",
+          "input": { "action": "status" }
+        },
+        {
+          "description": "Cleanup stale worktrees older than 7 days",
+          "input": { "action": "cleanup", "max_age_days": 7 }
+        }
+      ]
+    },
+
+    "mcp__bobs-mcp__bob_debug": {
+      "title": "System Debug Tool",
+      "category": "system",
+      "description": "Internal state inspection and troubleshooting",
+      "permissions": { "file_read": true },
+      "rate_limits": { "rps": 1, "burst": 2 },
+      "timeouts": { "ms": 3000 }
+    },
+
+    "mcp__bobs-mcp__bob_manual_get": {
+      "title": "Manual Getter",
+      "category": "manual",
+      "description": "Retrieves SPEC manual details and logs",
+      "permissions": { "file_read": true },
+      "rate_limits": { "rps": 4, "burst": 8 },
+      "timeouts": { "ms": 3000 }
+    },
+
+    "mcp__bobs-mcp__bob_manual_list": {
+      "title": "Manual Lister",
+      "category": "manual",
+      "description": "Lists all project SPECs with status",
+      "permissions": { "file_read": true },
+      "rate_limits": { "rps": 2, "burst": 4 },
+      "timeouts": { "ms": 3000 }
+    },
+
+    "mcp__bobs-mcp__bob_approval_request": {
+      "title": "Approval Request",
+      "category": "approval",
+      "description": "Create user approval request for spec review, implementation, bugfix, or completion",
+      "permissions": { "file_write": true },
+      "rate_limits": { "rps": 2, "burst": 4 },
+      "timeouts": { "ms": 3000 },
+      "input_schema": {
+        "spec_id": "string (REQUIRED) - the specification ID",
+        "approval_type": "enum(spec_approval,implementation_approval,bugfix_approval,review_approval,completion_confirmation) (REQUIRED)",
+        "message": "string (REQUIRED) - approval message to display to user",
+        "context": "object? - additional context for the approval"
+      },
+      "examples": [
+        {
+          "description": "Request spec approval from architect",
+          "input": {
+            "spec_id": "SPEC-2025-09-30-user-profile",
+            "approval_type": "spec_approval",
+            "message": "Comprehensive manual completed. Please review the planning details and approve to proceed with implementation."
+          }
+        },
+        {
+          "description": "Request implementation approval from engineer",
+          "input": {
+            "spec_id": "SPEC-2025-09-30-user-profile",
+            "approval_type": "implementation_approval",
+            "message": "Implementation completed successfully! Please test the new functionality and confirm if you're satisfied with the results."
+          }
+        }
+      ]
+    },
+
+    "mcp__bobs-mcp__bob_approval_status": {
+      "title": "Approval Status",
+      "category": "approval",
+      "description": "Check status of pending approval requests",
+      "permissions": { "file_read": true },
+      "rate_limits": { "rps": 4, "burst": 8 },
+      "timeouts": { "ms": 2000 },
+      "input_schema": {
+        "spec_id": "string (REQUIRED) - the specification ID",
+        "approval_type": "enum(spec_approval,implementation_approval,bugfix_approval,review_approval,completion_confirmation)?"
+      },
+      "examples": [
+        {
+          "description": "Check spec approval status",
+          "input": {
+            "spec_id": "SPEC-2025-09-30-user-profile",
+            "approval_type": "spec_approval"
+          }
+        }
+      ]
+    },
+
+    "mcp__bobs-mcp__bob_approval_respond": {
+      "title": "Approval Response",
+      "category": "approval",
+      "description": "Process user approval response (approve/reject)",
+      "permissions": { "file_write": true },
+      "rate_limits": { "rps": 2, "burst": 4 },
+      "timeouts": { "ms": 3000 },
+      "input_schema": {
+        "spec_id": "string (REQUIRED) - the specification ID",
+        "approval_type": "enum(spec_approval,implementation_approval,bugfix_approval,review_approval,completion_confirmation) (REQUIRED)",
+        "response": "enum(approved,rejected) (REQUIRED)",
+        "feedback": "string? - optional feedback from user"
+      },
+      "examples": [
+        {
+          "description": "User approves specification",
+          "input": {
+            "spec_id": "SPEC-2025-09-30-user-profile",
+            "approval_type": "spec_approval",
+            "response": "approved"
+          }
+        },
+        {
+          "description": "User rejects with feedback",
+          "input": {
+            "spec_id": "SPEC-2025-09-30-user-profile",
+            "approval_type": "spec_approval",
+            "response": "rejected",
+            "feedback": "Need to add more details about security considerations"
+          }
+        }
+      ]
+    }
+  }
+}