@madmatt112org/spec-workflow-mcp 3.0.0

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

@@ -0,0 +1,396 @@
+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 (Decomposition → 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: [
+            'If steering docs exist, run decomposition first with decomposition-guide',
+            'Follow sequence: Decomposition → 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 Decomposition → Requirements → Design → Tasks → Implementation phases. When steering docs exist, always begin with Decomposition to break the project into ordered specs before starting the first spec's Requirements phase. 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.
+
+## Entry Points
+
+Pick the entry point that matches the user's request before stepping through the workflow:
+
+| Situation | Where to enter |
+|---|---|
+| New feature, no spec yet | Start at the top of the diagram (CheckSteering). If steering exists, do Decomposition before Phase 1. |
+| User-provided per-task prompt (e.g. "Implement the task for spec X…") | Skip Phases 1-3 — those documents already exist. Jump to **Phase 4: Implementation** and follow that section. |
+| User asks to revise a document after a 'needs-revision' approval | Re-enter the same phase you were in; update the document, request a NEW approval. |
+| User asks for an adversarial critique of a doc | Use the \`adversarial-review\` tool (it works for any phase: requirements, design, tasks, decomposition, product, tech, structure). See "Adversarial Review" section below. |
+| User asks to respond to an adversarial review (or the approval comment requests it) | Use the \`adversarial-response\` tool. See "Adversarial Review" section below. |
+| User wants to create steering docs | Call \`steering-guide\` instead — that is a separate workflow. |
+
+## Workflow Diagram
+\`\`\`mermaid
+flowchart TD
+    Start([Start: User requests feature]) --> CheckSteering{Steering docs exist?}
+    CheckSteering -->|No| P1_Template
+
+    %% Decomposition
+    CheckSteering -->|Yes| Decomp_Check{Decomposition<br/>exists?}
+    Decomp_Check -->|Yes| P1_Load[Read steering docs +<br/>decomposition.md]
+    Decomp_Check -->|No| Decomp_Guide[Call decomposition-guide]
+    Decomp_Guide --> Decomp_Read[Read all steering docs]
+    Decomp_Read --> Decomp_Create[Create file:<br/>.spec-workflow/spec-decomposition/<br/>decomposition.md]
+    Decomp_Create --> Decomp_Approve[approvals<br/>action: request<br/>filePath only]
+    Decomp_Approve --> Decomp_Status[approvals<br/>action: status<br/>poll status]
+    Decomp_Status --> Decomp_Decision{Status?}
+    Decomp_Decision -->|needs-revision| Decomp_Update[Update document using<br/>user comments as guidance]
+    Decomp_Update --> Decomp_Create
+    Decomp_Decision -->|approved| Decomp_Clean[approvals<br/>action: delete]
+    Decomp_Clean -->|failed| Decomp_Status
+    Decomp_Clean -->|success| P1_Load
+
+    %% 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_Review[Ask user to trigger review<br/>from dashboard;<br/>then get-task-review]
+    P4_Review --> 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 Decomp_Decision fill:#ffe6e6
+    style CheckSteering fill:#fff4e6
+    style Decomp_Check fill:#fff4e6
+    style P4_More fill:#fff4e6
+    style P4_Log fill:#e3f2fd
+    style P4_Review fill:#e3f2fd
+\`\`\`
+
+## Spec Workflow
+
+### Decomposition
+**Purpose**: Break steering documents into an ordered set of specs before starting any spec work.
+
+**When**: Always, when steering docs exist in \`.spec-workflow/steering/\`.
+
+**File Operations**:
+- Read all steering docs: \`.spec-workflow/steering/product.md\`, \`tech.md\`, \`structure.md\`
+- Create document: \`.spec-workflow/spec-decomposition/decomposition.md\`
+
+**Tools**:
+- decomposition-guide: Load the decomposition methodology (principles, process, output structure)
+- approvals: Manage approval workflow (actions: request, status, delete)
+
+**Process**:
+1. Check if \`.spec-workflow/spec-decomposition/decomposition.md\` already exists (if yes, skip to Phase 1)
+2. Call \`decomposition-guide\` to load the decomposition methodology
+3. Read all steering docs in full: product.md, tech.md, structure.md
+4. Apply the methodology: identify capabilities, group into specs, order by dependencies
+5. Surface open questions to the user before finalizing
+6. Create \`decomposition.md\` at \`.spec-workflow/spec-decomposition/decomposition.md\`
+7. Request approval using approvals tool with action:'request' (pass filePath; do NOT inline document content)
+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. Proceed to Phase 1 for the first spec in the decomposition
+
+**Optional**: Run \`adversarial-review\` against the decomposition document (specName: 'decomposition', phase: 'decomposition') if you want a fresh-context critique before requesting approval. Findings can drive revisions before approval is requested.
+
+### 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 criteria
+6. Create \`requirements.md\` at \`.spec-workflow/specs/{spec-name}/requirements.md\`
+7. Request approval using approvals tool with action:'request' (pass filePath; do NOT inline document content. Required fields: filePath, type, category, name, title)
+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 sections
+6. When deferring a design decision, record it with the \`deferrals\` tool (action: add) with originSpec and originPhase set
+7. Create \`design.md\` at \`.spec-workflow/specs/{spec-name}/design.md\`
+8. Request approval using approvals tool with action:'request' (pass filePath; do NOT inline document content)
+9. Poll status using approvals with action:'status' until approved/needs-revision
+10. If needs-revision: update document using comments, create NEW approval, do NOT proceed
+11. Once approved: use approvals with action:'delete' (must succeed) before proceeding
+12. 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' (pass filePath; do NOT inline document content)
+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)
+- review-task: Invoked by the dashboard reviewer (a fresh-context agent) — you do NOT call this directly. Listed for awareness only.
+- get-task-review: Retrieve findings after a dashboard-triggered review completes (step 6)
+- Direct editing: Mark tasks as in-progress [-] or complete [x] in tasks.md
+
+**Process**:
+1. Check current status with spec-status. Check deferred decisions with \`deferrals\` tool (action: list) — if any are relevant to the current spec's work, note them and address them if the implementation naturally covers them. Resolve addressed deferrals with action: resolve.
+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
+   - **After log-implementation succeeds, request a code review**:
+     - ⚠️ Do NOT review your own implementation — self-review is biased and unreliable
+     - Ask the user to trigger a review from the dashboard Tasks page (Review button), which runs a fresh-context agent
+     - Once the dashboard review completes, call \`get-task-review\` with specName and taskId to retrieve the findings
+     - Discuss findings with the user and address any critical or warning items
+     - If verdict is "fail": address critical findings, then ask the user to trigger a re-review from the dashboard
+   - **Only after review passes or has non-critical findings**: Edit tasks.md: Change \`[-]\` to \`[x]\`
+   - **Retroactive reviews**: Reviews can also be run against tasks already marked \`[x]\`. This is useful for reviewing historical tasks, running reviews after adding new review criteria, or catching issues in code that was completed before the review feature existed. Marking a task complete does not lock it from future review.
+4. Continue until all tasks show \`[x]\`
+
+## Steering Document Loading
+
+When steering docs exist in \`.spec-workflow/steering/\`, load them selectively by phase to conserve context:
+
+| Phase | Load in full | Skim or skip |
+|---|---|---|
+| Decomposition | product.md, tech.md, structure.md | (none — load all) |
+| Requirements | product.md, decomposition.md | tech.md (skim constraints only), structure.md (skip) |
+| Design | tech.md, structure.md | product.md (skip — internalized via requirements), decomposition.md (skip) |
+| Tasks | structure.md, the spec's design.md | tech.md (skip — internalized via design), product.md (skip), decomposition.md (skip) |
+
+Each phase's output internalizes the previous phase's primary inputs. The decomposition encodes the full project scope, so requirements only needs the decomposition and product docs. The requirements encode the product vision, so the design agent doesn't need to re-read product.md. The design encodes the tech decisions, so the tasks agent doesn't need to re-read tech.md.
+
+## Adversarial Review (Optional)
+
+Two tools support adversarial analysis of spec documents:
+
+- **adversarial-review**: Prepares methodology and file paths for running an adversarial review against a spec phase document. The agent writes a tailored adversarial prompt and launches a fresh-context subagent to execute it.
+- **adversarial-response**: Finds the latest adversarial analysis and returns instructions for evaluating findings. Used when responding to a revision comment requesting adversarial review response.
+
+These are not part of the core approval flow — they are invoked when requested by the user or as a revision comment on an approval.
+
+## 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: pass \`filePath\` (and the other required fields: type, category, name, title); do NOT inline document content into the request
+- 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
+- When steering docs exist, decomposition is required before starting the first spec — call \`decomposition-guide\` for methodology
+- When explicitly deferring a decision in any phase, record it using the deferrals tool. Deferrals are project-level artifacts that persist across specs.
+
+## File Structure
+\`\`\`
+.spec-workflow/
+├── spec-decomposition/        # Decomposition output
+│   └── decomposition.md
+├── templates/           # Auto-populated on server start
+│   ├── requirements-template.md
+│   ├── design-template.md
+│   ├── tasks-template.md
+│   ├── product-template.md
+│   ├── tech-template.md
+│   └── structure-template.md
+├── deferrals/              # Project-level deferred decisions
+│   ├── d-abc123.md
+│   └── d-def456.md
+├── specs/
+│   └── {spec-name}/
+│       ├── requirements.md
+│       ├── design.md
+│       ├── tasks.md
+│       ├── reviews/                 # Adversarial review artifacts
+│       │   ├── adversarial-prompt-{phase}.md
+│       │   └── adversarial-analysis-{phase}.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;;;kYAGmX;IAChY,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,0EAA0E;YAC1E,iFAAiF;YACjF,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;;;;oaAI2Z,WAAW;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;+EAiJhW,WAAW;;;;;;;;;;;;;;;;;;;;;;;;yEAwBjB,WAAW;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAmL7E,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?" — when the user is ready, call \`spec-workflow-guide\` to load the spec workflow (which begins with Decomposition since steering docs now exist).
+
+## 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: pass \`filePath\` (and the other required fields: type, category, name, title); do NOT inline document content into the request
+- 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"}