Use XState machines for designing and explaining complex state

Start by reading the architect, interrogate, how, and teach entry points and the repository’s existing reference files. Then resolve the listed questions about Stately login, privacy, sketch format, and tooling before drafting state-machines.md and updating the relevant phases. Done means the guidance and edits cover the agreed workflow and its fallback; the issue does not name tests to run.

Problem

When agents design or explain parts of a system, everything comes back as prose. Lifecycle and protocol state (auth flows, sync, retry/cancel/timeout, wizards, connection handling) is hard to review that way. Impossible states hide in boolean flags, and nobody can check that the code still matches the agreed design.

Idea

Use XState machines as the notation for complex state. An agent writes the machine as code, the human reviews it as a diagram, and the same machine yields a test plan and a check for drift. Use the Stately CLI (statelyai) for the tooling.

Draft placement:

Default to using the machine as a design document: the sketch lives outside the project's source, and the project gains no dependency. Adding xstate to the app is a separate architect candidate. It's labelled as adding a dependency and goes ahead only on approval, or when scan shows the project already uses xstate.

Tldraw is out of scope for now. It would need its own bridge into Claude Code, and the Stately CLI already covers the state-machine case.

Findings (tested 2026-10-22)

Probes ran in throwaway folders with no package.json or node_modules.

• The CLI needs no xstate in the target project. It reads the source as text and never imports xstate.
  • scan --json found the machines with no config and no login.
  • diff a.ts b.ts --fail-on-changes works on two local files. It reported Added edges: root.closed->SLAM->root.open, exiting 1 when the machines differ and 0 when they match.
• [email protected] (latest) doesn't install. It depends on @statelyai/[email protected], which isn't on npm (404). 0.14.3 works. Pin an exact version.
• A JSON machine compares equal to the same machine in TS. diff door.machine.ts door.json reported no changes. A plain .json sketch would avoid the problem of an import 'xstate' line breaking the project's typecheck. scan only listed the .ts file, though.
• diff can't read Mermaid. It fails on .mmd with a JSON parse error, even though the CLI's file pattern includes .mmd/.mermaid.
• open needs a Stately account. The CLI starts a local server, but the editor is an iframe from editor.stately.ai. Its access endpoint (/api/editor-sync/access) returns 401 AUTH_INVALID: A valid Stately credential is required for editor sync without a credential. Write-back to the source file is not verified.
• Path generation works outside the project. @xstate/[email protected] with [email protected] and tsx, installed in a scratch folder, produced shortest paths as event sequences. Example: FETCH → REJECT → RETRY → RESOLVE.
• Sketches with stubbed actions give misleading paths. In a retry machine whose bumpRetries action was named but not implemented, the retry count never changed, and gaveUp was never reached. With bumpRetries implemented as an assign, it was reached via FETCH, REJECT, RETRY, REJECT, RETRY, REJECT, RETRY, along with 13 paths in all. Implementing the action also showed that CANCEL doesn't reset the retry count. That's the kind of design gap this approach should surface.

Open questions

• Stately account. Is a login acceptable for the visual part, and does the free tier cover editor sync? Without one, gstack gets scan, diff and test paths, but no diagram editing.
• Privacy. With open, the machine is shown in a page hosted by Stately. Does the machine content leave the machine (i.e. reach Stately's servers)? Is that OK for private repos?
• Write-back. Once logged in, do edits in open land cleanly in a .ts sketch? What about a .json one? And what does --source-update preserve|rewrite do to formatting?
• Fallback diagram. Without an account, what do we show? Options: a Mermaid stateDiagram written by the agent, or one generated from the machine.
• Sketch format and location. .ts (scan finds it, but it imports xstate) or .json (no import, diff works, scan doesn't list it)? Scratchpad or a committed planning folder?
• Stubbed implementations. Should architect require real assigns for context the guards read? Or should paths only be generated from an implemented machine?
• Path explosion. Context values multiply the states the path search explores. What limits do we set before we feed the paths to tdd?
• Tooling dependency. gstack would need Node, npx and network access to fetch pinned packages. Is that acceptable for a skill, and what's the fallback when they're missing?
• Trigger. How does architect decide that work is "state-heavy" without asking every time?

Next step

Grill the open questions, starting with the Stately account and privacy questions. Then write state-machines.md and the architect edits.