smd-engine

Русская версия: README_ru.md

smd is a command-line tool for thinking sessions in the SMD tradition (system-thought-activity, the Shchedrovitsky school). It does five things:

1. Keeps the state of a session as a YAML record: boards, positions, frames, functions, gaps, qualifications, numbered transitions, theses from the transcript, hypotheses, human sign-offs.
2. Checks the record against the schema, the conventions of the method and, across cycles, against the previous cycle.
3. Draws the record as an SVG screen, step-by-step frames, a 3D graph, an index with YAML lines, Markdown, Mermaid or an Obsidian vault. Drawings are generated, never edited by hand.
4. Applies decisions as records: a patch to the current cycle, or the next cycle with the human's sign-offs.
5. Packs a thinking procedure, its roles and lenses into one Markdown file that any model can run, and compares what a run produced with a reference record.

The default screen is the three-board screen of the MIPT program "Третья ступень" (org-activity, object and situation boards). A profile can lay out other boards: classic-two-boards is the classic org-activity and object-ontological pair. Terms that belong to the program and not to the classic method are marked as such in roles/README.md.

Version 0.3.6, schema 0.3. Python 3.14. The engine proposes and checks; a human decides, by sign-offs that each state a function.

Install

Run without installing, from the repository:

uvx --from git+https://github.com/viberesearch/smd-engine smd validate path/to/case

Or install from PyPI:

pip install smd-engine
smd --help

From a checkout, for development (uv only):

uv sync
uv run smd --help

The package carries the procedures, roles, lenses, profiles and the data model, so smd pack works from an installed copy.

Try it

The repository has two invented teaching cases with the same content: cases/example (English labels) and cases/example_ru (Russian labels). Three bakeries consider shared production for independent bakeries of a region.

uv run smd validate cases/example_ru --sources cases/example_ru/sources.yaml --hints
uv run smd render cases/example_ru/pekarni-c2.board.yaml -o out/screen.svg
uv run smd frames cases/example_ru/pekarni-c2.board.yaml -o out/frames.html

Commands

Examples with options are in docs/commands.md; smd <command> --help lists the options.

Data model on one screen

Full format: docs/data-model.md. Records are YAML; JSON Schemas are in src/smd_engine/schemas/.

Inside a board_set:

Rules the validator enforces: nothing lies on a board without a position it is seen from; an AI voice never signs off; an AI variant stays a variant until a human sign-off raises it; every closed K, refined thesis and confirmed result needs its sign-off. Addresses in cites point into sources by id and time, page, turn or line: s3#t=00:08:10.

Profiles

A profile (profiles/*.yaml) holds the boards, the element kinds, the relation kinds, the hints in force and the reading steps of smd frames. A record names its profile in profile; without it, program-three-boards applies. The profile format, with the layout of boards by their regions, is in docs/profiles.md.

An unknown profile, board or kind is an error naming the element. Format and the keys of a profile: docs/data-model.md, section Profiles.

How a case repository uses the engine

A real case lives in the repository of its object of thinking; this repository holds invented examples only. A case repository keeps:

• board sets, one file per cycle (<case>-c1.board.yaml, -c2, ...) and patches (*.patch.yaml);
• one sources.yaml manifest: ids, checksums and the clean-room decision for each source. Raw materials stay where they are and records cite them by id;
• optionally a taxonomies.yaml.

It runs the engine without a local copy, pinned to a release, for example in CI:

uvx --from git+https://github.com/viberesearch/smd-engine@v0.3.6 smd validate . --sources sources.yaml --strict

Generated drawings (smd publish) are build output and are not committed. Records of an older schema are moved with smd migrate.

Run a procedure with any model

A procedure (procedures/*.md) is a model-agnostic prompt. The roles and lenses it uses, and the data model, are packed with it:

smd pack small-situation cases/example/bakeries-c1.board.yaml --sources cases/example/sources.yaml -o pack.md

1. Attach pack.md and the source files the procedure names to any model, and say "run this procedure".
2. The model returns a record. It proposes; it does not sign off. Decisions it cannot take go to state.open.
3. Save the record and run smd validate on it. Fix what it reports.
4. For a reference run, smd eval run.board.yaml expected.board.yaml --min-agreement N shows whether the run got worse (cases/example/golden/README.md).
5. Record the human's decisions as sign-offs or as a patch (smd apply), and open the next cycle with smd revise.

In Claude Code, inside this repository, /procedure <id> <inputs> runs a procedure directly; role subagents are in .claude/agents/. smd pack --help lists the options. The procedures are listed in procedures/README.md, the lenses in lenses/README.md.

Repository contents

Licence

Code is under the MIT licence (LICENSE). Method notes, procedures, roles, lenses, profiles and the example cases (docs/, procedures/, roles/, lenses/, profiles/, cases/) are under CC BY 4.0: reuse them with attribution. Copyright (c) 2026 viberesearch.

The method notes summarise published work of G. P. Shchedrovitsky and others and cite it (docs/method/sources.md); the original texts keep their own rights.