Skip to content
Skills Library
Management & product · Planning

state-machine-workflow

/state-machine-workflow

Use when work has distinct modes and the user wants states, events, guards, outcomes, illegal transitions, not a prose todo list. Not for remote, credential, publish, deploy, or irreversible changes.

Licence
Apache-2.0
Last repository change
10.11.2026

Assessment and security

90/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content25 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
2
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 10.11.2026, without references to retired models or APIs.

Licence

Apache-2.0, otwarta: można używać i zmieniać, z zachowaniem licencji i informacji o zmianach.

What it does and when to use it

Use when work has distinct modes and the user wants states, events, guards, outcomes, illegal transitions, not a prose todo list. Not for remote, credential, publish, deploy, or irreversible changes.

Original author description

Use when work has distinct modes and the user wants states, events, guards, outcomes, illegal transitions, not a prose todo list. Not for remote, credential, publish, deploy, or irreversible changes.

How it works

  1. What you need before you start
  2. Building the machine
  3. What you hand back
Original SKILL.md headings · 30 lines, 590 words
SKILL.md preview
---
name: state-machine-workflow
description: 'Use when work has distinct modes and the user wants states, events, guards, outcomes, illegal transitions, not a prose todo list. Not for remote, credential, publish, deploy, or irreversible changes.'
---

# State machine workflow

Some work is not a todo list. The system sits in one mode at a time and moves between modes on events. When that is the shape of the problem, write it down as a state machine: every mode named, every move guarded, every forbidden shortcut called out, so the result can be encoded directly in types, a state-machine library, or a runtime enum.

This skill writes one specification file to the project and nothing else. It never touches remote systems. Rolling back is deleting that file.

## What you need before you start

You need a description of the domain, process, or system being modeled: who owns the states and where the boundary sits. Optionally, an existing list of states or transitions to refine, or an existing state-machine file to extend. If the domain is too vague to enumerate states from (no named entity, no boundary, no modes), stop and ask the user to supply them. Do not invent scope.

## Building the machine

Work through these in order. Each step has a bar for moving on. Do not skip ahead past an unresolved step.

1. Confirm the scope with the user first. Name the system boundary and the entity or process that owns the states, and move on once the user confirms the boundary.
2. List every distinct mode the system can occupy. Name each state as a noun or adjective-noun pair describing the mode, not the action that caused it. Give each an entry condition and at least one outgoing transition, and move on once every state has both.
3. For each state, list every valid move to another state with all five fields: source state, destination state, triggering event, the guard condition that must hold for it to fire, and the outcome or side effect it produces. If two guards contradict each other or a state turns out unreachable, surface the contradiction with a proposed resolution and do not write until it is resolved.
4. For terminal and milestone states, name the concrete observable result: a file written, a decision recorded, a value returned, a signal emitted. Vague outcomes do not count.
5. For every pair of states where a direct transition must never occur, name the pair and say why it is forbidden. These guard against invalid shortcuts.
6. Check four things: every state has at least one outgoing transition (no dead states except explicit terminal states); every path from the initial state reaches a terminal or outcome state; no two transitions from the same state share an identical event and guard; every guard references a condition observable within the scoped domain. Fix failures before continuing.
7. Show the full specification as a structured table or diagram (states, transitions, guards, illegal transitions) and ask the user to confirm. If the user rejects the enumeration, revise from their feedback. Never write a specification the user has not approved.
8. Write the specification to the project using the format it already prefers (Markdown table, Mermaid diagram, or code). With no preference, write a Markdown file with sections for states, transitions, guards, outcomes, and illegal transitions.

If only part of the machine is complete and approved, write only that part and mark the rest as open. Never present unfinished states or transitions as stubs or placeholders.

## What you hand back

The specification file: all states with entry conditions, all transitions with source, destination, event, guard, and outcome, all terminal outcomes, and all illegal transitions with rationale. It should be sufficient to encode directly.
Files in this package (2)
  • SKILL.md 4 KB
  • agents/openai.yaml 1 KB

Versions

RepositoryScoreLicence
This page · gosuda/dalcom-skills90Apache-2.0
OutlineDriven/outline-driven-development90Apache-2.0

Database snapshot: 13.11.2026 · package version 80210d9b091b (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100model-the-state-machine
    Use when designing any lifecycle, workflow, phase, or status field (order, job, session, document, deployment, request) — model it as explicit states, transitions, and guards rather than scattered boolean flags.
  • 100figure-it-out
    Use when non-trivial work should run a matched playbook to verified real-surface completion, or a bespoke workflow when none fits. Not for remote, credential, publish, deploy, or irreversible changes.
  • 100state-machine
    Model a workflow, status lifecycle or approval flow with the nandordudas/state-machine library (PHP 8.5+). Use when the user wants states/transitions, guards, hooks, order/payment/document statuses, or to replace scattered `if ($status === ...)` checks.
  • 90state-machine
    Model component behaviour as explicit states, events, and transitions. Use when a component has many interacting states that must be exhaustive. For the feel and feedback of a single interaction, use `micro-interaction-spec`.
  • 100spring-statemachine
    Spring Statemachine for building finite state machine applications. Covers states, transitions, guards, actions, persistence, and hierarchical states. USE WHEN: user mentions "spring statemachine", "state machine Spring", "workflow Spring", "finite state machine", "order state",…
  • 85state-machine-design
    Use when a feature involves multiple states or transitions. Recognizes the shape, names states and events, designs guards, actions, and hierarchy, and visualizes or simulates the result.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.