spec-workflow-guide.ts•12.3 kB
import { Tool } from '@modelcontextprotocol/sdk/types.js';
import { ToolContext, ToolResponse } from '../types.js';
export const specWorkflowGuideTool: Tool = {
name: 'spec-workflow-guide',
description: `Load essential spec workflow instructions to guide feature development from idea to implementation.
# Instructions
Call this tool FIRST when users request spec creation, feature development, or mention specifications. This provides the complete workflow sequence (Requirements → Design → Tasks → Implementation) that must be followed. Always load before any other spec tools to ensure proper workflow understanding. Its important that you follow this workflow exactly to avoid errors.`,
inputSchema: {
type: 'object',
properties: {},
additionalProperties: false
}
};
export async function specWorkflowGuideHandler(args: any, context: ToolContext): Promise<ToolResponse> {
// Get dashboard URL from context or session
let dashboardUrl = context.dashboardUrl;
if (!dashboardUrl && context.sessionManager) {
dashboardUrl = await context.sessionManager.getDashboardUrl();
}
const dashboardMessage = dashboardUrl ?
`Monitor progress on dashboard: ${dashboardUrl}` :
'Please start the dashboard or use VS Code extension "Spec Workflow MCP"';
return {
success: true,
message: 'Complete spec workflow guide loaded - follow this workflow exactly',
data: {
guide: getSpecWorkflowGuide(),
dashboardUrl: dashboardUrl,
dashboardAvailable: !!dashboardUrl
},
nextSteps: [
'Follow sequence: Requirements → Design → Tasks → Implementation',
'Load templates with get-template-context first',
'Request approval after each document',
'Use MCP tools only',
dashboardMessage
]
};
}
function getSpecWorkflowGuide(): string {
const currentYear = new Date().getFullYear();
return `# Spec Development Workflow
## Overview
You guide users through spec-driven development using MCP tools. Transform rough ideas into detailed specifications through Requirements → Design → Tasks → Implementation phases. Use web search when available for current best practices (current year: ${currentYear}). Its important that you follow this workflow exactly to avoid errors.
Feature names use kebab-case (e.g., user-authentication). Create ONE spec at a time.
## Workflow Diagram
\`\`\`mermaid
flowchart TD
Start([Start: User requests feature]) --> CheckSteering{Steering docs exist?}
CheckSteering -->|Yes| P1_Load[Read steering docs:<br/>.spec-workflow/steering/*.md]
CheckSteering -->|No| P1_Template
%% Phase 1: Requirements
P1_Load --> P1_Template[Check user-templates first,<br/>then read template:<br/>requirements-template.md]
P1_Template --> P1_Research[Web search if available]
P1_Research --> P1_Create[Create file:<br/>.spec-workflow/specs/{name}/<br/>requirements.md]
P1_Create --> P1_Approve[approvals<br/>action: request<br/>filePath only]
P1_Approve --> P1_Status[approvals<br/>action: status<br/>poll status]
P1_Status --> P1_Check{Status?}
P1_Check -->|needs-revision| P1_Update[Update document using user comments as guidance]
P1_Update --> P1_Create
P1_Check -->|approved| P1_Clean[approvals<br/>action: delete]
P1_Clean -->|failed| P1_Status
%% Phase 2: Design
P1_Clean -->|success| P2_Template[Check user-templates first,<br/>then read template:<br/>design-template.md]
P2_Template --> P2_Analyze[Analyze codebase patterns]
P2_Analyze --> P2_Create[Create file:<br/>.spec-workflow/specs/{name}/<br/>design.md]
P2_Create --> P2_Approve[approvals<br/>action: request<br/>filePath only]
P2_Approve --> P2_Status[approvals<br/>action: status<br/>poll status]
P2_Status --> P2_Check{Status?}
P2_Check -->|needs-revision| P2_Update[Update document using user comments as guidance]
P2_Update --> P2_Create
P2_Check -->|approved| P2_Clean[approvals<br/>action: delete]
P2_Clean -->|failed| P2_Status
%% Phase 3: Tasks
P2_Clean -->|success| P3_Template[Check user-templates first,<br/>then read template:<br/>tasks-template.md]
P3_Template --> P3_Break[Convert design to tasks]
P3_Break --> P3_Create[Create file:<br/>.spec-workflow/specs/{name}/<br/>tasks.md]
P3_Create --> P3_Approve[approvals<br/>action: request<br/>filePath only]
P3_Approve --> P3_Status[approvals<br/>action: status<br/>poll status]
P3_Status --> P3_Check{Status?}
P3_Check -->|needs-revision| P3_Update[Update document using user comments as guidance]
P3_Update --> P3_Create
P3_Check -->|approved| P3_Clean[approvals<br/>action: delete]
P3_Clean -->|failed| P3_Status
%% Phase 4: Implementation
P3_Clean -->|success| P4_Ready[Spec complete.<br/>Ready to implement?]
P4_Ready -->|Yes| P4_Status[spec-status]
P4_Status --> P4_Task[Edit tasks.md:<br/>Change [ ] to [-]<br/>for in-progress]
P4_Task --> P4_Code[Implement code]
P4_Code --> P4_Complete[Edit tasks.md:<br/>Change [-] to [x]<br/>for completed]
P4_Complete --> P4_More{More tasks?}
P4_More -->|Yes| P4_Task
P4_More -->|No| End([Implementation Complete])
style Start fill:#e1f5e1
style End fill:#e1f5e1
style P1_Check fill:#ffe6e6
style P2_Check fill:#ffe6e6
style P3_Check fill:#ffe6e6
style CheckSteering fill:#fff4e6
style P4_More fill:#fff4e6
\`\`\`
## Spec Workflow
### Phase 1: Requirements
**Purpose**: Define what to build based on user needs.
**File Operations**:
- Read steering docs: \`.spec-workflow/steering/*.md\` (if they exist)
- Check for custom template: \`.spec-workflow/user-templates/requirements-template.md\`
- Read template: \`.spec-workflow/templates/requirements-template.md\` (if no custom template)
- Create document: \`.spec-workflow/specs/{spec-name}/requirements.md\`
**Tools**:
- approvals: Manage approval workflow (actions: request, status, delete)
**Process**:
1. Check if \`.spec-workflow/steering/\` exists (if yes, read product.md, tech.md, structure.md)
2. Check for custom template at \`.spec-workflow/user-templates/requirements-template.md\`
3. If no custom template, read from \`.spec-workflow/templates/requirements-template.md\`
4. Research market/user expectations (if web search available, current year: ${currentYear})
5. Generate requirements as user stories with EARS criteria6. Create \`requirements.md\` at \`.spec-workflow/specs/{spec-name}/requirements.md\`
7. Request approval using approvals tool with action:'request' (filePath only, never content)
8. Poll status using approvals with action:'status' until approved/needs-revision (NEVER accept verbal approval)
9. If needs-revision: update document using comments, create NEW approval, do NOT proceed
10. Once approved: use approvals with action:'delete' (must succeed) before proceeding
11. If delete fails: STOP - return to polling
### Phase 2: Design
**Purpose**: Create technical design addressing all requirements.
**File Operations**:
- Check for custom template: \`.spec-workflow/user-templates/design-template.md\`
- Read template: \`.spec-workflow/templates/design-template.md\` (if no custom template)
- Create document: \`.spec-workflow/specs/{spec-name}/design.md\`
**Tools**:
- approvals: Manage approval workflow (actions: request, status, delete)
**Process**:
1. Check for custom template at \`.spec-workflow/user-templates/design-template.md\`
2. If no custom template, read from \`.spec-workflow/templates/design-template.md\`
3. Analyze codebase for patterns to reuse
4. Research technology choices (if web search available, current year: ${currentYear})
5. Generate design with all template sections6. Create \`design.md\` at \`.spec-workflow/specs/{spec-name}/design.md\`
7. Request approval using approvals tool with action:'request'
8. Poll status using approvals with action:'status' until approved/needs-revision
9. If needs-revision: update document using comments, create NEW approval, do NOT proceed
10. Once approved: use approvals with action:'delete' (must succeed) before proceeding
11. If delete fails: STOP - return to polling
### Phase 3: Tasks
**Purpose**: Break design into atomic implementation tasks.
**File Operations**:
- Check for custom template: \`.spec-workflow/user-templates/tasks-template.md\`
- Read template: \`.spec-workflow/templates/tasks-template.md\` (if no custom template)
- Create document: \`.spec-workflow/specs/{spec-name}/tasks.md\`
**Tools**:
- approvals: Manage approval workflow (actions: request, status, delete)
**Process**:
1. Check for custom template at \`.spec-workflow/user-templates/tasks-template.md\`
2. If no custom template, read from \`.spec-workflow/templates/tasks-template.md\`
3. Convert design into atomic tasks (1-3 files each)
4. Include file paths and requirement references
5. **IMPORTANT**: Generate a _Prompt field for each task with:
- Role: specialized developer role for the task
- Task: clear description with context references
- Restrictions: what not to do, constraints to follow
- _Leverage: files/utilities to use
- _Requirements: requirements that the task implements
- Success: specific completion criteria
- Instructions related to setting the task in progress in tasks.md and then marking it as complete when the task is complete.
- Start the prompt with "Implement the task for spec {spec-name}, first run spec-workflow-guide to get the workflow guide then implement the task:"
6. Create \`tasks.md\` at \`.spec-workflow/specs/{spec-name}/tasks.md\`
7. Request approval using approvals tool with action:'request'
8. Poll status using approvals with action:'status' until approved/needs-revision
9. If needs-revision: update document using comments, create NEW approval, do NOT proceed
10. Once approved: use approvals with action:'delete' (must succeed) before proceeding
11. If delete fails: STOP - return to polling
12. After successful cleanup: "Spec complete. Ready to implement?"
### Phase 4: Implementation
**Purpose**: Execute tasks systematically.
**File Operations**:
- Read specs: \`.spec-workflow/specs/{spec-name}/*.md\` (if returning to work)
- Edit tasks.md to update status:
- \`- [ ]\` = Pending task
- \`- [-]\` = In-progress task
- \`- [x]\` = Completed task
**Tools**:
- spec-status: Check overall progress
- implement-task prompt: Guide for implementing tasks
- Direct editing: Mark tasks as in-progress [-] or complete [x] in tasks.md
**Process**:
1. Check current status with spec-status
2. Read \`tasks.md\` to see all tasks
3. For each task:
- Edit tasks.md: Change \`[ ]\` to \`[-]\` for the task you're starting
- **Read the _Prompt field** for guidance on role, approach, and success criteria
- Follow _Leverage fields to use existing code/utilities
- Implement the code according to the task description
- Test your implementation
- Edit tasks.md: Change \`[-]\` to \`[x]\` when completed
4. Continue until all tasks show \`[x]\`
## Workflow Rules
- Create documents directly at specified file paths
- Read templates from \`.spec-workflow/templates/\` directory
- Follow exact template structures
- Get explicit user approval between phases (using approvals tool with action:'request')
- Complete phases in sequence (no skipping)
- One spec at a time
- Use kebab-case for spec names
- Approval requests: provide filePath only, never content
- BLOCKING: Never proceed if approval delete fails
- CRITICAL: Must have approved status AND successful cleanup before next phase
- CRITICAL: Verbal approval is NEVER accepted - dashboard or VS Code extension only
- NEVER proceed on user saying "approved" - check system status only
- Steering docs are optional - only create when explicitly requested
## File Structure
\`\`\`
.spec-workflow/
├── templates/ # Auto-populated on server start
│ ├── requirements-template.md
│ ├── design-template.md
│ ├── tasks-template.md
│ ├── product-template.md
│ ├── tech-template.md
│ └── structure-template.md
├── specs/
│ └── {spec-name}/
│ ├── requirements.md
│ ├── design.md
│ └── tasks.md
└── steering/
├── product.md
├── tech.md
└── structure.md
\`\`\``;
}