Related Pages

Related topics: MCP Server, Tools, Prompts, and Core Services, Dashboard, VSCode Extension, and Approval Workflow, Deployment, Configuration, Security, and Troubleshooting

Project Overview and System Architecture

Purpose and Scope

spec-workflow-mcp is a Model Context Protocol (MCP) server that provides structured, spec-driven development tooling with two companion surfaces: a real-time web dashboard and a VSCode extension. Its purpose is to enforce a sequential documentation workflow (Requirements → Design → Tasks), track task progress, capture implementation logs, and manage a request/review approval loop between an AI agent and a human reviewer. Source: README.md.

The product targets AI coding assistants (e.g., Claude Code) that need an external, file-backed state store. The MCP server exposes tools that read and write spec files; the dashboard and VSCode extension render the same data and let humans approve, reject, or annotate documents. All artifacts live under a single .spec-workflow/ directory in the user's project, keeping the system portable across machines and branches. Source: README.md.

The repository ships in 11 languages (English, Japanese, Chinese, Spanish, Portuguese, German, French, Russian, Italian, Korean, Arabic), which is reflected in the locale files bundled with the VSCode extension. Source: vscode-extension/src/webview/locales/en.json, vscode-extension/src/webview/locales/ja.json, vscode-extension/src/webview/locales/ar.json.

System Components

The system is composed of three primary surfaces that share the same on-disk state.

flowchart LR
    A[AI Agent / MCP Client] -->|MCP tools| B[spec-workflow-mcp Server]
    B -->|read/write| C[.spec-workflow/ files]
    D[Web Dashboard] -->|HTTP + WebSocket| B
    E[VSCode Extension] -->|file watchers| C
    D -->|render| C
    B -->|TOON-encoded responses| A

MCP Server. The core process implements the MCP tool surface. Tool responses are encoded with @toon-format/toon for compactness (a community proposal in issue #230 suggests swapping it for GCF, but TOON is the current implementation). Source: README.md.

Web Dashboard. A React application served by the server. The shell is implemented in src/dashboard_frontend/src/modules/app/App.tsx, which renders a sidebar, mobile menu, language selector, and a changelog modal bound to the current project and version. Source: src/dashboard_frontend/src/modules/app/App.tsx.

VSCode Extension. Published as Pimzino.spec-workflow-mcp, requiring VSCode ≥ 1.99.0. It activates on onStartupFinished and exposes commands like spec-workflow.openDashboard, spec-workflow.refreshData, spec-workflow.approveFromEditor, and spec-workflow.rejectFromEditor. It watches the local .spec-workflow/ directory for changes and renders the same six-tab interface (Overview, Steering, Specs, Tasks, Approvals, Logs). Source: vscode-extension/package.json, vscode-extension/README.md.

Data Model and On-Disk Layout

All three surfaces operate on a shared schema defined in the extension's TypeScript types. The central entities are specs, tasks, steering documents, approvals, and implementation logs.

The on-disk layout under .spec-workflow/ separates concerns into approvals/, archive/, specs/, steering/, templates/, and user-templates/, alongside a config.example.toml. This folder is the single source of truth that all three components read from and write to. Source: README.md.

Approval Workflow and Community Pain Points

The approval loop is the system's most interactive surface. The VSCode extension adds an "Annotate" mode on top of markdown preview so reviewers can attach ApprovalComment objects (with line ranges and highlight colors) to a document. The state transitions are encoded directly in the status enum: pending → approved | rejected | needs-revision. Source: vscode-extension/src/extension/types.ts.

Community discussions surface several real-world frictions worth knowing before adoption:

• Path-traversal in categoryName. Issue #220 reports that the approval tool does not validate the caller-supplied categoryName before joining it under the approvals directory, allowing writes outside the intended folder — a hardening target rather than a documented feature. Source: community: issue #220.
• Multiple simultaneous sessions. Issue #5 reports that session.json is overwritten by the latest session, breaking dashboard discovery for parallel agents. Source: community: issue #5.
• Git worktrees. Issue #187 notes that because specs live inside the working tree, branches and worktrees don't share them, requiring either git-tracking the directory or relocating it. Source: community: issue #187.
• Task-template parsing. Issue #218 highlights that the official tasks-template.md separates the checkbox and title onto different lines, which the dashboard's parser does not currently handle. Source: community: issue #218.
• Response encoding. Issue #230 proposes replacing the current TOON encoder with GCF for tighter compression and better LLM comprehension. Source: community: issue #230.

See Also

• README.md — primary entry point, feature list, and showcase videos.
• vscode-extension/README.md — extension-specific commands and settings.
• vscode-extension/package.json — engine requirements and command contribution manifest.

Related Pages

Related topics: Project Overview and System Architecture, Dashboard, VSCode Extension, and Approval Workflow, Deployment, Configuration, Security, and Troubleshooting

MCP Server, Tools, Prompts, and Core Services

Overview and Purpose

The MCP Server is the central component of @pimzino/spec-workflow-mcp, exposing the spec-driven development workflow as a set of Model Context Protocol tools that AI coding assistants can invoke. The package is described as an "MCP server for spec-driven development workflow with real-time web dashboard" (Source: package.json:2-2).

It enforces a three-phase document pipeline (Requirements → Design → Tasks), an approval workflow for human review of artifacts, an implementation log system, and a multi-project aware dashboard. From the project README:

*"Structured Development Workflow - Sequential spec creation (Requirements → Design → Tasks)"*

Source: README.md:99-99

The same README highlights that the server pairs with a "Real-Time Web Dashboard" and a VSCode extension, both of which consume the same underlying file-based project layout under .spec-workflow/ (Source: README.md:103-103).

Server Architecture and Configuration

The runtime entry point is the compiled dist/index.js; in development the server is started via tsx src/index.ts (Source: package.json:14-16). It is published both as an npm library and as an executable CLI binary named spec-workflow-mcp (Source: package.json:7-9).

The dashboard is intentionally a localhost service. The README documents that it "Binds to 127.0.0.1 by default, preventing network exposure" alongside rate limiting (120 req/min/client) and structured audit logging (Source: README.md:148-156). A Docker image and docker-compose.yml under containers/ provide an alternative deployment (Source: README.md:119-128).

The server is also plug-in aware: scripts/sync-plugin-version.js keeps the VSCode extension's package.json aligned with the server release (Source: package.json:22-22).

MCP Tools and Their Roles

The MCP server registers multiple tools that AI agents call. The community-tracked set (referenced in the README's tools reference and in related issues) covers the spec lifecycle:

• spec-workflow-guide — Returns the canonical workflow instructions so an LLM client bootstraps correct behavior on first contact.
• create-spec-documents — Creates the Requirements/Design/Tasks documents in sequence, enforcing that earlier phases exist before later ones.
• spec-status — Reports current progress, counts, and document existence for one or all specs.
• approvals — Manages approval requests and responses; the corresponding VSCode types declare status values 'pending' | 'approved' | 'rejected' | 'needs-revision' (Source: vscode-extension/src/extension/types.ts:67-67).
• log-implementation — Appends entries to the implementation log, capturing linesAdded, linesRemoved, and filesChanged statistics (Source: vscode-extension/src/webview/lib/vscode-api.ts:60-64).

Tool responses are encoded with @toon-format/toon. The README confirms the dependency surface, and community discussion in #230 has explored replacing TOON with GCF for better compression and LLM comprehension (Source: community issue #230).

flowchart LR
    LLM[AI Agent / MCP Client] -->|tool call| MCP[Spec Workflow MCP Server]
    MCP -->|read/write| FS[(.spec-workflow/ on disk)]
    MCP -->|WS events| DASH[Web Dashboard]
    MCP -->|WS events| EXT[VSCode Extension]
    DASH -->|approve/reject| MCP
    EXT -->|approve/reject| MCP

Approval Workflow and Task Data Model

Approvals are first-class domain objects. The shared TypeScript surface describes an ApprovalData record containing id, title, filePath, type, status, createdAt, optional respondedAt, response, comments[], and revisionHistory[] (Source: vscode-extension/src/extension/types.ts:65-80). Each ApprovalComment supports multi-line selections with startLine, endLine, selectedText, and a customizable highlightColor (Source: vscode-extension/src/extension/types.ts:46-58).

Tasks follow a parallel model. TaskStatus is a closed union of 'pending' | 'in-progress' | 'completed' | 'blocked', and each task may carry prompt and promptStructured[] fields so the dashboard can render a "Copy prompt for AI agent" affordance (Source: vscode-extension/src/extension/types.ts:23-25, 33-34).

Community issue #220 identified that the approvals tool previously joined a caller-controlled categoryName directly under the approvals directory, allowing path traversal writes. The fix narrows input validation to mirror the existing checks performed on filePath (Source: community issue #220). Community issue #218 highlights a related authoring pitfall: the official tasks-template.md places the task title and its - File: / - _Requirements: lines on separate lines, which the dashboard parser must tolerate (Source: community issue #218).

Dashboard Frontend and Extensibility

The dashboard SPA is bootstrapped by App.tsx, which exposes a multi-tab navigation (Overview, Steering, Specs, Tasks, Approvals, Logs) and renders the running server version via info.version (Source: src/dashboard_frontend/src/modules/app/App.tsx:903-913). It supports a mobile drawer, persistent sidebar collapse state, and a changelog modal.

The VSCode extension shares the same types and follows the same tab model (Source: vscode-extension/README.md:21-32). Both UIs receive real-time updates via file-system watchers, as documented in the extension README.

Several long-standing community requests shape near-term evolution: #187 asks for git worktree support so specs follow branches; #5 asks for an array of sessions rather than a single session.json (the latter causes the latest parallel Claude Code session to overwrite the dashboard URL); #185 documents a Windows regression where the server exits immediately after start in v2.1.8; and #229 asks for bundled image assets inside spec directories (Source: community issues #187, #5, #185, #229).

See Also

• Project README — Overview, security controls, Docker deployment.
• VSCode Extension README — Sidebar dashboard, editor integration, sound notifications.
• Containers README — Docker Compose and CLI usage for hosting the dashboard.
• package.json — Scripts, tooling, and module metadata.

Related Pages

Related topics: Project Overview and System Architecture, MCP Server, Tools, Prompts, and Core Services, Deployment, Configuration, Security, and Troubleshooting

Dashboard, VSCode Extension, and Approval Workflow

Overview

Spec Workflow MCP is a Model Context Protocol (MCP) server that provides structured spec-driven development tooling, with a real-time web dashboard, a VSCode extension, and a document approval workflow. The system is designed around three core artifacts: spec documents (requirements, design, tasks), steering documents (product, tech, structure), and approval requests that drive the human-in-the-loop process.

The dashboard exposes spec status, task progress, approval state, and implementation logs to a browser interface. The VSCode extension brings the same data into the editor sidebar, while the approval workflow ties AI-generated documents to human review. Source: README.md.

flowchart LR
  A[MCP Server] --> B[Web Dashboard]
  A --> C[VSCode Extension]
  A --> D[Approval Storage]
  B -->|.spec-workflow/*| A
  C -->|file watchers| A
  D -->|.spec-workflow/approvals| A
  E[AI Agent] -->|MCP tools| A
  F[Human Reviewer] -->|approve / reject / revise| B
  F -->|approve / reject / revise| C

Project Structure and Configuration

The server and dashboard are built and published as a single npm package, @pimzino/spec-workflow-mcp, version 2.2.7 at the time of the listed sources. The package's main entry is dist/index.js, and the CLI binary is exposed as spec-workflow-mcp. Build scripts include build, dev, build:dashboard, and a validate:i18n step that runs before the TypeScript build. Source: package.json.

The on-disk project layout managed by the dashboard is:

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

The dashboard reads specs, tasks, and approvals from this directory and watches it for changes, which is what enables real-time updates in the browser. Source: README.md.

Approval Workflow

The approval workflow is the bridge between AI-generated documents and human review. The ApprovalData type defines the canonical state of an approval record and includes:

• id, title, filePath, and a discriminated category of either 'spec' or 'steering'.
• A status field with one of 'pending' | 'approved' | 'rejected' | 'needs-revision'.
• Optional response, annotations, and comments arrays.
• A revisionHistory array, with each entry carrying a version number, full content, timestamp, and an optional revision reason.
• A metadata bag for arbitrary additional context.

Source: vscode-extension/src/extension/types.ts.

The editor surfaces the approval state through colored decorations. The APPROVAL_STATUS_COLORS map in ApprovalEditorService.ts ties each status to a background and border color, so reviewers can see at a glance whether a document is pending, approved, rejected, needs revision, or simply commented on. The pending state uses amber, approved green, rejected red, needs-revision orange, and commented blue. Source: vscode-extension/src/extension/services/ApprovalEditorService.ts.

The dashboard complements the editor with a browser-based approval UI. The web interface offers approve, reject, request revision, and comment actions. Community discussion in issue #179 shows users want to annotate directly on the rendered markdown preview rather than switching between preview and annotate modes, which is a known gap in the current dashboard.

A reported security issue, issue #220, documented that the categoryName parameter on the approval tool was not validated for path traversal, allowing writes outside the approvals directory. Operators of older versions should upgrade to a build where this input is normalized before being joined to the approvals base path.

VSCode Extension

The VSCode extension is published separately as Pimzino.spec-workflow-mcp, version 1.1.7, and requires VSCode 1.99.0 or higher. It activates on onStartupFinished and contributes a sidebar dashboard plus editor commands. The contributed commands include opening the dashboard, refreshing data, opening a spec, and editor-context actions for approve, reject, request revision, add comment, and a generic approval actions menu. Source: vscode-extension/package.json.

The extension sidebar is organized into tabs that mirror the dashboard: Overview, Steering, Specs, Tasks, Approvals, and Logs. The Overview tab shows active versus archived specs, total task counts, and overall progress. The Tasks tab provides per-spec task status with copyable AI prompts such as Please work on task {{taskId}} for spec "{{specName}}", which is intended to be pasted back into an agent session. Source: vscode-extension/src/webview/locales/en.json.

Sound notifications are configurable through settings such as specWorkflow.notifications.sounds.enabled, specWorkflow.notifications.sounds.volume, specWorkflow.notifications.sounds.approvalSound, and specWorkflow.notifications.sounds.taskCompletionSound, with a default volume of 0.3. The webview's TypeScript definitions declare the matching SoundNotificationConfig interface, confirming the runtime contract. Source: vscode-extension/src/webview/lib/vscode-api.ts.

The extension UI is localized into 11 languages, including English, Japanese, Chinese, Spanish, Portuguese, German, French, Russian, Italian, Korean, and Arabic. Locale JSON files are loaded on demand by the webview and used to render tab titles, button labels, and status messages. Source: vscode-extension/src/webview/locales/ja.json, vscode-extension/src/webview/locales/zh.json, vscode-extension/src/webview/locales/ar.json.

Common Failure Modes and Community Notes

Several recurring community issues shape how the dashboard, extension, and approval workflow are used in practice:

• Multiple sessions overwriting session data. Issue #5 reports that parallel Claude Code sessions overwrite session.json, making the dashboard URL hard to find. Workarounds include running a single session per project or capturing the URL from logs when the file is rewritten.
• Server exits immediately on Windows. Issue #185 describes the MCP server exiting on startup under npx on Windows 11, version 2.1.8. Operators on that version should pin to a known-good build or run via the locally installed binary.
• Tasks template format mismatch. Issue #218 reports that the official tasks-template.md puts the checkbox and task title on separate lines, which the dashboard parser does not handle. Use the in-template format with the title on the same line as the checkbox when generating tasks.
• Remote dashboard access. Issue #202 requested exposing the dashboard beyond localhost. The maintainer noted the feature is already implemented, so users on a recent build can bind the dashboard to a routable interface.
• Bundled image assets. Issue #229 requests an assets directory inside .spec-workflow/specs/<name>/ so that design documents can reference local SVGs and PNGs. This is an open enhancement, not yet covered by the types in vscode-extension/src/extension/types.ts.

See Also

• README.md for the high-level feature list and links to the full docs directory.
• vscode-extension/README.md for the full extension command and settings reference.
• vscode-extension/src/extension/types.ts for the canonical ApprovalData, SteeringStatus, and related interfaces.
• vscode-extension/src/extension/services/ApprovalEditorService.ts for editor decoration and approval action logic.

Related Pages

Related topics: Project Overview and System Architecture, MCP Server, Tools, Prompts, and Core Services, Dashboard, VSCode Extension, and Approval Workflow

Deployment, Configuration, Security, and Troubleshooting

This page consolidates the operational concerns of the spec-workflow-mcp server: how to install, build, and run it; how its configuration, environment, and on-disk layout are organized; the security boundaries enforced on file writes; and the failure modes that the community most frequently reports. The intended audience is an operator or contributor bringing up the server in a local, containerized, or VSCode-integrated environment.

Deployment

The project ships as an npm package named @pimzino/spec-workflow-mcp (version 2.2.7) with a bin entry of spec-workflow-mcp pointing at dist/index.js, and a module type of module — confirming it runs as a native ES module on modern Node. Source: package.json:1-12.

Three deployment surfaces are supported:

The build pipeline is driven from package.json and chains localization validation, TypeScript compilation, a Vite dashboard build, and a static-asset copy step. Source: package.json:17-25. The relevant scripts are:

npm install            # install dependencies
npm run build          # validate i18n, compile TS, build dashboard
npm run dev            # tsx src/index.ts (dev mode with hot reload)
npm start              # node dist/index.js (production)
npm run build:dashboard # vite build + copy static
npm test               # vitest
npm run test:e2e       # playwright end-to-end

For the VSCode companion, vscode-extension/package.json declares engines.vscode: ^1.99.0 and uses onStartupFinished activation, so the extension attaches automatically when VSCode opens a workspace containing a .spec-workflow directory. Source: vscode-extension/package.json:25-32. The containerized deployment is documented in containers/DOCKER_USAGE.md, with containers/.env.example providing the canonical environment template and containers/docker-compose.yml orchestrating the service.

Configuration

The on-disk configuration lives inside the project's .spec-workflow/ directory, whose canonical layout is documented in the README. Source: README.md:46-58.

your-project/
  .spec-workflow/
    approvals/        # approval request files
    archive/          # archived specs
    specs/            # active specifications
    steering/         # product/tech/structure steering docs
    templates/        # built-in document templates
    user-templates/   # user-overridable templates
    config.example.toml

config.example.toml is the source of truth for runtime options. The dashboard frontend surfaces the running version (Spec-Workflow-MCP v{info.version}) in the footer, which is useful when validating a deployment. Source: src/dashboard_frontend/src/modules/app/App.tsx:900-920.

VSCode extension configuration is namespaced under specWorkflow.*. Documented settings include specWorkflow.notifications.sounds.enabled, specWorkflow.notifications.sounds.volume, and specWorkflow.notifications.sounds.approvalSound. Source: vscode-extension/README.md:60-66.

For Docker deployments, environment variables are read from containers/.env.example; copying it to .env and editing the values is the supported bootstrap. Source: containers/.env.example; containers/DOCKER_USAGE.md.

Security

The server mediates all writes through typed storage classes, but a known class of bug involves path traversal via caller-controlled path segments. A community-reported vulnerability described how the approvals tool accepted an unvalidated categoryName and joined it directly under the approvals directory, allowing escape from the sandbox when filePath itself was hardened. Source: Issue #220. Operators should:

• Keep filePath inputs constrained to the spec/steering tree.
• Validate that categoryName resolves inside the approvals directory after path resolution (e.g., reject .., absolute paths, and symlink escapes).
• Run the MCP server with a working directory matching the project root so the .spec-workflow boundary is unambiguous.

For remote deployments, an earlier community request to expose the dashboard beyond localhost was tracked in Issue #202 and is now implemented — operators should still front the dashboard with reverse-proxy authentication, since the server itself does not provide built-in auth.

Troubleshooting

Common failure modes and their remedies:

flowchart LR
    A[Start MCP server] --> B{Process exits immediately?}
    B -- Yes --> C[Check Node version, .mcp.json, working dir]
    B -- No --> D{Dashboard reachable?}
    D -- No --> E[Inspect port, .env, reverse proxy]
    D -- Yes --> F{Approvals writable?}
    F -- No --> G[Validate categoryName & filePath]
    F -- Yes --> H[Operational]

• Server exits immediately after start (v2.1.8, Windows 11). Reported in Issue #185. Verify the .mcp.json cwd, confirm Node 18+ is on PATH, and run npm run dev directly to surface stack traces.
• Dashboard URL overwritten by concurrent sessions. When multiple Claude Code sessions share a project, session.json is overwritten. Source: Issue #5. Workaround: pin one session per .spec-workflow directory, or back up session.json between runs.
• tasks.md template format rejected by the dashboard parser. The official template places the task title and the - File: line on separate lines; the parser expects a single-line format. Source: Issue #218. Adjust user-templates/tasks-template.md to keep each task on one line.
• Specs missing in git worktree branches. The .spec-workflow directory is per working copy, not per branch. Source: Issue #187. Symlink or commit the spec tree when relying on worktrees.
• Bundled image assets not supported in spec documents. A long-standing request to allow assets/ alongside design.md. Source: Issue #229. Until implemented, reference external image URLs.
• Custom log directory in config.toml. Closed as an enhancement request — current behavior is to use the default log location. Source: Issue #213.
• TOON response encoding considerations. A community proposal to swap @toon-format/toon for GCF; TOON is still in use, with discussion ongoing. Source: Issue #230.

For deeper guidance, see the upstream docs/TROUBLESHOOTING.md and docs/DEVELOPMENT.md referenced in the project README. Source: README.md:18-26.

See Also

• Tools Reference
• Development Guide
• Interfaces Guide
• Docker Usage

Doramagic Pitfall Log

Found 11 structured pitfall item(s), including 0 high/blocking item(s). Top priority: Installation risk - Installation risk requires verification.

1. Installation risk: Installation risk requires verification

• Severity: medium
• Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: community_evidence:github | https://github.com/Pimzino/spec-workflow-mcp/issues/220

2. Configuration risk: Configuration risk requires verification

• Severity: medium
• Finding: Project evidence flags a configuration risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: capability.host_targets | https://github.com/Pimzino/spec-workflow-mcp

3. Configuration risk: Configuration risk requires verification

• Severity: medium
• Finding: Project evidence flags a configuration risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: community_evidence:github | https://github.com/Pimzino/spec-workflow-mcp/issues/218

4. Capability evidence risk: Capability evidence risk requires verification

• Severity: medium
• Finding: README/documentation is current enough for a first validation pass.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: capability.assumptions | https://github.com/Pimzino/spec-workflow-mcp

5. Maintenance risk: Maintenance risk requires verification

• Severity: medium
• Finding: Project evidence flags a maintenance risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: evidence.maintainer_signals | https://github.com/Pimzino/spec-workflow-mcp

6. Security or permission risk: Security or permission risk requires verification

• Severity: medium
• Finding: no_demo
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: downstream_validation.risk_items | https://github.com/Pimzino/spec-workflow-mcp

7. Security or permission risk: Security or permission risk requires verification

• Severity: medium
• Finding: no_demo
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: risks.scoring_risks | https://github.com/Pimzino/spec-workflow-mcp

8. Security or permission risk: Security or permission risk requires verification

• Severity: medium
• Finding: Project evidence flags a security or permission risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: community_evidence:github | https://github.com/Pimzino/spec-workflow-mcp/issues/230

9. Security or permission risk: Security or permission risk requires verification

• Severity: medium
• Finding: Project evidence flags a security or permission risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: community_evidence:github | https://github.com/Pimzino/spec-workflow-mcp/issues/229

10. Maintenance risk: Maintenance risk requires verification

• Severity: low
• Finding: issue_or_pr_quality=unknown。
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: evidence.maintainer_signals | https://github.com/Pimzino/spec-workflow-mcp

11. Maintenance risk: Maintenance risk requires verification

• Severity: low
• Finding: release_recency=unknown。
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: evidence.maintainer_signals | https://github.com/Pimzino/spec-workflow-mcp

Community Discussion Evidence

Doramagic exposes project-level community discussion separately from official documentation. Review these links before using spec-workflow-mcp with real data or production workflows.

• Consider replacing TOON with GCF for tool response encoding - github / github_issue
• [[Feature]: Support bundled image assets in spec documents](https://github.com/Pimzino/spec-workflow-mcp/issues/229) - github / github_issue
• [[Feature]:](https://github.com/Pimzino/spec-workflow-mcp/issues/213) - github / github_issue
• [[Bug]: approval categoryName path traversal writes outside approvals dir](https://github.com/Pimzino/spec-workflow-mcp/issues/220) - github / github_issue
• Community source 5 - github / github_issue
• [[Bug]: Bug Report for spec-workflow-mcp](https://github.com/Pimzino/spec-workflow-mcp/issues/218) - github / github_issue
• Configuration risk requires verification - GitHub / issue