The Methodology

How FlowState Engineering Works

Six load-bearing parts: two modes, one protocol, one ecosystem, one loop, and one enforcement layer. Remove any of them and the methodology fails.

Section 1

The Two Modes

FSE separates thinking from doing into two modes of the same assistant. Planning is a read-only mode — it weighs approaches, trades off architectures, writes the plan, and pushes back when the ask doesn't fit the system; in this mode the assistant cannot touch code. Execution is a mode — it opens files, runs builds, edits source, and reports what actually happened. The wall between them is an approval gate and explicit provenance tagging — not a boundary between two apps.

Each mode 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 the executing mode 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 the project's build or check command. 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

    No stubs, no placeholders, no TODOs. Nothing is written that isn't finished, and nothing changes outside the agreed scope — adjacent cleanup gets surfaced, not slipped in. 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 and an explicit growth rule.

Tier 1 — Required

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. FSE_DISCOVERY.md is the initial audit: solution structure, dependencies, infrastructure gaps. All three are read at the start of every session.

Tier 2 — Add When Needed

FSE_POLICE.md (absolute rules — security, compliance, data boundaries), FSE_SCHEMA.md, FSE_UI.md, FSE_PACKAGES.md, and PATTERNS.md. A Tier 2 file is created when a category of rules keeps repeating across sessions, or when a domain warrants its own authoritative document. Read on demand, not on every session.

Tier 3 — Optional / Aged-Out

Build logs, point-in-time audits, changelogs, and session reports that have been superseded and archived. Read rarely. They exist so the state file stays lean.

Growth rule: every document starts unified. Passing ~15 KB is a split trigger, not a hard cap — it applies to bedrock methodology files, not to source code, and it prompts moving a self-contained domain into its own Tier 2 file with a pointer 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:
  run the project build command
  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.

Section 5

Executable Enforcement

A rule that exists only as prose is unenforced. It depends entirely on the vigilance of whoever is reading it at the moment they are most tired. So every invariant the project intends to hold — an architectural boundary, a naming grammar, a forbidden construct — is encoded as a check that fails the build, not written down as an expectation.

The harder half is the second clause. A check can report success without having verified anything: its target set is empty, so a test command runs where no tests exist and exits zero; its dependency is unreachable, so an integration suite skips politely and skipping is scored as passing; its matching logic is silently broken, so a filter inspects nothing and reports clean. In each case the signal inverts — the absence of verification becomes indistinguishable from successful verification, and every later session trusts the green.

So a check must fail loudly when it cannot run, and an enforcement artifact is itself verified: it is watched failing on a known violation before it is trusted to pass. A guard nobody has seen fail is a guard nobody has tested.

Rule: a vacuous pass is more dangerous than a visible failure — a gap gets noticed, a false green gets relied upon.

What the checks are is the project's business, not the methodology's. Test framework, gate wiring, fixture strategy, and CI topology belong to the stack. The core defines only that the invariants are executable, that they fail loudly, and that they have been seen to fail.

Section 6

When Not to Use FSE

FSE is not a universal development process. It is designed for AI-assisted production work where context drift, late-stage integration failure, and scope expansion are real risks. If those risks are not present, the protocol may cost more than it protects.

Greenfield discovery without a known target

FSE requires a plan before execution. If the goal is exploratory — finding the schema, finding the requirements, finding what the AI can do — the methodology has nothing to enforce. Use FSE once the target is known.

Trivial scripts and throwaway utilities

Scripts under a few hundred lines, single-file tools, one-off automation. The protocol overhead exceeds the value of the artifact. Maintaining FSE_STATE.md for a build script is bureaucracy without payoff.

Manual-dominant development

When you are writing 90% of the code yourself and using AI only for autocomplete or code completion, the state-synchronization protocol is overhead without payoff. FSE addresses AI-assisted execution failure modes — if AI is not making meaningful execution decisions, those failure modes are not present.

Emergency production fixes

When restoring service matters more than preserving methodology, the methodology yields. Patch the production issue, recover the system, then return to the protocol for the post-incident work. FSE is an investment in long-run integrity, not a constraint on emergency triage.

Volatile requirements and rapid pivot environments

When product direction changes hourly, the cost of the baseline ratchet and the re-plan loop exceeds the cost of throwing work away. FSE is for building high-integrity infrastructure, not for finding product-market fit through rapid experimentation.

Bottom line: FSE earns its overhead in long-running, AI-assisted, production-bound work. Outside that envelope, it is the wrong tool.

See the Ten Tenets →