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 generates five context files from your interview answers using pure Python templates — no LLM calls, no network requests, no timeouts. The entire Context Generation step completes in under one second and produces deterministic output that GSD skills, Claude Code sessions, and the research adapter all consume downstream. Every file is regeneratable at any time without re-running the full pipeline.

​
The five context files

FileConsumerContent
.planning/PROJECT.mdGSDVision, problem, constraints, architecture pattern, test coverage target, milestones
.planning/ROADMAP.mdGSDPhase-based roadmap — one phase per milestone with goal, deliverables, acceptance criteria, and status
.planning/config.jsonGSDWorkflow config: mode, granularity, auto_commit, verification
.claude/CLAUDE.mdAll toolsProject context: problem, vision, architecture, active tools, current phase
research/brief.mdResearch adapterStructured research questions split by topic

​
File details and example content

Generated by generate_project_md(answers, project_name). Contains the vision, problem statement, architecture pattern, test coverage target, and all milestones as a bulleted list.
# semantic-search

## Problem
Semantic search is slow and expensive at scale

## Vision
Sub-10ms semantic search for 1B documents

## Architecture
- Pattern: microservices
- Test coverage target: 80%

## Milestones
- MVP indexer
- Query optimisation
- Production hardening
GSD’s /gsd:plan-phase and /gsd:execute-phase skills read this file to understand the project scope before planning or executing a phase.
Generated by generate_roadmap_md(answers). Each milestone from the interview becomes a numbered phase with a goal, deliverables placeholder, acceptance criteria placeholder, and a Pending status. One milestone = one phase, preserving the order from your interview answers.
# Roadmap

## Phase 1: MVP indexer
- **Goal**: MVP indexer
- **Deliverables**: TBD (refine during planning)
- **Acceptance criteria**: TBD
- **Status**: Pending

## Phase 2: Query optimisation
- **Goal**: Query optimisation
- **Deliverables**: TBD (refine during planning)
- **Acceptance criteria**: TBD
- **Status**: Pending

## Phase 3: Production hardening
- **Goal**: Production hardening
- **Deliverables**: TBD (refine during planning)
- **Acceptance criteria**: TBD
- **Status**: Pending
The deliverables and acceptance criteria are intentionally left as TBD — GSD’s /gsd:plan-phase fills these in during planning with Claude’s help.
Generated by generate_gsd_config(). Sets the GSD workflow mode and options. The defaults are:
{
  "mode": "balanced",
  "granularity": "standard",
  "auto_commit": true,
  "verification": true
}
You can pass a preferences dict to generate_gsd_config(preferences) to override any of these values. auto_commit: true means GSD commits after each completed task; verification: true enables test-run verification before marking tasks complete.
Generated by generate_claude_md(state). This is the project-level context file that Claude Code reads at the start of every session. It contains the problem statement, vision, architecture details, a list of active FlowState tools, and a pointer to the roadmap.
# semantic-search — Project Context

## Problem
Semantic search is slow and expensive at scale

## Vision
Sub-10ms semantic search for 1B documents

## Architecture
- Pattern: microservices
- Test coverage: 80%

## Active Tools
- research
- strategy
- gsd
- discipline

## Current Phase
See `.planning/ROADMAP.md` for phase details.
The ## Active Tools section is populated from state.tools.keys() and reflects whichever tools have been initialised in the current pipeline run.
Generated by generate_research_brief(answers). Splits research_focus on commas and creates a section per topic, each with three standard questions framed around the project’s architecture constraint.
# Research Brief

## Context
- Core problem: Semantic search is slow and expensive at scale
- Architecture: microservices

## Topic 1: vector databases
- What are current best practices?
- What are the top 2-3 approaches and their trade-offs?
- What is the recommended approach given the architecture (microservices)?

## Topic 2: embedding models
- What are current best practices?
- What are the top 2-3 approaches and their trade-offs?
- What is the recommended approach given the architecture (microservices)?
The research adapter reads this file before building its per-topic bridge prompts. The architecture context in each question helps Claude Code tailor recommendations to your specific constraints.

​
Generator functions

All five files are produced by functions in flowstate/context.py:
FunctionOutput fileInputs
generate_project_md(answers, project_name).planning/PROJECT.mdInterviewAnswers, project name string
generate_roadmap_md(answers).planning/ROADMAP.mdInterviewAnswers (milestones list)
generate_gsd_config(preferences).planning/config.jsonOptional preferences dict
generate_claude_md(state).claude/CLAUDE.mdFull FlowStateModel
generate_research_brief(answers)research/brief.mdInterviewAnswers (research_focus, core_problem, architecture_pattern)
The orchestrating function write_context_files(state, root) calls all five generators, writes the files to disk, and updates state.context_files with the relative paths of everything created.

​
How milestones map to roadmap phases

The mapping is direct and ordered: milestones[0] becomes Phase 1, milestones[1] becomes Phase 2, and so on. There is no gap-filling or reordering. If you enter milestones in the interview as: 
MVP indexer, Query optimisation, Production hardening
You get exactly three phases in that order. GSD’s flowstate launch gsd 1 command refers to Phase 1 (MVP indexer), flowstate launch gsd 2 to Phase 2, and so on.

​
How to regenerate context files

Run flowstate context to regenerate all five files from the current state in flowstate.json without re-running the pipeline: 
flowstate context
This is useful when you want to:
  • Update CLAUDE.md after the pipeline has completed (e.g., to reflect a completed phase)
  • Regenerate files after manually editing flowstate.json
  • Recover context files that were accidentally deleted
flowstate context reads interview answers and preferences from flowstate.json. If you haven’t run flowstate init yet, there are no answers to generate from and the command will produce files with placeholder values.

​
Downstream consumption

GSD skills

/gsd:plan-phase N reads .planning/PROJECT.md and .planning/ROADMAP.md to plan tasks for phase N. /gsd:execute-phase N uses .planning/config.json for workflow preferences. Launch GSD phases with flowstate launch gsd <N>.

Claude Code sessions

.claude/CLAUDE.md is loaded automatically by Claude Code at session start, giving every claude session awareness of the project’s problem, vision, and architecture without any manual context-setting.

Research adapter

research/brief.md is the source of truth for the topics the research adapter investigates. It’s also available to Claude Code sessions that want to understand what research questions have been defined.

Regeneration

All five files are idempotent — regenerating them with the same interview answers produces byte-identical output. Safe to run flowstate context at any time.

Build docs developers (and LLMs) love

Get started for freeTalk to us