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

``bash


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

$3

`bash

Create a new project directly (no installation needed)

npx create-specflow-project@latest my-project
cd my-project
`

$3

`bash

Install globally

npm install -g create-specflow-project

Create a project

create-specflow-project my-project
cd my-project
`

$3

`bash

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
`

$3

- 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

$3

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

$3

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

$3

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:

`json
{
"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

$3

#### "npx: command not found"
`bash


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"
`bash


Clear npm cache and reinstall


npm cache clean --force
npx clear-npx-cache
npx create-specflow-project@latest my-app
`

#### "Directory already exists"
`bash


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"
`bash


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