The Problem
AI-assisted development often fails because models work from vague instructions and lose context across sessions. Teams need a way to structure AI work into spec-driven phases with tracked tasks, so that a Claude Code session can pick up where the last one left off without re-deriving the project's conventions.
What This Does
flowspec is a workflow framework for Claude Code that enforces spec-driven development (SDD). It installs a set of slash commands (/flow:specify, /flow:plan, /flow:implement, /flow:validate) defined under .claude/commands/flow/ that route work through specialized agents defined in .claude/agents/. Each command reads from and writes to a backlog.md task file and a .beads/ issue tracker, giving AI sessions persistent state.
The repo is almost entirely Markdown (156 of 200 files) — prompt templates, agent definitions, and hook scripts. The actual logic lives in Python hooks under .claude/hooks/ (e.g., pre-implement.py, stop-quality-gate.py) that enforce gates like "no commits to main" and "run tests before PR." A flowspec init command bootstraps the whole setup into an existing project.
How To Use It
Install via uv and run flowspec init to scaffold the workflow into a project. The README documents these commands directly:
uv tool install flowspec-cli --from git+https://github.com/jpoley/flowspec.git flowspec init my-project --ai claude cd my-project
After init, run /flow:assess "feature description" to score complexity (8–12 = simple, 13–20 = medium, 21+ = complex). Simple tasks skip straight to backlog task create; medium runs /flow:specify then /flow:implement; complex adds /flow:plan and /flow:validate. All commands are Claude Code slash commands, so there's no standalone server or daemon to run.
Configuration lives in .claude/settings.json (hook enablement), .backlog/config.yml (task rules), and .beads/config.yaml (issue tracking). No environment variables are required.
Real-World Use
A team building a JWT-authenticated REST API would run /flow:specify "Build task management API with JWT". That spawns .claude/agents/software-architect-enhanced.md to produce a spec, then /flow:implement invokes .claude/agents/backend-engineer.md to write code against the spec, with pre-implement.py checking the backlog for acceptance criteria before any file changes.
Code Health & Issues
High — No LICENSE file — despite the README showing a license badge, no LICENSE exists in the repo root. Usage rights are ambiguous. High — Possible secrets committed — .backlog/hooks/pre-commit-secrets.sh appears to contain or reference credential detection logic; verify no actual secrets are in the file. Med — No CI/CD pipeline — .github/ has issue templates and prompts but no workflow YAML files; the release badge in the README references the upstream jpoley/flowspec repo, not this fork. Med — Fork drift — this repo is a fork of jpoley/flowspec with 50 stars upstream. The .github/prompts/ directory contains three generations of prompts (specflow.DEPRECATED, jpspec., flowspec.), suggesting incomplete migration.
The Bottom Line
flowspec is a well-structured SDD framework for teams already invested in Claude Code — it brings real discipline to AI-assisted development. The lack of CI and license, plus evidence of fork drift, means you should verify the upstream repo's state before adopting this fork. Solo developers will find the ceremony heavy; teams with multi-session AI workflows will get the most value.