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’s full pipeline — context generation, research, strategy, GSD management setup, and discipline audit — runs from a single flowstate init command. This guide walks you through installation, the intake interview, watching the pipeline run, and reviewing the output files that prepare your project for agentic development.
1

Install FlowState

The fastest path is Flox, which handles Python, Node, Claude Code CLI, and MCP servers in one command:
git clone https://github.com/8BitTacoSupreme/flowstate.git
cd flowstate
flox activate
Alternatively, install manually with pip:
git clone https://github.com/8BitTacoSupreme/flowstate.git
cd flowstate
python3.12 -m venv .venv
source .venv/bin/activate
pip install -e .
See the Installation guide for full details on both options.
2

Verify the Bridge

Before running the pipeline, confirm that FlowState can find the claude CLI:
flowstate check
You should see:
claude CLI found: /Users/you/.local/bin/claude
Timeout: 300s | Max turns: 10
If the binary is not found, install Claude Code or set the FLOWSTATE_CLAUDE_BIN environment variable to your binary’s path. See Installation → Environment Variables for details.
You can test the entire pipeline without making any real Claude CLI calls by passing --dry-run to flowstate init. This is useful for verifying your setup before incurring any API usage.
flowstate init --dry-run
3

Initialize Your Project

Run the pipeline from your project’s root directory:
flowstate init
FlowState opens with its ASCII banner, then starts the intake interview. You’ll be prompted for the following fields:
PromptWhat to enter
research_focusThe primary topic or domain to research
core_problemThe specific problem you’re solving
ten_x_visionWhat a 10× outcome looks like
milestonesKey delivery milestones (comma-separated)
test_coverageYour target test coverage percentage
architecture_patternPreferred architectural pattern (e.g., hexagonal, layered)
project_nameA short name for your project
Your answers are persisted to flowstate.json immediately after the interview completes. If you need to re-run the pipeline with the same answers — for example after modifying source files — skip the interview entirely:
flowstate init --skip-interview
Use --skip-interview on subsequent runs to reuse your existing answers without being prompted again. FlowState loads the saved state from flowstate.json and proceeds directly to the pipeline.
4

Watch the Pipeline Run

After the interview, FlowState executes all five steps and reports progress as each completes. A successful run looks like this:
[1/5] Context Generation ... done  (<1s)
[2/5] Research           ... done  (~30s per topic)
[3/5] Strategy           ... done  (~75s)
[4/5] GSD Management     ... done  (<1s)
[5/5] Discipline Audit   ... done  (<1s)
Each step’s result is persisted to flowstate.json after it completes. If a step fails, it is marked BLOCKED and the pipeline continues with the remaining steps — partial results are never discarded.At the end of the run, FlowState prints a summary listing all created files and suggested next-step commands.
Use --dry-run to simulate the full pipeline without any real claude --print calls. This completes in under two seconds and is ideal for testing your interview answers and context file output before committing to a live run.
flowstate init --dry-run
5

Check Pipeline Status

At any time after flowstate init, you can inspect the state of each pipeline step:
flowstate status
FlowState renders a Rich table showing each tool’s phase, status, and artifact paths:
┌──────────────────────────────────────────────────────┐
│                   FlowState Status                    │
├──────────────┬──────────────┬───────────┬────────────┤
│ Tool         │ Phase        │ Status    │ Artifacts  │
├──────────────┼──────────────┼───────────┼────────────┤
│ research     │ Research     │ completed │ research/… │
│ strategy     │ Strategy     │ completed │ research/… │
│ gsd          │ Management   │ completed │ .planning… │
│ discipline   │ Discipline   │ completed │ ---        │
└──────────────┴──────────────┴───────────┴────────────┘
Possible statuses are Ready, Running, Completed, and Blocked. A Blocked status means the step encountered an error; the error context is automatically stored in memory.db for injection into the next run.
6

Launch a GSD Phase

With context files written and research complete, you’re ready to run GSD phases natively inside Claude Code. Use flowstate launch to get the exact command:
flowstate launch gsd 1
FlowState prints the native Claude Code command to execute:
Launch command:

  cd /path/to/project && claude
  /gsd:plan-phase 1
GSD slash commands run inside an active Claude Code session where they have access to the full tool environment. FlowState’s role is to prepare the context; execution always happens in Claude Code natively.

​
What Was Created

A successful flowstate init run writes five context files that downstream tools consume:
FileConsumerContent
.planning/PROJECT.mdGSDVision, problem statement, constraints, and requirements
.planning/ROADMAP.mdGSDPhases derived from your milestones with acceptance criteria
.planning/config.jsonGSDWorkflow preferences (mode, granularity)
.claude/CLAUDE.mdAll toolsProject context, active tools, and current phase
research/brief.mdResearch adapterStructured research questions derived from your interview answers
After the Research and Strategy steps complete, two additional files are written:
  • research/report.md — Merged findings from all split-topic claude --print research calls
  • research/strategy.md — Output from the single strategy pressure-test call
All pipeline state is tracked in flowstate.json (Pydantic-validated, gitignored by default). Research findings and strategy decisions accumulate in memory.db and are automatically injected as prior knowledge into future pipeline runs.

Build docs developers (and LLMs) love

Get started for freeTalk to us