refactor: restructure diagram module and add Sphinx directive

AGENTS.md

@@ -160,6 +160,26 @@ async def test_something(self, sm_runner):
 
 Do **not** manually add async no-op listeners or duplicate test classes — prefer `sm_runner`.
 
+### TDD and coverage requirements
+
+Follow a **test-driven development** approach: tests are not an afterthought — they are a
+first-class requirement that must be part of every implementation plan.
+
+- **Planning phase:** every plan must include test tasks as explicit steps, not a final
+  "add tests" bullet. Identify what needs to be tested (new branches, edge cases, error
+  paths) while designing the implementation.
+- **100% branch coverage is mandatory.** The pre-commit hook enforces `--cov-fail-under=100`
+  with branch coverage enabled. Code that drops coverage will not pass CI.
+- **Verify coverage before committing:** after writing tests, run coverage on the affected
+  modules and check for missing lines/branches:
+  ```bash
+  timeout 120 uv run pytest tests/<test_file>.py --cov=statemachine.<module> --cov-report=term-missing --cov-branch
+  ```
+- **Use pytest fixtures** (`tmp_path`, `monkeypatch`, etc.) — never hardcode paths or
+  use mutable global state when a fixture exists.
+- **Unreachable defensive branches** (e.g., `if` guards that can never be True given the
+  type system) may be marked with `pragma: no cover`, but prefer writing a test first.
+
 ## Linting and formatting
 
 ```bash

docs/conf.py

@@ -51,6 +51,7 @@
     "sphinx.ext.autosectionlabel",
     "sphinx_gallery.gen_gallery",
     "sphinx_copybutton",
+    "statemachine.contrib.diagram.sphinx_ext",
 ]
 
 autosectionlabel_prefix_document = True