Plan features with specialized AI agents. Track tasks with backlog.md + beads. Ship with confidence.
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:
- Read existing specifications and tasks
- Create the right artifacts for each phase
- Track progress in your backlog
- Commit with proper formatting and validation
# 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-projectNote: During
flowspec init, you'll be prompted to install:
- backlog.md - task management
- beads - issue tracking for AI agents
/flow:init # Creates constitution with project principles/flow:assess Build a REST API for task management with JWT authenticationFor Full SDD (complex features):
/flow:specify Build a REST API for task management with JWT authentication
/flow:plan
/flow:implement
/flow:validateFor Light/Medium (medium features):
/flow:specify Build a new user settings page
/flow:implementFor Simple tasks:
# Just create a task and implement
backlog task create "Fix login button alignment" --ac "Button aligns with form fields"
# Then code directly┌────────────────────────────────────────────────────────────────────────┐
│ 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 │
│ │
└────────────────────────────────────────────────────────────────────────┘
/flow:assess Build a REST API with user authenticationThis scores your feature across 8 dimensions and recommends: Skip SDD, Light/Medium, or Full SDD.
All modes produce the same artifacts - only the review depth changes:
┌─────────────────────────────────────────────────────────────────────────┐
│ WORKFLOW MODES │
├───────────┬─────────────────────────┬───────────────────────────────────┤
│ MODE │ ARTIFACTS PRODUCED │ REVIEW APPROACH │
├───────────┼─────────────────────────┼───────────────────────────────────┤
│ FULL │ PRD │ Deep review at each stage │
│ │ Functional Spec │ Explicit approval gates │
│ │ Technical Spec │ Formal ADRs │
│ │ ADRs │ Multi-reviewer sign-off │
│ │ Code + Tests │ │
│ │ Runbook │ │
├───────────┼─────────────────────────┼───────────────────────────────────┤
│ MEDIUM │ PRD │ Quick review │
│ │ Functional Spec │ Proceed unless issues found │
│ │ Technical Spec │ Combined passes allowed │
│ │ ADRs │ Single reviewer OK │
│ │ Code + Tests │ │
│ │ Runbook │ │
├───────────┼─────────────────────────┼───────────────────────────────────┤
│ LIGHT │ PRD │ Minimal review │
│ │ Functional Spec │ Trust the process │
│ │ Technical Spec │ Decision notes (not full ADRs) │
│ │ ADRs │ Fast iteration │
│ │ Code + Tests │ │
│ │ Runbook │ │
└───────────┴─────────────────────────┴───────────────────────────────────┘
Light mode is NOT an excuse to skip artifacts. It's permission to move faster.
┌────────────────────────────────────────────────────────────────────────────────┐
│ FLOWSPEC WORKFLOW STATE MACHINE │
├────────────────────────────────────────────────────────────────────────────────┤
│ │
│ COMMAND STATE ARTIFACTS PRODUCED │
│ ─────── ───── ───────────────── │
│ │
│ (start) ┌──────────┐ │
│ │ To Do │ (none) │
│ └────┬─────┘ │
│ │ │
│ ▼ │
│ /flow:assess ┌──────────┐ • [feature]-assessment.md │
│ │ Assessed │ • Complexity scoring │
│ └────┬─────┘ │
│ │ │
│ ▼ │
│ /flow:specify ┌──────────┐ • [feature]-prd.md │
│ │Specified │ • Implementation tasks │
│ └────┬─────┘ │
│ │ │
│ ▼ │
│ /flow:plan ┌──────────┐ • [feature]-technical.md │
│ │ Planned │ • adr-XXX-[topic].md │
│ └────┬─────┘ • Platform design docs │
│ │ │
│ ▼ │
│ /flow:implement┌──────────┐ • Source code (src/) │
│ │ In │ • Unit & integration tests │
│ │Progress │ • API documentation │
│ └────┬─────┘ │
│ │ │
│ ▼ │
│ /flow:validate ┌──────────┐ • QA reports │
│ │Validated │ • Security scan results │
│ └────┬─────┘ • Test coverage reports │
│ │ │
│ ▼ │
│ ┌──────────┐ │
│ │ Done │ │
│ └──────────┘ │
│ │
│ Note: /flow:research (optional) can be run after Specified → Researched │
│ before proceeding to /flow:plan │
│ │
└────────────────────────────────────────────────────────────────────────────────┘
┌────────────────────────────────────────────────────────────────────────────────┐
│ FLOWSPEC COMMAND REFERENCE │
├──────────────────┬───────────────┬────────────────┬────────────────────────────┤
│ COMMAND │ INPUT STATE │ OUTPUT STATE │ PRIMARY AGENTS │
├──────────────────┼───────────────┼────────────────┼────────────────────────────┤
│ /flow:assess │ To Do │ Assessed │ Workflow Assessor │
│ /flow:specify │ Assessed │ Specified │ PM Planner │
│ /flow:research │ Specified │ Researched │ Researcher, Validator │
│ /flow:plan │ Specified* │ Planned │ Architect, Platform Eng │
│ /flow:implement│ Planned │ In Progress │ Frontend/Backend Engineers │
│ /flow:validate │ In Progress │ Validated │ QA, Security Engineers │
└──────────────────┴───────────────┴────────────────┴────────────────────────────┘
* Also accepts "Researched" state
/flow:research is optional - can skip directly from Specified to /flow:plan
Every feature follows this document progression:
┌──────────────────────────────────────────────────────────────────────────────┐
│ ARTIFACT PROGRESSION │
│ │
│ Assessment ──► PRD ──► Technical ──► ADR ──► Code + Tests │
│ Spec │
│ │
│ "Is SDD "What & "How to "Why this Working │
│ needed?" Why" build" path" software │
│ │
└──────────────────────────────────────────────────────────────────────────────┘
| Stage | Artifact | Question Answered | Location |
|---|---|---|---|
| 1 | Assessment | Is SDD appropriate, what's the complexity | docs/assess/ |
| 2 | PRD | What must it do and why the user cares | docs/prd/ |
| 3 | Technical Spec | How will we build it | docs/specs/ |
| 4 | ADR | Why we chose this technical path | docs/adr/ |
| 5 | Implementation | The code and tests | src/, tests/ |
| Document | Pattern | Example |
|---|---|---|
| Assessment | [feature]-assessment.md |
user-auth-assessment.md |
| PRD | [feature]-prd.md |
user-auth-prd.md |
| Technical Spec | [feature]-technical.md |
user-auth-technical.md |
| ADR | adr-[number]-[topic].md |
adr-015-auth-provider.md |
# View kanban board
backlog board
# List tasks (AI-friendly)
backlog task list --plain
# Start work on a task
backlog task edit 42 -s "In Progress" -a @myself
# Check off acceptance criteria as you work
backlog task edit 42 --check-ac 1
backlog task edit 42 --check-ac 2
# Complete task
backlog task edit 42 -s DoneEvery /flow:implement produces three mandatory deliverables:
┌─────────────────────────────────────────────────────────────────────────┐
│ IMPLEMENTATION DELIVERABLES │
├─────────────────┬─────────────────────┬─────────────────────────────────┤
│ DELIVERABLE │ DESCRIPTION │ VERIFICATION │
├─────────────────┼─────────────────────┼─────────────────────────────────┤
│ Code │ Production-ready │ PR passes CI, review approved │
│ │ reviewed source │ │
├─────────────────┼─────────────────────┼─────────────────────────────────┤
│ Documents │ API docs, comments │ Docs updated, comments added │
│ │ config examples │ │
├─────────────────┼─────────────────────┼─────────────────────────────────┤
│ Tests │ Unit, integration │ Test suite passes │
│ │ edge cases │ Coverage threshold met │
└─────────────────┴─────────────────────┴─────────────────────────────────┘
Implementation is NOT complete until all three are delivered.
| Agent | Support |
|---|---|
| Claude Code | Fully supported (primary) |
| GitHub Copilot CLI | Fully supported |
| Codex CLI | Fully supported |
| Gemini CLI | Fully supported |
| Cursor | Fully supported |
| Windsurf | Fully supported |
# Initialize with multiple agents
flowspec init my-project --ai claude,copilot,cursor-agentproject/
├── docs/
│ ├── assess/ # Assessment reports from /flow:assess
│ ├── prd/ # PRDs from /flow:specify
│ ├── specs/ # Technical specs from /flow:plan
│ ├── adr/ # Architecture Decision Records
│ ├── platform/ # Platform design docs
│ ├── qa/ # QA reports from /flow:validate
│ └── security/ # Security scans
├── src/ # Implementation code
├── tests/ # Test suites
├── backlog/ # Task management
└── memory/ # Constitution and specs
└── constitution.md # Project principles
- Spec-Driven Development - Core SDD methodology
- What's New - Recent updates and changes
- Task Management Tiers - Backlog.md + Beads workflow
- Custom Workflows - Customize flowspec workflows
- Logging - Agent logging configuration
- Security CI/CD Setup - Security scanning in CI/CD
- Pre-commit Hooks - Git hook integration
The original /speckit.* commands are available for standalone specification work but do not integrate with backlog.md. Use /flow:* commands for the fully integrated workflow with task tracking.
Contributions are welcome! All commits require DCO sign-off:
git commit -s -m "feat: your feature"See CODE_OF_CONDUCT.md for community guidelines.
Found a bug or have a suggestion? Please open an issue at github.com/jpoley/flowspec/issues
MIT License - see LICENSE for details.
Built on GitHub's spec-kit | Powered by Backlog.md