An open toolkit that turns product ideas into production launches through Spec-Driven Development.

Table of Contents

• What is Spec-Driven Development?
• Get Started
• Supported AI Agents
• Script Reference
• Core Philosophy
• Development Phases
• Prerequisites
• Learn More
• Detailed Process
• Troubleshooting
• Packages & Releases
• Maintainers
• License

🌟 Why Spec-Flow?

Building software with AI assistants is powerful, but without structure, projects drift. You lose context, forget decisions, skip testing, and ship inconsistent features. Spec-Flow solves this.

The Problem Without Spec-Flow

What You Get

✅ Repeatable Process - Every feature follows the same proven workflow (spec → plan → tasks → ship)

✅ Context Discipline - Token budgets enforced per phase, auto-compaction prevents context bloat

✅ Quality Gates - Automated checks for accessibility, performance, testing, security

✅ Auditable Trail - Every decision documented in NOTES.md, every phase produces artifacts

✅ Faster Velocity - Skip decision paralysis, let the workflow guide you

✅ Team Alignment - Specs reviewed upfront, parallel work enabled, consistent outcomes

Use Cases

• Web Apps - Full-stack features with frontend + backend coordination
• APIs - Contract-first development with automated testing
• CLIs - Command structure definition to distribution
• Mobile Apps - Offline-first architecture with platform-specific handling
• Design Systems - Component libraries with accessibility built-in
• Infrastructure - Terraform modules with security scanning
• ML Projects - Experiment tracking with reproducible pipelines

👉 See more: Use Cases

What is Spec-Driven Development?

Spec-Driven Development flips the traditional model: specifications become executable assets that orchestrate planning, implementation, QA, and release. Each Claude command owns a phase of delivery, produces auditable artifacts, and tees up the next specialist.

The Workflow

💡 Ideas → 🗺️ Roadmap → 📝 Spec → 📋 Plan → ✅ Tasks → 🔍 Analyze →
💻 Implement → ⚡ Optimize → 👀 Preview → 🚀 Staging → ✅ Validate → 🎉 Production

Key Principle: Plan your roadmap first, then write specifications from prioritized features, and let AI agents execute faithfully.

🚀 New: Optimized Phase Agent Architecture (v1.5.0)

Spec-Flow now features an optimized orchestrator (/spec-flow) that runs each workflow phase in isolated contexts for maximum efficiency:

Benefits:

• ⚡ 67% Token Reduction - Each phase runs in isolated context (240k → 80k tokens per feature)
• 🏃 2-3x Faster - No cumulative context bloat, no /compact overhead between phases
• ✅ Same Quality - All slash commands unchanged, proven workflow maintained
• 🔄 Easy Rollback - Original /flow command available as backup

How it works:

/spec-flow (Orchestrator - Lightweight State Tracking)
  ├→ spec-phase-agent → /specify → Returns summary
  ├→ plan-phase-agent → /plan → Returns summary
  ├→ tasks-phase-agent → /tasks → Returns summary
  ├→ /implement → Spawns worker agents directly (bypasses phase agent*)
  └→ ... (each phase isolated, efficient handoffs)

  * Phase 4 calls /implement directly due to sub-agent spawning limits

Choose your workflow:

• /spec-flow "feature" - New optimized workflow (recommended)
• /flow "feature" - Original workflow (backup/fallback)
• /quick "fix" - Fast path for small changes (<100 LOC)

🚀 Quick Start

Option 1: NPM (Recommended)

Install Spec-Flow with a single command:

# Initialize in current directory
npx spec-flow init

# Or\spec-flow target directory
npx spec-flow init --target ./my-project

Option 2: Manual Installation

Clone and run the interactive wizard:

# 1. Clone Spec-Flow repository
git clone https://github.com/marcusgoll/Spec-Flow.git
cd Spec-Flow

# 2. Run the installation wizard (Windows)
powershell -File .spec-flow/scripts/powershell/install-wizard.ps1

# OR (macOS/Linux)
./.spec-flow/scripts/bash/install-wizard.sh

What gets installed:

• ✅ .claude/ - Agents, commands, and settings
• ✅ .spec-flow/ - Scripts, templates, and memory
• ✅ CLAUDE.md - Workflow documentation
• ✅ QUICKSTART.md - Quick start guide (copied to your project)
• ✅ Memory files initialized with defaults

Next steps after installation:

1. Read the guide - Open QUICKSTART.md in your project
2. Open in Claude Code - Navigate to your project directory
3. Set up your project (optional but recommended):

   /constitution         # Interactive Q&A for engineering standards
   /roadmap              # Plan and prioritize features with ICE scoring
   /design-inspiration   # Curate visual references for consistency

4. Start building:

   /spec-flow "my-feature"  # Optimized workflow (recommended)
   /flow "my-feature"       # Original workflow (backup)
   /quick "fix bug"         # Fast path for small changes

👉 Full guide: QUICKSTART.md | Detailed tutorial: Getting Started

Get Started

1. Install the toolkit

From npm (fastest):

npm install -g spec-flow
# or use npx without a global install
npx spec-flow init --target ./my-project

From source:

Clone this repository and ensure you have either PowerShell 7.3+ (pwsh) or a POSIX shell (bash) plus Python 3.10+ available. Scripts live under .spec-flow/scripts/powershell/ and .spec-flow/scripts/bash/.

Full installation guide: docs/installation.md

Copy .claude/settings.example.json to .claude/settings.local.json and update the allow list for your environment.

2. Establish principles

Run the /constitution command in Claude to document the engineering principles that guard every feature. Store the output in .spec-flow/memory/constitution.md.

3. Build your roadmap

Use /roadmap to add features, prioritize them with ICE scoring (Impact × Confidence / Effort), and organize them into:

• Backlog - Ideas to consider
• Next - Top 5-10 prioritized features
• In Progress - Currently being built
• Shipped - Completed features

4. Kick off a feature

Select a feature from your roadmap and choose your workflow:

Optimized workflow (recommended):

/spec-flow "feature-name"  # Runs full workflow with isolated phase agents
# Auto-progresses through: spec → plan → tasks → analyze → implement → optimize → ship
# Pauses at manual gates: /preview, /validate-staging
# Use: /spec-flow continue (to resume after manual gates)

Original workflow (backup):

/flow "feature-name"  # Traditional workflow with cumulative context

Manual step-by-step:

/specify "feature-name"  # Create specification
/plan                    # Create plan
/tasks                   # Break down tasks
/implement              # Execute implementation
# ... continue through remaining phases

Supported AI Agents

Script Reference

Every automation script is provided in both PowerShell (.ps1) and shell (.sh) form. Pick the variant that matches your environment.

Additional scripts such as enable-auto-merge, wait-for-ci, and update-agent-context also ship with .sh wrappers that delegate to PowerShell so you can run them from a POSIX shell while we build native equivalents.

Core Philosophy

1. Specification first every artifact traces back to an explicit requirement.
2. Agents as teammates commands encode expectations so assistants stay aligned.
3. Context discipline token budgets are measured, compacted, and recycled.
4. Ship in stages staging and production have dedicated rituals with human gates.

Development Phases

Context Management: The /compact command is optional and reduces token usage by summarizing verbose artifacts. Use it between phases when context feels heavy or when suggested by auto-progression. In /flow mode, compaction happens automatically.

Prerequisites

• Git 2.39+
• Python 3.10+
• PowerShell 7.3+ (pwsh) for Windows scripts
• Bash 5+ (or Zsh) for shell scripts
• Claude Code access with slash-command support

Optional:

• GitHub CLI (gh) for auto-merge helpers
• Pester 5 for PowerShell test suites

📚 Examples

Complete Working Example: Dark Mode Toggle

Explore a fully-documented feature workflow in specs/001-example-feature/:

specs/001-example-feature/
├── spec.md                    # Feature specification with user scenarios
├── NOTES.md                   # Progress tracking and decisions
├── artifacts/
│   ├── plan.md                # Implementation plan with architecture
│   ├── tasks.md               # 28 tasks with acceptance criteria
│   ├── analysis-report.md     # Risk assessment (0 critical issues)
│   ├── optimization-report.md # Performance metrics (145ms avg)
│   └── release-notes.md       # v1.2.0 release notes
└── visuals/
    └── README.md              # Design references and color tokens

What's included:

• Complete specification with FR/NFR requirements
• 28 tasks broken down across 5 implementation phases
• Performance benchmarks (27% better than target)
• WCAG 2.1 AA accessibility compliance
• Cross-browser testing matrix
• Release notes for v1.2.0

👉 Browse the example: specs/001-example-feature/

Learn More

• docs/architecture.md — how the repository fits together
• docs/commands.md — quick lookup for every slash command
• docs/getting-started.md — step-by-step tutorial for your first feature
• docs/installation.md — platform-specific installation guide
• docs/troubleshooting.md — common issues and solutions
• docs/use-cases.md — examples for different project types
• PUBLISHING.md — release checklist for npm & GitHub Packages
• AGENTS.md — contributor guide for working in this repo
• CONTRIBUTING.md — branching, reviews, and release process

Detailed Process

1. Run .spec-flow/scripts/bash/check-prerequisites.sh --json (or the PowerShell variant) to ensure your environment is ready.
2. Build your roadmap with /roadmap - add features, prioritize with ICE scoring, and organize into Backlog → Next → In Progress → Shipped.
3. Select a feature from the roadmap and launch /spec-flow "<feature-slug>" in Claude to scaffold the spec from the roadmap entry.
4. Progress through /clarify, /plan, /tasks, and /analyze, addressing blockers as they appear.
5. Use calculate-tokens to watch context budgets and compact-context to summarise when approaching thresholds.
6. Walk the release staircase: /preview, /phase-1-ship, /validate-staging, /phase-2-ship.
7. The feature automatically moves to "Shipped" in the roadmap, and changelog is updated with the release.

Packages & Releases

• npm: Published as spec-flow. Install globally with npm install -g spec-flow or run one-off with npx spec-flow.
• GitHub Packages: The Publish Packages workflow mirrors each release to GitHub Packages under the scoped name @marcusgoll/spec-flow, enabling the repository's Packages tab.
• Automation: Creating a GitHub release (or manually running the workflow) triggers the dual publish. Set the NPM_TOKEN repository secret with an npm automation token that has publish rights; GitHub packages use the built-in GITHUB_TOKEN.

Troubleshooting

Maintainers

• Marcus Gollahon (@marcusgoll)

• Community contributors join via pull requests!

License

Released under the MIT License.