spec-weaver
/spec-weaver
[WHAT IT DOES]: Formally specifies and mathematically proves concurrent, distributed, and state-machine algorithms using TLA+, PlusCal, or automated state-space exploration before implementation. [WHEN TO USE]: Use when the user designs financial ledgers, concurrent transaction logic, distributed locks, consensus protocols, or complex asynchronous workflows where race conditions, deadlocks, or state corruption are critical. [WHEN NOT TO USE]: Do NOT use for basic CRUD operations, static web forms, or synchronous single-threaded UI rendering.
- Author
- kicode01 ↗
- Repository
- spec-weaver ↗
- Licence
- MIT
- Last repository change
- 03.11.2026
Assessment and security
- Files in this package
- 4
- Scripts
- 0
- HTML comments
- 0
- URLs in SKILL.md
- 0
No signals detected. Repository changed on 03.11.2026, without references to retired models or APIs.
MIT, open: use and modify while retaining author attribution.
What it does and when to use it
[WHAT IT DOES]: Formally specifies and mathematically proves concurrent, distributed, and state-machine algorithms using TLA+, PlusCal, or automated state-space exploration before implementation. [WHEN TO USE]: Use when the user designs financial ledgers, concurrent transaction logic, distributed locks, consensus protocols, or complex asynchronous workflows where race conditions, deadlocks, or state corruption are critical. [WHEN NOT TO USE]: Do NOT use for basic CRUD operations, static web forms, or synchronous single-threaded UI rendering.
Original author description
[WHAT IT DOES]: Formally specifies and mathematically proves concurrent, distributed, and state-machine algorithms using TLA+, PlusCal, or automated state-space exploration before implementation. [WHEN TO USE]: Use when the user designs financial ledgers, concurrent transaction logic, distributed locks, consensus protocols, or complex asynchronous workflows where race conditions, deadlocks, or state corruption are critical. [WHEN NOT TO USE]: Do NOT use for basic CRUD operations, static web forms, or synchronous single-threaded UI rendering.
How it works
- 1. When to Activate
- 2. Mathematical Formalization Runbook
- 3. Reference Files
SKILL.md preview
---
name: spec-weaver
description: >-
[WHAT IT DOES]: Formally specifies and mathematically proves concurrent, distributed, and state-machine algorithms
using TLA+, PlusCal, or automated state-space exploration before implementation.
[WHEN TO USE]: Use when the user designs financial ledgers, concurrent transaction logic, distributed locks,
consensus protocols, or complex asynchronous workflows where race conditions, deadlocks, or state corruption are critical.
[WHEN NOT TO USE]: Do NOT use for basic CRUD operations, static web forms, or synchronous single-threaded UI rendering.
---
# Spec Weaver: Mathematical Formal Verification Engine
```
+--------------------------------------------------------------------------+
| SPEC WEAVER |
| Mathematical Invariant & State-Space Proof Engine |
+--------------------------------------------------------------------------+
| |
v v
[State Invariants] [System Transitions]
- Type Invariants - Next State Relations
- Safety: [](NoNegativeBalance) - Message Dropping
- Liveness: <>(TerminalState) - Concurrency Interleaving
| |
+-------------------------+--------------------------+
|
v
[BFS Model Checker Loop]
- Cycle Detection
- Invariant Guard Evaluation
- State-Space Hash Deduplication
|
+----------------+----------------+
| |
[Passed (100%)] [Counterexample]
v v
[Generate Code Scaffold] [Emit Minimal Error Trace]
- Pre/Post Condition Guards - Pinpoint Interleaving Bug
- Mathematical Certificate - Auto-Propose Invariant Fix
```
---
## 1. When to Activate
Trigger `spec-weaver` whenever the user's task involves:
- **Financial & Ledger Systems:** Account balances, currency transfers, multi-party escrow, double-spend prevention.
- **Distributed Concurrency:** Two-phase commits (2PC), leader elections (Raft/Paxos variants), distributed mutexes.
- **Complex Asynchronous Lifecycles:** Stateful job runners, saga orchestrators, retry-with-cancellation pipelines.
- **Elusive Heisenbugs:** Flaky race conditions or deadlock bug reports that are difficult to reproduce with standard unit tests.
---
## 2. Mathematical Formalization Runbook
### Step 1: Elicit Invariants
Before generating code or specs, list the core invariants:
1. **Safety Properties ($\square P$):** "Bad things never happen."
* *Example:* `\A a \in Accounts : balance[a] >= 0`
* *Example:* `Cardinality(ActiveLeaders) <= 1`
2. **Liveness Properties ($\diamondsuit P$):** "Good things eventually happen."
* *Example:* `RequestIssued ~> RequestResolved`
3. **Type Correctness ($TypeOK$):** State bounds, enum domains, set memberships.
### Step 2: Run Automated State-Space Exploration
Execute the Python verification engine to prove the algorithm across all possible interleaved transitions:
```bash
python scripts/verify_invariants.py --demo
```
Or define custom states in Python and run:
```python
from scripts.verify_invariants import StateSpaceVerifier
verifier = StateSpaceVerifier(initial_state={"status": "IDLE", "lock": False})
verifier.add_safety_invariant("ValidStatus", lambda s: s["status"] in {"IDLE", "RUNNING", "DONE"})
verifier.add_transition("Start", lambda s: [{"status": "RUNNING", "lock": True}] if not s["lock"] else [])
is_valid, err, trace = verifier.verify(check_deadlocks=True)
```
### Step 3: Handle Counterexamples
If the model checker finds an invariant violation:
1. Read the minimal state trace emitted by `print_counterexample()`.
2. Locate the specific transition where mutual exclusion was lost or a race occurred.
3. Propose a refined guard (e.g. Compare-And-Swap, atomic transaction boundary, or sequence token).
### Step 4: Export Verified Production Code
Translate the verified transitions into the target language (Go, Rust, TypeScript, Python) with runtime invariant assertion checks embedded directly into the code.
---
## 3. Reference Files
- [verify_invariants.py](./scripts/verify_invariants.py): The industrial-grade BFS state-space model checker.
- [model_template.tla](./templates/model_template.tla): Standard TLA+/PlusCal formal model template.
Files in this package (4)
- .gitignore 1 KB
- LICENSE 1 KB
- README.md 4 KB
- SKILL.md 5 KB
Versions
The database has no other skills named spec-weaver.
Database snapshot: 13.11.2026 · package version 67c01ec72407 (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
- 100tla-model
Models concurrent and distributed designs in TLA+ or PlusCal and checks them with the TLC model checker. Use when asked to write, review, or debug a TLA+ spec, .tla/.cfg files, or TLC output, or to model-check or formally verify a protocol, lock, lease, consensus, replication,… - 100tla
Formally verify a capability's invariants with TLA+ and TLC, and record the result as metamodel Evidence. Use when the constitution's formal verification assessment flags a component (concurrency, distributed state, financial transactions, safety-critical logic, complex state machines, protocols). - 100tlaplus-spec-generator
Automatically generate TLA+ specifications from source code (C/C++, Python) for formal verification of distributed systems. Use when users need to: (1) Generate TLA+ specs from program implementations, (2) Model distributed systems, consensus protocols, or concurrent algorithms,… - 100program-to-tlaplus-spec-generator
Automatically generate TLA+ specifications from program code, repositories, or system implementations. Use when asked to generate TLA+ spec, create TLA+ specification from code, convert program to TLA+, formalize system in TLA+, extract TLA+ model from code, or when working with… - 100slo-tla
Use this skill when /slo-architect has set tla_required=true, or when the user asks to "verify the design", "model check", "prove this is correct", "add TLA+ to this plan", or whenever a design involves concurrent actors, distributed state, ordering guarantees, resource… - 90tlaplus
Use to model-check real code or a design with TLA+ and TLC. Model retries, locks, async flows, protocols or state machines as written, check invariants over every interleaving, and reproduce any counterexample trace as a failing test. Dispatched by /engineer.harden for…