topsyde-utils

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

---

File Structure