Instructions

Implementation Reference

• src/tools/spec-status.ts:28-180 (handler)

  The specStatusHandler function implements the core logic for the 'spec-status' tool. It parses the specification directory structure, determines phase completion status, computes task progress, and returns a comprehensive status report with next steps.

  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 {
      // Translate path at tool entry point (components expect pre-translated paths)
      const translatedPath = PathUtils.translatePath(projectPath);
      const parser = new SpecParser(translatedPath);
      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)

  The tool definition including name, description, and inputSchema for validating arguments to the spec-status tool.

  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)

  Registration of the specStatusTool in the array returned by registerTools(), making it available to the MCP server.

  export function registerTools(): Tool[] {
    return [
      specWorkflowGuideTool,
      steeringGuideTool,
      specStatusTool,
      approvalsTool,
      logImplementationTool
    ];
  }

• src/tools/index.ts:31-33 (registration)

  Handler dispatch for 'spec-status' tool call in the central handleToolCall switch statement.

  case 'spec-status':
    response = await specStatusHandler(args, context);
    break;