Flow Framework
Iterative Design-Driven Development where humans drive, AI executes.
You make the decisions. AI implements within your framework. Context is never lost.
Table of Contents
- Philosophy
- Installation
- Core Workflow
- The Iteration Structure
- Core Principles
- File Structure
- Example Session
- Why Flow Works
- Key Features
- Common Use Cases
- Documentation
- Contributing
- Support
Philosophy
Flow is human-in-loop development that leverages AI as an execution engine, not a decision maker.
The human drives. The AI executes.
Traditional AI: You prompt → Wait → Hope → Refactor when it fails → Lose context between sessions.
Flow: You design → AI implements → You verify → Iterate with preserved context.
Installation
Option 1: Claude Code Plugin (Recommended)
# Add Flow marketplace
/plugin marketplace add khgs2411/flow
# Install plugin
/plugin install flow@topsyde-utils
Option 2: Standalone Script
# Download and run in your project
curl -O https://raw.githubusercontent.com/khgs2411/flow/master/flow.sh
chmod +x flow.sh
./flow.sh
Both methods install:
- 28 slash commands in
.claude/commands/(AI workflow helpers) - 8 agent skills in
.claude/skills/(specialized AI assistants) - Framework reference in
.flow/framework/(methodology guide) - Examples in
.flow/framework/examples/(templates)
Core Workflow
Flow follows a simple loop:
1. Install → flow.sh or plugin
2. Blueprint → /flow-blueprint (create project structure)
3. Start Phase/Task → /flow-phase-start or /flow-task-start
4. Iterate:
a. Brainstorm → /flow-brainstorm-start
→ /flow-brainstorm-review
→ /flow-brainstorm-complete
OR
b. Implement → /flow-implement-start (skip brainstorming)
5. Complete → /flow-implement-complete
6. Finish Task → /flow-task-complete (when all iterations done)
7. Finish Phase → /flow-phase-complete (when all tasks done)
Management Commands
At any point, you can:
- Add structure:
/flow-phase-add,/flow-task-add,/flow-iteration-add - Check status:
/flow-status,/flow-next,/flow-summarize - Manage scope:
/flow-backlog-add,/flow-backlog-view,/flow-backlog-pull - Archive work:
/flow-plan-split,/flow-compact - Verify accuracy:
/flow-verify-plan
The Iteration Structure
"Build the skeleton first, then add flesh." — Flow Framework
Progressive Refinement
Flow uses a body-building metaphor for iterations:
- V1 - Skeleton: Basic structure, happy path only
- V2 - Veins: Core data flow, error handling
- V3 - Flesh: Edge cases, optimization
- V4 - Fibers: Polish, performance tuning
Each iteration follows the same pattern: brainstorm → implement → complete.
Core Principles
1. Human-in-Loop Decision Making
You control architecture. AI executes within your framework.
- Humans make design decisions
- AI implements according to those decisions
- Every decision is documented with rationale
- Context never lost between sessions
2. Progressive Iteration
Build incrementally with clear scope boundaries.
- Break work into small, manageable iterations
- Each iteration: one focused goal
- Brainstorm before implementing (or skip if trivial)
- Complete one iteration before starting next
3. Separation of Concerns
Dashboard (progress) vs Plan (architecture) vs Tasks (work).
.flow/
├── DASHBOARD.md → Single source of truth for current work
├── PLAN.md → Static architecture, testing, constraints
└── phase-N/task-M.md → Detailed iterations with action items
- DASHBOARD.md: Where am I? What's next? Progress overview.
- PLAN.md: High-level architecture, testing strategy, DO/DON'Ts.
- Task files: Brainstorming, action items, implementation notes.
4. Scope Boundary Enforcement
If you discover NEW work outside current scope: STOP and DISCUSS.
Flow enforces scope boundaries:
- AI stops when discovering unplanned work
- User decides: handle now, defer, or create new iteration
- No surprise scope creep
- Explicit user approval required
5. Flexible Structure Management
Add, remove, archive, defer work as project evolves.
- Add phases/tasks/iterations dynamically
- Move work to backlog when priorities shift
- Archive completed phases to reduce noise
- Pull backlog items when ready