statechart
Skill5 starsChanged yesterdayMITView on GitHub
use this when charting how a system or a user flow moves between states, in the reader's words — draw a Mermaid stateDiagram-v2 from a TLC-checked TLA+ model and report each broken rule as its shortest path, or chart a user flow from approved stories, labelled "not model-checked" when no checked model backs it.
29 other projects use a version of this.
Adopted by
Most recently taken up by
- shiwenbin1617/pstacktheir own version, first seen Nov 16, 2026
- anis-dr/skillstheir own version, first seen Nov 16, 2026
- Scino/fstacktheir own version, first seen Nov 15, 2026
- upamune/skillstheir own version, first seen Nov 15, 2026
- mdsmithaustin/pstacktheir own version, first seen Nov 15, 2026
- Yeachan-Heo/oh-my-claude-sisyphustheir own version, first seen Nov 8, 2026
Used with
Projects with it also use ketchup-video, show-me and 1 more.
Other files people use alongside this one.
Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
tristanphvnSkillketchup-video
Catch the user up like /keel:ketchup, with a short silent video of slides for what happened and the waiting calls as text under it. Use for /keel:ketchup-video.
Also in 10 projects that use this
AnasX7Skillshow-me
Help the user understand the current topic visually with concise diagrams, code-shape sketches, and focused HTML artifacts.
Also in 3 projects that use this
SentrySkilldeslop
Strip AI-generated noise from the diff before pushing — extra comments a human wouldn't write, defensive try/catch in trusted code paths, casts to any, inline imports in Python, and other style inconsistencies with the surrounding file. Use this immediately before commit so the diff stays clean.
Also in 3 projects that use this
Other versions29 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 29
- Yeachan-Heo/oh-my-claudecode★ 41ksame name
- Yeachan-Heo/oh-my-claude-sisyphus★ 41ksame name
- backnotprop/pstack★ 4.2ksame name
- UniClipboard/UniClipboard★ 2ksame name
- jtaroreh/agystack★ 128same name
- painhardcore/pstack★ 22same name
- TheOnlyFusionCube/potetos-for-everyone★ 21same name
- creedants/pstack-t3★ 18same name
- mariusflorescu/pstack-t3★ 13same name
- Scino/fstack★ 13same name
19 more not listed
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository54 other files it gives its agents.
- AGENTS.mdAGENTS.md
- maintainers/AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- astryxSkill
- buying-researcherSkill
- cursor-cloud-agents-whenSkill
- debug-anthropicSkill
- debug-pocockSkill
- debugSkill
- discover-the-ideaSkill
- docs-google-styleSkill
- formal-verificationSkill
- golang-safetySkill
- golang-securitySkill
- golang-testingSkill
- grok-acpSkill
- host-config-pyinfraSkill
- lang-cppSkill
- lang-csharpSkill
- lang-cSkill
- lang-dartSkill
- lang-dockerSkill
- lang-goSkill
- lang-javaSkill
- lang-js-tsSkill
- lang-kotlinSkill
- lang-luaSkill
- lang-makefileSkill
- lang-phpSkill
- lang-powershellSkill
- lang-protobufSkill
- lang-pythonSkill
- lang-rubySkill
- lang-rustSkill
- lang-shellSkill
- lang-sqlSkill
- lang-swiftSkill
- lang-terraformSkill
- language-routerSkill
- lang-web-markupSkill
- modern-pythonSkill
- modern-web-guidanceSkill
- pr-reviewSkill
- sdlc-artifactsSkill
- sdlc-onboardingSkill
- sdlcSkill
- security-hardeningSkill
- shell-safetySkill
- tddSkill
- tracker-sdlcSkill
- ui-craftSkill
- ux-designSkill
- verify-before-doneSkill
- yagniSkill
The file
Show its rules and text
We split this skill into the rules it gives an agent
25 rules. 0 are common, 13 are distinctive, and 12 are very specific to this project.
0
Common
Most of the 28 edited versions we read keep these.
13
Distinctive
This author's own choices. Worth a look.
12
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- could be automatic: a setting could enforce it
- Distinctive: line 26
Never weaken a reader rule to make it hold: When no variable can express a rule, add one to the model.
- Distinctive: line 39
Run TLC from the TLA+ tools the product repo already uses.
- Distinctive: line 45
Ask the operator only per Asking the operator.
- Very specific: line 60
Write each reader rule as an INVARIANT in the config.
- Very specific: line 61
Write Next as a disjunction of named actions, such as YouPressPlay \/ YouPressStop.
- Very specific: line 68
Keep the constants small, or add a CONSTRAINT, so the state space is finite.
- Very specific: line 72
Run TLC once on the unmodified config with -workers 1 -dump dot,actionlabels <file>.
- Very specific: line 73
Keep the output as tlc.out.
- Very specific: line 74
If TLC reports a broken invariant, a broken PROPERTY or a deadlock, save its trace as that rule's bug path, in tlc-<rule>.out.
- Very specific: line 78
Remove that rule from the working copy of the config, keeping earlier removals.
- Very specific: line 82
Keep the .dot graph and the distinct state count from the last run.
- Very specific: line 83
If the last run finished with no error, it explored every reachable state inside any CONSTRAINT.
- Distinctive: line 85
If a run stops on an error or does not finish, list each rule it did not check under "Rules not checked".
- Distinctive: line 89
Read these limits before you trust a result:
- Distinctive: line 99
Write a table: each model state, or each group of variable values, to one chart state label.
- Distinctive: line 106
Write a table: each TLC action to one step label, in the reader's words.
- Very specific: line 109
If a step is possible only in some situations, append that situation in square brackets, phrased for the reader, as in you tap pay [while …
- Distinctive: line 114
When a hidden value picks the step's destination, put the outcome in the label, as in "the stock lookup fails".
- Distinctive: line 121
If the distinct state count kept in Run TLC step 5 is above 500, draw only the bug paths.
- Very specific: line 130
Never merge two states that break different rules.
- Distinctive: line 133
If it is still too busy, hide steps the reader can skip, such as a reset available everywhere or an arrow that duplicates others.
- Distinctive: line 143
Add the class lines and a Legend.
- Very specific: line 156
Put a title on the chart with Mermaid front matter title:.
- Distinctive: line 165
When the model describes code, re-run each bug path on the real code, as a test or a live reproduction, one code step per model action.
- Distinctive: line 181
If no TLC run backs the chart, put "not model-checked" in its title and in the handoff.
“Common” is measured: kept by at least 6 in 10 of the 28 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Statechart
Rewrite of cursor/plugins pstack/skills/statechart @ 3dbd22ff12742fb28c9700b9760baa29ed41dc13 (MIT), method only. Compress, not a paste. Pin: SOURCES.md.
A statechart draws the states a system passes through and the steps
between them, labelled for the reader, who judges whether the behavior is right. The deliverable is
plain Mermaid stateDiagram-v2 text, written by hand. Rendering it is optional.
Names
- Reader — whoever decides whether the charted behavior is right: the operator, or someone the operator names in writing.
- Reader rule — one rule the reader agrees to, in the reader's words, such as "you are never charged twice". It may concern what a screen shows, an outcome, saved data or a sent message.
- Model state — one state TLC reports: one value for every variable.
- Chart state — one box in the chart, labelled in the reader's words. Several model states can share one chart state.
- Step label — the words on an arrow: the event as the reader would describe it, such as "you tap pay" or "the card is declined".
- Bug path — TLC's shortest trace from a start state to a state that breaks one reader rule.
- Mark — the class
breakson a chart state where every model state behind it breaks a rule, ormayBreakwhere only some do.
Iron law
Never weaken a reader rule to make it hold. When no variable can express a rule, add one to the model. If a rule breaks, report its bug path instead. A chart drawn without a checked model is labelled "not model-checked" in its title and in the handoff.
Actors
- architect or verifier: charts a TLA+ model and reads TLC's results.
- builder: reads TLC results while following a verify skill.
- designer: charts a user flow from approved stories.
Toolbox policies
- Run TLC from the TLA+ tools the product repo already uses. Adding TLA+ tools to a product repo follows formal-verification Toolbox policies step 3.
- Work in a scratch folder outside the repo. When a verify skill keeps the spec in the repo, read the spec there and write every TLC output and chart to the scratch folder.
- Ask the operator only per Asking the operator.
- The upstream pstack
statechartcommand is an operator opt-in, used only when the operator says so in writing, at the operator's own risk. It is TypeScript at cursor/pluginspstackat3dbd22f. It needsmiseand a TypeScript runtime already installed; its first run installs Java and TLC into the user's mise store and needs the network. This toolbox does not vendor it, run it or give an install command for it. Without that opt-in, follow this file.
Chart a checked model
The architect, verifier or builder uses this section.
Write the spec
- Write each reader rule as an
INVARIANTin the config. Name it after the rule. - Write
Nextas a disjunction of named actions, such asYouPressPlay \/ YouPressStop. Without names, every step isNext. - For each correct end state, add one action to
Nextthat is true only in end states and leaves every variable as it is, for exampleFinished == stage \in {"shipped", "cancelled"} /\ UNCHANGED vars. TLC reports any state with no step out as a deadlock, a correct end state included; once those actions exist, every deadlock TLC reports is a bug. - Keep the constants small, or add a
CONSTRAINT, so the state space is finite.
Run TLC
- Run TLC once on the unmodified config with
-workers 1 -dump dot,actionlabels <file>. Keep the output astlc.out. - If TLC reports a broken invariant, a broken
PROPERTYor a deadlock, save its trace as that rule's bug path, intlc-<rule>.out. TLC stops at the first break; for an invariant or a deadlock its trace is the shortest path to it. - Remove that rule from the working copy of the config, keeping earlier
removals; for a deadlock, set
CHECK_DEADLOCK FALSE. Rerun TLC on the working copy with the same flags. - Repeat steps 2 and 3 until no rule breaks.
- Keep the
.dotgraph and the distinct state count from the last run. If the last run finished with no error, it explored every reachable state inside anyCONSTRAINT; otherwise apply step 6. - If a run stops on an error or does not finish, list each rule it did not check under "Rules not checked". Do not mark those rules. A rule not checked can hold or break.
Read these limits before you trust a result:
- A state beyond a
CONSTRAINTorACTION_CONSTRAINTstill has its reader rules checked, but TLC neither expands it nor tests it for deadlock, so a deadlock there stays hidden. - A
VIEWorSYMMETRYmakes TLC fold equivalent states into one. An arrow can lead to that one state rather than to the state the step reaches. Say so in the report.
Map states and steps
- Write a table: each model state, or each group of variable values, to one chart state label. Use what the reader sees or cares about, such as "Checking out" or "Lock taken, save not yet written", never a variable name. The label is a function of the model state alone.
- Choose the form. Flat: one label per state. Nested: a parent state
holds child states, written as
state "Parent" as p { ... }. Parallel: one region per independent part, separated by--inside a parent state. - Write a table: each TLC action to one step label, in the reader's words. Never name the code or the TLA+ action. Actions that land the same way in the chart get one shared label, and so one arrow.
- If a step is possible only in some situations, append that situation
in square brackets, phrased for the reader, as in
you tap pay [while the cart is saving]. In a parallel chart, never bracket a condition on another region; write that region's label, such as[when Offline]. - When a hidden value picks the step's destination, put the outcome in the label, as in "the stock lookup fails".
- A step that stays inside one chart state draws no arrow. If the reader must see that step, split the label.
Draw the chart
- If the distinct state count kept in Run TLC step 5 is above 500, draw only the bug paths; if no rule broke, draw no chart, report the state count, and say that a smaller model is needed to see the graph. Otherwise draw every chart state reachable from a start state, and every arrow.
- Count the arrows. Above about 20, coarsen first: merge values that behave alike under one label, and drop detail the reader can skip, such as a pending call whose answer changes nothing.
- While coarsening, keep every state of every bug path and every mark.
Never merge two states that break different rules; keep them as
separate chart states. A merge that turns
breaksintomayBreakhides where a rule breaks; undo it. - If it is still too busy, hide steps the reader can skip, such as a reset available everywhere or an arrow that duplicates others. Hide every step behind an arrow, or none. Every chart state must stay reachable from a start state. A chart state that can move in the model keeps at least one outgoing arrow.
- Mark broken invariants by their values in the graph's state labels:
breaksif every model state behind a chart state breaks one,mayBreakif only some do. Mark a deadlock on each graph state with no outgoing edge. A brokenPROPERTYgets its bug path only, no mark. The graph explored past each broken rule, so states after a bug appear too. Add the class lines and a Legend. One Legend state per mark names the rules it marks; if two rules break in one state, name both:
stateDiagram-v2 classDef breaks fill:#ffecee,stroke:#e72e3b,color:#cd2834 classDef mayBreak fill:#fff3e6,stroke:#e8730c,color:#b85a06 state "Breaks rule: never charged twice" as legend_breaks class legend_breaks breaks- To color phases, give each phase a
classDefand aclassline. A chart state whose model states are in different phases gets no phase color. - Put a title on the chart with Mermaid front matter
title:.
Report and replay
- For each broken rule, write: the rule's name, the reader's sentence for it, and its bug path as numbered steps in step labels.
- Say which chart state breaks which rule.
- List "Rules not checked", if any, and the steps the chart hides.
- Say what the model leaves out.
- When the model describes code, re-run each bug path on the real code, as a test or a live reproduction, one code step per model action. If a bug does not occur, treat the model as wrong until you show it is not.
- Hand off the Mermaid text in a
mermaidcode block, the report, and the TLC commands that make the files again into a new scratch folder.
Chart a user flow
The designer uses this section for the product's most important user flows.
- Take the flow from stories the operator approved in
ux-design. - Name the reader rules the stories promise, in the reader's words.
- Map each screen or state the user sees to a chart state, and each user action or system event to a step label, per Map states and steps steps 1–6.
- Draw it per Draw the chart steps 2, 4, 7 and 8. Without a checked model, draw no mark.
- If no TLC run backs the chart, put "not model-checked" in its title and in the handoff.
- To check the flow, write it as a spec with the reader rules as invariants and follow Chart a checked model.
- Hand off the Mermaid text in a
mermaidcode block, the stories it came from, and whether it is model-checked.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

