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

🆕 Recent Updates

v2.1.2 (October 2025)

/feature next Auto-Pull - Automatically start highest priority roadmap item

• Usage: /feature next - Auto-pulls highest priority feature from GitHub Issues
• Smart Search: Queries status:next first, falls back to status:backlog
• Priority Sorting: Sorts by priority:high → priority:medium → priority:low
• ICE Display: Shows Impact/Confidence/Effort scores and calculated ICE score
• Auto-Status Update: Moves issue from next/backlog → in-progress
• Full Traceability: Links workflow state to GitHub issue number
• No Manual Input: Just run /feature next - no feature description needed

Benefits: Work on highest priority items automatically, reduce context switching, maintain roadmap sync.

v2.1.0 (October 2025)

GitHub Issues Roadmap Migration - Complete migration from markdown to GitHub Issues

• Backend Migration: /roadmap command now uses GitHub Issues instead of markdown files
• Label-Based State: Features organized via labels (status:backlog, status:next, status:in-progress, status:shipped)
• ICE Scoring Preserved: Impact × Confidence / Effort stored in YAML frontmatter in issue descriptions
• Priority Labels: Auto-applied based on ICE score (priority:high >= 1.5, priority:medium 0.8-1.5, priority:low < 0.8)
• Dynamic Sorting: Features sorted by priority labels via queries (no manual file editing)
• Native Integration: Issues, PRs, and roadmap in one place with GitHub Projects support
• Cross-Platform: Both Bash and PowerShell examples throughout
• Same Workflow: All actions (add, brainstorm, move, delete, ship) work identically

Breaking Change: Roadmap data is now in GitHub Issues, not .spec-flow/memory/roadmap.md. Old markdown roadmap can be migrated using .spec-flow/scripts/bash/migrate-roadmap-to-github.sh.

Setup Required: Run .spec-flow/scripts/bash/setup-github-labels.sh to create labels, then authenticate with gh auth login or set GITHUB_TOKEN.

Documentation: See docs/github-roadmap-migration.md for complete guide.

v1.13.0 (October 2025)

Local Project Integration Workflow - Automatic merge-to-main for local-only projects

• New Phase S.4.5a: Merges feature branch → main/master after successful local build
• Auto-detects main branch: Supports both main and master branch names
• Preserves feature history: Uses --no-ff merge to maintain branch context
• Remote sync: Automatically pushes to origin if remote exists
• Branch cleanup: Offers to delete feature branch locally and remotely after merge
• Correct sequencing: Merge happens BEFORE version bump and roadmap update
• Git best practices: Version tag created on main branch (not feature branch)

Before: optimize → build-local → finalize ❌ (stayed on feature branch) After: optimize → build-local → merge-to-main → finalize ✅ (integrated to main)

Impact: Local-only projects now have complete parity with remote deployment models - all features properly integrate to main branch before being marked "Shipped" in roadmap.

v1.12.1 (October 2025)

Update Command Simplification - Removed backup overhead for faster, cleaner updates

• Removed backup creation: npx spec-flow update no longer creates backup folders
• Faster updates: No backup overhead, instant template updates
• User data still preserved: Templates updated while learnings.md, memory, and specs remain untouched
• Removed --force flag: No longer needed (backwards compatible)
• Cleaner output: Shows "Templates updated, user data preserved" message

Why? The preserveMemory flag already protects user data during updates. Backups created redundant folders that users had to manually clean up. This change simplifies the update process while maintaining safety.

v1.12.0 (October 2025)

Learnings Persistence & Design Iteration - Skills learn across npm updates + enhanced design workflow

Part 1: Learnings Persistence (All 16 Skills)

• Separated learnings data from SKILL templates: Created learnings.md for all 16 phase skills
• Preserves knowledge across npm updates: SKILL.md templates get updated, learnings.md data persists
• Tracks pitfall frequencies: Auto-updates frequency stars (⭐☆☆☆☆ → ⭐⭐⭐☆☆) as issues occur
• Tracks pattern success rates: Records usage counts and success rates for proven approaches
• Zero manual intervention: System learns automatically as you work

Part 2: Design Iteration Enhancements

• Screen-specific targeting: /design-variations $SLUG [$SCREEN] - iterate on single component
• Overwrite protection: Warns before regenerating, offers [b]ackup to create git tag first
• Re-enable support: Can enable design workflow after initially declining in /feature
• Iteration patterns guide: 5 common scenarios with step-by-step solutions (component iteration, A/B testing, state-specific refinement)

Documentation

• Added "Skills & Learning System" section to README
• Two-file architecture explained (templates vs data)
• Iteration patterns guide for design workflow

Files: 36 changed (16 learnings.md created, 16 SKILL.md updated, iteration-patterns.md created)

v1.11.1 (October 2025)

Folder Cleanup Refactor - Cleaner spec directories with on-demand folder creation

• Eliminated empty folders: Removed blanket directory pre-creation from /spec command
• On-demand creation: Folders (visuals/, design/) now created only when files are written
• Benefits: Cleaner spec directories, easier to identify UI features, follows YAGNI principle
• Files modified: .claude/commands/specify.md

v1.11.0 (October 2025)

Phase-Specific Learning Skills - Workflow improvement tracking

• Added learning Skills for each workflow phase (spec, plan, tasks, implement, optimize, ship, etc.)
• Auto-triggers on workflow events to capture lessons and improve future iterations
• Skills track common issues: clarification overload, test failures, deployment blockers

View all releases →

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 (/feature) 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

How it works:

/feature (Orchestrator - Lightweight State Tracking)
  ├→ spec-phase-agent → /spec → 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:

• /feature "feature" - Full feature workflow (recommended)
• /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):

   /setup-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:

   /feature "my-feature"  # Full feature workflow
   /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 /setup-constitution command in Claude to document the engineering principles that guard every feature. Store the output in .spec-flow/memory/setup-constitution.md.

3. Build your roadmap

Use /roadmap to manage features via GitHub Issues with ICE scoring (Impact × Confidence / Effort):

• Setup: Authenticate with gh auth login or set GITHUB_TOKEN, then run .spec-flow/scripts/bash/setup-github-labels.sh
• Add features: /roadmap add "feature description" creates GitHub issue with priority labels
• Brainstorm: /roadmap brainstorm [quick|deep] generates ideas from research
• Organize via labels:
  • status:backlog - Ideas to consider
  • status:next - Top 5-10 prioritized features
  • status:in-progress - Currently being built
  • status:shipped - Completed features (issue closed)
• View roadmap: Browse GitHub Issues or use gh issue list --label status:next

Documentation: See docs/github-roadmap-migration.md for complete guide.

4. Kick off a feature

Select a feature from your roadmap and choose your workflow:

Full workflow (recommended):

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

Manual step-by-step:

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

Supported AI Agents

Skills & Learning System

Spec-Flow includes an auto-learning system that captures lessons from each workflow phase to continuously improve your process.

How Skills Work

16 Phase-Specific Skills: Each workflow phase has a dedicated skill that learns from execution:

• .claude/skills/specification-phase/ - Learn from /spec (reduce clarifications, improve classification)
• .claude/skills/planning-phase/ - Learn from /plan (maximize code reuse, detect patterns)
• .claude/skills/implementation-phase/ - Learn from /implement (TDD enforcement, anti-duplication)
• .claude/skills/ui-ux-design/ - Learn from design workflow (Jobs principles, a11y compliance)
• ...and 12 more for other phases

Two-File Architecture:

1. SKILL.md - Template with pitfall descriptions, detection logic, prevention strategies (updated with npm)
2. learnings.md - Accumulated data with frequencies, metrics, instances (preserved across updates)

Learnings Persistence

When you update Spec-Flow via npm, your accumulated learnings are preserved:

What Gets Updated (npm overwrites):

• SKILL.md - Template improvements, new pitfalls, better detection logic
• .claude/commands/*.md - Command improvements, new features
• .spec-flow/templates/*.md - Artifact templates

What Gets Preserved (your local data):

• learnings.md - Pitfall frequencies, pattern usage counts, metrics
• GitHub Issues - Your product roadmap (stored as issues with labels)
• .spec-flow/memory/setup-constitution.md - Your project principles
• specs/*/ - All your feature specifications

Example: After 10 features, your learnings.md shows:

common_pitfalls:
  - id: "over-clarification"
    frequency: 2/5 ⭐⭐☆☆☆
    last_seen: "2025-01-15"
    instances: [feature-001, feature-007]

successful_patterns:
  - id: "informed-guess-strategy"
    usage_count: 8
    success_rate: 87.5%

This data persists across npm updates, so your workflow gets smarter over time.

Auto-Learning in Action

Skills auto-trigger when:

• Starting a phase (loads relevant lessons)
• Completing a phase (detects pitfalls, updates frequencies)
• Encountering errors (captures patterns for prevention)

Skills auto-update when:

• Pitfall detected: Increments frequency (0/5 → 1/5 → 2/5 ★★☆☆☆)
• Pattern used successfully: Increments usage count, recalculates success rate
• Metrics updated: Averages recalculated after each feature

No manual intervention required - the system learns as you work.

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.

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
• yq 4.0+ for YAML state management:
  • macOS: brew install yq
  • Linux: See mikefarah/yq releases
  • Windows: choco install yq
• PowerShell-yaml module for PowerShell scripts:
  • Install-Module -Name powershell-yaml -Scope CurrentUser

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. Set up roadmap: Authenticate with GitHub (gh auth login), run .spec-flow/scripts/bash/setup-github-labels.sh to create labels.
3. Build roadmap: Use /roadmap to add features as GitHub Issues, prioritize with ICE scoring, organize via labels (status:backlog → status:next → status:in-progress → status:shipped).
4. Select a feature from GitHub Issues and launch /feature "<feature-slug>" in Claude to scaffold the spec from the issue.
5. Progress through /clarify, /plan, /tasks, and /validate, addressing blockers as they appear.
6. Use calculate-tokens to watch context budgets and compact-context to summarise when approaching thresholds.
7. Walk the release staircase: /preview, /ship-staging, /validate-staging, /ship-prod.
8. The feature is automatically marked as shipped in GitHub Issues (label changed to status:shipped, issue closed), 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.