New advertisers: 50% off your first month with code FIRSTMONTHSee slots

Formal verification plugin that model-checks TLA+ specs and charts states, flagging broken rules for review.

GitHub stars
32
View on GitHub

What it does

  • Adds /formal-verification:chart, /formal-verification:setup, and /formal-verification:specify for checking, installing, and writing formal models
  • Covers TLC model checking with Mermaid state charts and the shortest path to each rule that breaks
  • Enforces a checksum match on the pinned model checker and renderer before any download is kept
  • Designed for teams whose bugs in critical code paths are hard to reach with ordinary tests

Formal verification for the part of a codebase where a bug costs most. /formal-verification:chart model-checks a TLA+ spec with TLC and draws its states as a Mermaid chart, with the shortest path to each broken rule for a person to judge. /formal-verification:setup checks the toolchain and installs the pinned, checksummed model checker only on a typed yes. A consumer's formal-<area> skill follows reference/formal-skill.md; /formal-verification:specify proposes, writes and checks them.

Add marketplace

/plugin marketplace add melodic-software/claude-code-plugins

Run it inside Claude Code once, then install the plugin below.

Install

/plugin install formal-verification@melodic-software

Run it inside Claude Code after adding the marketplace.

Readme

formal-verification

Formal verification for the part of a codebase where a bug costs most and tests reach least. /formal-verification:specify finds that part, writes a check for it, checks the result against the contract, and refreshes the check when the code changes. /formal-verification:chart checks a TLA+ model with TLC, draws its states as a Mermaid chart, and gives the shortest path to each rule that breaks, for a person to judge. A consumer keeps each model in its own formal-<area> skill, shaped by reference/formal-skill.md.

Install

/plugin marketplace add melodic-software/claude-code-plugins
/plugin install formal-verification@melodic-software

Skills

SkillWhat it does
/formal-verification:specifyBare proposes the promise most worth proving: its harm, its tool and the formal-<area> folder create would write; it writes nothing. create "<promise>" first checks that your project instructions opt in to the enforcement ladder's formal-verification rung (without it, it goes on only on your yes for that run, and an unattended run reports blocked: formal verification not opted in), chooses the tool with you, writes the model and the formal-<area> skill, and proves a seeded break, made in a throwaway git worktree, is caught; create --unattended is a dry run. check runs scripts/check.mjs, the contract check. refresh brings each check back in line with code changed since its sync commit and ends it in sync, updated, bug or blocked: it changes a property only on your yes, files a replayed bug through /bugs:write and /work-items:track add, and commits the verification alone, on your ticket branch or on a formal-verification-upkeep/<folder> branch through one pull request; --convert <skill-dir> turns a verification skill outside the contract into a formal-<area> skill, attended only. Names no verification tool and installs none. Model-invoked too, so /corrections:codify can chain to it.
/formal-verification:chartModel-checks a TLA+ spec with TLC and writes chart.mmd and report.md: each rule that holds, each that breaks with its shortest path, and the rules a bound left unchecked. Model-invoked too, so a formal-<area> skill's Run can call it.
/formal-verification:setupcheck reports the script runtime, Java, the model checker and the renderer; apply install-model-checker and apply install-renderer download the pinned file into the plugin data directory and keep it only when its checksum matches. Typed only.

Configuration

Machine paths are plugin options, set through /plugin configure: the model checker jar, the Java binary and the script runtime (the options block below).

Version pins and default bounds are keys in the consumer's docs/conventions/formal-verification.yaml, checked against schemas/formal-verification.schema.json. An absent key takes the shipped value in defaults.json. Download URLs and checksums are not settings: they live only in releases.json, and a version chosen in the convention file must have an entry there. The convention files can only remove modules from the shipped allowed_modules: a module they add is dropped, with a line naming it. scripts/settings.mjs prints the resolved values:

node <plugin root>/scripts/settings.mjs --project-dir .

A bound for one model goes in that model's run command (--chart-states, --rerun-states), in its formal-<area> skill.

skills_dir (default .claude/skills) is where formal-<area> skills live. check.on_stale (warn by default, or fail) says what the contract check reports for a check whose covered code changed after its sync commit; a sync.yaml entry's own on_stale wins over it.

The contract check

scripts/check.mjs passes or fails each formal-<area> skill against reference/formal-skill.md and edits nothing:

node <plugin root>/scripts/check.mjs --project-dir . [--skills-dir DIR] [--default-ref REF] [SKILL_DIR...]

--default-ref names the default branch's ref; a sync or seeded-break commit not on it fails, because a squash or rebase merge discards a commit only a feature branch holds. A ref that does not resolve draws one warning and skips that check.

A stale-coverage line names the check and /formal-verification:specify refresh; in CI it is the advisory for a pull request that touches a covered path, a failure only under on_stale: fail.

--skills-dir wins over the skills_dir key; CI passes .claude/skills so the pull request's own convention file cannot move the check. It exits 0 with no failure, 1 with one, and 2 when it cannot run. It reads git history, so a shallow clone fails the sync-commit check.

Prerequisites

ToolWho installs it
A script runtime: Node, Bun or Deno (the launcher names the versions it accepts)You.
Java (the java.min_version setting)You. The plugin never installs Java.
The TLC model checker, tla2tools.jar/formal-verification:setup apply install-model-checker, on your typed request, from the pinned URL and SHA-256. Or point the model checker jar option at your own.
The Pele renderer, only for an image of a chart/formal-verification:setup apply install-renderer, from the pinned tarball and integrity string.

No script installs anything while a skill runs, and an unattended run that finds the toolchain missing reports blocked: toolchain missing and stops. prerequisites.json declares the runtime, Java, the jar and the renderer for /harness-ops:prerequisites; scripts/toolchain.mjs check also checks the jar's pinned SHA-256.

Tests

node --test scripts/toolchain.test.mjs covers settings resolution and the toolchain check and install; node --test scripts/check.test.mjs covers the contract check. The chart scripts carry their own suite under skills/chart/scripts/test/.

Options reference

Generated from this plugin's .claude-plugin/plugin.json. For how Claude Code asks for these and hands them to the plugin, see User configuration.

OptionTypeDefaultDescription
model_checker_jarfile(none)Path to tla2tools.jar, the TLC model checker. Unset uses the jar that setup installs under the plugin data directory.
javafile(none)Path to the java binary that runs TLC. Unset uses java on PATH. The plugin never installs Java.
script_runtimefile(none)Path to the Node, Bun or Deno binary that runs the chart scripts. Unset lets the launcher pick the first supported one on PATH.

How to set these

Set the options above for formal-verification@<marketplace>, replacing <marketplace> with the marketplace you installed this plugin from:

Do not uninstall the plugin to reconfigure it: see What an uninstall deletes and keeps. For a Claude Code release without plugin configure, see Plugin install.

Upstream documentation

Attribution

/formal-verification:chart carries the statechart skill of pstack in cursor/plugins, its text and its scripts, changed so that the scripts take the jar, Java and bounds as arguments and install nothing. /formal-verification:specify and the formal-<area> contract carry the text of pstack's create-formal-verification-skill and maintain-formal-verification-skill, except its sentence "TLA+ is the default": per ADR 0101, the tool is chosen from the consumer's repository and recorded only in its formal-<area> skill. The record is docs/upstream/cursor-pstack.md. Those files are used under this license:

MIT License

Copyright (c) 2026 Lauren Tan

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

Details

Marketplace
melodic-software/claude-code-plugins
Source
plugins/formal-verification
Category
Testing

More from melodic-software/claude-code-plugins

All 139

Similar to formal-verification

More Testing & Code Quality