State Machines — Knowledge Map

A centralized hub connecting all documents related to finite state machines in UI, agents, and document lifecycle management. The cluster spans 10+ documents across 3 accounts and continues to grow.

Conceptual Posts

On this account — state machine advocacy, examples, and arguments for adoption:

State machines to visualize the work of agents — argues state machines are essential for LLM agent determinism, making agent behavior visualizable and predictable

How to Background Agents — practical guide to using Cursor background agents; state machines make agent behavior observable and predictable, directly complementing the visualization argument

Vibe code like a PRO — proposes a Linear→PR pipeline using spawned background agents; directly references state machines for deterministic agent behavior

State machines are great, but hard to establish — team adoption challenges and the risk of mixing state machine logic with ad-hoc logic

Modeling resizable panels using State Machines — concrete UI example applying state machines to resizable panel layouts

Notes about how the document machine should work — the document editing lifecycle (loaded → editing → publishing → rebase) as a concrete state machine implementation

These posts are collected in the Short Posts directory under the State Machines heading.

Cross-Account Notes (Develop Seed Hypermedia)

From Iskak's account — deeper theoretical grounding and practical scenarios:

Agents and State Machines — detailed Lamport-style model of Pi-based agents as message-driven state machines with invariants, durable state, and event subscriptions

Our distributed objects are state machines — Leslie Lamport's original articulation of state machines for distributed systems, including the Byzantine Generals Problem

Why aren't we using state machines more in our complex application? — practical scenarios where state machines reduce complexity: account picker, auto-updater, panel management, onboarding, device linking, comment publishing

Implementation Documents

Concrete code and architecture implementing state machine patterns:

Project Plan — No more Edit mode: New Publish mental model Pt.1 — implements document-machine.ts (XState v5, 465 lines) with loaded/editing/publishing lifecycle states

Publish Guard: block publishing when document content references local drafts — implements publish.start → publishing.inProgress guard transition in the document machine

Root Level Grouping Research — proposes blank/fragment node strategy that enables the document machine's editing and rebase states (adopted by Tech Sync)

Document Web Editing — web-side implementation of the document machine with web-flavored actors (IndexedDB drafts, WebCrypto signer, capability gate) for vault-delegated editing

Draft Publishing Chain solution proposal — resolves draft-link chains during publishing, extending the document machine's publishing state

External Resources

Educational and community resources on state-machine-driven development beyond this repository:

UI with State Machines — comprehensive educational site (XState, React, TypeScript) with structured learning paths, practical patterns, case studies, and tooling guides — referenced from 3 documents in this cluster

Product Backlog

State Machine Inspector (Opportunity #2) — proposes a visual inspector/debugger for the document machine's 10+ states, addressing the "hard to establish" pain point

Learning Paths

State Machine Fundamentals → Our distributed objects are state machines → Why aren't we using state machines?

UI State Machines → Modeling resizable panels → State machines are great, but hard to establish → State Machine Inspector opportunity

Document Machine → Notes about how the document machine should work → Project Plan → Publish Guard → Root Level Grouping Research

Agentic Coding Workflow (vision→reality→practical→theory→foundation) → Vibe code like a PRO (the vision: Linear→PR pipeline) → How I Built a Full Booking System as a Side Project — With Devin as My Engineering Partner (the reality: 6 merged PRs in a month using the exact pipeline) → How to Background Agents (the practical: executing agents) → State machines to visualize the work of agents (the argument: determinism through state machines) → Agents and State Machines (the theory: Lamport-style agent state machines) → Our distributed objects are state machines (the foundation: distributed state machine origins)