The Methodology

How FlowState Engineering Works

Five load-bearing parts: two layers, one protocol, one ecosystem, and one loop. Remove any of them and the methodology fails.

Section 1

The Two Layers

FSE separates thinking from doing. Claude Web is the planning layer — it weighs approaches, trades off architectures, writes the plan, and pushes back when the ask doesn't fit the system. Claude Code is the execution layer — it opens files, runs builds, edits source, and reports what actually happened.

Each layer has one job. The planner never edits code directly. The executor never invents architecture on its own. This separation is a mechanical safeguard against the primary failure mode in AI-assisted development: the agent that drifts mid-task because it is simultaneously deciding and doing.

Rule: If Claude Code encounters a decision that wasn't in the plan, it stops and escalates — it does not improvise.

Section 2

Session Protocol

Every session follows four phases. No phase is skipped, even for trivial work.

  1. Phase 1

    Verify

    Read FSE.md, FSE_STATE.md, and FSE_DISCOVERY.md. Run dotnet build. Report the baseline. You cannot improve a state you haven't measured.

  2. Phase 2

    Plan

    Restate the request in one sentence. List every file that will be created, modified, or deleted. Surface conflicts with standing orders or known debt before a single keystroke of execution.

  3. Phase 3

    Execute

    Write complete files only. No stubs, no placeholders, no TODOs. Each file is production-ready the moment it is written. The Self-Healing Build Loop runs after every meaningful change.

  4. Phase 4

    Validate

    Final build is 0 errors, 0 warnings — that is the only acceptable terminal state. Trace every new route and binding. Update FSE_STATE.md so the next session starts informed.

Section 3

Document Ecosystem

FSE treats documentation as the operating context for the agent, not as a deliverable for humans to read later. Three tiers, explicit growth rules, and a mandatory 15 KB size limit.

Tier 1 — Operating Context

FSE.md is the protocol itself — session phases, standing orders, project identity. FSE_STATE.md is the living state: build status, lessons learned, known technical debt, next priorities. Both files are read at the start of every session.

Tier 2 — Reference

FSE_DISCOVERY.md is the snapshot: solution structure, dependencies, architectural choices. FSE_POLICE.md is born only when a standing order has been violated — it records the incident and the new guard rule. Reference docs are read on demand, not on every session.

Tier 3 — Historical

Session history and lesson logs that have aged out of Tier 1. Read rarely. They exist so the state file stays lean.

Growth rule: every document starts unified. When it crosses 15 KB, the oldest or most self-contained section splits into a Tier 3 file and a pointer is left in the origin. The ecosystem starts at three files and grows only when growth is forced.

Section 4

Self-Healing Build Loop

Every change that could affect compilation triggers a build. Zero errors and zero warnings is not a release criterion — it is a continuous state. The moment the build is not green, the agent stops adding code and starts removing error. 

// Self-Healing Build Loop
loop:
  dotnet build FlowState.sln
  if errors == 0 and warnings == 0:
      break
  read first error
  form hypothesis
  apply fix
  if same error class fails 3 times:
      invoke Counter-Point Protocol
goto loop

Counter-Point Protocol

On the third failed retry — or whenever a user instruction conflicts with a standing order — the agent stops, states the conflict plainly, and offers two or three concrete alternatives. It does not guess. Friction at this moment is a feature: it prevents the agent from drilling deeper into a bad path.

See the Ten Tenets →