Plan features with specialized AI agents. Track progress in backlog.md. 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
Use the pre-built jpoley/flowspec-agents Docker image with all AI coding assistants pre-installed:
# Copy devcontainer template to your project
mkdir -p .devcontainer
curl -o .devcontainer/devcontainer.json \
https://raw.githubusercontent.com/jpoley/flowspec/main/templates/devcontainer/devcontainer.jsonOpen in VS Code → "Reopen in Container". The image includes:
- Claude Code, Codex, Gemini CLI, GitHub Copilot CLI
- Python 3.11, Node.js 20, pnpm, uv, backlog.md
# Specify CLI (project initialization)
uv tool install specify-cli --from git+https://github.com/jpoley/flowspec.git
# Backlog.md (task management)
pnpm i -g backlog.mdspecify init my-project --ai claude
cd my-project
backlog init "$(basename "$PWD")"/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:validate
/flow:operateFor 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:specify ┌──────────┐ • [feature]-prd.md │
│ │Specified │ • [feature]-functional.md │
│ └────┬─────┘ │
│ │ │
│ ▼ │
│ /flow:research ┌──────────┐ • Research reports OPTIONAL │
│ (optional) │Researched│ • Competitive analysis │
│ └────┬─────┘ │
│ │ │
│ ▼ │
│ /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 │
│ │ │
│ ▼ │
│ /flow:operate ┌──────────┐ • [service]-runbook.md │
│ │Deployed │ • Deployment configs │
│ └────┬─────┘ • Monitoring dashboards │
│ │ │
│ ▼ │
│ ┌──────────┐ │
│ │ Done │ │
│ └──────────┘ │
│ │
└────────────────────────────────────────────────────────────────────────────────┘
┌────────────────────────────────────────────────────────────────────────────────┐
│ FLOWSPEC COMMAND REFERENCE │
├──────────────────┬───────────────┬────────────────┬────────────────────────────┤
│ COMMAND │ INPUT STATE │ OUTPUT STATE │ PRIMARY AGENTS │
├──────────────────┼───────────────┼────────────────┼────────────────────────────┤
│ /flow:assess │ (any) │ (no change) │ Complexity Scorer │
│ /flow:specify │ To Do │ 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 │
│ /flow:operate │ Validated │ Deployed │ SRE Agent │
└──────────────────┴───────────────┴────────────────┴────────────────────────────┘
* Also accepts "Researched" state
Every feature follows this document progression:
┌──────────────────────────────────────────────────────────────────────────────┐
│ ARTIFACT PROGRESSION │
│ │
│ PRD ──► Functional ──► Technical ──► ADR ──► Code ──► Runbook │
│ Spec Spec │
│ │
│ "What & "What "How to "Why this Actual "How to │
│ Why" behaviors" build" path" code operate" │
│ │
└──────────────────────────────────────────────────────────────────────────────┘
| Stage | Artifact | Question Answered | Location |
|---|---|---|---|
| 1 | PRD | What must it do and why the user cares | docs/prd/ |
| 2 | Functional Spec | What behaviors are required | docs/specs/ |
| 3 | Technical Spec | How will we build it | docs/specs/ |
| 4 | ADR | Why we chose this technical path | docs/adr/ |
| 5 | Implementation | The code itself | src/ |
| 6 | Runbook | How to operate and troubleshoot | docs/runbooks/ |
| Document | Pattern | Example |
|---|---|---|
| PRD | [feature]-prd.md |
user-auth-prd.md |
| Functional Spec | [feature]-functional.md |
user-auth-functional.md |
| Technical Spec | [feature]-technical.md |
user-auth-technical.md |
| ADR | adr-[number]-[topic].md |
adr-015-auth-provider.md |
| Runbook | [service]-runbook.md |
auth-service-runbook.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 | Included in Devcontainer |
|---|---|---|
| Claude Code | Fully supported (primary) | ✅ |
| GitHub Copilot CLI | Fully supported | ✅ |
| Codex CLI | Fully supported | ✅ |
| Gemini CLI | Fully supported | ✅ |
| Cursor | Fully supported | - |
| Windsurf | Fully supported | - |
The jpoley/flowspec-agents Docker image provides a ready-to-use development environment with Claude Code, Codex, Gemini CLI, and GitHub Copilot CLI pre-installed. See Quick Start for setup instructions.
# Initialize with multiple agents
specify init my-project --ai claude,copilot,cursor-agentproject/
├── .devcontainer/ # Devcontainer configuration
│ └── devcontainer.json # Uses jpoley/flowspec-agents image
├── docs/
│ ├── prd/ # PRDs from /flow:specify
│ ├── specs/ # Functional & Technical specs
│ ├── adr/ # Architecture Decision Records
│ ├── platform/ # Platform design docs
│ ├── qa/ # QA reports from /flow:validate
│ ├── security/ # Security scans
│ └── runbooks/ # Operational runbooks
├── src/ # Implementation code
├── tests/ # Test suites
├── backlog/ # Task management
└── memory/ # Constitution and specs
└── constitution.md # Project principles
- Backlog Quick Start - 5-minute intro
- Problem Sizing Assessment - When to use SDD
- Devcontainer Template - Devcontainer setup guide
- Flowspec Workflow Diagram - Full visual workflow
- Flowspec + Backlog Integration - How commands integrate
- Agent Loop Classification - Which agents for which phases
- Backlog User Guide - Complete task management
- Inner Loop Reference - Development cycle
- Outer Loop Reference - CI/CD and deployment
- Docker Hub Architecture - flowspec-agents image details
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.
See CONTRIBUTING.md for guidelines. All commits require DCO sign-off:
git commit -s -m "feat: your feature"MIT License - see LICENSE for details.
Built on GitHub's spec-kit | Powered by Backlog.md | Docker: jpoley/flowspec-agents