flowspec

flowspec – Spec‑Driven Development with AI‑Powered Task Management (Clone: https://github.com/moses-y/flowspec)

Overview

flowspec implements spec‑kit and backlog.md with a task‑memory layer. The repo contains 2 407 files (≈1 800 markdown, 318 Python, 91 YAML, 66 Shell, plus Go, JSON, TOML). It is built with Docker, FastAPI, React, and Spring components; CI runs on GitHub Actions. The code base is organized into eight projects (src, .claude, scripts, templates, utils, examples, .stacks, build‑docs) and ships a CLI, hooks, telemetry, and a net‑log utility.

How It Is Wired

Entry points (real files, not guessed):

Import graph (deterministic, 397 files analysed): 320 internal modules, 81 import edges, 0 circular dependencies.

Most connected modules (Ca = importers, Ce = imports, instability = Ce/(Ca+Ce)):

Hubs such as src/flowspec_cli/satellite/__init__ (instability 1) mean a change ripples widely; low‑instability modules (hooks/events) are leaf‑only.

What the code touches outside the repo – the CLI invokes backlog task create, beads issue tracking, and Docker builds; telemetry pushes metrics to a configurable endpoint (see src/flowspec_cli/telemetry/config.py). The Go net‑log binary listens on 0.0.0.0:9090 by default.

How To Use It

Configuration: environment variables read from .env (not present by default) or from backlog/config.yml. Secrets are committed (see hygiene section) – avoid adding real keys.

Real‑World Use

A product team wants to ship a new “payment‑intent” feature. They run:

1. flowspec init payment‑app --ai claude – creates backlog.md and a beads workspace.
2. /flow:specify Implement payment‑intent flow with Stripe integration – generates backlog/payment-intent.md and template hooks.
3. /flow:plan – produces a design doc under build-docs/.
4. /flow:implement – AI agents scaffold FastAPI routes in src/flowspec_cli/backlog/parser.py, add Stripe webhook handling, and commit with formatted messages.
5. /flow:validate – runs the test suite (tests/e2e/upgrade/) and a Docker build (tests/e2e/upgrade/Dockerfile) to confirm the container runs as an unprivileged user.

The flow keeps task state in backlog/, tracks progress with beads, and each commit is validated by the CI pipeline before merge.

Code Health & Issues

Measured findings (static analysis, 141 total):

• HIGH cognitive_load – deep nesting (max indent 9) in src/flowspec_cli/hooks/schema.py, src/flowspec_cli/backlog/parser.py, src/flowspec_cli/hooks/runner.py. Flatten with guard clauses.
• MEDIUM resilience – broad except clauses in src/flowspec_cli/telemetry/config.py, src/flowspec_cli/telemetry/integration.py, .claude/hooks/logging_helper.py. Catch specific exceptions.
• HIGH clarity – 1 737 repeated 6‑line blocks across 155 files (e.g., .claude/hooks/logging_helper.py, templates/hooks/logging_helper.py). Extract shared helpers.
• HIGH cognitive_load – oversized files: src/flowspec_cli/__init__.py (8 236 lines) and src/flowspec_cli/satellite/audit.py. Split by responsibility.
• MEDIUM resource_safety – open(...) without context manager in .claude/hooks/test-stop-quality-gate.py, src/flowspec_cli/security/mcp_server.py, src/flowspec_cli/security/triage/classifiers/path_traversal.py. Use with open(...) as f:.

Code‑health audit (10 findings, 0 critical):

• [HIGH] Pin third‑party GitHub Actions to commit SHA – .github/workflows includes astral-sh/setup-uv@v4; replace @v4 with 40‑char SHA.
• [HIGH] Commit a lockfile beside the manifest – package.json has no lockfile; run the package manager once and commit the generated file.
• [HIGH] Remove continue-on-error from correctness‑gating steps – .github/workflows/security-parallel.yml line 105; delete or move advisory step.
• [MEDIUM] Declare least‑privilege GITHUB_TOKEN permissions – add permissions: contents: read at workflow top.
• [MEDIUM] Enable Dependabot / Renovate – no update bot configured; add .github/dependabot.yml covering Python, Node, and GitHub‑Actions.
• [MEDIUM] Pin container base image by digest – tests/e2e/upgrade/Dockerfile uses python:3.11-slim; pin to python:3.11-slim@sha256<digest> and enable Dependabot Docker.
• [MEDIUM] Gate PRs on dependency vulnerability scan – no scan in CI; add dependency-review-action on pull_request or osv-scanner.
• [MEDIUM] Set persist-credentials: false on checkout – .github/workflows/security-parallel.yml; add with: persist-credentials: false and explicit token only to push steps.
• [MEDIUM] Add non‑root USER to the image – tests/e2e/upgrade/Dockerfile has no USER directive; create unprivileged user, chown needed paths, and USER at Dockerfile end.
• [LOW] Set timeout-minutes on workflow jobs – ci.yml lacks job timeouts; add realistic bounds.

Repository hygiene (detected): tests yes, CI yes (GitHub Actions), Dockerfile yes, licence yes, lockfile no, committed secrets YES (several .backlog/hooks/pre-commit-secrets.sh, src/flowspec_cli/security/... files contain secret‑shaped paths).

The Bottom Line

flowspec delivers a structured, agent‑driven workflow for spec‑driven development and backlog tracking, with solid CI/Docker scaffolding. The code base is large and contains several high‑impact maintainability problems (deep nesting, duplicated logic, oversized files) and security hygiene gaps (missing lockfile, unpinned Actions, committed secrets). Teams comfortable with AI‑augmented SDLC and willing to invest in refactoring and CI hardening will get the most value; organisations requiring out‑of‑the‑box security and reproducible builds should address the audit items before production use.