spec-status
Track specification progress by displaying detailed status, phase completion, and task updates within the Spec Workflow MCP server for streamlined AI-assisted software development.
Instructions
Show detailed status of a specification including phase completion and task progress
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| projectPath | Yes | Absolute path to the project root | |
| specName | Yes | Name of the specification |
Input Schema (JSON Schema)
{
"properties": {
"projectPath": {
"description": "Absolute path to the project root",
"type": "string"
},
"specName": {
"description": "Name of the specification",
"type": "string"
}
},
"required": [
"projectPath",
"specName"
],
"type": "object"
}
Implementation Reference
- src/tools/spec-status.ts:28-178 (handler)The handler function that executes the 'spec-status' tool. Parses spec files using SpecParser, computes phase status (requirements, design, tasks, implementation), task progress, generates next steps, and returns a structured ToolResponse.export async function specStatusHandler(args: any, context: ToolContext): Promise<ToolResponse> { const { specName } = args; // Use context projectPath as default, allow override via args const projectPath = args.projectPath || context.projectPath; if (!projectPath) { return { success: false, message: 'Project path is required but not provided in context or arguments' }; } try { const parser = new SpecParser(projectPath); const spec = await parser.getSpec(specName); if (!spec) { return { success: false, message: `Specification '${specName}' not found`, nextSteps: [ 'Check spec name', 'Use spec-list for available specs', 'Create spec with create-spec-doc' ] }; } // Determine current phase and overall status let currentPhase = 'not-started'; let overallStatus = 'not-started'; if (!spec.phases.requirements.exists) { currentPhase = 'requirements'; overallStatus = 'requirements-needed'; } else if (!spec.phases.design.exists) { currentPhase = 'design'; overallStatus = 'design-needed'; } else if (!spec.phases.tasks.exists) { currentPhase = 'tasks'; overallStatus = 'tasks-needed'; } else if (spec.taskProgress && spec.taskProgress.pending > 0) { currentPhase = 'implementation'; overallStatus = 'implementing'; } else if (spec.taskProgress && spec.taskProgress.total > 0 && spec.taskProgress.completed === spec.taskProgress.total) { currentPhase = 'completed'; overallStatus = 'completed'; } else { currentPhase = 'implementation'; overallStatus = 'ready-for-implementation'; } // Phase details const phaseDetails = [ { name: 'Requirements', status: spec.phases.requirements.exists ? (spec.phases.requirements.approved ? 'approved' : 'created') : 'missing', lastModified: spec.phases.requirements.lastModified }, { name: 'Design', status: spec.phases.design.exists ? (spec.phases.design.approved ? 'approved' : 'created') : 'missing', lastModified: spec.phases.design.lastModified }, { name: 'Tasks', status: spec.phases.tasks.exists ? (spec.phases.tasks.approved ? 'approved' : 'created') : 'missing', lastModified: spec.phases.tasks.lastModified }, { name: 'Implementation', status: spec.phases.implementation.exists ? 'in-progress' : 'not-started', progress: spec.taskProgress } ]; // Next steps based on current phase const nextSteps = []; switch (currentPhase) { case 'requirements': nextSteps.push('Read template: .spec-workflow/templates/requirements-template-v*.md'); nextSteps.push('Create: .spec-workflow/specs/{name}/requirements.md'); nextSteps.push('Request approval'); break; case 'design': nextSteps.push('Read template: .spec-workflow/templates/design-template-v*.md'); nextSteps.push('Create: .spec-workflow/specs/{name}/design.md'); nextSteps.push('Request approval'); break; case 'tasks': nextSteps.push('Read template: .spec-workflow/templates/tasks-template-v*.md'); nextSteps.push('Create: .spec-workflow/specs/{name}/tasks.md'); nextSteps.push('Request approval'); break; case 'implementation': if (spec.taskProgress && spec.taskProgress.pending > 0) { nextSteps.push(`Read tasks: .spec-workflow/specs/${specName}/tasks.md`); nextSteps.push('Edit tasks.md: Change [ ] to [-] for task you start'); nextSteps.push('Implement the task code'); nextSteps.push('Edit tasks.md: Change [-] to [x] when completed'); } else { nextSteps.push(`Read tasks: .spec-workflow/specs/${specName}/tasks.md`); nextSteps.push('Begin implementation by marking first task [-]'); } break; case 'completed': nextSteps.push('All tasks completed (marked [x])'); nextSteps.push('Run tests'); break; } return { success: true, message: `Specification '${specName}' status: ${overallStatus}`, data: { name: specName, description: spec.description, currentPhase, overallStatus, createdAt: spec.createdAt, lastModified: spec.lastModified, phases: phaseDetails, taskProgress: spec.taskProgress || { total: 0, completed: 0, pending: 0 } }, nextSteps, projectContext: { projectPath, workflowRoot: PathUtils.getWorkflowRoot(projectPath), currentPhase, dashboardUrl: context.dashboardUrl } }; } catch (error) { const errorMessage = error instanceof Error ? error.message : String(error); return { success: false, message: `Failed to get specification status: ${errorMessage}`, nextSteps: [ 'Check if the specification exists', 'Verify the project path', 'List directory .spec-workflow/specs/ to see available specifications' ] }; } }
- src/tools/spec-status.ts:6-26 (schema)Tool definition including name, description, and input schema for 'spec-status'.export const specStatusTool: Tool = { name: 'spec-status', description: `Display comprehensive specification progress overview. # Instructions Call when resuming work on a spec or checking overall completion status. Shows which phases are complete and task implementation progress. After viewing status, read tasks.md directly to see all tasks and their status markers ([ ] pending, [-] in-progress, [x] completed).`, inputSchema: { type: 'object', properties: { projectPath: { type: 'string', description: 'Absolute path to the project root (optional - uses server context path if not provided)' }, specName: { type: 'string', description: 'Name of the specification' } }, required: ['specName'] } };
- src/tools/index.ts:9-17 (registration)Registers the specStatusTool (imported from './spec-status.js') in the array returned by registerTools() for MCP tool registration.export function registerTools(): Tool[] { return [ specWorkflowGuideTool, steeringGuideTool, specStatusTool, approvalsTool, logImplementationTool ]; }
- src/tools/index.ts:31-33 (registration)Dispatches 'spec-status' tool calls to the specStatusHandler function in the main tool handler switch statement.case 'spec-status': response = await specStatusHandler(args, context); break;
- src/tools/index.ts:3-3 (registration)Imports the tool definition and handler from the implementation file.import { specStatusTool, specStatusHandler } from './spec-status.js';