Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/8BitTacoSupreme/flowstate/llms.txt

Use this file to discover all available pages before exploring further.

FlowState is a CLI-first orchestrator that bridges the gap between raw project ideas and productive Claude Code sessions. Rather than dropping you into an agentic loop cold, FlowState runs a structured five-step pipeline — generating context files, conducting targeted research, pressure-testing your strategy, wiring up GSD project management, and auditing your repo discipline — before handing off to native Claude Code tools for execution.

​
The Problem FlowState Solves

Agentic development tools like Claude Code are powerful, but they’re only as good as the context they’re given. Without structured project context, research grounding, and a coherent strategy, long-running agents tend to drift, repeat work, or miss critical constraints. FlowState solves this by acting as a context preparation layer: it gathers your goals through an intake interview, runs targeted LLM calls to build research and strategy artifacts, and writes the structured files that downstream tools (Claude Code, GSD, and others) need to perform well.

​
The Four Pillars

FlowState unifies four distinct approaches to agentic development into a single pipeline:
  • Autoresearch-style Research — Inspired by Andrej Karpathy’s iterative experiment loop, FlowState’s research adapter splits your topic into focused subtopics and runs individual claude --print calls per topic, merging the results into a consolidated research/report.md. This keeps each call short and targeted rather than issuing one broad, shallow query.
  • Gstack-style Strategy Pressure-Test — Inspired by Garry Tan’s /office-hours slash command, FlowState’s strategy adapter issues a single advisor-style claude --print call that systematically challenges your approach, surfaces risks, and writes findings to research/strategy.md. No Gstack installation required.
  • GSD Project Management — FlowState generates the PROJECT.md and ROADMAP.md context files that GSD (Get Shit Done) consumes, and provides flowstate launch gsd <N> to hand off phase execution to native GSD slash commands inside a Claude Code session.
  • Superpowers-style Discipline Audit — Inspired by Jesse Vincent’s Claude Code Superpowers plugin, FlowState’s discipline module performs a pure-Python audit of your git repository, test configuration, and git hooks — no LLM required, sub-second execution.

​
The Five-Step Pipeline

Every flowstate init run executes these five steps in order:
StepRoleWhat Happens
Context GenerationSetupWrites PROJECT.md, ROADMAP.md, CLAUDE.md, config.json, and research/brief.md deterministically in under 1 second
ResearchIntelligenceSplits topics and runs focused claude --print calls (~30s/topic), producing research/report.md
StrategyStrategyRuns a single pressure-test claude --print call (~75s), producing research/strategy.md
GSD ManagementManagementWrites context files for GSD skills; phases run natively via flowstate launch gsd <N>
Discipline AuditAuditPure Python audit of git repo, test config, and hooks — no LLM needed

​
Architecture

FlowState is organized into three distinct layers backed by a persistent state machine: 
┌──────────────────────────────────────────────────┐
│                   flowstate CLI                   │
│  init · status · launch · context · memory · check│
└─────────────────────┬────────────────────────────┘
                      │
┌─────────────────────▼────────────────────────────┐
│                 Orchestrator                       │
│   5-step pipeline with state persistence           │
│   EventBus emits StepCompleted / StepFailed        │
└──┬──────────┬──────────┬──────────┬──────────┬───┘
   │          │          │          │          │
   ▼          ▼          ▼          ▼          ▼
Context    Research   Strategy    GSD      Discipline
Generator  Adapter    Adapter   Adapter     Audit
(Python)   (bridge)   (bridge)  (context)  (Python)
   │          │          │          │          │
   ▼          ▼          ▼          ▼          ▼
 5 files   claude     claude    .planning/  git/test
 written   --print    --print   files       checks
                      │
              ┌───────▼────────┐
              │  MemoryStore   │
              │  (SQLite FTS5) │
              │  memory.db     │
              └────────────────┘

​
The Three Layers

Layer 1 — Context Generator (context.py): Pure Python templates that transform interview answers into the files upstream tools consume. No LLM calls, no timeouts, fully testable. This layer completes in under one second regardless of project size. Layer 2 — Targeted LLM Calls (research.py, strategy.py): FlowState uses claude --print for exactly two operations where LLM reasoning adds real value — split-topic research (~30s per topic) and a single strategy pressure-test (~75s). Each call is scoped with a system prompt, allowed tools, and a max-turns bound to keep costs predictable. Layer 3 — Session Launcher (launcher.py): flowstate launch prints the exact commands needed to run GSD phases natively inside Claude Code sessions, where the slash commands actually work. FlowState itself never tries to replicate Claude Code’s execution environment.

​
State and Memory

All pipeline state is persisted to flowstate.json — a Pydantic-validated file tracking each tool’s status (Ready, Running, Completed, Blocked), artifact paths, context files, and user preferences. If a tool fails mid-pipeline, it’s marked BLOCKED and the pipeline continues with the remaining steps. Research findings, strategy decisions, and failure context are stored in memory.db — a SQLite FTS5 database with porter-stemmed full-text search. On each subsequent run, relevant prior knowledge is automatically injected into bridge prompts so research compounds over time.

​
Prerequisites

Before installing FlowState, ensure you have the following:
  • Flox (recommended) — handles Python, Node, Claude Code CLI, and MCP server setup automatically
  • Python 3.12+ — required for the FlowState package itself
  • Claude Code CLI v2.0+ — used for all claude --print bridge calls; see the install guide
  • GSD (optional) — required only for the Management phase; see github.com/gsd-build/gsd-2
Claude Code requires an active Anthropic account. Use of the claude CLI is subject to Anthropic’s Commercial Terms of Service.

​
Next Steps

Installation

Install FlowState with Flox for a fully reproducible environment, or manually with pip and a Python venv.

Quickstart

Run FlowState for the first time, answer the intake interview, and launch your first agentic pipeline in under five minutes.

Build docs developers (and LLMs) love

Get started for freeTalk to us