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.

Dry-run mode lets you exercise the entire FlowState pipeline — interview, context generation, research, strategy, GSD, and discipline — without making a single call to the claude CLI. Every adapter that normally calls the bridge checks self.dry_run first and returns a deterministic mock result instead. The state machine, file writes, and flowstate.json persistence all behave identically to a live run, making dry-run the right tool for CI/CD testing, local development, and validating the interview flow.

​
How to use it

Pass --dry-run to flowstate init: 
flowstate init --dry-run
To re-run with existing interview answers and skip the prompts: 
flowstate init --dry-run --skip-interview
Check the resulting state with: 
flowstate status

​
What each step does in dry-run mode

Context generation is pure Python with no LLM calls, so it runs identically in dry-run and live mode. The five context files are written from your interview answers using deterministic templates:
  • .planning/PROJECT.md
  • .planning/ROADMAP.md
  • .planning/config.json
  • .claude/CLAUDE.md
  • research/brief.md
This step completes in under one second regardless of mode.
The ResearchAdapter checks self.dry_run and, when true, formats the MOCK_REPORT template with your comma-separated research topics and writes it to research/report.md:
# Research Report

## Focus Areas
{focus}

## Findings
- **Libraries**: Analysis pending research integration.
- **Edge Cases**: Identified areas requiring deeper investigation.
- **References**: Queued for search.

## Recommendations
1. Proceed with initial architecture while research continues.
2. Flag blocking unknowns for async resolution.

---
*Generated by FlowState (mock mode)*
The {focus} placeholder is replaced with your actual research_focus topics joined by commas. The file path, artifact registration, and ToolResult shape are identical to a real run.
The StrategyAdapter.pressure_test method checks self.dry_run and formats the MOCK_STRATEGY template with your core_problem and ten_x_vision, then writes it to research/strategy.md:
# Strategy: Pressure Test

## Core Problem
{problem}

## 10x Vision
{vision}

## Assessment
- **Market fit**: Validated against the core problem statement.
- **Scalability**: Architecture supports 10x growth path.
- **Risk**: Key risks identified and mitigated in milestone planning.

---
*Generated by FlowState (mock mode)*
The {problem} and {vision} placeholders are filled from your actual interview answers.
The GSD adapter writes the .planning/ context files that GSD skills consume. In dry-run mode it skips any claude --print calls and returns a successful ToolResult after confirming the files exist. The .planning/PROJECT.md, .planning/ROADMAP.md, and .planning/config.json files were already written by the Context Generation step.
The discipline audit is pure Python — it checks for .git, pyproject.toml / pytest.ini / setup.cfg, .pre-commit-config.yaml, installed git hooks, a tests/ directory, a src/ directory or Python package, and a .planning/ directory. No LLM is involved, so dry-run and live mode are identical.

​
State persistence in dry-run

flowstate.json is written after every pipeline step, just like in a live run. Tool statuses transition through ready → running → completed (or blocked on failure), and artifacts are registered against each tool entry. After a dry-run you can inspect the full state: 
flowstate status

┌──────────────────────────────────────────────────────┐
│                   FlowState Status                    │
├──────────────┬──────────────┬───────────┬────────────┤
│ Tool         │ Phase        │ Status    │ Artifacts  │
├──────────────┼──────────────┼───────────┼────────────┤
│ research     │ Research     │ completed │ research/… │
│ strategy     │ Strategy     │ completed │ research/… │
│ gsd          │ Management   │ completed │ .planning… │
│ discipline   │ Discipline   │ completed │ ---        │
└──────────────┴──────────────┴───────────┴────────────┘

​
Automatic fallback

If FlowState starts a live run and the claude CLI is not found on your PATH and isn’t set via FLOWSTATE_CLAUDE_BIN, the orchestrator automatically falls back to dry-run mode and prints a warning: 
⚠  claude CLI not found — falling back to dry-run mode.
   Install Claude Code or set FLOWSTATE_CLAUDE_BIN to use live mode.
This means flowstate init never hard-fails due to a missing CLI — you always get a complete state file and context files even in environments where Claude Code isn’t installed.
The automatic fallback produces the same mock artifacts as --dry-run. To confirm whether a run used real LLM calls, check the artifact files: mock-mode output ends with *Generated by FlowState (mock mode)*.

​
Use cases

CI/CD testing

Run flowstate init --dry-run in a GitHub Actions workflow to verify the pipeline, interview flow, and context file generation on every PR — no API keys needed.

Local development

Iterate on prompts, context templates, or adapter logic without waiting for claude --print calls (~30–75 seconds each in live mode).

Interview validation

Test that custom interview answers produce the correct context files and roadmap phases before committing to a live research run.

Pipeline diagnosis

When a live run fails mid-pipeline, re-run with --dry-run --skip-interview to check whether the issue is in the orchestration logic or the LLM calls.
All 155 FlowState tests run in dry-run mode and do not require the claude CLI. Run them with python -m pytest tests/ -v from inside your venv or flox activate shell.

Build docs developers (and LLMs) love

Get started for freeTalk to us