Guide AI to systematically complete software development through a structured Requirements → Design → Tasks workflow, ensuring code implementation stays aligned with business needs.
- AI jumps randomly between tasks, lacking systematic approach
- Requirements disconnect from actual code implementation
- Scattered documentation, difficult to track project progress
- Missing design decision records
- AI completes tasks sequentially, maintaining focus and context
- Complete traceability from user stories to code implementation
- Standardized document templates with automatic progress management
- Each stage requires confirmation, ensuring correct direction
- Persistent progress: Continue from where you left off with
check, even in new conversations
v1.0.7
- 🎯 Improved reliability for most models to manage tasks with spec workflow
v1.0.6
- ✨ Batch task completion: Complete multiple tasks at once for faster progress on large projects
v1.0.5
- 🐛 Edge case fixes: Distinguish between "task not found" and "task already completed" to prevent workflow interruption
v1.0.4
- ✅ Task management: Added task completion tracking for systematic project progression
v1.0.3
- 🎉 Initial release: Core workflow framework for Requirements → Design → Tasks
claude mcp add spec-workflow-mcp -s user -- npx -y spec-workflow-mcp@latestSee full installation guide for other clients.
"Help me use spec workflow to create a user authentication system"
"Use spec workflow to check ./my-project"
The AI will automatically detect project status and continue from where it left off.
You: "I need to build a user authentication system"
AI: "I'll help you create spec workflow for user authentication..."
📝 requirements.md - User stories and functional requirements
🎨 design.md - Technical architecture and design decisions
✅ tasks.md - Concrete implementation task list
After each stage, the AI requests your confirmation before proceeding, ensuring the project stays on the right track.
my-project/specs/
├── requirements.md # Requirements: user stories, functional specs
├── design.md # Design: architecture, APIs, data models
├── tasks.md # Tasks: numbered implementation steps
└── .workflow-confirmations.json # Status: automatic progress tracking
my-project/specs/
├── user-authentication/ # Auth module
├── payment-system/ # Payment module
└── notification-service/ # Notification module
You can specify any directory: "Use spec workflow to create auth docs in ./src/features/auth"
Strongly recommended to add the following prompt to your AI assistant configuration. Without it, AI may:
- ❌ Not know when to invoke Spec Workflow
- ❌ Forget to manage task progress, causing disorganized work
- ❌ Not utilize Spec Workflow for systematic documentation
- ❌ Unable to continuously track project status
With this configuration, AI will intelligently use Spec Workflow to manage the entire development process.
Configuration Note: Please modify the following based on your needs:
- Change
./specsto your preferred documentation directory path- Change "English" to your preferred documentation language (e.g., "Chinese")
# Spec Workflow Usage Guidelines
## 1. Check Project Progress
When user mentions continuing previous project or is unsure about current progress, proactively use:
specs-workflow tool with action.type="check" and path="./specs"
## 2. Documentation Language
All spec workflow documents should be written in English consistently, including all content in requirements, design, and task documents.
## 3. Documentation Directory
All spec workflow documents should be placed in ./specs directory to maintain consistent project documentation organization.
## 4. Task Management
Always use the following to manage task progress:
specs-workflow tool with action.type="complete_task" and taskNumber="current task number"
Follow the workflow guidance to continue working until all tasks are completed.
## 5. Best Practices
- Proactive progress check: When user says "continue from last time", first use check to see current status
- Language consistency: Use the same language throughout all project documents
- Flexible structure: Choose single-module or multi-module organization based on project scale
- Task granularity: Each task should be completable within 1-2 hours
📦 Installation Instructions
- Node.js ≥ v18.0.0
- npm or yarn
- Claude Desktop or any MCP-compatible client
Use the Claude CLI to add the MCP server:
claude mcp add spec-workflow-mcp -s user -- npx -y spec-workflow-mcp@latestAdd to your Claude Desktop configuration:
- macOS:
~/Library/Application Support/Claude/claude_desktop_config.json - Windows:
%APPDATA%/Claude/claude_desktop_config.json - Linux:
~/.config/Claude/claude_desktop_config.json
{
"mcpServers": {
"spec-workflow": {
"command": "npx",
"args": ["-y", "spec-workflow-mcp@latest"]
}
}
}Add to your Cursor configuration (~/.cursor/config.json):
{
"mcpServers": {
"spec-workflow": {
"command": "npx",
"args": ["-y", "spec-workflow-mcp@latest"]
}
}
}Use Cline's MCP server management UI to add the server:
- Open VS Code with Cline extension
- Open Cline settings (gear icon)
- Navigate to MCP Servers section
- Add new server with:
- Command:
npx - Arguments:
-y spec-workflow-mcp@latest
- Command:
Add to your Windsurf configuration (~/.codeium/windsurf/mcp_config.json):
{
"mcpServers": {
"spec-workflow": {
"command": "npx",
"args": ["-y", "spec-workflow-mcp@latest"],
"env": {},
"autoApprove": [],
"disabled": false,
"timeout": 60,
"transportType": "stdio"
}
}
}Add to your VS Code settings (settings.json):
{
"mcp.servers": {
"spec-workflow": {
"command": "npx",
"args": ["-y", "spec-workflow-mcp@latest"]
}
}
}Add to your Zed configuration (~/.config/zed/settings.json):
{
"assistant": {
"version": "2",
"mcp": {
"servers": {
"spec-workflow": {
"command": "npx",
"args": ["-y", "spec-workflow-mcp@latest"]
}
}
}
}
}git clone https://github.com/kingkongshot/specs-mcp.git
cd specs-mcp
npm install
npm run buildThen add to Claude Desktop configuration:
{
"mcpServers": {
"spec-workflow": {
"command": "node",
"args": ["/absolute/path/to/specs-mcp/dist/index.js"]
}
}
}MIT License