# spec-workflow-setup

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.

- command · `type=command` · Claude Code, Codex, GitHub Copilot, Gemini CLI · ★ 1357 repo stars
- Author: qdhenry
- License: not stated · policy=link-only · description only; the file stays with the author
- Source: https://github.com/qdhenry/Claude-Command-Suite/tree/HEAD/.claude/commands/spec-workflow/spec-workflow-setup.md
- Updated: 2026-03-01
- Security check: automated, 2026-11-16 (text) — no signs of malicious code found.
- HTML: https://affpapa.org/en/nevibecode/commands/spec-workflow-setup

## What it 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.

## Install

### Claude Code (native platform)

**Manually: put the files in place**
- File: `.claude/commands/spec-workflow-setup.md` — Call it with /spec-workflow-setup. For all projects use ~/.claude/commands/

### Codex

**Manually: put the files in place**
- File: `~/.codex/prompts/spec-workflow-setup.md` — Call it with /prompts:spec-workflow-setup. Codex marks this format deprecated in favour of skills

### GitHub Copilot

**Manually: put the files in place**
- File: `.github/prompts/spec-workflow-setup.prompt.md`

### Gemini CLI

**Manually: put the files in place**
- File: `.gemini/commands/spec-workflow-setup.toml` — Gemini stores commands as TOML: the prompt text goes into the prompt field

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/qdhenry/Claude-Command-Suite/tree/HEAD/.claude/commands/spec-workflow/spec-workflow-setup.md

## When to use it
- install the spec-workflow MCP server into an existing repo
- write a `.mcp.json` that launches the server through `npx`
- 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
- \`/spec-workflow-setup` — walk me through installing spec-workflow MCP in this repo.
- Use `/spec-workflow-setup` and configure the server globally instead of per project.
- Run `/spec-workflow-setup`, then check the link with `/spec-workflow:test-connection`.

## Similar
- [notion-spec-to-implementation](https://affpapa.org/en/nevibecode/skills/notion-spec-to-implementation-2.md) — skill · 389 installs
- [wiki-setup](https://affpapa.org/en/nevibecode/skills/wiki-setup.md) — skill · 3600 installs
- [om-setup-discovery-pipeline](https://affpapa.org/en/nevibecode/skills/om-setup-discovery-pipeline.md) — skill · 2400 installs
- [setup](https://affpapa.org/en/nevibecode/skills/anthropics-setup.md) — skill · 371 installs
- [asana-setup](https://affpapa.org/en/nevibecode/commands/asana-setup.md) — command · ★ 47914 repo stars
- [make-issue-spec](https://affpapa.org/en/nevibecode/skills/make-issue-spec.md) — skill · ★ 2039 repo stars

From the same set: [qdhenry/claude-command-suite](https://affpapa.org/en/nevibecode/by/qdhenry/claude-command-suite.md) — 112 cards

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md
