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 init is the main entrypoint for FlowState. It walks you through a short intake interview, then runs the full five-step pipeline: deterministic context file generation, split-topic LLM research, a strategic pressure-test call, GSD management context setup, and a pure-Python discipline audit of your project’s git and test configuration. State is persisted to flowstate.json after every step so interrupted runs can resume cleanly.
Synopsis
Options
Simulate tool execution without calling real CLIs. All pipeline steps run and produce output, but no
claude subprocess is spawned. Useful for testing setup or CI.Project root directory. All context files and state are written relative to this path.
Skip the intake interview and use existing answers from
flowstate.json. Use this to re-run the pipeline after manually editing your state file.Claude model to use for bridge calls. Accepts short names passed directly to the
claude CLI (e.g., sonnet, opus, haiku).Maximum spend per bridge call in USD. Passed to the
claude CLI as --max-budget-usd. Example: 0.50.Effort level hint for the
claude CLI. Accepted values depend on your Claude Code version (e.g., low, medium, high).Interview prompts
When--skip-interview is not set, flowstate init opens an interactive intake interview divided into four sections:
| Section | Field | Prompt |
|---|---|---|
| Intelligence | research_focus | What specific libraries, APIs, or edge cases should we research before starting? |
| Strategy | core_problem | What is the core user problem we are solving? |
| Strategy | ten_x_vision | What does the 10x version of this look like? |
| Management | milestones | What are the three most critical milestones for this phase? (comma-separated) |
| Discipline | test_coverage | Required test coverage percentage? |
| Discipline | architecture_pattern | Architectural pattern to follow? (e.g., hexagonal, event-driven, layered) |
| Project | project_name | Project name |
flowstate.json immediately after the interview completes.
Pipeline steps
After the interview,flowstate init runs five steps in sequence:
| Step | Label | What happens |
|---|---|---|
| 1/5 | Context Generation | Writes 5 context files deterministically from interview answers. No LLM, runs in under 1 second. |
| 2/5 | Research | Splits research_focus into individual topics and runs one focused claude --print call per topic (~30s each). Produces research/report.md. |
| 3/5 | Strategy | Runs a single pressure-test claude --print call (~75s). Produces research/strategy.md. |
| 4/5 | Management | Sets up context files for GSD skills (already written in step 1, this step enriches them). GSD phases themselves run natively via flowstate launch gsd <N>. |
| 5/5 | Discipline | Pure-Python audit of git repo, test configuration, and hooks. No LLM required. |
claude CLI is not found and --dry-run is not set, the pipeline automatically falls back to dry-run mode with a warning.
Context files written
After a successful run, five context files exist in your project:| File | Consumer | Content |
|---|---|---|
.planning/PROJECT.md | GSD | Vision, problem statement, architecture pattern, constraints |
.planning/ROADMAP.md | GSD | Phase breakdown from milestones with acceptance criteria |
.planning/config.json | GSD | Workflow preferences (mode, granularity, auto-commit) |
.claude/CLAUDE.md | All tools | Project context, active tools, current phase summary |
research/brief.md | Research adapter | Structured research questions derived from interview answers |
Examples
Run the full pipeline with the interactive interview:flowstate.json:
Notes
- If
claudeCLI is not installed and--dry-runis not passed, FlowState logs a warning and falls back to dry-run mode automatically. - State is written to
flowstate.jsonafter every pipeline step. If a step fails, it is markedblockedand the pipeline continues to the next step. - Run
flowstate checkbeforeflowstate initto confirm your Claude Code bridge is configured correctly.