Flow — Agentic Workflow Framework

Version: 1.5.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 updates Flow-managed SPECS/COMMANDS/ and SPECS/ROLES/, installs shipped Codex assets (.agents/skills/flow-*, plugins/flow), and creates SPECS/Workplan.md, SPECS/ARCHIVE/INDEX.md, and SPECS/INPROGRESS/next.md from templates when missing.

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.5.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.yamlproject:
name: MyProjectdefault_branch: mainverify:
tests: npm testlint: npm run lintcoverage_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:

1. BRANCH — Create a feature branch for the task
2. SELECT — Choose the next task from the workplan
3. PLAN — Create the implementation PRD
4. EXECUTE — Implement with quality gates
5. ARCHIVE — Move completed work to archive
6. REVIEW — Review and capture findings
7. FOLLOW-UP — Add remediation tasks when review finds issues
8. 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/, SPECS/ROLES/, .agents/skills/flow-*, and plugins/flow are updated.# User-owned planning files remain untouched.

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

License

MIT License — Copyright (c) 2026 Egor Merkushev