# Bengous Agents Skills State Machine > State Machine - Skill: `tomevault-io/bengous-agents-skills-state-machine` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add tomevault-io/bengous-agents-skills-state-machine` - Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/bengous-agents-skills-state-machine/raw - Safety review: pending (external: skill-scanner PASS, skillspector PASS) - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: tomevault-io (https://skillmd.com/u/tomevault-io) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/tomevault-io/bengous-agents-skills-state-machine --- # State Machine Model behavior as a finite state machine to eliminate impossible states and make every transition explicit. ## Agent contract This skill is for state-machine design, not tool installation. Model first; choose tools later only when the model needs them. Before changing code, produce or hold in working context: 1. Finite states with one-line meaning. 2. Events that can occur. 3. Transition table: current state, event, optional guard, actions, next state. 4. Impossible states the model prevents. 5. Smallest implementation shape that preserves the model. Inspect the repository first. Reuse existing state patterns and dependencies. Do not introduce a visualization tool or runtime library just because this skill triggered. ## When to use - Two or more `isXxx` booleans gate behavior and can drift out of sync - A flow has visible idle / pending / success / error / retry phases - A form, wizard, auth flow or protocol has order-dependent steps - A bug report says "stuck loading", "showing both states", or "shouldn't be possible" - An embedded controller or workflow engine is being designed ## When NOT to use - Single boolean toggle with no side effects - Pure server cache (use TanStack Query or SWR; their internal FSM is enough) - Stateless pure transformations ## Output contract Prefer explicit, reviewable artifacts: | Situation | Output | |---|---| | Design or review request | State list, event list, transition table, impossible states | | Human review needed | Mermaid `stateDiagram-v2` plus the transition table | | Simple TypeScript state | Discriminated union and transition function | | React local UI state | `useReducer` state/event reducer | | Complex app logic | XState only when hierarchy, parallel regions, history, actors, or inspection justify it | | Rust | Typestate or `statig`, matching repo style | | Embedded C/C++ | Explicit transition table or QP/QM if already part of the stack | Load only the implementation reference that matches the selected stack. ## Human review gate Pause for human review before implementation when: - The machine has more than about seven states. - Transitions cross multiple user or business workflows. - Guards encode business policy. - States are hierarchical, parallel, historical, or actor-based. - The implementation would add a new runtime dependency. - The model affects persisted state, auth, payments, delivery, or irreversible actions. For review, use a text-first Mermaid diagram. Do not install visual tools unless the user explicitly asks for them. ## The 5 components | Component | Definition | |---|---| | **State** | Distinct mode the system can occupy (idle, loading, success...) | | **Event** | Trigger for a transition (click, submit, response, timeout) | | **Transition** | In state A, on event E, go to state B (optional guard / action) | | **Action** | Side effect run on transition, entry, or exit (fetch, log, toast) | | **Guard** | Boolean condition that must hold for the transition to fire | Full glossary with citations: `references/concepts.md` ## Modeling checklist 1. Enumerate states. Start with the happy path. 2. Enumerate events. 3. Draw transitions. Every non-final state needs an exit. 4. List impossible state combinations and confirm they are unrepresentable. 5. Add guards only where a transition is conditional. 6. Define entry / exit actions only where side effects are required. 7. Sketch Mermaid `stateDiagram-v2` only when it improves review. See `references/visual-notation.md`. Worked example: `references/modeling-process.md` ## Pick an implementation | Stack | Reference | |---|---| | TypeScript, no lib | `references/implementations/typescript-discriminated-unions.md` | | React, no lib | `references/implementations/react-usereducer.md` | | Svelte 5 runes | `references/implementations/svelte5-runes.md` | | XState v5 (cross-framework, statecharts) | `references/implementations/xstate.md` | | C (embedded, kernel) | `references/implementations/c.md` | | Java (backend, workflows) | `references/implementations/java.md` | | Rust (typestate, embedded) | `references/implementations/rust.md` | Validation manifest and rerunner: `config/validation/manifest.json` and `scripts/validate-references.sh`. Reach for a statechart library (XState, statig, QP, Spring StateMachine) when a flat reducer becomes hard to audit or needs hierarchy, parallel regions, or history. See `references/statecharts-extensions.md`. ## Common patterns Form, data fetching with retry, auth, multi-step wizard, toggle with optimistic UI, network protocol handshake. Diagrams and implementation sketches in `references/patterns.md`. ## Don't `references/anti-patterns.md` covers boolean explosion, isLoading flags, syncing derivable state, dead-end states, and switch-FSM without a typed table. ## Further reading `references/further-reading.md` curates Harel 1987, the W3C SCXML 1.0 recommendation, statecharts.dev, Samek's PSiCC2, Khourshid talks, and Wuyts' state-machine blog series. --- > Source: [bengous/agents-skills](https://github.com/bengous/agents-skills) — distributed by [TomeVault](https://tomevault.io).