@madmatt112org/spec-workflow-mcp

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"]
    }
  }
}

{
  "mcpServers": {
    "spec-workflow": {
      "command": "npx",
      "args": ["-y", "@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"]
    }
  }
}

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

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "spec-workflow": {
      "type": "local",
      "command": ["npx", "-y", "@madmatt112org/spec-workflow-mcp@latest", "/path/to/your/project"],
      "enabled": true
    }
  }
}

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

[mcp_servers.spec-workflow]
command = "npx"
args = ["-y", "@madmatt112org/spec-workflow-mcp@latest", "/path/to/your/project"]

Docker Deployment

Run the dashboard in a Docker container for isolated deployment:

# Using Docker Compose (recommended)
cd containers
docker-compose up --build

# Or using Docker CLI
docker build -f containers/Dockerfile -t spec-workflow-mcp .
docker run -p 5000:5000 -v "./workspace/.spec-workflow:/workspace/.spec-workflow:rw" spec-workflow-mcp

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

See Docker setup guide →

Security

Spec-Workflow MCP includes enterprise-grade security features suitable for corporate environments:

Implemented Security Controls

Not Yet Implemented

For External/Network Access

If you need to expose the dashboard beyond localhost, we recommend:

1. Keep dashboard on localhost (127.0.0.1)
2. Use nginx or Apache as a reverse proxy with:
   • TLS/HTTPS termination
   • Basic authentication or OAuth2
3. Configure firewall rules to restrict access

# Example nginx reverse proxy with auth
server {
    listen 443 ssl;
    server_name dashboard.example.com;

    ssl_certificate /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;

    auth_basic "Dashboard Access";
    auth_basic_user_file /etc/nginx/.htpasswd;

    location / {
        proxy_pass http://127.0.0.1:5000;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }
}

See Docker security guide →

Sandboxed Environments

For sandboxed environments (e.g., Codex CLI with sandbox_mode=workspace-write) where $HOME is read-only, use the SPEC_WORKFLOW_HOME environment variable to redirect global state files to a writable location:

SPEC_WORKFLOW_HOME=/workspace/.spec-workflow-mcp npx -y @madmatt112org/spec-workflow-mcp@latest /workspace

See Configuration Guide →

Reviewer Configuration

The dashboard's adversarial-review and task-review subagents read their per-runner configuration from .spec-workflow/adversarial-settings.json. This section covers the runner/model keys; the same file also holds dashboard-managed keys (requiredPhases, customPreamble, reviewMethodology, responseMethodology) documented in docs/CONFIGURATION.md. The runner config uses a grouped per-runner shape with a legacy top-level fallback:

{
  "adversarial": { "model": "claude-opus-4-7" },
  "taskReview":  { "model": "claude-haiku-4-5" },
  "features":    { "typecheck": true },
  "model":       "claude-sonnet-4-6",
  "cli":         "claude",
  "cliArgs":     ["--print", "--output-format", "stream-json", "--verbose"]
}

• adversarial.model / taskReview.model — per-runner model overrides. The grouped shape extends naturally for future per-runner settings (e.g. cliArgs) without a config migration.
• model — legacy top-level fallback used when a runner's per-runner override is absent. Stays valid indefinitely; there is no deprecation timeline.
• features.typecheck — boolean kill switch for the tsc --noEmit pre-computation that review-task action: prepare runs against TypeScript projects. Defaults to enabled; set to false to disable.
• cli / cliArgs — global CLI command and arguments used to spawn both runners. Per-runner overrides are not implemented in v1.

Precedence ladder (per-runner): per-runner override (adversarial.model / taskReview.model) > legacy top-level model > undefined (no --model flag passed; CLI default applies).

Empty-string clears the override: setting adversarial.model: "" or taskReview.model: "" is treated as "explicitly cleared" — the runner falls back to the legacy model, or to undefined if legacy is absent. This is the documented way to disable a per-runner override without removing the key.

Retry behavior

When a review is retried from the dashboard, the retry runner reuses the model the initial run was invoked with, looked up from the prior runner job. This keeps per-review telemetry and billing consistent across the initial and retry attempts. Per-retry model overrides are intentionally not supported.

Server-restart fallback: if the dashboard server restarts between an initial review and its retry, the prior runner job is gone (jobs live in an in-memory map that does not persist across restarts). The retry handler falls back to re-resolving the model from current settings, logging [spec-workflow] retry: prior job not found in runner, re-resolving model from settings once per process. This is documented degraded behavior; persisting jobs across restarts is out of scope for v1.

Only model is pinned across retry; cli and cliArgs always reflect current settings, so editing cliArgs between an initial run and its retry causes the retry to use the edited cliArgs while still using the initial run's model.

If you upgrade the CLI binary or claude-cli package between an initial run and its retry AND the model name from the initial run is no longer valid (deprecated, renamed), the retry will fail inside the spawned process with the CLI's "unknown model" error — recover by clearing the prior job (trigger a fresh initial run, or restart the dashboard server to clear the in-memory job map).

Limitations

Concurrent prepare against the same project is unsupported in v1. Running two review-task action: prepare invocations against the same project simultaneously may corrupt the typecheck buildinfo cache. Recovery: rm <projectPath>/.spec-workflow/.cache/tsc.tsbuildinfo.

Documentation

• Configuration Guide - Command-line options, config files
• User Guide - Comprehensive usage examples
• Workflow Process - Development workflow and best practices
• Autonomous Usage - Non-interactive / headless operation
• Interfaces Guide - Dashboard and VSCode extension details
• Prompting Guide - Advanced prompting examples
• Tools Reference - Complete tools documentation
• Development - Contributing and development setup
• Troubleshooting - Common issues and solutions

Project Structure

your-project/
  .spec-workflow/
    approvals/
    archive/
    spec-decomposition/
    specs/
    steering/
    templates/
    user-templates/
    config.example.toml

Development

# Install dependencies
npm install

# Build the project
npm run build

# Run in development mode
npm run dev

See development guide →

Publishing to npm

This package publishes to npm as @madmatt112org/spec-workflow-mcp via a manually-dispatched GitHub Actions workflow. Three gates run before any version reaches the registry.

Version source

package.json version is the single source of truth. There is no auto-bump. Use npm version (preferred) or edit package.json directly:

npm version patch    # 3.0.0 → 3.0.1, also creates git tag v3.0.1
npm version minor    # 3.0.0 → 3.1.0
npm version major    # 3.0.0 → 4.0.0

scripts/sync-plugin-version.js keeps the .claude-plugin/*.json manifest versions in sync. After bumping, run npm run sync:plugin-version to update the manifests; CI runs npm run check:plugin-version and fails if they drift.

Publish gates

The Publish to npm workflow (.github/workflows/npm-publish.yml) runs three jobs in sequence — every step must pass before the publish job runs:

1. test — calls ci.yml (typecheck, build, plugin-version sync check, full vitest suite).
2. preflight:
   • Registry uniqueness: aborts if package.json version is already published.
   • Git tag check: requires a v<version> tag pointing at the exact commit being run.
3. publish — npm publish --access public --tag <input>.

Publishing steps

# 1. Bump version + create matching git tag
npm version patch          # or minor / major

# 2. Push commit and tag together
git push origin main --follow-tags

# 3. Trigger the workflow
#    GitHub → Actions → "Publish to npm" → "Run workflow"
#    tag input: latest (or beta / next for pre-release routing)

The tag input controls the npm dist-tag, not the version. For a first cautious release, dispatch with next, then promote later:

npm dist-tag add @madmatt112org/spec-workflow-mcp@<version> latest

Required secrets

Set in Settings → Secrets and variables → Actions:

• NPM_TOKEN — npm Granular Access Token with read+write on @madmatt112org/*. 2FA-for-publish must be enabled on the npm account.

Common failure modes

License

GPL-3.0

Credit

Originally forked from Pimzino/spec-workflow-mcp at version 2.2.6. Upstream did not respond to feature PRs, so this fork carries the work forward independently. Released under the same GPL-3.0 license as upstream.