spec-kit-pro

Spec Kit Pro Logo

🚀 Spec Kit Pro

Build high-quality software faster. Now with full UI/UX support.

An open source toolkit for Spec-Driven Development with first-class support for complex UI applications, mobile apps, and full UX artifact generation.

Release GitHub stars License Documentation

Table of Contents

🆕 What’s New in Pro

Spec Kit Pro extends the original toolkit with first-class UI/UX support for building complex applications:

Feature Description
User Flow Diagrams Generate Mermaid flowcharts for every user journey
Information Architecture Auto-generate navigation structures and site maps
ASCII Wireframes Create screen layouts in universal text format
Component Hierarchies Extract reusable component trees from designs
UX Task Analysis Identify pain points and optimization opportunities

Pro Workflow

┌─────────────┐    ┌─────────────┐    ┌─────────────┐    ┌─────────────┐
│   specify   │───▶│  userflows  │───▶│     ia      │───▶│ wireframes  │
│  (spec.md)  │    │ (journeys)  │    │ (nav/sitemap)│   │  (screens)  │
└─────────────┘    └─────────────┘    └─────────────┘    └─────────────┘
                                                                │
┌─────────────┐    ┌─────────────┐    ┌─────────────┐           │
│  implement  │◀───│    tasks    │◀───│    plan     │◀───┬──────┘
│   (build)   │    │  (+ [UI])   │    │ (+ UX refs) │    │
└─────────────┘    └─────────────┘    └─────────────┘    │
                                                         ▼
                                               ┌─────────────┐
                                               │ components  │
                                               │   (tree)    │
                                               └─────────────┘

Why Pro?

🤔 What is Spec-Driven Development?

Spec-Driven Development flips the script on traditional software development. For decades, code has been king — specifications were just scaffolding we built and discarded once the “real work” of coding began. Spec-Driven Development changes this: specifications become executable, directly generating working implementations rather than just guiding them.

⚡ Get Started

1. Install Specify CLI Pro

Choose your preferred installation method:

Install once and use everywhere:

uv tool install spec-kit-pro --from git+https://github.com/Dong237/spec-kit-pro.git

Then use the tool directly:

# Create new project
specify-pro init <PROJECT_NAME>

# Or initialize in existing project
specify-pro init . --ai claude
# or
specify-pro init --here --ai claude

# Check installed tools
specify-pro check

To upgrade Specify Pro, see the Upgrade Guide for detailed instructions. Quick upgrade:

uv tool install spec-kit-pro --force --from git+https://github.com/Dong237/spec-kit-pro.git

Option 2: One-time Usage

Run directly without installing:

uvx --from git+https://github.com/Dong237/spec-kit-pro.git specify-pro init <PROJECT_NAME>

Benefits of persistent installation:

2. Establish project principles

Launch your AI assistant in the project directory. The /speckit.* commands are available in the assistant.

Use the /speckit.constitution command to create your project’s governing principles and development guidelines that will guide all subsequent development.

/speckit.constitution Create principles focused on code quality, testing standards, user experience consistency, and performance requirements

3. Create the spec

Use the /speckit.specify command to describe what you want to build. Focus on the what and why, not the tech stack.

/speckit.specify Build an application that can help me organize my photos in separate photo albums. Albums are grouped by date and can be re-organized by dragging and dropping on the main page. Albums are never in other nested albums. Within each album, photos are previewed in a tile-like interface.

4. Create a technical implementation plan

Use the /speckit.plan command to provide your tech stack and architecture choices.

/speckit.plan The application uses Vite with minimal number of libraries. Use vanilla HTML, CSS, and JavaScript as much as possible. Images are not uploaded anywhere and metadata is stored in a local SQLite database.

5. Break down into tasks

Use /speckit.tasks to create an actionable task list from your implementation plan.

/speckit.tasks

6. Execute implementation

Use /speckit.implement to execute all tasks and build your feature according to the plan.

/speckit.implement

For detailed step-by-step instructions, see our comprehensive guide.

## 🎨 UX Workflow for Complex Apps ### ✨ **THE PRO DIFFERENCE** ✨ *This is what sets Spec Kit Pro apart from the standard toolkit*

📱 Building a mobile app? Complex web UI? Multi-screen dashboard?

The UX Workflow generates complete design artifacts that bridge the gap between requirements and implementation. No design tools needed — everything stays in version control as Markdown.

For mobile apps, complex web applications, or any UI-heavy project, use the enhanced UX workflow:

1. Generate User Flows

After creating your spec, generate Mermaid flowcharts for each user journey:

/speckit.userflows

This creates userflows.md with:

2. Create Information Architecture

Generate navigation structure and content hierarchy:

/speckit.ia

This creates ia.md with:

3. Design Wireframes

Generate ASCII wireframe layouts for all screens:

/speckit.wireframes

This creates wireframes.md with:

4. Extract Components

Generate component hierarchy from wireframes:

/speckit.components

This creates components.md with:

5. Analyze User Tasks (Optional)

Run UX task analysis for optimization insights:

/speckit.tasks-ux

This creates tasks-ux.md with:

Example: Mobile Task App

# Create the specification
/speckit.specify Build a mobile task management app with projects, tasks, due dates, and notifications

# Generate UX artifacts
/speckit.userflows    # Mermaid flows for task creation, assignment, completion
/speckit.ia           # Tab bar navigation (Projects, Tasks, Notifications, Profile)
/speckit.wireframes   # ASCII layouts for each screen
/speckit.components   # TaskCard, ProjectList, NotificationBadge, etc.

# Continue with standard workflow
/speckit.plan         # References UX artifacts automatically
/speckit.tasks        # Includes [UI] tasks from components.md
/speckit.implement    # Build with full UX context

📽️ Video Overview

Want to see Spec Kit in action? Watch our video overview!

Spec Kit video header

🤖 Supported AI Agents

Agent Support Notes
Qoder CLI ✅  
Amazon Q Developer CLI ⚠️ Amazon Q Developer CLI does not support custom arguments for slash commands.
Amp ✅  
Auggie CLI ✅  
Claude Code ✅  
CodeBuddy CLI ✅  
Codex CLI ✅  
Cursor ✅  
Gemini CLI ✅  
GitHub Copilot ✅  
IBM Bob ✅ IDE-based agent with slash command support
Jules ✅  
Kilo Code ✅  
opencode ✅  
Qwen Code ✅  
Roo Code ✅  
SHAI (OVHcloud) ✅  
Windsurf ✅  

🔧 Specify CLI Reference

The specify-pro command supports the following options:

Commands

Command Description
init Initialize a new Specify project from the latest template
check Check for installed tools (git, claude, gemini, code/code-insiders, cursor-agent, windsurf, qwen, opencode, codex, shai, qoder)

specify-pro init Arguments & Options

Argument/Option Type Description
<project-name> Argument Name for your new project directory (optional if using --here, or use . for current directory)
--ai Option AI assistant to use: claude, gemini, copilot, cursor-agent, qwen, opencode, codex, windsurf, kilocode, auggie, roo, codebuddy, amp, shai, q, bob, or qoder
--script Option Script variant to use: sh (bash/zsh) or ps (PowerShell)
--ignore-agent-tools Flag Skip checks for AI agent tools like Claude Code
--no-git Flag Skip git repository initialization
--here Flag Initialize project in the current directory instead of creating a new one
--force Flag Force merge/overwrite when initializing in current directory (skip confirmation)
--skip-tls Flag Skip SSL/TLS verification (not recommended)
--debug Flag Enable detailed debug output for troubleshooting
--github-token Option GitHub token for API requests (or set GH_TOKEN/GITHUB_TOKEN env variable)

Examples

# Basic project initialization
specify-pro init my-project

# Initialize with specific AI assistant
specify-pro init my-project --ai claude

# Initialize with Cursor support
specify-pro init my-project --ai cursor-agent

# Initialize with Qoder support
specify-pro init my-project --ai qoder

# Initialize with Windsurf support
specify-pro init my-project --ai windsurf

# Initialize with Amp support
specify-pro init my-project --ai amp

# Initialize with SHAI support
specify-pro init my-project --ai shai

# Initialize with IBM Bob support
specify-pro init my-project --ai bob

# Initialize with PowerShell scripts (Windows/cross-platform)
specify-pro init my-project --ai copilot --script ps

# Initialize in current directory
specify-pro init . --ai copilot
# or use the --here flag
specify-pro init --here --ai copilot

# Force merge into current (non-empty) directory without confirmation
specify-pro init . --force --ai copilot
# or
specify-pro init --here --force --ai copilot

# Skip git initialization
specify-pro init my-project --ai gemini --no-git

# Enable debug output for troubleshooting
specify-pro init my-project --ai claude --debug

# Use GitHub token for API requests (helpful for corporate environments)
specify-pro init my-project --ai claude --github-token ghp_your_token_here

# Check system requirements
specify-pro check

Available Slash Commands

After running specify-pro init, your AI coding agent will have access to these slash commands for structured development:

Core Commands

Essential commands for the Spec-Driven Development workflow:

Command Description
/speckit.constitution Create or update project governing principles and development guidelines
/speckit.specify Define what you want to build (requirements and user stories)
/speckit.plan Create technical implementation plans with your chosen tech stack
/speckit.tasks Generate actionable task lists for implementation
/speckit.implement Execute all tasks to build the feature according to the plan

UX Commands

Commands for UI/UX-heavy applications (mobile apps, complex web apps):

Command Description
/speckit.userflows Generate Mermaid flowchart diagrams for user journeys (run after /speckit.specify)
/speckit.ia Create information architecture and navigation structure (run after /speckit.userflows)
/speckit.wireframes Generate ASCII wireframe layouts for all screens (run after /speckit.ia)
/speckit.components Extract UI component hierarchy from wireframes (run after /speckit.wireframes)
/speckit.tasks-ux Analyze user tasks for UX optimization (can run after /speckit.specify)

Optional Commands

Additional commands for enhanced quality and validation:

Command Description
/speckit.clarify Clarify underspecified areas (recommended before /speckit.plan; formerly /quizme)
/speckit.analyze Cross-artifact consistency & coverage analysis (run after /speckit.tasks, before /speckit.implement)
/speckit.checklist Generate custom quality checklists that validate requirements completeness, clarity, and consistency (like “unit tests for English”)

Environment Variables

Variable Description
SPECIFY_FEATURE Override feature detection for non-Git repositories. Set to the feature directory name (e.g., 001-photo-albums) to work on a specific feature when not using Git branches.
**Must be set in the context of the agent you’re working with prior to using /speckit.plan or follow-up commands.

📚 Core Philosophy

Spec-Driven Development is a structured process that emphasizes:

🌟 Development Phases

Phase Focus Key Activities
0-to-1 Development (“Greenfield”) Generate from scratch <ul><li>Start with high-level requirements</li><li>Generate specifications</li><li>Plan implementation steps</li><li>Build production-ready applications</li></ul>
Creative Exploration Parallel implementations <ul><li>Explore diverse solutions</li><li>Support multiple technology stacks & architectures</li><li>Experiment with UX patterns</li></ul>
Iterative Enhancement (“Brownfield”) Brownfield modernization <ul><li>Add features iteratively</li><li>Modernize legacy systems</li><li>Adapt processes</li></ul>

🎯 Experimental Goals

Our research and experimentation focus on:

Technology independence

Enterprise constraints

User-centric development

Creative & iterative processes

🔧 Prerequisites

If you encounter issues with an agent, please open an issue so we can refine the integration.

📖 Learn More

📋 Detailed Process

Click to expand the detailed step-by-step walkthrough You can use the Specify CLI to bootstrap your project, which will bring in the required artifacts in your environment. Run: ```bash specify-pro init ``` Or initialize in the current directory: ```bash specify-pro init . # or use the --here flag specify-pro init --here # Skip confirmation when the directory already has files specify-pro init . --force # or specify-pro init --here --force ``` ![Specify CLI bootstrapping a new project in the terminal](/spec-kit-pro/media/specify_cli.gif) You will be prompted to select the AI agent you are using. You can also proactively specify it directly in the terminal: ```bash specify-pro init --ai claude specify-pro init --ai gemini specify-pro init --ai copilot # Or in current directory: specify-pro init . --ai claude specify-pro init . --ai codex # or use --here flag specify-pro init --here --ai claude specify-pro init --here --ai codex # Force merge into a non-empty current directory specify-pro init . --force --ai claude # or specify-pro init --here --force --ai claude ``` The CLI will check if you have Claude Code, Gemini CLI, Cursor CLI, Qwen CLI, opencode, Codex CLI, Qoder CLI, or Amazon Q Developer CLI installed. If you do not, or you prefer to get the templates without checking for the right tools, use `--ignore-agent-tools` with your command: ```bash specify-pro init --ai claude --ignore-agent-tools ``` ### **STEP 1:** Establish project principles Go to the project folder and run your AI agent. In our example, we're using `claude`. ![Bootstrapping Claude Code environment](/spec-kit-pro/media/bootstrap-claude-code.gif) You will know that things are configured correctly if you see the `/speckit.constitution`, `/speckit.specify`, `/speckit.plan`, `/speckit.tasks`, and `/speckit.implement` commands available. The first step should be establishing your project's governing principles using the `/speckit.constitution` command. This helps ensure consistent decision-making throughout all subsequent development phases: ```text /speckit.constitution Create principles focused on code quality, testing standards, user experience consistency, and performance requirements. Include governance for how these principles should guide technical decisions and implementation choices. ``` This step creates or updates the `.specify/memory/constitution.md` file with your project's foundational guidelines that the AI agent will reference during specification, planning, and implementation phases. ### **STEP 2:** Create project specifications With your project principles established, you can now create the functional specifications. Use the `/speckit.specify` command and then provide the concrete requirements for the project you want to develop. > [!IMPORTANT] > Be as explicit as possible about *what* you are trying to build and *why*. **Do not focus on the tech stack at this point**. An example prompt: ```text Develop Taskify, a team productivity platform. It should allow users to create projects, add team members, assign tasks, comment and move tasks between boards in Kanban style. In this initial phase for this feature, let's call it "Create Taskify," let's have multiple users but the users will be declared ahead of time, predefined. I want five users in two different categories, one product manager and four engineers. Let's create three different sample projects. Let's have the standard Kanban columns for the status of each task, such as "To Do," "In Progress," "In Review," and "Done." There will be no login for this application as this is just the very first testing thing to ensure that our basic features are set up. For each task in the UI for a task card, you should be able to change the current status of the task between the different columns in the Kanban work board. You should be able to leave an unlimited number of comments for a particular card. You should be able to, from that task card, assign one of the valid users. When you first launch Taskify, it's going to give you a list of the five users to pick from. There will be no password required. When you click on a user, you go into the main view, which displays the list of projects. When you click on a project, you open the Kanban board for that project. You're going to see the columns. You'll be able to drag and drop cards back and forth between different columns. You will see any cards that are assigned to you, the currently logged in user, in a different color from all the other ones, so you can quickly see yours. You can edit any comments that you make, but you can't edit comments that other people made. You can delete any comments that you made, but you can't delete comments anybody else made. ``` After this prompt is entered, you should see Claude Code kick off the planning and spec drafting process. Claude Code will also trigger some of the built-in scripts to set up the repository. Once this step is completed, you should have a new branch created (e.g., `001-create-taskify`), as well as a new specification in the `specs/001-create-taskify` directory. The produced specification should contain a set of user stories and functional requirements, as defined in the template. At this stage, your project folder contents should resemble the following: ```text └── .specify ├── memory │ └── constitution.md ├── scripts │ ├── check-prerequisites.sh │ ├── common.sh │ ├── create-new-feature.sh │ ├── setup-plan.sh │ └── update-claude-md.sh ├── specs │ └── 001-create-taskify │ └── spec.md └── templates ├── plan-template.md ├── spec-template.md └── tasks-template.md ``` ### **STEP 3:** Functional specification clarification (required before planning) With the baseline specification created, you can go ahead and clarify any of the requirements that were not captured properly within the first shot attempt. You should run the structured clarification workflow **before** creating a technical plan to reduce rework downstream. Preferred order: 1. Use `/speckit.clarify` (structured) – sequential, coverage-based questioning that records answers in a Clarifications section. 2. Optionally follow up with ad-hoc free-form refinement if something still feels vague. If you intentionally want to skip clarification (e.g., spike or exploratory prototype), explicitly state that so the agent doesn't block on missing clarifications. Example free-form refinement prompt (after `/speckit.clarify` if still needed): ```text For each sample project or project that you create there should be a variable number of tasks between 5 and 15 tasks for each one randomly distributed into different states of completion. Make sure that there's at least one task in each stage of completion. ``` You should also ask Claude Code to validate the **Review & Acceptance Checklist**, checking off the things that are validated/pass the requirements, and leave the ones that are not unchecked. The following prompt can be used: ```text Read the review and acceptance checklist, and check off each item in the checklist if the feature spec meets the criteria. Leave it empty if it does not. ``` It's important to use the interaction with Claude Code as an opportunity to clarify and ask questions around the specification - **do not treat its first attempt as final**. ### **STEP 4:** Generate a plan You can now be specific about the tech stack and other technical requirements. You can use the `/speckit.plan` command that is built into the project template with a prompt like this: ```text We are going to generate this using .NET Aspire, using Postgres as the database. The frontend should use Blazor server with drag-and-drop task boards, real-time updates. There should be a REST API created with a projects API, tasks API, and a notifications API. ``` The output of this step will include a number of implementation detail documents, with your directory tree resembling this: ```text . ├── CLAUDE.md ├── memory │ └── constitution.md ├── scripts │ ├── check-prerequisites.sh │ ├── common.sh │ ├── create-new-feature.sh │ ├── setup-plan.sh │ └── update-claude-md.sh ├── specs │ └── 001-create-taskify │ ├── contracts │ │ ├── api-spec.json │ │ └── signalr-spec.md │ ├── data-model.md │ ├── plan.md │ ├── quickstart.md │ ├── research.md │ └── spec.md └── templates ├── CLAUDE-template.md ├── plan-template.md ├── spec-template.md └── tasks-template.md ``` Check the `research.md` document to ensure that the right tech stack is used, based on your instructions. You can ask Claude Code to refine it if any of the components stand out, or even have it check the locally-installed version of the platform/framework you want to use (e.g., .NET). Additionally, you might want to ask Claude Code to research details about the chosen tech stack if it's something that is rapidly changing (e.g., .NET Aspire, JS frameworks), with a prompt like this: ```text I want you to go through the implementation plan and implementation details, looking for areas that could benefit from additional research as .NET Aspire is a rapidly changing library. For those areas that you identify that require further research, I want you to update the research document with additional details about the specific versions that we are going to be using in this Taskify application and spawn parallel research tasks to clarify any details using research from the web. ``` During this process, you might find that Claude Code gets stuck researching the wrong thing - you can help nudge it in the right direction with a prompt like this: ```text I think we need to break this down into a series of steps. First, identify a list of tasks that you would need to do during implementation that you're not sure of or would benefit from further research. Write down a list of those tasks. And then for each one of these tasks, I want you to spin up a separate research task so that the net results is we are researching all of those very specific tasks in parallel. What I saw you doing was it looks like you were researching .NET Aspire in general and I don't think that's gonna do much for us in this case. That's way too untargeted research. The research needs to help you solve a specific targeted question. ``` > [!NOTE] > Claude Code might be over-eager and add components that you did not ask for. Ask it to clarify the rationale and the source of the change. ### **STEP 5:** Have Claude Code validate the plan With the plan in place, you should have Claude Code run through it to make sure that there are no missing pieces. You can use a prompt like this: ```text Now I want you to go and audit the implementation plan and the implementation detail files. Read through it with an eye on determining whether or not there is a sequence of tasks that you need to be doing that are obvious from reading this. Because I don't know if there's enough here. For example, when I look at the core implementation, it would be useful to reference the appropriate places in the implementation details where it can find the information as it walks through each step in the core implementation or in the refinement. ``` This helps refine the implementation plan and helps you avoid potential blind spots that Claude Code missed in its planning cycle. Once the initial refinement pass is complete, ask Claude Code to go through the checklist once more before you can get to the implementation. You can also ask Claude Code (if you have the [GitHub CLI](https://docs.github.com/en/github-cli/github-cli) installed) to go ahead and create a pull request from your current branch to `main` with a detailed description, to make sure that the effort is properly tracked. > [!NOTE] > Before you have the agent implement it, it's also worth prompting Claude Code to cross-check the details to see if there are any over-engineered pieces (remember - it can be over-eager). If over-engineered components or decisions exist, you can ask Claude Code to resolve them. Ensure that Claude Code follows the [constitution](base/memory/constitution.md) as the foundational piece that it must adhere to when establishing the plan. ### **STEP 6:** Generate task breakdown with /speckit.tasks With the implementation plan validated, you can now break down the plan into specific, actionable tasks that can be executed in the correct order. Use the `/speckit.tasks` command to automatically generate a detailed task breakdown from your implementation plan: ```text /speckit.tasks ``` This step creates a `tasks.md` file in your feature specification directory that contains: - **Task breakdown organized by user story** - Each user story becomes a separate implementation phase with its own set of tasks - **Dependency management** - Tasks are ordered to respect dependencies between components (e.g., models before services, services before endpoints) - **Parallel execution markers** - Tasks that can run in parallel are marked with `[P]` to optimize development workflow - **File path specifications** - Each task includes the exact file paths where implementation should occur - **Test-driven development structure** - If tests are requested, test tasks are included and ordered to be written before implementation - **Checkpoint validation** - Each user story phase includes checkpoints to validate independent functionality The generated tasks.md provides a clear roadmap for the `/speckit.implement` command, ensuring systematic implementation that maintains code quality and allows for incremental delivery of user stories. ### **STEP 7:** Implementation Once ready, use the `/speckit.implement` command to execute your implementation plan: ```text /speckit.implement ``` The `/speckit.implement` command will: - Validate that all prerequisites are in place (constitution, spec, plan, and tasks) - Parse the task breakdown from `tasks.md` - Execute tasks in the correct order, respecting dependencies and parallel execution markers - Follow the TDD approach defined in your task plan - Provide progress updates and handle errors appropriately > [!IMPORTANT] > The AI agent will execute local CLI commands (such as `dotnet`, `npm`, etc.) - make sure you have the required tools installed on your machine. Once the implementation is complete, test the application and resolve any runtime errors that may not be visible in CLI logs (e.g., browser console errors). You can copy and paste such errors back to your AI agent for resolution. </details> --- ## 🔍 Troubleshooting ### Git Credential Manager on Linux If you're having issues with Git authentication on Linux, you can install Git Credential Manager: ```bash #!/usr/bin/env bash set -e echo "Downloading Git Credential Manager v2.6.1..." wget https://github.com/git-ecosystem/git-credential-manager/releases/download/v2.6.1/gcm-linux_amd64.2.6.1.deb echo "Installing Git Credential Manager..." sudo dpkg -i gcm-linux_amd64.2.6.1.deb echo "Configuring Git to use GCM..." git config --global credential.helper manager echo "Cleaning up..." rm gcm-linux_amd64.2.6.1.deb ``` ## 👥 Maintainers - Den Delimarsky ([@localden](https://github.com/localden)) - John Lam ([@jflam](https://github.com/jflam)) ## 💬 Support For support, please open a [GitHub issue](https://github.com/Dong237/spec-kit-pro/issues/new). We welcome bug reports, feature requests, and questions about using Spec-Driven Development. ## 🙏 Acknowledgements Spec Kit Pro is built on top of [GitHub's Spec Kit](https://github.com/github/spec-kit), which was created by [John Lam](https://github.com/jflam) and [Den Delimarsky](https://github.com/localden). The Pro version adds UI/UX artifact generation capabilities. ## 📄 License This project is licensed under the terms of the MIT open source license. Please refer to the [LICENSE](/spec-kit-pro/LICENSE) file for the full terms.
This site is open source. Improve this page.