SpecFlow CLI

🚀 The official CLI for creating AI-powered software specifications using the SpecFlow framework. Build better software by starting with clear, convergent specifications that AI assistants can understand and implement.

🎯 Quick Start

# Create a new SpecFlow project
npx create-specflow-project my-app
cd my-app

# Open in your AI-powered editor
# For Claude: Load CLAUDE.md and execute /specflow start
# For others: Copy start-prompt.txt to your AI assistant

What is SpecFlow?

SpecFlow is a framework for creating machine-readable specifications that AI assistants can use to generate production-ready code. It consists of 6 interconnected templates:

1. PIS - Product Intent Specification (Vision & Goals)
2. DKB - Domain Knowledge Base (Business Rules)
3. UXS - User Experience Specification (User Journeys)
4. DSS - Design System Specification (Visual Design)
5. TAB - Technical Architecture Blueprint (System Design)
6. BSM - Behavioral Specification Matrix (Test Scenarios)

Features

• 🤖 Multi-AI Support - Works with Claude, Gemini, and GPT-5
• 📝 Guided Creation - AI interviews you to create specs
• 🔄 Document Convergence - Ensures consistency across all specs
• 📊 Progress Tracking - Know exactly where you are
• ✅ Validation - Automatic consistency checking
• 📦 Export Ready - Generate markdown, JSON, or PDF

📦 Installation & Setup

Option 1: NPX (Recommended)

# Create a new project directly (no installation needed)
npx create-specflow-project@latest my-project
cd my-project

Option 2: Global Installation

# Install globally
npm install -g create-specflow-project

# Create a project
create-specflow-project my-project
cd my-project

Options

# Skip Git initialization
npx create-specflow-project my-project --skip-git

# Skip telemetry
npx create-specflow-project my-project --skip-telemetry

# Both options
npx create-specflow-project my-project --skip-git --skip-telemetry

System Requirements

• Node.js: 16.0.0 or higher (check with node --version)
• npm: 7.0.0 or higher (check with npm --version)
• Git: Optional, for version control
• AI Editor: Claude Code CLI, Cursor, VS Code, or any text editor

Project Structure

After installation, your project will have:

my-project/
├── specs/              # The 6 SpecFlow templates
│   ├── 01_PIS.md      # Product Intent
│   ├── 02_DKB.md      # Domain Knowledge
│   ├── 03_UXS.md      # User Experience
│   ├── 04_DSS.md      # Design System
│   ├── 05_TAB.md      # Technical Architecture
│   └── 06_BSM.md      # Behavioral Specs
├── .specflow/          # State and configuration
│   ├── state.json     # Progress tracking
│   └── config.json    # User preferences
├── CLAUDE.md          # Instructions for Claude
├── GEMINI.md          # Instructions for Gemini
├── GPT5.md            # Instructions for GPT-5
├── start-prompt.txt   # Quick start prompt
└── README.md          # Project documentation

Usage

Starting with Claude

1. Open your project in Claude Code CLI
2. Say: "Load CLAUDE.md and execute /specflow start"
3. Follow the guided process

Starting with Gemini

1. Open your project in your preferred editor
2. Load GEMINI.md into Gemini
3. Execute: /specflow start

Starting with GPT-5

1. Open your project
2. Load GPT5.md into GPT-5
3. Execute: /specflow start

Commands

All AI assistants support these commands:

• /specflow start - Begin specification process
• /specflow status - Check progress
• /specflow validate - Validate specifications
• /specflow converge - Check convergence score
• /specflow export [format] - Export specifications

Configuration

Edit .specflow/config.json to customize:

{
  "convergence_threshold": 85,    // When documents are "ready"
  "max_iterations": 3,            // Max rounds before human decides
  "auto_validate": true,          // Validate on each change
  "preferred_model": "claude",    // Default AI model
  "telemetry": true              // Anonymous usage stats
}

The SpecFlow Process

1. Foundation Phase: Define your product vision (PIS) and technical approach (TAB)
2. Journey Cycles: For each feature, elaborate UXS, DKB, DSS, and TAB
3. Convergence: Documents negotiate until they agree (85% threshold)
4. Synthesis: Generate comprehensive test scenarios (BSM)
5. Export: Create final blueprint for implementation

Convergence Scoring

Documents must agree on:

• Reference integrity (25%) - All references valid
• Naming consistency (20%) - Same terms everywhere
• Requirement coverage (25%) - PIS goals addressed
• No conflicts (20%) - No contradictions
• Completeness (10%) - No gaps or TODOs

🔧 Troubleshooting

Common Issues

"npx: command not found"

# Install Node.js and npm from nodejs.org
# Or use a version manager like nvm:
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
nvm install 16

"TypeError: inquirer.prompt is not a function"

# Clear npm cache and reinstall
npm cache clean --force
npx clear-npx-cache
npx create-specflow-project@latest my-app

"Directory already exists"

# Choose a different name or remove the existing directory
rm -rf my-app  # Be careful!
npx create-specflow-project my-app

"Command not recognized" in AI

Make sure to load the appropriate AI instruction file:

• Claude: Load CLAUDE.md first
• Gemini: Load GEMINI.md first
• GPT: Load GPT5.md first

"Low convergence score"

# Run validation to see specific issues
/specflow validate
# Address each issue one by one
# Re-run convergence check
/specflow converge

"State lost between sessions"

• State is saved in .specflow/state.json
• Make sure this file isn't deleted
• Keep the project directory intact between sessions

Privacy & Telemetry

Basic anonymous telemetry is collected to improve the framework:

• Project creation events
• Node.js version
• Timestamp

To opt out: --skip-telemetry flag or set telemetry: false in config.json

Contributing

We welcome contributions! Visit our GitHub repository

License

MIT © SpecFlow Team

Support

• Documentation: SpecFlow Docs
• Issues: GitHub Issues
• Discussions: GitHub Discussions

Built with ❤️ for the future of AI-assisted development