Install

npx flow-cc

One command. Installs skills, hooks, templates, and configures your statusLine. Works on Mac, Linux, and Windows.

Why Flow?

Claude Code is powerful but unstructured. Without a system, you lose context between sessions, repeat mistakes, and waste tokens re-explaining what you've already decided.

Flow gives Claude Code a memory system and execution framework:

• Spec interviews extract decisions upfront so agents execute instead of guessing
• Per-project PRDs in .planning/prds/ become execution contracts — spec future projects in parallel
• Wave-based agent teams execute milestones autonomously with built-in verification
• Session handoffs preserve full context across fresh sessions — no more "where was I?"
• Lessons compound — mistakes get captured, refined, and promoted into permanent rules

How It Works

One-time setup, then a repeating build cycle:

/flow:setup  →  /flow:triage  →  /flow:spec  →  /flow:go  →  /flow:done
  (once)          (intake)         (plan)         (build)       (wrap)

1. /flow:setup — Scaffolds your project with planning docs and execution rules
2. /flow:spec — Interviews you, then writes an executable PRD with milestones, acceptance criteria, and agent-team structure
3. /flow:go — Spawns parallel agent teams to build the next milestone, verifies, commits
4. /flow:done — Updates docs, captures lessons, generates a handoff prompt so the next session starts instantly

Run /flow:go repeatedly until all milestones are done, then /flow:done to wrap up. Next session, paste the handoff prompt and keep going.

Multi-PRD: Parallel Project Planning

Before (single PRD)

project/
└── PRD.md          ← one at a time

Finish or archive the current project before speccing the next. Serial bottleneck on large roadmaps.

Now (per-project PRDs)

.planning/prds/
├── user-auth.md          ← active
├── dashboard.md          ← pre-specced
└── payments.md           ← pre-specced

Spec any project at any time. Execute the current one while planning ahead.

How it works:

• /flow:spec writes PRDs to .planning/prds/{slug}.md — one file per project
• /flow:spec Payments targets a specific future project without changing your current position
• PRD resolution matches the current git branch against each PRD's **Branch:** header — STATE.md "Active PRD" is fallback
• Smart resolution: user argument > STATE.md > slug derivation > legacy fallback
• Existing PRD.md at root? Still works — legacy files are consumed transparently and migrated on archive

Commands

The Build Cycle

| Command | When | What it does | |---|---|---| | /flow:setup | Once per project | Creates .planning/, CLAUDE.md, templates, full roadmap | | /flow:spec | Once per project | Interview that produces an executable PRD in .planning/prds/ | | /flow:go | Once per milestone | Executes the next milestone with wave-based agent teams | | /flow:done | End of session | Updates docs, captures lessons, generates handoff prompt |

Standalone

| Command | When | What it does | |---|---|---| | /flow:task | Anytime | Bug fixes, cleanup, small features — no PRD needed | | /flow:triage | Anytime | Brain dump → categorized Linear issues, milestones, ROADMAP entries, lessons |

Utility

| Command | When | What it does | |---|---|---| | /flow:intro | First time | Walkthrough of the entire system | | /flow:status | Anytime | Where am I? What's next? Shows PRD inventory | | /flow:update | Anytime | Update Flow to the latest version |

Project Structure

Every Flow project gets this structure via /flow:setup:

your-project/
├── CLAUDE.md                    # Execution rules + learned rules
├── .claude/
│   └── memory/
│       └── session-{branch}.md  # Per-branch session state (gitignored)
├── .planning/
│   ├── STATE.md                 # Project-level GPS — shared across developers
│   ├── ROADMAP.md               # Project milestones and progress tracking
│   ├── prds/                    # Per-project PRD specs
│   │   ├── user-auth.md         #   One file per project
│   │   └── dashboard.md         #   Pre-spec future projects anytime
│   └── archive/                 # Completed projects and archived PRDs
└── tasks/
    └── lessons.md               # Active lessons (max 10) → promoted to CLAUDE.md

What Gets Installed

~/.claude/
├── commands/flow/
│   ├── flow-setup.md            # 9 skill files
│   ├── flow-spec.md
│   ├── flow-go.md
│   ├── flow-task.md
│   ├── flow-done.md
│   ├── flow-status.md
│   ├── flow-intro.md
│   ├── flow-triage.md
│   ├── flow-update.md
│   ├── VERSION
│   └── templates/               # Project scaffolding templates
│       ├── CLAUDE.md.template
│       ├── STATE.md.template
│       ├── ROADMAP.md.template
│       ├── lessons.md.template
│       └── session.md.template
├── hooks/
│   ├── flow-check-update.js     # Notifies when updates are available
│   └── flow-statusline.js       # Shows project context in statusLine
└── settings.json                # statusLine configured automatically

The Lessons System

Flow's knowledge compounding is what makes it get better over time:

1. Capture — Mistake happens, one-liner written to tasks/lessons.md (max 10 active)
2. Promote — When full, most battle-tested lesson moves to CLAUDE.md ## Learned Rules (max 15 permanent)

Hard caps prevent context bloat. Total worst-case: ~30 lines of lessons context per session.

Multi-Developer Support

Flow supports multiple developers on the same repo without conflicts:

• Branch-scoped sessions — Each branch gets its own session file at .claude/memory/session-{branch-slug}.md (gitignored). Multiple terminals on different branches never conflict. Same-branch conflicts are prevented by Linear assignment (one dev per issue/branch).
• Branch-based PRD resolution — Skills match the current git branch against each PRD's **Branch:** header to find the active PRD. STATE.md "Active PRD" is fallback.
• Cross-developer awareness — /flow:status shows all active sessions across branches. /flow:go warns if another developer was recently active on the same branch.
• STATE.md — Shared project-level state in .planning/STATE.md. Updated at project boundaries only (not every session), so conflicts are rare.

Linear Integration

Flow optionally integrates with Linear via MCP for issue tracking:

• /flow:spec can create Linear issues automatically from PRD milestones
• /flow:done can post progress comments to Linear issues
• /flow:triage sorts unstructured brain dumps into categorized Linear issues, ROADMAP entries, and lessons
• Branch convention feat/msig-{issue#}-desc auto-links PRs to Linear issues
• Auto-close — Closes MSIG-XX in PR body triggers Linear status transition on merge

Requires the Linear MCP server to be configured.

Compatible With GSD

Flow uses the same .planning/ directory structure as GSD. You can use /gsd:debug, /gsd:map-codebase, and other GSD commands alongside Flow without conflict.

Requirements

Claude Code CLI with skills support.

Links

• Changelog — what changed in each version
• Contributing — how to report bugs, suggest features, submit PRs
• Design — architecture decisions and system design

License

MIT