flowspec

Plan features with specialized AI agents. Track tasks with backlog.md + beads. Ship with confidence.

---

What is flowspec?

flowspec transforms how you build software with AI. Instead of giving AI loose instructions, you give it structured specifications and tracked tasks. Each /flowspec command launches specialized AI agents that:

1. Read existing specifications and tasks
2. Create the right artifacts for each phase
3. Track progress in your backlog
4. Commit with proper formatting and validation

Quick Start

Installation

# Install flowspec CLI
uv tool install flowspec-cli --from git+https://github.com/jpoley/flowspec.git

# Initialize your project (prompts to install backlog.md + beads if missing)
flowspec init my-project --ai claude
cd my-project

Note: During flowspec init, you'll be prompted to install:

• backlog.md - task management
• beads - issue tracking for AI agents

Establish Principles (Optional but Recommended)

/flow:init   # Creates constitution with project principles

Assess Your Feature

/flow:assess Build a REST API for task management with JWT authentication

Run the Appropriate Workflow

For Full SDD (complex features):

/flow:specify Build a REST API for task management with JWT authentication
/flow:plan
/flow:implement
/flow:validate

For Light/Medium (medium features):

/flow:specify Build a new user settings page
/flow:implement

For Simple tasks:

# Just create a task and implement
backlog task create "Fix login button alignment" --ac "Button aligns with form fields"
# Then code directly

Choose Your Workflow Mode

┌────────────────────────────────────────────────────────────────────────┐
│                        WORKFLOW MODE SELECTION                          │
├────────────────────────────────────────────────────────────────────────┤
│                                                                         │
│  ┌─────────────┐     ┌─────────────┐     ┌─────────────┐              │
│  │   SIMPLE    │     │   MEDIUM    │     │   COMPLEX   │              │
│  │  (Score 8-12)│     │ (Score 13-20)│    │ (Score 21+) │              │
│  └──────┬──────┘     └──────┬──────┘     └──────┬──────┘              │
│         │                   │                   │                      │
│         ▼                   ▼                   ▼                      │
│    Skip SDD           Light/Medium            Full SDD                 │
│    Just code          Quick specs             All phases               │
│                                                                         │
│  Examples:            Examples:               Examples:                 │
│  • Bug fix            • New endpoint          • New auth system         │
│  • Config change      • UI component          • Payment integration     │
│  • Doc update         • Small feature         • Major refactor          │
│                                                                         │
└────────────────────────────────────────────────────────────────────────┘

Quick Decision: Run /flow:assess first

/flow:assess Build a REST API with user authentication

This scores your feature across 8 dimensions and recommends: Skip SDD, Light/Medium, or Full SDD.

Workflow Modes Explained

All modes produce the same artifacts - only the review depth changes: