Skip to content
/
Tier A A3 MCP-anchored

Pimzino spec-workflow-mcp

spec-workflow-mcp · Pimzino/spec-workflow-mcp · ★ 4.2k · last commit 2026-05-05

MCP server providing spec-driven development workflow with dashboard-backed approval gates, implementation logging, and VSCode extension for multi-tool AI clients.

Best whenHuman approval should be a blocking gate in a dedicated UI (dashboard or VSCode sidebar), not a question asked in chat that the conversation can accidentally…
Skip ifIncluding document content in approvals tool calls, Running multiple dashboard instances for the same team
vs seeds
spec-kitit adds real-time dashboard and approval tracking but replaces the Python CLI with an npx server.
Primitive shape 10 total
MCP tools 10
00

Summary

spec-workflow-mcp — Summary

spec-workflow-mcp (Pimzino) is an MCP (Model Context Protocol) server for spec-driven development, packaged as @pimzino/spec-workflow-mcp v2.2.7 under GPL-3.0. It exposes 5 MCP tools (spec-workflow-guide, steering-guide, spec-status, approvals, log-implementation) and 5 MCP prompts (create-spec, create-steering-doc, implement-task, inject-spec-workflow-guide, inject-steering-guide) to any MCP-capable AI client. Its dashboard (Node.js + Vite-built React frontend) runs on port 5000 and provides real-time spec tracking, task progress bars, implementation logs, and a formal approval workflow where the AI agent requests dashboard-based review and waits for explicit user approval before continuing. A VSCode extension is separately available on the VSCode Marketplace. This is the successor to claude-code-spec-workflow (Claude Code-only) and explicitly targets multi-client compatibility (Augment Code, Claude Code, Claude Desktop, Cline, Cursor, and others). Version 2.2.7, last committed May 2026.

Differs from seeds: Most similar to taskmaster-ai (MCP-anchored toolserver pattern) but focuses on spec-driven workflow rather than task management. The approvals tool is unique in the corpus — it bridges the MCP server's file system access with the browser dashboard to create a human-in-the-loop gate that survives session boundaries. Compared to claude-code-spec-workflow (its predecessor), it replaces slash commands with MCP tools and adds a VSCode extension sidebar, making it the only framework in the batch that ships both an MCP server and an IDE extension. Compared to spec-kit, it adds a real-time dashboard and formal approval workflow, but lacks spec-kit's Python CLI installer.

01

Overview

spec-workflow-mcp — Overview

Origin

Created by Pimzino as the MCP-based successor to claude-code-spec-workflow. The predecessor README states: "Development focus has shifted to the MCP version of this workflow system. The MCP version provides enhanced features, real-time dashboard, and broader AI tool compatibility." First published on npm as @pimzino/spec-workflow-mcp. Version 2.2.7 (May 2026). License: GPL-3.0 (more restrictive than the predecessor's MIT).

Philosophy (From README)

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

"Simply mention spec-workflow in your conversation: 'Create a spec for user authentication' — Creates complete spec workflow; 'Execute task 1.2 in spec user-auth' — Runs a specific task."

Key Design Choices

  1. MCP tool architecture: All workflow operations exposed as MCP tools, not slash commands. Any MCP-capable client (Claude Desktop, Cursor, Cline, Augment) can use the same server with no per-client installation.

  2. Dashboard-gated approvals: The approvals MCP tool creates approval requests that appear in the web dashboard (or VSCode sidebar). The AI agent literally cannot continue until the dashboard shows an explicit approval — a stronger gate than just asking the user a question in chat.

  3. Implementation logging: log-implementation tool lets agents record what was done and what files were changed for each task. Logs appear in the dashboard's "Logs" tab, preventing implementation details from being lost in chat history.

  4. VSCode Extension: Separate extension (Pimzino.spec-workflow-mcp) provides the same dashboard functionality in a VSCode sidebar panel — users don't need to manage a separate browser tab.

  5. Multi-language support: 11 languages supported (English, Japanese, Chinese, Spanish, Portuguese, German, French, Russian, Italian, Korean, Arabic) — internationalization built into the MCP server's prompt templates.

  6. Spec-workflow spec storage under .spec-workflow/: Files stored in .spec-workflow/specs/ and .spec-workflow/templates/, not .claude/ or .kiro/ — its own namespace.

Antipatterns

  • Including document content in approvals tool calls (dashboard reads files directly; content inclusion wastes tokens)
  • Running multiple dashboard instances (one instance serves all projects)
02

Architecture

spec-workflow-mcp — Architecture

Distribution

  • npm package: @pimzino/spec-workflow-mcp v2.2.7
  • CLI binary: spec-workflow-mcp (entrypoint dist/index.js)
  • VSCode Extension: Pimzino.spec-workflow-mcp (separate from npm package; on VSCode Marketplace)
  • TypeScript + ESM; built with tsc + vite (dashboard frontend)
  • License: GPL-3.0

Install

# Add to MCP configuration (any MCP-capable client):
npx -y @pimzino/spec-workflow-mcp@latest /path/to/your/project

# Claude Code:
claude mcp add spec-workflow npx @pimzino/spec-workflow-mcp@latest -- /path/to/project

# Start dashboard:
npx -y @pimzino/spec-workflow-mcp@latest --dashboard
# Dashboard accessible at http://localhost:5000

Directory Tree (project-level, created by tools)

.spec-workflow/
  specs/
    {feature-name}/
      requirements.md
      design.md
      tasks.md
  templates/
    requirements-template.md
    design-template.md
    tasks-template.md
  steering/
    product.md
    tech.md
    structure.md

Required Runtime

  • Node.js ≥ 18
  • Any MCP-capable AI client

Source Structure

src/
  index.ts           # MCP server entry point
  server.ts          # MCP server setup
  types.ts           # Shared types
  tools/
    approvals.ts           # Approval workflow tool
    spec-workflow-guide.ts # Workflow guidance
    spec-status.ts         # Status reporting
    steering-guide.ts      # Steering document guide
    log-implementation.ts  # Implementation logging
    index.ts               # Tool registration
  prompts/
    create-spec.ts         # Spec creation prompt
    create-steering-doc.ts
    implement-task.ts
    inject-spec-workflow-guide.ts
    inject-steering-guide.ts
  core/
    parser.ts
    task-validator.ts
    task-parser.ts
    path-utils.ts
    workspace-initializer.ts
    project-registry.ts
    git-utils.ts
    implementation-log-migrator.ts
    dashboard-session.ts
  dashboard/
    approval-storage.ts    # Approval state persistence
    ...
  dashboard_frontend/      # Vite-built React frontend
vscode-extension/          # Separate VSCode extension source

Target AI Tools (MCP clients supported)

Claude Code, Claude Desktop, Cursor, Cline/Claude Dev, Augment Code, and any other MCP-compliant client.

03

Components

spec-workflow-mcp — Components

MCP Tools (5)

Tool Name Purpose
spec-workflow-guide Returns workflow guidance and best practices for the spec-driven development methodology
steering-guide Returns guidance for creating and using steering documents
spec-status Shows status of all specs and tasks for a given project
approvals Create/check/delete approval requests that appear in the dashboard; supports request, status, delete actions
log-implementation Record implementation details (files changed, what was done) for a completed task; logs appear in dashboard

MCP Prompts (5)

Prompt Name Purpose
create-spec Template for creating a spec document (requirements/design/tasks) — reads template file, creates at correct path, then requests dashboard approval
create-steering-doc Template for creating steering documents
implement-task Template for implementing a specific task from the spec
inject-spec-workflow-guide Injects workflow guidance into conversation context
inject-steering-guide Injects steering guidance into conversation context

CLI Binary

Name Purpose
spec-workflow-mcp Starts the MCP server (stdin/stdout); pass --dashboard to start web dashboard on port 5000

Dashboard Features

  • Real-time spec and task progress tracking
  • Approval workflow (request → dashboard display → user approve/reject/request-revision → agent continues)
  • Implementation log viewer ("Logs" tab)
  • Project registry (multiple projects connected to one dashboard instance)
  • WebSocket-based live updates

VSCode Extension

  • Provides same dashboard as sidebar panel in VSCode
  • Available on VSCode Marketplace as Pimzino.spec-workflow-mcp
  • Multi-language UI (English, Japanese, Chinese)
05

Prompts

spec-workflow-mcp — Prompts

Excerpt 1: create-spec Prompt — Template-Driven Document Creation

Source: src/prompts/create-spec.ts

Prompting technique: Template-enforced structure; explicit workflow sequencing (requirements → design → tasks); distinct task-document instructions with _Prompt, _Leverage, _Requirements fields for AI-executable task definitions.

text: `Create a ${documentType} document for the "${specName}" feature using the spec-workflow methodology.

**Instructions:**
1. First, read the template at: .spec-workflow/templates/${documentType}-template.md
2. Follow the template structure exactly - this ensures consistency across the project
3. Create comprehensive content that follows spec-driven development best practices
4. Include all required sections from the template
5. Use clear, actionable language
6. Create the document at: .spec-workflow/specs/${specName}/${documentType}.md
7. After creating, use approvals tool with action:'request' to get user approval

**Workflow Guidelines:**
- Requirements documents define WHAT needs to be built
- Design documents define HOW it will be built  
- Tasks documents break down implementation into actionable steps
- Each document builds upon the previous one in sequence
- Templates are automatically updated on server start

${documentType === 'tasks' ? `
**Special Instructions for Tasks Document:**
- For each task, generate a _Prompt field with structured AI guidance
- Format: _Prompt: Role: [role] | Task: [description] | Restrictions: [constraints] | Success: [criteria]
- Make prompts specific to the project context and requirements
- Include _Leverage fields pointing to existing code to reuse
- Include _Requirements fields showing which requirements each task implements
- Tasks should be atomic (1-3 files each) and in logical order` : ''}`

Excerpt 2: approvals Tool — Dashboard-Gated Approval Protocol

Source: src/tools/approvals.ts

Prompting technique: CRITICAL stop rule with explicit file-path-only protocol to avoid token waste; state-machine model (pending → approved/rejected/needs-revision).

description: `Manage approval requests through the dashboard interface.

# Instructions
Use this tool to request, check status, or delete approval requests. The action parameter determines the operation:
- 'request': Create a new approval request after creating each document
- 'status': Check the current status of an approval request
- 'delete': Clean up completed, rejected, or needs-revision approval requests (cannot delete pending requests)

CRITICAL: Only provide filePath parameter for requests - the dashboard reads files directly. Never include document content. Wait for user to review and approve before continuing.`

Excerpt 3: spec-workflow-guide Tool — Workflow Injection

Source: src/tools/spec-workflow-guide.ts

Prompting technique: Guidance injection — provides workflow methodology as tool output rather than system prompt, allowing any MCP client to receive the same guidance without CLAUDE.md configuration.

09

Uniqueness

spec-workflow-mcp — Uniqueness and Positioning

Differs from Seeds

Closest to taskmaster-ai in the MCP-anchored toolserver pattern (both expose workflow operations as MCP tools and rely on file-based state). Key differences: spec-workflow-mcp focuses on the spec-creation and approval phase rather than task breakdown and execution; its approvals tool creates a dashboard-backed human-in-the-loop gate that is unique in the corpus. Compared to claude-code-spec-workflow (its direct predecessor), it replaces Claude Code-specific slash commands with MCP tools and adds a VSCode extension sidebar. Compared to spec-kit (GitHub), it adds a formal approval workflow and real-time dashboard but replaces the Python CLI installer with an npx server. No other framework in the batch ships both an MCP server and a VSCode extension alongside a web dashboard.

Distinctive Positioning

  1. Dashboard-backed approval gates: The approvals tool creates a formal approval request visible in the browser/VSCode sidebar. The agent cannot proceed until the dashboard shows approval — this is structurally different from just asking the user a question in chat, where the conversation can continue accidentally.
  2. Implementation logging as first-class feature: log-implementation tool with a dedicated "Logs" tab in the dashboard prevents implementation context from being lost as chat scrolls away. No other framework in the batch has this.
  3. GPL-3.0 license (vs MIT for predecessor) — more restrictive; may affect commercial adoption.
  4. VSCode extension + MCP server combo: The only framework in the batch that ships both an IDE extension and an MCP server as coordinated components.
  5. Natural language invocation: No slash commands — the agent infers which tool to call from the user's natural language, relying on MCP tool descriptions as the interface.

Observable Failure Modes

  1. Approval state loss on server restart: If the dashboard server restarts, pending approvals may be lost unless approval-storage.ts persists to disk (unclear from code inspection).
  2. One dashboard per environment: README warns "Only one dashboard instance is needed. All your projects will connect to the same dashboard." — if multiple developers share a project registry, approval signals can be ambiguous.
  3. No slash-command discoverability: Natural-language invocation means users must know to say "create a spec for X" — the tool won't surface itself unless the inject-spec-workflow-guide prompt is used to prime context.
  4. GPL-3.0 viral licensing: Any project that embeds or modifies spec-workflow-mcp must release under GPL-3.0 — unusual for a developer tooling package.
04

Workflow

spec-workflow-mcp — Workflow

Phases and Artifacts

Phase Agent Action Artifact Approval Gate
0. Steering Use steering-guide prompt + create-steering-doc .spec-workflow/steering/product.md, tech.md, structure.md Optional
1. Requirements Use create-spec prompt with documentType: requirements .spec-workflow/specs/{name}/requirements.md approvals tool → dashboard
2. Design Use create-spec prompt with documentType: design .spec-workflow/specs/{name}/design.md approvals tool → dashboard
3. Tasks Use create-spec prompt with documentType: tasks .spec-workflow/specs/{name}/tasks.md approvals tool → dashboard
4. Implementation Use implement-task prompt per task Code changes log-implementation tool

Approval Workflow (Distinctive Feature)

1. Agent creates document (requirements.md / design.md / tasks.md)
2. Agent calls approvals tool with action:'request', filePath to document
3. Dashboard shows document for user review
4. User clicks Approve / Reject / Request Revision in dashboard
5. Agent polls approvals tool with action:'status' until resolved
6. If approved: proceed to next phase
7. If rejected/revision: agent revises document and re-requests approval

The approvals tool stores approval state in approval-storage.ts — state persists across sessions.

Implementation Logging Protocol

After implementing each task:

1. Agent uses log-implementation tool with:
   - task description
   - files changed
   - implementation summary
2. Log appears in dashboard "Logs" tab
3. Prevents implementation decisions from being lost in chat history

Usage (Natural Language Invocation)

Unlike slash-command frameworks, this is invoked via natural language:

  • "Create a spec for user authentication" — agent calls create-spec prompt
  • "List my specs" — agent calls spec-status tool
  • "Execute task 1.2 in spec user-auth" — agent calls implement-task prompt
06

Memory Context

spec-workflow-mcp — Memory and Context

State Storage

Hybrid: file-based for spec content + server-side persistent for approval state.

Storage Content
.spec-workflow/specs/{feature}/requirements.md Feature requirements
.spec-workflow/specs/{feature}/design.md Technical design
.spec-workflow/specs/{feature}/tasks.md Task list with _Prompt, _Leverage, _Requirements fields
.spec-workflow/steering/*.md Project-wide context documents
.spec-workflow/templates/*.md Document templates (auto-updated on server start)
MCP server approval-storage.ts In-process approval state storage (pending/approved/rejected/needs-revision)
Dashboard session storage Project registry, implementation logs

Persistence Level

project for spec files; server-level for approval state (lost on server restart unless persisted to disk via approval-storage.ts).

Cross-Session Handoff

Yes — spec files on disk provide complete state for resumption. Approval state may need re-requesting if server restarts.

Context Compaction

The MCP tool architecture naturally handles context compaction: tools return targeted information rather than loading full file contents into the conversation. The spec-workflow-guide tool injects guidance on demand rather than requiring it in every context window.

Implementation Logs

log-implementation tool writes structured logs accessible via the dashboard "Logs" tab. This is the primary audit trail — prevents implementation decisions from being lost as chat history scrolls away.

Multi-Project Support

project-registry.ts tracks multiple projects connected to a single dashboard instance. One dashboard server handles N projects.

07

Orchestration

spec-workflow-mcp — Orchestration

Multi-Agent

No — the MCP server is single-agent. The agent calls MCP tools; no subagent spawning mechanism.

Orchestration Pattern

sequential — phases run in order, each gated by dashboard approval.

Multi-Model

No — model selection is the client's responsibility; MCP server is model-agnostic.

Isolation Mechanism

None — file edits in-place.

Subagent Definition Format

none — no subagents.

Execution Mode

interactive-loop — each phase ends with an approvals tool call that blocks until the dashboard shows user approval. This is a stronger blocking gate than most frameworks.

Prompt Chaining

Yes — create-spec prompt instructions explicitly reference reading prior phase documents before creating the next one.

Consensus Mechanism

None.

Cross-Tool Portability

High — any MCP-capable client works with the same server. Tested clients: Augment Code, Claude Code, Claude Desktop, Cline, Cursor, and others.

Protocol

stdio (standard input/output MCP transport).

08

Ui Cli Surface

spec-workflow-mcp — UI, CLI, and Surface

CLI Binary

  • Name: spec-workflow-mcp
  • Mode: MCP server (stdio) by default; --dashboard flag starts web dashboard
  • Is thin wrapper: No — full MCP server implementation

Web Dashboard

  • Type: web-dashboard
  • Port: 5000 (default)
  • Tech stack: Node.js server + Vite-built React frontend (src/dashboard_frontend/)
  • Features:
    • Real-time spec and task progress tracking
    • Visual progress bars per spec
    • Approval workflow UI (Approve / Reject / Request Revision buttons)
    • Implementation logs viewer (searchable, with code change statistics)
    • Project registry (multiple projects, one dashboard)
    • WebSocket live updates

VSCode Extension

  • Extension ID: Pimzino.spec-workflow-mcp
  • Source: vscode-extension/
  • Type: Sidebar webview panel — same dashboard UI embedded in VSCode
  • Features: Multi-language (English, Japanese, Chinese); batch approval actions
  • Available on VSCode Marketplace

MCP Integration

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

Observability

  • Audit log: Yes — log-implementation tool + dashboard Logs tab
  • Approval history: Tracked via approval-storage.ts
  • Replay capability: No

Related frameworks

same archetype · same primary tool · same memory type

Taskmaster AI ★ 27k
A3 MCP-anchored

Converts a PRD into a dependency-ordered JSON task graph that AI coding agents execute one task at a time, eliminating context…

ccmemory ★ 1
A3 MCP-anchored

Accumulates decisions, corrections, and failed approaches from Claude Code sessions into a queryable Neo4j graph so each new…

MCP Shrimp Task Manager ★ 2.1k
A3 MCP-anchored

Convert natural language requests into structured AI development tasks with chain-of-thought enforcement, reflection gates, and…

Bernstein ★ 460
A3 MCP-anchored

Govern parallel CLI coding agents with a deterministic Python scheduler, HMAC-chained audit trail, and compliance-ready signed…

LeanSpec ★ 252
A3 MCP-anchored

Provides a unified spec CLI and MCP server over any existing spec backend (markdown, GitHub Issues, ADO), making spec-driven…

Specs Workflow MCP ★ 127
A3 MCP-anchored

Enforces Requirements → Design → Tasks workflow via a single MCP tool with persistent JSON progress tracking that survives…