tla-spec

Generate TLA+ specifications and run TLC model checking to detect deadlocks and invariant violations.

Updated Mar 16, 2026
One-click install
npx skills add https://github.com/shihwesley/shihwesleys-harness --skill tla-spec-shihwesley
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: tla-spec
Source: https://github.com/shihwesley/shihwesleys-harness/tree/main/skills/tla-spec
Command: npx skills add https://github.com/shihwesley/shihwesleys-harness --skill tla-spec-shihwesley

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

Formal verification of state machines helps identify impossible states, deadlocks, and invariants violations that runtime testing may overlook by exploring all reachable states with a model checker.

Core Features & Use Cases

  • Generate .tla and .cfg from planning specs or code by using /tla-spec generate <source>
  • Verify generated specs with TLC using /tla-spec verify [machine-name] to detect violations and deadlocks
  • Audit existing code to auto-detect state machines, validate against generated specs, and report drift via /tla-spec audit [path] or /tla-spec drift [machine-name]
  • Support end-to-end workflows from planning to implementation to ensure sound designs and rapid iteration

Quick Start

Provide a source file describing a state machine and run /tla-spec generate <machine-name> to produce the .tla module, .cfg, and README.

Frequently Asked Questions about tla-spec

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I formally verify a state machine for deadlocks and invariant violations?

Formal verification of a state machine uses TLC model checking to exhaustively explore all reachable states, detecting deadlocks, invariant violations, and unreachable states that runtime testing may overlook. You generate a TLA+ specification and run the model checker to validate correctness.

Can I generate a TLA+ specification directly from existing source code?

Yes, you can generate a TLA+ specification from existing code by applying a generation command to the source file. This process extracts the state machine logic and produces a .tla module, a .cfg configuration file, and an evaluation report for model checking.

What is the best way to audit code drift against a formal state machine specification?

Auditing code drift involves auto-detecting state machines in existing code and validating them against previously generated TLA+ specifications. This comparison reports any drift between the implementation and the formal spec, ensuring the deployed code matches the verified design.

When do I need formal verification instead of standard runtime testing for state machines?

You need formal verification when runtime testing is insufficient to guarantee correctness across all possible state transitions. Model checking exhaustively explores the state space to identify impossible states and deadlocks that conventional tests might never trigger during execution.

Does formal verification with TLA+ and TLC work for state machines defined in planning documents?

Yes, formal verification supports end-to-end workflows starting from planning documents. You can generate a TLA+ specification from planning specs, verify the design with TLC before implementation, and subsequently audit the final code against the initial verified specification.

What files are required to run TLC model checking for exhaustive state exploration?

Running TLC model checking requires a .tla module defining the state machine specification and a .cfg configuration file specifying the model parameters. These files are generated automatically from your source code or planning documents to initiate the exhaustive state exploration.