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:

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

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

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 — distributed by TomeVault.