spec-workflow-setup — Claude Code command: what it does
spec-workflow-setup — a slash command that walks you through wiring the spec-workflow MCP server into Claude: dependencies, .mcp.json, .spec-workflow.json, then a connection check.
no license ★ 1,357 updated 2026-03-01
.claude/commands/spec-workflow-setup.mdWhat spec-workflow-setup does
The command is a guided install for the spec-workflow MCP server inside Claude. It opens with a prerequisite sweep: Node.js 18+, npm or yarn, Git, MCP support switched on. From there it installs the server, drops .mcp.json at the project root and fills in .spec-workflow.json with folders for specs and tasks.
Three routes are covered. The @pimzino/spec-workflow-mcp package from npm, global or as a dev dependency. A clone of the repo, built locally and linked. Or the ./scripts/install-spec-workflow-mcp.sh script that ships with the suite. Environment variables such as SPEC_WORKFLOW_PROJECT_PATH and SPEC_WORKFLOW_AUTO_SYNC get set along the way, and the project file carries task statuses plus maxParallel for agents.
Node.js 18+ and MCP enabled in Claude are the floor — skip them and step one fails. Verification runs through /spec-workflow:test-connection, /spec-workflow:list-specs and /spec-workflow:task-status. When the server stays silent, the guide points at the settings syntax and a restart.
What it helps with
- install the spec-workflow MCP server into an existing repo
- write a
.mcp.jsonthat launches the server throughnpx - declare spec and task folders in
.spec-workflow.json - set task statuses and the parallel agent cap
- diagnose a server that refuses to connect
Example prompts for the agent
/spec-workflow-setup— walk me through installing spec-workflow MCP in this repo.- Use
/spec-workflow-setupand configure the server globally instead of per project. - Run
/spec-workflow-setup, then check the link with/spec-workflow:test-connection.
How to install spec-workflow-setup
Manually: put the files in place
.claude/commands/spec-workflow-setup.mdCall it with /spec-workflow-setup. For all projects use ~/.claude/commands/
Manually: put the files in place
~/.codex/prompts/spec-workflow-setup.mdCall it with /prompts:spec-workflow-setup. Codex marks this format deprecated in favour of skills
Manually: put the files in place
.github/prompts/spec-workflow-setup.prompt.mdManually: put the files in place
.gemini/commands/spec-workflow-setup.tomlGemini stores commands as TOML: the prompt text goes into the prompt field
Questions about spec-workflow-setup
How do I install spec-workflow-setup in Claude Code?
Copy the command file to .claude/commands/spec-workflow-setup.md; Claude then exposes it as /spec-workflow-setup.
What does spec-workflow-setup do?
It runs the spec-workflow MCP server setup step by step: prerequisites, a choice of install route, the .mcp.json and .spec-workflow.json files, and a final connection test.
What do I need before running it?
Node.js 18+, npm or yarn, Git, and Claude with MCP support enabled.