Spec MCP Server

Instructions

Implementation Reference

• src/server.ts:429-616 (handler)

  The handler function generates and returns a detailed text prompt that instructs the AI agent on how to analyze tasks.md, construct dependency graphs, identify executable tasks, and coordinate their implementation using other tools like task-executor and task-checker.
  async ({ project_path = '.' }) => { const prompt = `# Task Orchestration Analysis for ${project_path} ## PREREQUISITE CHECK 1. **USE Read tool** to check if ${project_path}/.spec/specs/tasks.md exists 2. If it doesn't exist, STOP and return: "❌ No tasks.md found. This tool is for implementing existing tasks only. Use generate-tasks tool first." 3. If tasks.md exists, proceed with orchestration below ## CRITICAL: This tool IMPLEMENTS existing tasks - DO NOT generate new steering documents, plans, or task lists - ONLY coordinate execution of tasks already defined in tasks.md - Focus on dependencies and parallelization of existing tasks ## SIMPLICITY PRINCIPLES 1. Keep outputs simple, clean, and straightforward. 2. Do not cut scope or functionality to be "simple". 3. Implement only what’s needed to satisfy acceptance criteria. 4. Prefer minimal steps and sections; avoid ceremony. 5. Reuse existing patterns; avoid new abstractions unless essential. 6. Avoid overengineering — choose the smallest design that works. 7. Be concise in wording, complete in coverage. 8. Iterate: ship minimal complete, then improve. ## CRITICAL: THIS IS A COORDINATION TOOL This tool analyzes the task queue and creates an execution strategy. It does NOT execute tasks directly. ## PHASE 1: TASK QUEUE ANALYSIS 1. Read the tasks file: ${project_path}/.spec/specs/tasks.md 2. Parse all tasks and their current status: - ⚪ Not Started - Available for execution - 🟡 In Progress - Currently being worked on - ✅ Done - Completed tasks ## PHASE 2: DEPENDENCY GRAPH CONSTRUCTION Analyze the "Task Phases and Dependencies" section to understand: - Which tasks block others - Which tasks can run in parallel - Critical path identification - Phase groupings ## PHASE 3: EXECUTION STRATEGY ### Identify Executable Tasks Find all tasks that meet these criteria: - Status: ⚪ Not Started - All dependencies (if any) are ✅ Done - Not blocked by 🟡 In Progress tasks ### Parallelization Analysis Group tasks that can be executed simultaneously: - Independent tasks with no shared dependencies - Tasks in the same phase that don't conflict ### Execution Order Analysis Determine optimal sequential order based on: - Dependency requirements - Priority levels - Phase progression ## PHASE 4: EXECUTOR DEPLOYMENT PLAN For each executable task or task group, prepare deployment instructions: ### Tasks That Can Run Simultaneously: **Group 1**: Independent tasks - Task T-X: [Brief description] - Dependencies satisfied: [List completed dependencies] - Priority: [High/Medium/Low] - Task T-Y: [Brief description] - Dependencies satisfied: [List] - Priority: [Level] ### Recommended Execution Order: 1. **Immediate Execution** (no dependencies): - T-X: [Task title] - Ready to start - T-Y: [Task title] - Ready to start 2. **Next Wave** (will be unblocked after current tasks): - T-Z: [Task title] - Waiting for T-X - T-W: [Task title] - Waiting for T-Y 3. **Future Tasks** (multiple dependencies): - [List tasks that need multiple completions] ## PHASE 5: EXECUTION INSTRUCTIONS ### Deployment Options **Option 1: Deploy Multiple Executors** (for independent tasks) \`\`\` 1. Deploy task-executor for Task T-X with focus on [specific requirement] 2. Deploy task-executor for Task T-Y with focus on [specific requirement] 3. Monitor progress and reassess after completion \`\`\` **Option 2: Sequential Execution** (for dependent tasks) \`\`\` 1. Execute Task T-X first (foundational) 2. Upon completion, verify and proceed to T-Y 3. Continue with dependency order \`\`\` ### Progress Monitoring Strategy - Check task status updates regularly - When a task reports completion, run task-checker to verify - Deploy new executors for newly unblocked tasks - Handle any blockers or failures ### Task Verification Process When a task is marked as 🟡 In Progress with all checkboxes checked: 1. Run task-checker tool to verify completion 2. If PASS: Update status to ✅ Done 3. If FAIL: Keep as 🟡 In Progress and fix issues ## PHASE 6: RISK ASSESSMENT ### Potential Bottlenecks: - Tasks with many dependents that could block progress - High-complexity tasks that might take longer - External dependencies that could cause delays ### Mitigation Strategies: - Prioritize bottleneck tasks - Prepare fallback plans for risky tasks - Consider partial implementations for large tasks ## OUTPUT SUMMARY **Tasks Ready for Execution**: [Count and list] **Tasks Blocked**: [Count and list with blockers] **Tasks Completed**: [Count] **Parallelizable Tasks**: [List of tasks that can run simultaneously] **Critical Path**: [Sequence of tasks that determine minimum completion time] ## NEXT STEPS 1. Review the execution plan above 2. Deploy task-executor tool for each ready task 3. Use task-checker tool to verify task completion 4. Re-run orchestrator when tasks complete to identify newly available work Note: This orchestrator provides strategic coordination. Actual implementation happens through the task-executor tool, and verification through the task-checker tool. ## ⚠️ CRITICAL: YOU MUST NOW USE SPEC MCP TOOLS ⚠️ **IMPORTANT**: The instructions above are analysis only. You MUST now ACTUALLY CALL the Spec MCP tools to implement tasks! ### 🔴 REQUIRED ACTIONS - USE THESE SPEC MCP TOOLS NOW: Based on the analysis above, you MUST immediately: 1. **For EACH ready task identified above**, CALL the Spec MCP \`task-executor\` tool: \`\`\` USE Spec MCP tool: task-executor Parameters: - task_id: "[Task ID from above, e.g., T-1]" - project_path: "${project_path}" \`\`\` 2. **After implementing each task**, CALL the Spec MCP \`task-checker\` tool: \`\`\` USE Spec MCP tool: task-checker Parameters: - task_id: "[Same Task ID]" - project_path: "${project_path}" \`\`\` ### ⚠️ DO NOT JUST READ THESE INSTRUCTIONS ⚠️ **You MUST actually CALL/INVOKE/USE the Spec MCP tools mentioned above!** These are NOT suggestions - they are REQUIRED tool calls you must make NOW. **Clarification**: - These are Spec MCP tools (external MCP server tools) - NOT internal VSCode TODO tools - Task status is tracked in tasks.md file - You MUST invoke these tools through the Spec MCP interface **Example of what you should do next:** "I will now call the Spec MCP task-executor tool for task T-1..." [Then ACTUALLY call the tool]`; return { content: [{ type: "text", text: prompt }] }; }
• src/server.ts:425-427 (schema)

  Zod input schema defining the optional project_path parameter.
  inputSchema: { project_path: z.string().optional().describe("Path to the project directory (defaults to current directory)") }
• src/server.ts:420-617 (registration)

  The server.registerTool call that registers the 'task-orchestrator' tool with its metadata and handler function.
  server.registerTool( 'task-orchestrator', { title: 'Task Orchestrator', description: 'Use this to **implement/execute existing tasks** from tasks.md that have already been defined. This tool assumes tasks already exist and focuses on coordinating their implementation. DO NOT use this for generating new plans or tasks - only for executing tasks that have already been created.', inputSchema: { project_path: z.string().optional().describe("Path to the project directory (defaults to current directory)") } }, async ({ project_path = '.' }) => { const prompt = `# Task Orchestration Analysis for ${project_path} ## PREREQUISITE CHECK 1. **USE Read tool** to check if ${project_path}/.spec/specs/tasks.md exists 2. If it doesn't exist, STOP and return: "❌ No tasks.md found. This tool is for implementing existing tasks only. Use generate-tasks tool first." 3. If tasks.md exists, proceed with orchestration below ## CRITICAL: This tool IMPLEMENTS existing tasks - DO NOT generate new steering documents, plans, or task lists - ONLY coordinate execution of tasks already defined in tasks.md - Focus on dependencies and parallelization of existing tasks ## SIMPLICITY PRINCIPLES 1. Keep outputs simple, clean, and straightforward. 2. Do not cut scope or functionality to be "simple". 3. Implement only what’s needed to satisfy acceptance criteria. 4. Prefer minimal steps and sections; avoid ceremony. 5. Reuse existing patterns; avoid new abstractions unless essential. 6. Avoid overengineering — choose the smallest design that works. 7. Be concise in wording, complete in coverage. 8. Iterate: ship minimal complete, then improve. ## CRITICAL: THIS IS A COORDINATION TOOL This tool analyzes the task queue and creates an execution strategy. It does NOT execute tasks directly. ## PHASE 1: TASK QUEUE ANALYSIS 1. Read the tasks file: ${project_path}/.spec/specs/tasks.md 2. Parse all tasks and their current status: - ⚪ Not Started - Available for execution - 🟡 In Progress - Currently being worked on - ✅ Done - Completed tasks ## PHASE 2: DEPENDENCY GRAPH CONSTRUCTION Analyze the "Task Phases and Dependencies" section to understand: - Which tasks block others - Which tasks can run in parallel - Critical path identification - Phase groupings ## PHASE 3: EXECUTION STRATEGY ### Identify Executable Tasks Find all tasks that meet these criteria: - Status: ⚪ Not Started - All dependencies (if any) are ✅ Done - Not blocked by 🟡 In Progress tasks ### Parallelization Analysis Group tasks that can be executed simultaneously: - Independent tasks with no shared dependencies - Tasks in the same phase that don't conflict ### Execution Order Analysis Determine optimal sequential order based on: - Dependency requirements - Priority levels - Phase progression ## PHASE 4: EXECUTOR DEPLOYMENT PLAN For each executable task or task group, prepare deployment instructions: ### Tasks That Can Run Simultaneously: **Group 1**: Independent tasks - Task T-X: [Brief description] - Dependencies satisfied: [List completed dependencies] - Priority: [High/Medium/Low] - Task T-Y: [Brief description] - Dependencies satisfied: [List] - Priority: [Level] ### Recommended Execution Order: 1. **Immediate Execution** (no dependencies): - T-X: [Task title] - Ready to start - T-Y: [Task title] - Ready to start 2. **Next Wave** (will be unblocked after current tasks): - T-Z: [Task title] - Waiting for T-X - T-W: [Task title] - Waiting for T-Y 3. **Future Tasks** (multiple dependencies): - [List tasks that need multiple completions] ## PHASE 5: EXECUTION INSTRUCTIONS ### Deployment Options **Option 1: Deploy Multiple Executors** (for independent tasks) \`\`\` 1. Deploy task-executor for Task T-X with focus on [specific requirement] 2. Deploy task-executor for Task T-Y with focus on [specific requirement] 3. Monitor progress and reassess after completion \`\`\` **Option 2: Sequential Execution** (for dependent tasks) \`\`\` 1. Execute Task T-X first (foundational) 2. Upon completion, verify and proceed to T-Y 3. Continue with dependency order \`\`\` ### Progress Monitoring Strategy - Check task status updates regularly - When a task reports completion, run task-checker to verify - Deploy new executors for newly unblocked tasks - Handle any blockers or failures ### Task Verification Process When a task is marked as 🟡 In Progress with all checkboxes checked: 1. Run task-checker tool to verify completion 2. If PASS: Update status to ✅ Done 3. If FAIL: Keep as 🟡 In Progress and fix issues ## PHASE 6: RISK ASSESSMENT ### Potential Bottlenecks: - Tasks with many dependents that could block progress - High-complexity tasks that might take longer - External dependencies that could cause delays ### Mitigation Strategies: - Prioritize bottleneck tasks - Prepare fallback plans for risky tasks - Consider partial implementations for large tasks ## OUTPUT SUMMARY **Tasks Ready for Execution**: [Count and list] **Tasks Blocked**: [Count and list with blockers] **Tasks Completed**: [Count] **Parallelizable Tasks**: [List of tasks that can run simultaneously] **Critical Path**: [Sequence of tasks that determine minimum completion time] ## NEXT STEPS 1. Review the execution plan above 2. Deploy task-executor tool for each ready task 3. Use task-checker tool to verify task completion 4. Re-run orchestrator when tasks complete to identify newly available work Note: This orchestrator provides strategic coordination. Actual implementation happens through the task-executor tool, and verification through the task-checker tool. ## ⚠️ CRITICAL: YOU MUST NOW USE SPEC MCP TOOLS ⚠️ **IMPORTANT**: The instructions above are analysis only. You MUST now ACTUALLY CALL the Spec MCP tools to implement tasks! ### 🔴 REQUIRED ACTIONS - USE THESE SPEC MCP TOOLS NOW: Based on the analysis above, you MUST immediately: 1. **For EACH ready task identified above**, CALL the Spec MCP \`task-executor\` tool: \`\`\` USE Spec MCP tool: task-executor Parameters: - task_id: "[Task ID from above, e.g., T-1]" - project_path: "${project_path}" \`\`\` 2. **After implementing each task**, CALL the Spec MCP \`task-checker\` tool: \`\`\` USE Spec MCP tool: task-checker Parameters: - task_id: "[Same Task ID]" - project_path: "${project_path}" \`\`\` ### ⚠️ DO NOT JUST READ THESE INSTRUCTIONS ⚠️ **You MUST actually CALL/INVOKE/USE the Spec MCP tools mentioned above!** These are NOT suggestions - they are REQUIRED tool calls you must make NOW. **Clarification**: - These are Spec MCP tools (external MCP server tools) - NOT internal VSCode TODO tools - Task status is tracked in tasks.md file - You MUST invoke these tools through the Spec MCP interface **Example of what you should do next:** "I will now call the Spec MCP task-executor tool for task T-1..." [Then ACTUALLY call the tool]`; return { content: [{ type: "text", text: prompt }] }; } );