tla-plus
Create, run, and verify TLA+ and PlusCal formal specifications. Use for modeling distributed systems, protocols, concurrent algorithms, state machines. Can compose specs from code, find divergences between spec and implementation, spot concurrency bugs and invariant violations. Use when asked to "write a TLA+ spec", "model check", "verify protocol", "find race conditions", or "formal verification".
- License 许可
- Apache-2.0
- 所属仓库
- apache/cassandra
- 最近更新
- 2026-11-14
- Stars
- ★ 1.0w
- Forks
- 4.1k
01 前言 Front Matter
- name
- tla-plus
- version
- 1.0.0
- description
- Create, run, and verify TLA+ and PlusCal formal specifications. Use for modeling distributed systems, protocols, concurrent algorithms, state machines. Can compose specs from code, find divergences between spec and implementation, spot concurrency bugs and invariant violations. Use when asked to "write a TLA+ spec", "model check", "verify protocol", "find race conditions", or "formal verification".
02 资源文件 22
- 参考文档references/bootstrap-registration.md3.5 KB
- 参考文档references/build-test-and-runtime-validation.md6.6 KB
- 参考文档references/config-data-and-async.md3.6 KB
- 参考文档references/language.md5.3 KB
- 参考文档references/maps-heroes-and-feature-modules.md3.5 KB
- 参考文档references/minigame-instance-flow.md7.0 KB
- 参考文档references/patterns/code-to-spec.md6.0 KB
- 参考文档references/patterns/distributed-systems.md5.7 KB
- 参考文档references/patterns/invariants.md5.4 KB
- 参考文档references/patterns/protocols.md5.5 KB
- 参考文档references/persistent-progression-and-events.md5.8 KB
- 参考文档references/pluscal.md5.1 KB
- 参考文档references/project-patterns.md5.1 KB
- 参考文档references/state-sessions-and-phases.md3.4 KB
- 脚本scripts/check.sh921 B
- 脚本scripts/parse.sh417 B
- 脚本scripts/setup.sh2.9 KB
- 脚本scripts/tlc.sh1.3 KB
- 脚本scripts/translate.sh440 B
- 其他templates/basic.tla930 B
- 其他templates/distributed.tla2.6 KB
- 其他templates/pluscal.tla1004 B
03 SKILL.md 正文
TLA+ Formal Specification Skill
Write non-trivial TLA+ specifications, run the TLC model checker, and bridge the gap between formal specs and implementation code.
Setup (Run Once)
bash SKILL_DIR/scripts/setup.sh
This downloads tla2tools.jar (v1.8.0) and verifies Java 11+. The JAR is stored at SKILL_DIR/lib/tla2tools.jar.
Quick Reference
Load the right reference for your task:
| Task | Reference |
|---|---|
| TLA+ syntax, operators, types | references/language.md |
| PlusCal syntax, processes, labels | references/pluscal.md |
| Distributed systems patterns | references/patterns/distributed-systems.md |
| Protocol specifications | references/patterns/protocols.md |
| Invariants, safety, liveness | references/patterns/invariants.md |
| Code ↔ spec mapping, bug finding | references/patterns/code-to-spec.md |
Load references on-demand — read the ones relevant to the current task before writing any spec.
Templates
Start from a template when creating a new spec:
| Template | Use For |
|---|---|
| templates/basic.tla | Pure TLA+ state machine |
| templates/pluscal.tla | PlusCal algorithm with processes |
| templates/distributed.tla | Distributed system with messages |
Running Specs
Full Check (Recommended)
Translates PlusCal (if present), parses, and model-checks in one step:
bash SKILL_DIR/scripts/check.sh spec.tla --config spec.cfg
Individual Tools
# Parse only (syntax check)
bash SKILL_DIR/scripts/parse.sh spec.tla
# Translate PlusCal to TLA+
bash SKILL_DIR/scripts/translate.sh spec.tla -nocfg
# Model check with TLC
bash SKILL_DIR/scripts/tlc.sh spec.tla --config spec.cfg --workers auto
bash SKILL_DIR/scripts/tlc.sh spec.tla --no-deadlock # suppress deadlock check
Direct Java Invocation
JAR="SKILL_DIR/lib/tla2tools.jar"
# Parse
java -cp "$JAR" tla2sany.SANY spec.tla
# Translate PlusCal
java -cp "$JAR" pcal.trans -nocfg spec.tla
# Model check
java -cp "$JAR" tlc2.TLC -workers auto -config spec.cfg spec.tla
# REPL
java -cp "$JAR" tlc2.REPL
# Dump state graph (for visualization)
java -cp "$JAR" tlc2.TLC -dump dot,actionlabels,colorize states.dot spec.tla
Workflow: Writing a Spec
1. Understand the System
Before writing any TLA+:
- Identify the concurrent agents (processes, nodes, threads)
- Identify shared mutable state (queues, databases, locks, counters)
- Identify the key safety property ("what must never happen?")
- Identify the key liveness property ("what must eventually happen?")
2. Choose PlusCal vs Pure TLA+
Use PlusCal when:
- The system is naturally sequential/imperative
- You're modeling code (threads, goroutines, async tasks)
- You need
await,while,gotosemantics - The audience is programmers
Use Pure TLA+ when:
- You need fine-grained fairness control
- The system is naturally a state machine
- You need interruptible/restartable actions
- You need refinement mappings
- A single label would need to update a variable twice
3. Start Small, Then Expand
- Write the simplest possible spec that captures the core behavior
- Add a type invariant immediately
- Run TLC with small constants (2-3 nodes, 2-3 messages)
- Add safety invariants one at a time, running after each
- Add liveness properties with fairness
- Increase constants to expand coverage
4. Config File
Every spec needs a .cfg file. Create one alongside the .tla:
SPECIFICATION Spec
\* Properties to check
INVARIANT TypeInvariant
INVARIANT Safety
\* Uncomment for liveness (slower)
\* PROPERTY Liveness
\* Constants
CONSTANT
NumNodes = 3
MaxMsgs = 5
NULL = NULL
\* Uncomment to bound state space
\* CONSTRAINT StateConstraint
\* Uncomment to ignore deadlocks
\* CHECK_DEADLOCK FALSE
Workflow: Spec From Code
When the user has existing code and wants a spec:
- Read the code — understand concurrency structure, shared state, synchronization
- Read references/patterns/code-to-spec.md
- Map constructs — threads→processes, locks→await, channels→queues
- Abstract — don't model every line, only concurrency-relevant operations
- Write spec — start with the concurrent skeleton, add detail iteratively
- Run TLC — find deadlocks, invariant violations, liveness failures
- Report — translate any TLC error traces back to code execution paths
Workflow: Finding Bugs
When comparing a spec to code, or looking for bugs:
- Read references/patterns/code-to-spec.md
- Write a spec modeling the suspected buggy area
- Run with small constants — TLC is exhaustive, small state space is fine
- Interpret error traces — map TLA+ state sequences to code execution paths
- Check atomicity — does the code do atomically what the spec's label does?
- Check completeness — does the code handle all
either/orbranches? - Check ordering — does the code enforce the same happens-before relations?
If TLC finds a violation:
- The error trace is a concrete counterexample — a specific sequence of events
- Map each state in the trace to concrete code state
- The transition that causes the violation is the bug location
Interpreting TLC Output
Success
Model checking completed. No error has been found.
Estimates of the probability that TLC did not check all reachable states
because two distinct states had the same fingerprint:
calculated (optimistic): val: 0
Invariant Violation
Error: Invariant SafetyInvariant is violated.
The following behavior constitutes a counter-example:
State 1: <Initial predicate>
/\ var1 = ...
State 2: <Action line X>
/\ var1 = ... (changed values in red)
Deadlock
Error: Deadlock reached.
→ No process can make progress. Check await conditions and process completion.
Liveness Violation
Error: Temporal properties were violated.
→ Check fairness settings. Add WF_vars or SF_vars. Trace may include a "stuttering" suffix.
Key Principles
- Type invariants first — catch spec bugs before checking real properties
- Small constants — 3 nodes finds most bugs; 10 nodes takes 1000× longer
- Safety before liveness — invariants are faster to check
- One property at a time — add incrementally, run after each addition
- Fairness is opt-in — TLA+ assumes everything can crash by default
=>with\A,/\with\E— never use=>with\E- Sequences are 1-indexed — always
- Every action must specify all variables — use
UNCHANGEDfor untouched ones
04 同仓库更多 Skills
write-reproducer
Write minimal, reliable bug reproducers (repros) for any project. Use when: (1) a bug report or issue needs a test that reliably demonstrates the failure, (2) converting a described failure scenario into runnable code, (3) minimizing an existing complex test to its essential trigger conditions. Covers the full repro workflow: failure characterization, scope selection, writing the repro, verifying it fails for the right reason, and minimizing to the smallest possible trigger.
targeted-review
Findings-driven targeted code review. Understands the patch via patch-explainer and surrounding code via codebase-analysis, then consults a catalog of bug patterns (~11 categories under references/categories/). Picks only categories whose diff-signals match the patch and items whose "look for" hints match actual code shapes, groups them by review focus (function/file/feature), and spawns parallel subagents — each with a tight scope and selective checklist. Use for medium-to-large patches (50-1000 LOC) as a focused alternative to whole-patch ensemble or whole-file deep review. Triggers on: "review this patch/diff/change", "find bugs in this change", "scoped review", "what could go wrong here", "review using findings", or proactive PR review.
shallow-review
Shallow (quick) ensemble bug-finding review using 6 specialist agents in parallel. Each specialist reviews the same patch through a different lens: Logic & Types, Boundaries & I/O, Concurrency & State, Resources & Serialization, Absence Analysis, and API Completeness. Findings are merged and deduplicated. Best for: quick first-pass review of patches, triage of diffs, broad surface-level bug scan. For deeper file-focused review with full pattern catalogs and codebase investigation, use the deep-review skill instead.
patch-explainer
Deep code analysis with ASCII visualizations showing structure, flow, and state transitions. Use when analyzing patches/diffs, explaining classes or subsystems, understanding code architecture, reviewing changes for inconsistencies, or when asked to visualize how code works. Provides before/after diagrams, data/control flow, concurrency analysis, assumptions, and failure modes. Triggers on explain this patch/code/class, how does X work, show me the flow, visualize this change, code review requests, or proactive analysis during PR reviews.
mega-review
Multi-pass deep code review for large patches (1000+ LOC) that maximizes real bug detection. Orchestrates targeted-review, shallow-review, and deep-review in parallel across all HIGH and MEDIUM risk files and commits: understands the feature holistically, splits by file and commit, runs deep review on every HIGH/MEDIUM file, targeted review across the same scope, and per-commit shallow review, followed by cross-cut consistency checks. Use when: reviewing a large patch (feature branch, multi-commit, or single large diff, 1000+ LOC), doing a thorough pre-merge review, or when shallower reviews miss bugs due to patch size. Triggers on: "review this branch", "review these commits", "review this feature", "mega review", "thorough review", "full review of X commits", or when the user specifies a commit range or feature for review.
heatmap
Use git heatmap analysis to identify high-churn files and lines as candidates for thorough review or bug hunting. Works for PR reviews, security audits, bug hunts, or any code analysis task.