@lbruton/spec-workflow-mcp 2.2.4

package/dist/tools/spec-workflow-guide.js

@@ -0,0 +1,291 @@
+export const specWorkflowGuideTool = {
+    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
+    },
+    annotations: {
+        title: 'Spec Workflow Guide',
+        readOnlyHint: true,
+    }
+};
+export async function specWorkflowGuideHandler(args, context) {
+    // Dashboard URL is populated from registry in server.ts
+    const dashboardMessage = context.dashboardUrl ?
+        `Monitor progress on dashboard: ${context.dashboardUrl}` :
+        'Please start the dashboard with: spec-workflow-mcp --dashboard';
+    return {
+        success: true,
+        message: 'Complete spec workflow guide loaded - follow this workflow exactly',
+        data: {
+            guide: getSpecWorkflowGuide(),
+            dashboardUrl: context.dashboardUrl,
+            dashboardAvailable: !!context.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() {
+    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_Log[log-implementation<br/>Record implementation<br/>details]
+    P4_Log --> 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
+    style P4_Log fill:#e3f2fd
+\`\`\`
+
+## 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, logging the implementation with log-implementation tool after completion, 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
+- Bash (grep/ripgrep): CRITICAL - Search existing code before implementing (step 3)
+- Read: Examine implementation log files directly
+- implement-task prompt: Guide for implementing tasks
+- log-implementation: Record implementation details with artifacts after task completion (step 5)
+- 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
+   - **CRITICAL: BEFORE implementing, search existing implementation logs**:
+     - Implementation logs are in: \`.spec-workflow/specs/{spec-name}/Implementation Logs/\`
+     - **Option 1: Use grep for fast searches**:
+       - \`grep -r "api\|endpoint" .spec-workflow/specs/{spec-name}/Implementation Logs/\` - Find API endpoints
+       - \`grep -r "component" .spec-workflow/specs/{spec-name}/Implementation Logs/\` - Find UI components
+       - \`grep -r "function" .spec-workflow/specs/{spec-name}/Implementation Logs/\` - Find utility functions
+       - \`grep -r "integration" .spec-workflow/specs/{spec-name}/Implementation Logs/\` - Find integration patterns
+     - **Option 2: Read markdown files directly** - Use Read tool to examine specific log files
+     - Best practice: Search 2-3 different terms to discover comprehensively
+     - This prevents: duplicate endpoints, reimplemented components, broken integrations
+     - Reuse existing code that already solves part of the task
+   - **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
+   - **MANDATORY: Log implementation BEFORE marking task complete** using log-implementation tool:
+     - ⚠️ Do NOT change [-] to [x] until log-implementation returns success
+     - A task without an implementation log is NOT complete — this is the most commonly skipped step
+     - Provide taskId and clear summary of what was implemented (1-2 sentences)
+     - Include files modified/created and code statistics (lines added/removed)
+     - **REQUIRED: Include artifacts field with structured implementation data**:
+       - apiEndpoints: All API routes created/modified (method, path, purpose, formats, location)
+       - components: All UI components created (name, type, purpose, location, props)
+       - functions: All utility functions created (name, signature, location)
+       - classes: All classes created (name, methods, location)
+       - integrations: Frontend-backend connections with data flow description
+     - Example: "Created API GET /api/todos/:id endpoint and TodoDetail React component with WebSocket real-time updates"
+     - This creates a searchable knowledge base for future AI agents to discover existing code
+     - Prevents implementation details from being lost in chat history
+   - **Only after log-implementation succeeds**: Edit tasks.md: Change \`[-]\` to \`[x]\`
+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: Every task marked [x] MUST have a corresponding implementation log — call log-implementation BEFORE changing [-] to [x]
+- 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
+│       └── Implementation Logs/     # Created automatically
+│           ├── task-1_timestamp_id.md
+│           ├── task-2_timestamp_id.md
+│           └── ...
+└── steering/
+    ├── product.md
+    ├── tech.md
+    └── structure.md
+\`\`\``;
+}
+//# sourceMappingURL=spec-workflow-guide.js.map

package/dist/tools/spec-workflow-guide.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"spec-workflow-guide.js","sourceRoot":"","sources":["../../src/tools/spec-workflow-guide.ts"],"names":[],"mappings":"AAGA,MAAM,CAAC,MAAM,qBAAqB,GAAS;IACzC,IAAI,EAAE,qBAAqB;IAC3B,WAAW,EAAE;;;kXAGmW;IAChX,WAAW,EAAE;QACX,IAAI,EAAE,QAAQ;QACd,UAAU,EAAE,EAAE;QACd,oBAAoB,EAAE,KAAK;KAC5B;IACD,WAAW,EAAE;QACX,KAAK,EAAE,qBAAqB;QAC5B,YAAY,EAAE,IAAI;KACnB;CACF,CAAC;AAEF,MAAM,CAAC,KAAK,UAAU,wBAAwB,CAAC,IAAS,EAAE,OAAoB;IAC5E,wDAAwD;IACxD,MAAM,gBAAgB,GAAG,OAAO,CAAC,YAAY,CAAC,CAAC;QAC7C,kCAAkC,OAAO,CAAC,YAAY,EAAE,CAAC,CAAC;QAC1D,gEAAgE,CAAC;IAEnE,OAAO;QACL,OAAO,EAAE,IAAI;QACb,OAAO,EAAE,oEAAoE;QAC7E,IAAI,EAAE;YACJ,KAAK,EAAE,oBAAoB,EAAE;YAC7B,YAAY,EAAE,OAAO,CAAC,YAAY;YAClC,kBAAkB,EAAE,CAAC,CAAC,OAAO,CAAC,YAAY;SAC3C;QACD,SAAS,EAAE;YACT,iEAAiE;YACjE,gDAAgD;YAChD,sCAAsC;YACtC,oBAAoB;YACpB,gBAAgB;SACjB;KACF,CAAC;AACJ,CAAC;AAED,SAAS,oBAAoB;IAC3B,MAAM,WAAW,GAAG,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;IAC7C,OAAO;;;;6PAIoP,WAAW;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;+EAqFzL,WAAW;;;;;;;;;;;;;;;;;;;;;;;yEAuBjB,WAAW;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAwI7E,CAAC;AACR,CAAC"}

package/dist/tools/steering-guide.d.ts

@@ -0,0 +1,5 @@
+import { Tool } from '@modelcontextprotocol/sdk/types.js';
+import { ToolContext, ToolResponse } from '../types.js';
+export declare const steeringGuideTool: Tool;
+export declare function steeringGuideHandler(args: any, context: ToolContext): Promise<ToolResponse>;
+//# sourceMappingURL=steering-guide.d.ts.map

package/dist/tools/steering-guide.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"steering-guide.d.ts","sourceRoot":"","sources":["../../src/tools/steering-guide.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,oCAAoC,CAAC;AAC1D,OAAO,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAExD,eAAO,MAAM,iBAAiB,EAAE,IAe/B,CAAC;AAEF,wBAAsB,oBAAoB,CAAC,IAAI,EAAE,GAAG,EAAE,OAAO,EAAE,WAAW,GAAG,OAAO,CAAC,YAAY,CAAC,CAgBjG"}

package/dist/tools/steering-guide.js

@@ -0,0 +1,192 @@
+export const steeringGuideTool = {
+    name: 'steering-guide',
+    description: `Load guide for creating project steering documents.
+
+# Instructions
+Call ONLY when user explicitly requests steering document creation or asks about project architecture docs. Not part of standard spec workflow. Provides templates and guidance for product.md, tech.md, and structure.md creation. Its important that you follow this workflow exactly to avoid errors.`,
+    inputSchema: {
+        type: 'object',
+        properties: {},
+        additionalProperties: false
+    },
+    annotations: {
+        title: 'Steering Guide',
+        readOnlyHint: true,
+    }
+};
+export async function steeringGuideHandler(args, context) {
+    return {
+        success: true,
+        message: 'Steering workflow guide loaded - follow this workflow exactly to avoid errors',
+        data: {
+            guide: getSteeringGuide(),
+            dashboardUrl: context.dashboardUrl
+        },
+        nextSteps: [
+            'Only proceed if user requested steering docs',
+            'Create product.md first',
+            'Then tech.md and structure.md',
+            'Reference in future specs',
+            context.dashboardUrl ? `Dashboard: ${context.dashboardUrl}` : 'Start the dashboard with: spec-workflow-mcp --dashboard'
+        ]
+    };
+}
+function getSteeringGuide() {
+    return `# Steering Workflow
+
+## Overview
+
+Create project-level guidance documents when explicitly requested. Steering docs establish vision, architecture, and conventions for established codebases. Its important that you follow this workflow exactly to avoid errors.
+
+## Workflow Diagram
+
+\`\`\`mermaid
+flowchart TD
+    Start([Start: Setup steering docs]) --> Guide[steering-guide<br/>Load workflow instructions]
+
+    %% Phase 1: Product
+    Guide --> P1_Template[Check user-templates first,<br/>then read template:<br/>product-template.md]
+    P1_Template --> P1_Generate[Generate vision & goals]
+    P1_Generate --> P1_Create[Create file:<br/>.spec-workflow/steering/<br/>product.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 for guidance]
+    P1_Update --> P1_Create
+    P1_Check -->|approved| P1_Clean[approvals<br/>action: delete]
+    P1_Clean -->|failed| P1_Status
+
+    %% Phase 2: Tech
+    P1_Clean -->|success| P2_Template[Check user-templates first,<br/>then read template:<br/>tech-template.md]
+    P2_Template --> P2_Analyze[Analyze tech stack]
+    P2_Analyze --> P2_Create[Create file:<br/>.spec-workflow/steering/<br/>tech.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 for guidance]
+    P2_Update --> P2_Create
+    P2_Check -->|approved| P2_Clean[approvals<br/>action: delete]
+    P2_Clean -->|failed| P2_Status
+
+    %% Phase 3: Structure
+    P2_Clean -->|success| P3_Template[Check user-templates first,<br/>then read template:<br/>structure-template.md]
+    P3_Template --> P3_Analyze[Analyze codebase structure]
+    P3_Analyze --> P3_Create[Create file:<br/>.spec-workflow/steering/<br/>structure.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 for guidance]
+    P3_Update --> P3_Create
+    P3_Check -->|approved| P3_Clean[approvals<br/>action: delete]
+    P3_Clean -->|failed| P3_Status
+
+    P3_Clean -->|success| Complete([Steering docs complete])
+
+    style Start fill:#e6f3ff
+    style Complete fill:#e6f3ff
+    style P1_Check fill:#ffe6e6
+    style P2_Check fill:#ffe6e6
+    style P3_Check fill:#ffe6e6
+\`\`\`
+
+## Steering Workflow Phases
+
+### Phase 1: Product Document
+**Purpose**: Define vision, goals, and user outcomes.
+
+**File Operations**:
+- Check for custom template: \`.spec-workflow/user-templates/product-template.md\`
+- Read template: \`.spec-workflow/templates/product-template.md\` (if no custom template)
+- Create document: \`.spec-workflow/steering/product.md\`
+
+**Tools**:
+- steering-guide: Load workflow instructions
+- approvals: Manage approval workflow (actions: request, status, delete)
+
+**Process**:
+1. Load steering guide for workflow overview
+2. Check for custom template at \`.spec-workflow/user-templates/product-template.md\`
+3. If no custom template, read from \`.spec-workflow/templates/product-template.md\`
+4. Generate product vision and goals
+5. Create \`product.md\` at \`.spec-workflow/steering/product.md\`
+6. Request approval using approvals tool with action:'request' (filePath only)
+7. Poll status using approvals with action:'status' until approved/needs-revision (NEVER accept verbal approval)
+8. If needs-revision: update document using comments, create NEW approval, do NOT proceed
+9. Once approved: use approvals with action:'delete' (must succeed) before proceeding
+10. If delete fails: STOP - return to polling
+
+### Phase 2: Tech Document
+**Purpose**: Document technology decisions and architecture.
+
+**File Operations**:
+- Check for custom template: \`.spec-workflow/user-templates/tech-template.md\`
+- Read template: \`.spec-workflow/templates/tech-template.md\` (if no custom template)
+- Create document: \`.spec-workflow/steering/tech.md\`
+
+**Tools**:
+- approvals: Manage approval workflow (actions: request, status, delete)
+
+**Process**:
+1. Check for custom template at \`.spec-workflow/user-templates/tech-template.md\`
+2. If no custom template, read from \`.spec-workflow/templates/tech-template.md\`
+3. Analyze existing technology stack
+4. Document architectural decisions and patterns
+5. Create \`tech.md\` at \`.spec-workflow/steering/tech.md\`
+6. Request approval using approvals tool with action:'request'
+7. Poll status using approvals with action:'status' until approved/needs-revision
+8. If needs-revision: update document using comments, create NEW approval, do NOT proceed
+9. Once approved: use approvals with action:'delete' (must succeed) before proceeding
+10. If delete fails: STOP - return to polling
+
+### Phase 3: Structure Document
+**Purpose**: Map codebase organization and patterns.
+
+**File Operations**:
+- Check for custom template: \`.spec-workflow/user-templates/structure-template.md\`
+- Read template: \`.spec-workflow/templates/structure-template.md\` (if no custom template)
+- Create document: \`.spec-workflow/steering/structure.md\`
+
+**Tools**:
+- approvals: Manage approval workflow (actions: request, status, delete)
+
+**Process**:
+1. Check for custom template at \`.spec-workflow/user-templates/structure-template.md\`
+2. If no custom template, read from \`.spec-workflow/templates/structure-template.md\`
+3. Analyze directory structure and file organization
+4. Document coding patterns and conventions
+5. Create \`structure.md\` at \`.spec-workflow/steering/structure.md\`
+6. Request approval using approvals tool with action:'request'
+7. Poll status using approvals with action:'status' until approved/needs-revision
+8. If needs-revision: update document using comments, create NEW approval, do NOT proceed
+9. Once approved: use approvals with action:'delete' (must succeed) before proceeding
+10. If delete fails: STOP - return to polling
+11. After successful cleanup: "Steering docs complete. Ready for spec creation?"
+
+## Workflow Rules
+
+- Create documents directly at specified file paths
+- Check for custom templates in \`.spec-workflow/user-templates/\` first
+- Read templates from \`.spec-workflow/templates/\` directory if no custom template exists
+- Follow exact template structures
+- Get explicit user approval between phases (using approvals tool with action:'request')
+- Complete phases in sequence (no skipping)
+- 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
+
+## File Structure
+\`\`\`
+.spec-workflow/
+├── templates/           # Auto-populated on server start
+│   ├── product-template.md
+│   ├── tech-template.md
+│   └── structure-template.md
+└── steering/
+    ├── product.md
+    ├── tech.md
+    └── structure.md
+\`\`\``;
+}
+//# sourceMappingURL=steering-guide.js.map

package/dist/tools/steering-guide.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"steering-guide.js","sourceRoot":"","sources":["../../src/tools/steering-guide.ts"],"names":[],"mappings":"AAGA,MAAM,CAAC,MAAM,iBAAiB,GAAS;IACrC,IAAI,EAAE,gBAAgB;IACtB,WAAW,EAAE;;;ySAG0R;IACvS,WAAW,EAAE;QACX,IAAI,EAAE,QAAQ;QACd,UAAU,EAAE,EAAE;QACd,oBAAoB,EAAE,KAAK;KAC5B;IACD,WAAW,EAAE;QACX,KAAK,EAAE,gBAAgB;QACvB,YAAY,EAAE,IAAI;KACnB;CACF,CAAC;AAEF,MAAM,CAAC,KAAK,UAAU,oBAAoB,CAAC,IAAS,EAAE,OAAoB;IACxE,OAAO;QACL,OAAO,EAAE,IAAI;QACb,OAAO,EAAE,+EAA+E;QACxF,IAAI,EAAE;YACJ,KAAK,EAAE,gBAAgB,EAAE;YACzB,YAAY,EAAE,OAAO,CAAC,YAAY;SACnC;QACD,SAAS,EAAE;YACT,8CAA8C;YAC9C,yBAAyB;YACzB,+BAA+B;YAC/B,2BAA2B;YAC3B,OAAO,CAAC,YAAY,CAAC,CAAC,CAAC,cAAc,OAAO,CAAC,YAAY,EAAE,CAAC,CAAC,CAAC,yDAAyD;SACxH;KACF,CAAC;AACJ,CAAC;AAED,SAAS,gBAAgB;IACvB,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA2JF,CAAC;AACR,CAAC"}

package/dist/types.d.ts

@@ -0,0 +1,172 @@
+export interface AutomationJob {
+    id: string;
+    name: string;
+    type: 'cleanup-approvals' | 'cleanup-specs' | 'cleanup-archived-specs';
+    enabled: boolean;
+    config: {
+        daysOld: number;
+    };
+    schedule: string;
+    lastRun?: string;
+    nextRun?: string;
+    createdAt: string;
+}
+export interface SecurityConfig {
+    rateLimitEnabled: boolean;
+    rateLimitPerMinute: number;
+    auditLogEnabled: boolean;
+    auditLogPath?: string;
+    auditLogRetentionDays: number;
+    corsEnabled: boolean;
+    allowedOrigins: string[];
+}
+export interface GlobalSettings {
+    automationJobs: AutomationJob[];
+    security?: SecurityConfig;
+    createdAt?: string;
+    lastModified?: string;
+}
+export interface JobExecutionHistory {
+    jobId: string;
+    jobName: string;
+    jobType: string;
+    executedAt: string;
+    success: boolean;
+    duration: number;
+    itemsProcessed: number;
+    itemsDeleted: number;
+    error?: string;
+}
+export interface JobExecutionLog {
+    executions: JobExecutionHistory[];
+    lastUpdated?: string;
+}
+export interface ToolContext {
+    projectPath: string;
+    dashboardUrl?: string;
+    lang?: string;
+}
+export interface SpecData {
+    name: string;
+    description?: string;
+    createdAt: string;
+    lastModified: string;
+    phases: {
+        requirements: PhaseStatus;
+        design: PhaseStatus;
+        tasks: PhaseStatus;
+        implementation: PhaseStatus;
+    };
+    taskProgress?: {
+        total: number;
+        completed: number;
+        pending: number;
+    };
+}
+export interface PhaseStatus {
+    exists: boolean;
+    approved?: boolean;
+    lastModified?: string;
+    content?: string;
+}
+export interface SteeringStatus {
+    exists: boolean;
+    documents: {
+        product: boolean;
+        tech: boolean;
+        structure: boolean;
+    };
+    lastModified?: string;
+}
+export interface PromptSection {
+    key: string;
+    value: string;
+}
+export interface TaskInfo {
+    id: string;
+    description: string;
+    leverage?: string;
+    requirements?: string;
+    completed: boolean;
+    details?: string[];
+    prompt?: string;
+    promptStructured?: PromptSection[];
+}
+export interface ImplementationLogEntry {
+    id: string;
+    taskId: string;
+    timestamp: string;
+    summary: string;
+    filesModified: string[];
+    filesCreated: string[];
+    statistics: {
+        linesAdded: number;
+        linesRemoved: number;
+        filesChanged: number;
+    };
+    artifacts: {
+        apiEndpoints?: Array<{
+            method: string;
+            path: string;
+            purpose: string;
+            requestFormat?: string;
+            responseFormat?: string;
+            location: string;
+        }>;
+        components?: Array<{
+            name: string;
+            type: string;
+            purpose: string;
+            location: string;
+            props?: string;
+            exports?: string[];
+        }>;
+        functions?: Array<{
+            name: string;
+            purpose: string;
+            location: string;
+            signature?: string;
+            isExported: boolean;
+        }>;
+        classes?: Array<{
+            name: string;
+            purpose: string;
+            location: string;
+            methods?: string[];
+            isExported: boolean;
+        }>;
+        integrations?: Array<{
+            description: string;
+            frontendComponent: string;
+            backendEndpoint: string;
+            dataFlow: string;
+        }>;
+    };
+}
+export interface ImplementationLog {
+    entries: ImplementationLogEntry[];
+    lastUpdated?: string;
+}
+export interface ToolResponse {
+    success: boolean;
+    message: string;
+    data?: any;
+    nextSteps?: string[];
+    projectContext?: {
+        projectPath: string;
+        workflowRoot: string;
+        specName?: string;
+        currentPhase?: string;
+        dashboardUrl?: string;
+    };
+}
+export interface MCPToolResponse {
+    content: Array<{
+        type: "text";
+        text: string;
+    }>;
+    isError?: boolean;
+    _meta?: Record<string, any>;
+}
+export declare function toMCPResponse(response: ToolResponse, isError?: boolean): MCPToolResponse;
+//# sourceMappingURL=types.d.ts.map