spec-workflow-mcp-with-dashboard

Spec Workflow MCP (madmatt112 fork)

A Model Context Protocol (MCP) server for structured spec-driven development with real-time dashboard and VSCode extension.

Fork Notice

This is a hard fork of Pimzino/spec-workflow-mcp, diverged from upstream version 2.2.6 on 2026-03-13. It is not tracking upstream and will not be merged back. All issues/PRs should be filed against this repository.

The .spec-workflow/ directory layout, tool names, config keys, and SPEC_WORKFLOW_HOME environment variable remain identical to upstream, so existing state from upstream 2.2.x migrates in place.

What This Fork Adds

Four features not present in upstream:

• Adversarial Review — automated oppositional review of spec documents (requirements / design / tasks / steering / decomposition). Spawns fresh-context CLI subagents (defaults to Claude CLI; configurable for any LLM CLI) to generate and execute adversarial prompts against spec content. Dashboard button, in-card progress stepper, versioning / retry, review memory for tracking prior critiques.
• Spec Decomposition — required workflow phase that forces task breakdown before implementation. New decomposition-guide tool with dashboard integration and adversarial-review eligibility.
• Deferred Decisions Tracker — new deferrals tool and dashboard UI for recording decisions that are intentionally punted during spec authoring.
• Task Review — new review-task and get-task-review tools that spawn a fresh-context dashboard agent to review completed task implementations before they're marked done.

Key Features

• Structured Development Workflow — Sequential spec creation (Requirements → Design → Tasks) with required decomposition phase.
• Real-Time Web Dashboard — Monitor specs, tasks, and progress with live updates.
• VSCode Extension — Integrated sidebar dashboard (build-from-source for this fork; see below).
• Approval Workflow — Full approval process with revisions and adversarial review.
• Task Progress Tracking — Visual progress bars and detailed status.
• Implementation Logs — Searchable logs of all task implementations with code statistics.

🚀 Quick Start

Step 1: Add to your AI tool

Add to your MCP configuration (see client-specific setup below):

{
  "mcpServers": {
    "spec-workflow": {
      "command": "npx",
      "args": ["-y", "@madmatt112org/spec-workflow-mcp@latest", "/path/to/your/project"]
    }
  }
}

Step 2: Choose your interface

Option A: Web Dashboard (Required for CLI users)

Start the dashboard (runs on port 5000 by default):

npx -y @madmatt112org/spec-workflow-mcp@latest --dashboard

The dashboard will be accessible at: http://localhost:5000

Note: Only one dashboard instance is needed. All your projects will connect to the same dashboard.

Option B: VSCode Extension (Build from source)

The fork's extension is not yet published to the VSCode Marketplace. Build and side-install:

cd vscode-extension
npm install
npm run package    # produces a .vsix file
code --install-extension spec-workflow-mcp-<version>.vsix

📝 How to Use

Simply mention spec-workflow in your conversation:

• "Create a spec for user authentication" — Creates complete spec workflow
• "List my specs" — Shows all specs and their status
• "Execute task 1.2 in spec user-auth" — Runs a specific task

See more examples →

🔧 MCP Client Setup

{
  "mcpServers": {
    "spec-workflow": {
      "command": "npx",
      "args": ["-y", "@madmatt112org/spec-workflow-mcp@latest", "/path/to/your/project"]
    }
  }
}

claude mcp add spec-workflow npx @madmatt112org/spec-workflow-mcp@latest -- /path/to/your/project

claude mcp add spec-workflow cmd.exe /c "npx @madmatt112org/spec-workflow-mcp@latest /path/to/your/project"

{
  "mcpServers": {
    "spec-workflow": {
      "command": "npx",
      "args": ["-y", "@madmatt112org/spec-workflow-mcp@latest", "/path/to/your/project"]
    }
  }
}