How do you convey a BLOC architecture to an AI Agent?

Help General
1

This is a non-coding question. I have seen a few posts online about design systems and how to convey UI design to an AI Agent. How do you convey System Design to an AI Agent, specifically, how do you convey States and Events in a BLOC Architecture? How do you guide and correct AI on States & Transitions?

I go back 40 years to State Transition Diagrams, but AI agents are apparently not currently equipped to read Node and Link diagrams, or are they? It seems to me I need to boil down a State/Transition Diagram into a set of statements that AI can digest. What do you do?

Here is a state diagram based on code that Gemini 3 generated for me. Red is a Page or Repository action; Green is an Event.

Temp State Transition
Temp State Transition1768×994 276 KB

There were a few issues with what was generated. Each of these required a follow-up with the Agent to fix them.

  1. In addition to the state model, Gemini added some redundant Booleans, isDirty, canEdit, force, _isInitialized, isNewRecord. I want to clean those up.
  2. One event, Load Organizations, is only used when the page is loaded, and probably is not really an event. Or am I still thinking ViewModel?
  3. Potential database errors were not addressed. I added those to this diagram which is starting to get messy!

Here is one way I thought to resolve this.

When user enters text in a typeahead field and selects a name from the dropdown list then add a LoadPerson Event, Get the “Person” from the Repository, and emit success or error state. Update and rebuild (relevant parts of) the page.

By my count I would need 18 such statements for this page. I think that there may be a way to simplify this. How do you do this? Is this a situation that anyone else has addressed?

2

AI seems fairly well trained on mermaid diagrams, and some types of mermaid diagrams are great for state transition. Ask AI to generate states.md containing mermaid, and then you can incrementally edit it via prompting (or even manually) to express your conditions. And once you have that as the source of truth, you can ask the LLM to respect that while generating Dart code.

Also, gemini suggested to me:
The quickest way to fix the “redundant booleans” issue Paul ran into is to explicitly instruct the agent to use Dart 3’s sealed classes (or Freezed unions).

  • The Prompt Directive: “Model all BLoC States and Events using strict sealed classes. Do not use a single state class with multiple boolean flags (e.g., no isLoading, isError, isDirty). Represent each phase of the UI as a distinct, exhaustive state class.”