Iterative Design-Driven Development where humans drive, AI executes.

You make the decisions. AI implements within your framework. Context is never lost.

Flow is not AI autopilot. It's human-in-loop development that leverages AI as an execution engine, not a decision maker.

The human drives. The AI executes.

Traditional AI development: You prompt → Wait → Hope it works → Refactor when it doesn't.

Flow development: You design → AI implements → You verify → Iterate with preserved context.

Building with AI often fails because:

• AI decides architecture (leads to refactoring hell)
• Context disappears between sessions (AI forgets your design)
• No iteration structure (everything is a rewrite)
• Decisions lack rationale (why did we choose this?)

Flow fixes this by putting you in control:

You Brainstorm → Document Decisions → AI Implements → You Verify → Next Iteration

Everything lives in .flow/PLAN.md - your design, your decisions, your rationale. The AI reads it, follows it, and never loses context.

👤 You (Human):

• Design the architecture
• Make technical decisions
• Define iterations
• Document rationale
• Verify implementations

🤖 AI:

• Reads your framework
• Follows your patterns
• Implements your decisions
• Asks when unclear
• Never decides architecture

Flow separates your workspace from AI reference files:

your-project/
├── .claude/commands/        # 25 slash commands (AI helpers)
│   ├── flow-blueprint.md
│   ├── flow-brainstorm-start.md
│   └── ...
│
└── .flow/
    ├── 👤 YOUR WORKSPACE (you own these)
    │   ├── PLAN.md          # Your design document
    │   ├── DASHBOARD.md     # Your progress tracker
    │   └── phase-*/task-*.md # Your detailed iterations
    │
    └── 🤖 AI REFERENCE (read-only templates)
        └── framework/
            ├── DEVELOPMENT_FRAMEWORK.md  # Complete methodology
            ├── SLASH_COMMANDS.md         # Command definitions
            └── examples/                 # Reference examples

Key principle: You control .flow/PLAN.md and task files. AI reads framework/ for patterns but never decides your architecture.

cd /path/to/your/project

# Download and run
curl -O https://raw.githubusercontent.com/khgs2411/flow/master/flow.sh
chmod +x flow.sh && ./flow.sh

# Rerun to update
curl -O https://raw.githubusercontent.com/khgs2411/flow/master/flow.sh
chmod +x flow.sh && ./flow.sh --force

For new features:

/flow-blueprint "Real-time chat with WebSocket, Redis pub/sub, and message history"

AI generates structured plan. You review and adjust the architecture.

/flow-brainstorm-start "WebSocket vs SSE, Redis pub/sub architecture, message persistence strategy"

AI presents decision points. You discuss and decide together.

/flow-implement-start

AI codes based on your documented decisions, not its assumptions.

/flow-blueprint "Payment Gateway Integration"

• You define requirements
• You set constraints
• You outline phases
• AI structures the plan

/flow-brainstorm-start "Payment flow, webhook security, retry strategy"
/flow-next-subject  # Discuss each decision point

AI presents options, you choose:

### Subject: Payment Flow Architecture ✅

**Decision**: Two-phase commit (reserve → capture)

**Rationale** (YOUR reasoning):

- Prevents double-charging on network failures
- Enables fraud checks between reserve and capture
- Industry standard (Amazon, Shopify)

**Action Items** (for AI to implement):

- [ ] Create PaymentIntent on checkout
- [ ] Implement reserve endpoint
- [ ] Implement capture endpoint

/flow-implement-start

AI implements your design decisions, following action items from brainstorming.

/flow-implement-complete

You verify the implementation matches your design.

"Build the skeleton first, then add flesh." — Flow Framework

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

Why this works: You validate the architecture before adding complexity. No big-bang rewrites.

PHASE (Testing, Implementation, Deployment)
  └── TASK (User Auth, API Layer)
      └── ITERATION (Skeleton, Error Handling)
          ├── BRAINSTORM (Design decisions)
          └── IMPLEMENTATION (Coding)

• ⏳ PENDING - Not started
• 🚧 IN PROGRESS - Working now
• 🎨 READY - Design complete, ready to code
• ✅ COMPLETE - Done and verified

Problem: AI forgets your design between sessions.

Solution: Everything in .flow/PLAN.md. Any AI (or human) can resume instantly.

Problem: Code shows WHAT, not WHY.

Solution: Every decision documented with reasoning during brainstorming.

**Decision**: Use PostgreSQL, not MongoDB

**Rationale**:

- Strong ACID guarantees for financial data
- Better complex query support for reporting
- Team has 5 years PostgreSQL experience

Problem: Refactoring discovered mid-implementation derails work.

Solution: Identify blockers during brainstorming, handle BEFORE coding.

### Pre-Implementation Tasks

#### Task 1: Refactor Legacy Payment Module

**Why**: Current code tightly coupled to Stripe
**What**: Extract PaymentProvider interface

- [ ] Create interface
- [ ] Implement StripeProvider
- [ ] Update controllers

Flow provides 25 slash commands for AI-assisted workflow:

Planning (3): /flow-blueprint, /flow-migrate, /flow-plan-update

Structure (9): /flow-phase-*, /flow-task-*, /flow-iteration-*

Brainstorming (5): /flow-brainstorm-start, /flow-next-subject, /flow-brainstorm-complete, etc.

Implementation (2): /flow-implement-start, /flow-implement-complete

Navigation (6): /flow-status, /flow-next, /flow-summarize, /flow-verify-plan, etc.

See SLASH_COMMANDS.md for full reference.

The methodology is framework-agnostic. You can use Flow principles with any AI (ChatGPT, Gemini, etc.).

First, get the framework reference files:

Option 1: Clone the repository (recommended)

git clone https://github.com/khgs2411/flow.git ~/flow-framework

Option 2: Download framework folder only

# Download the framework directory
curl -L https://github.com/khgs2411/flow/archive/refs/heads/master.zip -o flow.zip
unzip flow.zip "flow-master/framework/*"
mv flow-master/framework ~/flow-framework
rm -rf flow-master flow.zip

1. Use ~/flow-framework/examples/PLAN.md as a template
2. Follow Phase → Task → Iteration hierarchy
3. Use status markers (⏳ 🚧 ✅)
4. Document decisions with rationale
5. Reference ~/flow-framework/SLASH_COMMANDS.md for command patterns

Example ChatGPT prompt:

I'm using the Flow Framework for iterative development.

Please read ~/flow-framework/SLASH_COMMANDS.md and find
the /flow-brainstorm-start command instructions.

Follow those instructions to help me brainstorm
"WebSocket architecture decisions" for my project.

The AI will follow Flow patterns manually without slash command integration.

Building a payment gateway:

1. You design (via /flow-blueprint):

## Phase 1: Core Payment Flow

### Task 1: Stripe Integration

- Iteration 1: Basic charge flow (skeleton)
- Iteration 2: Error handling (veins)
- Iteration 3: Webhooks (flesh)

2. You brainstorm (via /flow-brainstorm-start):

### Subject: Charge Flow Architecture ✅

**Decision**: Two-phase commit (reserve → capture)

**Rationale** (you decide):

- Prevents double-charging
- Enables fraud checks
- Industry standard

**Action Items** (AI implements):

- [ ] PaymentIntent API integration
- [ ] Reserve endpoint
- [ ] Capture endpoint

3. AI implements your design:

/flow-implement-start

AI creates the code following YOUR documented decisions.

4. You verify:

/flow-implement-complete

Confirm implementation matches your design.

Flow's unique value: Human-driven design + AI-powered execution + mandatory context preservation.

1. flow.sh (~150KB)

   • Self-contained deployment script
   • All framework content embedded (no external dependencies)
   • This is what users download

2. framework/ (source files)

   • DEVELOPMENT_FRAMEWORK.md - Complete methodology (3,900 lines)
   • SLASH_COMMANDS.md - All command definitions
   • examples/ - Reference examples

3. Build system

   • build-standalone.sh - Generates flow.sh from sources
   • Embeds framework docs via heredocs

See CONTRIBUTING.md for detailed guide.

Quick start:

# Edit framework source
vim framework/DEVELOPMENT_FRAMEWORK.md

# Rebuild distribution
./build-standalone.sh

# Test
cd /test-project && ~/flow/flow.sh --force

• 📖 Methodology: DEVELOPMENT_FRAMEWORK.md
• 📝 Examples: framework/examples/
• ⚙️ Commands: SLASH_COMMANDS.md
• 🤝 Contributing: CONTRIBUTING.md
• 🐛 Issues: GitHub Issues

Created by: Liad Goren

Philosophy: Domain-Driven Design + Agile + Extreme Programming

AI Partner: Claude (Anthropic)

Inspired by: Real-world AI-assisted development on complex RPG systems, revealing what actually works when humans and AI collaborate.

MIT License - Free for personal and commercial use.