GitHub - SoundBlaster/Flow: Agentic Workflow

Flow — Agentic Workflow Framework

Version: 1.4.0

Flow is a documentation-driven agentic workflow framework for software development.

Overview

Flow mimics real-world software development through a linear, step-by-step execution of commands. Each command is a prompt that guides AI agents (and humans) through a structured workflow.

BRANCH → SELECT → PLAN → EXECUTE → ARCHIVE → REVIEW → FOLLOW-UP → ARCHIVE-REVIEW
   ↓        ↓       ↓        ↓         ↓         ↓          ↓             ↓
 COMMIT   COMMIT  COMMIT   COMMIT    COMMIT    COMMIT     COMMIT        COMMIT

Philosophy

Method over implementation — Flow defines the process, not the code
Linear execution — Step-by-step workflow without skipping phases
Documentation-driven — PRDs and specs are first-class artifacts
Source of Truth — SPECS/Workplan.md tracks all tasks
Language-agnostic — Works with any tech stack via .flow/params.yaml

Quick Start

1. Install Flow

# Clone Flow, then run the installer pointing at your repo
./install.sh /path/to/your/repo

# Or from inside your repo
/path/to/flow/install.sh

The installer copies the SPECS/COMMANDS/ and SPECS/ROLES/ folders managed by Flow, then creates SPECS/Workplan.md, SPECS/ARCHIVE/INDEX.md, and SPECS/INPROGRESS/next.md from templates — skipping any user-owned files that already exist.

Production Default: Pinned + Verified Bootstrap

For working repositories, treat Flow as a tooling dependency. Pin a release tag and verify checksums before install.

Reference bootstrap script:

bash docs/flow-bootstrap.sh .

Script contract (docs/flow-bootstrap.sh):

Reads FLOW_VERSION (default pinned value)
Reads FLOW_REPO (defaults to SoundBlaster/Flow)
Downloads flow-${FLOW_VERSION}-minimal.zip and SHA256SUMS from the same release
Fails hard on missing assets or checksum mismatch
Installs only after verification passes

Typical wrapper target in consumer repos:

flow-install:
  @FLOW_VERSION?=v1.4.0 bash tools/flow-bootstrap.sh

2. Configure for Your Project

# Create and fill in your project config
mkdir -p .flow
# See SPECS/COMMANDS/SETUP.md for the full template

# .flow/params.yaml
project:
  name: MyProject
  default_branch: main

verify:
  tests: npm test
  lint: npm run lint
  coverage_threshold: 80

3. Add Your Tasks

edit SPECS/Workplan.md    # Replace example tasks with yours

4. Run the Workflow

Follow the steps in SPECS/COMMANDS/FLOW.md:

BRANCH — Create a feature branch for the task
SELECT — Choose the next task from the workplan
PLAN — Create the implementation PRD
EXECUTE — Implement with quality gates
ARCHIVE — Move completed work to archive
REVIEW — Review and capture findings
FOLLOW-UP — Add remediation tasks when review finds issues
ARCHIVE-REVIEW — Archive the review report

Structure

.flow/
└── params.yaml                  # Your project config (survives Flow updates)

SPECS/
├── Workplan.md                  # Your task tracker        ← user data
├── ARCHIVE/                     # Completed PRDs           ← user data
│   ├── INDEX.md
│   └── {TASK_ID}_{TASK_NAME}/
│       ├── {TASK_ID}_{TASK_NAME}.md
│       └── {TASK_ID}_Validation_Report.md
├── INPROGRESS/                  # Active tasks             ← user data
│   ├── next.md
│   └── {TASK_ID}_{TASK_NAME}.md
├── COMMANDS/                    # ← managed by Flow, updated by installs
│   ├── FLOW.md
│   ├── SETUP.md
│   ├── SELECT.md
│   ├── PLAN.md
│   ├── EXECUTE.md
│   ├── ARCHIVE.md
│   ├── REVIEW.md
│   └── PRIMITIVES/
└── ROLES/                       # ← role prompts managed by Flow
    ├── Architect.md
    ├── Plan.md
    ├── Mentor.md
    ├── TDD_Executor.md
    └── TDD_Executor_xml.md

templates/                           # Install-time scaffolding (not copied to user repos)
├── Workplan_Example.md          # → SPECS/Workplan.md on first install
├── Archive_Index_Example.md     # → SPECS/ARCHIVE/INDEX.md on first install
└── next_example.md              # → SPECS/INPROGRESS/next.md on first install

Configuration

Flow reads project-specific values from .flow/params.yaml at the repo root:

Section	Purpose	Used By
`project.*`	Project name, language, default branch	all commands
`verify.*`	Test, lint, format, coverage commands	EXECUTE
`nfrs.*`	Performance budgets	REVIEW
`structure.*`	Key directory paths	EXECUTE, ARCHIVE

Commands reference it as [Params](.flow/params.yaml). See SPECS/COMMANDS/SETUP.md for the full template.

Updating Flow

# Run the installer again — Flow-managed SPECS folders are refreshed
./install.sh /path/to/your/repo

# SPECS/COMMANDS/ and SPECS/ROLES/ are updated; your workplan, archive, and .flow/params.yaml are never touched

Security Notes

Release assets include SHA256SUMS for integrity verification.
Bootstrap verification is mandatory: mismatches must stop installation.
This avoids silent corruption/tampering and makes CI behavior deterministic.

Commands

Command	Purpose
SETUP	Create `.flow/params.yaml` for your project
SELECT	Pick the next task from the workplan
PLAN	Write the implementation PRD
EXECUTE	Run implementation with quality gates
ARCHIVE	Move completed tasks to archive
REVIEW	Structured code review
FOLLOW-UP	Create tasks from review findings

Language Support

Flow works with any language — configure your toolchain in .flow/params.yaml under verify.*:

Language	Tests	Lint
JavaScript/TypeScript	`npm test`	`npm run lint`
Python	`pytest`	`ruff check src/`
Rust	`cargo test`	`cargo clippy`
Go	`go test ./...`	`golangci-lint run`
Swift	`swift test`	`swiftlint`

Current State Tracking

Active task: SPECS/INPROGRESS/next.md
Task PRD: SPECS/INPROGRESS/{TASK_ID}_{NAME}.md
Archive: SPECS/ARCHIVE/{TASK_ID}_{NAME}/
Workplan: SPECS/Workplan.md

Documentation

SPECS/COMMANDS/FLOW.md — Workflow reference
SPECS/COMMANDS/SETUP.md — Configuration guide
SPECS/COMMANDS/README.md — Commands overview
docs/flow-bootstrap.sh — Reference secure bootstrap script for consumer repos
docs/Flow_Dependency.md — Tooling dependency contract and update pattern