The FlowState Pipeline: Five Steps to Agentic Readiness

FlowState orchestrates five sequential steps that transform interview answers into a fully prepared project context. Each step has a distinct role: some are pure Python (instant, deterministic, no LLM), others are targeted claude --print calls that produce durable research artifacts. After every step, the pipeline writes state to flowstate.json so progress survives interruptions and re-runs only redo what’s needed.

Overview

Step	Role	What Happens
1. Context Generation	Setup	Writes 5 context files deterministically — no LLM, <1s
2. Research	Intelligence	Split-topic `claude --print` calls (~30s/topic) → `research/report.md`
3. Strategy	Pressure-test	Single `claude --print` call (~75s) → `research/strategy.md`
4. GSD Management	Management	Writes context files for GSD skills; phases run natively via `flowstate launch gsd <N>`
5. Discipline Audit	Audit	Pure Python check of git repo, pytest config, pre-commit hooks — no LLM

Architecture

┌──────────────────────────────────────────────────┐
│                   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 orchestrator sequences all five steps. An EventBus carries StepCompleted and StepFailed events to memory handlers, which automatically store artifacts as searchable knowledge for future runs.

The Five Steps

Context Generation — Deterministic Setup

The first step is pure Python: no LLM call, no network I/O, completes in under one second. The write_context_files() function reads the interview answers stored in flowstate.json and renders five files using deterministic templates.Files written:

File	Consumer	Content
`.planning/PROJECT.md`	GSD	Vision, problem, constraints, requirements
`.planning/ROADMAP.md`	GSD	Phases from milestones with acceptance criteria
`.planning/config.json`	GSD	Workflow preferences (mode, granularity)
`.claude/CLAUDE.md`	All tools	Project context, active tools, current phase
`research/brief.md`	Research adapter	Structured research questions from interview

Because this step is deterministic, you can re-run it any time with flowstate context to regenerate all five files from current state — no LLM cost.

Research — Split-Topic Bridge Calls

ResearchAdapter reads the research_focus field from the interview and splits it by commas into individual topics. It issues one claude --print call per topic (approximately 30 seconds each) and merges all outputs into research/report.md.

# flowstate/tools/research.py (simplified)
topics = [t.strip() for t in interview.research_focus.split(",")]
for topic in topics:
    context = memory.get_context(topic)   # inject prior knowledge
    result = bridge.run(prompt, system_prompt=RESEARCHER_PERSONA)

If prior knowledge exists in memory.db for a topic, the adapter prepends it as a ## Prior Knowledge section so each run builds on previous findings. The merged report is written to research/report.md and registered as an artifact on the tool’s state entry.

In dry-run mode, ResearchAdapter returns a mock BridgeResult immediately — no subprocess is launched. Enable dry-run with flowstate init --dry-run.

Strategy — Pressure-Test Call

StrategyAdapter issues a single claude --print call with an advisor-style system prompt that pressure-tests the project’s core problem, architecture choices, and milestones. The call takes approximately 75 seconds and writes its output to research/strategy.md.This step is intentionally single-call: the strategic assessment is meant to be one coherent critique, not a parallel sweep. Memory context relevant to the project’s core problem is injected before the prompt.

# flowstate/tools/strategy.py (simplified)
context = memory.get_context(interview.core_problem)
result = bridge.run(prompt, system_prompt=ADVISOR_PERSONA)

GSD Management — Context File Enrichment

GSDAdapter writes additional context files that the GSD (Get Shit Done) skills consume. The core .planning/PROJECT.md and .planning/ROADMAP.md files are already written in Step 1; this step enriches them and registers artifacts on the state model so flowstate launch gsd <N> knows where everything lives.GSD phases themselves run natively inside a Claude Code session — FlowState does not attempt to run them via the bridge. Instead, flowstate launch gsd 1 prints the exact commands to execute:

flowstate launch gsd 1
# → cd /path/to/project && claude
# → /gsd:plan-phase 1

Discipline Audit — Pure Python Checks

The final step runs a set of pure Python checks against the project directory. No LLM is involved. The check_setup() function inspects:

Git repository — is the directory a git repo?
pytest configuration — is pytest.ini, pyproject.toml [tool.pytest], or setup.cfg present?
Pre-commit hooks — is .pre-commit-config.yaml configured?
Tests directory — does a tests/ directory exist?
Planning directory — does .planning/ exist with required files?

The audit result carries a summary string that the orchestrator prints. This step completes in milliseconds and always succeeds from the pipeline’s perspective — the audit findings are informational.

State Persistence

Every step writes to flowstate.json — a Pydantic-validated file in the project root. The orchestrator calls save_state() after marking a tool RUNNING, again after marking it COMPLETED or BLOCKED. This means a crash mid-step leaves the state at running, which --skip-interview will detect and re-run.

ToolStatus enum

# flowstate/state.py
class ToolStatus(StrEnum):
    READY     = "ready"      # initial state, not yet started
    RUNNING   = "running"    # currently executing
    COMPLETED = "completed"  # finished successfully
    BLOCKED   = "blocked"    # failed; pipeline continues past this step

If a tool fails, it is marked BLOCKED and the pipeline continues to the next step. A partial run with blocked tools is still a valid run — check flowstate status to see which steps need attention.

The step runner in orchestrator.py follows this pattern for every LLM-backed step:

# flowstate/orchestrator.py
update_tool(state, tool_name, status=ToolStatus.RUNNING)
save_state(state, root)

result = execute_fn()

if result.success:
    update_tool(state, tool_name, status=ToolStatus.COMPLETED)
    bus.emit(StepCompleted(payload={"tool": tool_name, "artifacts": result.artifacts}))
else:
    update_tool(state, tool_name, status=ToolStatus.BLOCKED, error=result.error)
    bus.emit(StepFailed(payload={"tool": tool_name, "error": result.error}))

save_state(state, root)

Tool order

The canonical pipeline order is defined as a module-level constant:

# flowstate/orchestrator.py
TOOL_ORDER = ["research", "strategy", "gsd", "discipline"]

This list drives both the run_pipeline() execution sequence and the flowstate status table row order.

Inspecting state

flowstate status

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

You can also inspect flowstate.json directly — it’s plain JSON:

cat flowstate.json | python -m json.tool

Running and Re-running the Pipeline

Full run

flowstate init

Runs the interview then all five steps.

Dry run

flowstate init --dry-run

Every adapter returns mock output. No claude CLI required. Ideal for CI or testing.

Skip interview

flowstate init --skip-interview

Reuses existing answers from flowstate.json and re-runs all steps. Safe to run after editing the state file by hand.

Regenerate context only

flowstate context

Reruns Step 1 only — rewrites all five context files from current state, no LLM calls.

Dry-run mode

Every adapter checks self.dry_run before issuing a bridge call and returns a BridgeResult with mock output when it is True:

# flowstate/bridge.py
def run(self, prompt: str, ...) -> BridgeResult:
    if self.dry_run:
        return BridgeResult(
            success=True,
            output=f"[dry-run] claude prompt ({len(prompt)} chars): {prompt[:120]}...",
        )
    # ... real subprocess call

All 155 tests run in dry-run mode — the claude CLI is never required to run the test suite.

Get Started

Concepts

CLI Reference

Guides

The FlowState Pipeline: Five Steps to Agentic Readiness

Overview

Architecture

The Five Steps

State Persistence

ToolStatus enum

Tool order

Inspecting state

Running and Re-running the Pipeline

Full run

Dry run

Skip interview

Regenerate context only

Dry-run mode

Build docs developers (and LLMs) love

Get Started

Concepts

CLI Reference

Guides

Documentation Index

​Overview

​Architecture

​The Five Steps

​State Persistence

​ToolStatus enum

​Tool order

​Inspecting state

​Running and Re-running the Pipeline

Full run

Dry run

Skip interview

Regenerate context only

​Dry-run mode

Build docs developers (and LLMs) love

Overview

Architecture

The Five Steps

State Persistence

ToolStatus enum

Tool order

Inspecting state

Running and Re-running the Pipeline

Dry-run mode