Sirno

Semantic Intermediate Representation of Nominal Objects

Sirno is a development harness for project design. Its full name is literal: a Semantic Intermediate Representation of Nominal Objects. It is semantic because entries carry design meaning. It is intermediate because the lake sits between intent and implementation. It is a representation because entries, structural fields, and witnesses give that meaning form. It is nominal because each design object is named first by an entry id.

Lake: a queryable, misty collection of Markdown entries.
Entry: a named design object whose id acts as a symbol.
Witness: a link from a design claim back to the code, tests, config files, or assets it describes.
Frost: history for frozen lake snapshots.
Tide: the design review worklist between frost commits, preventing locally reasonable changes from freezing into suboptimal design.

This is the dawn of documentation-driven development.

TL;DR

If you've heard of RAG, Sirno is human-readable RAG that evolves naturally along with the project, avoiding cache invalidation, infamously one of the two major headaches in computer science (followed by naming variables, and off-by-one errors).

If you've heard of harness engineering, Sirno is a documentation harness that keeps design readable, connected, and resilient to drift. No more vibe-coded slop that only the author can understand -- or should we say not even the author can understand?

If you've heard of {spec/test/intent}-driven development, Sirno believe in all of them, and integrate these ideas and just consider them documentations of different aspects. Details should be so abundant that the codebase can be trivially recovered from the documentation alone.

This is what we call documentation-driven development. Any novelty should be contained in the documentation itself. Documentation should be able to choose its own form and representation. If a program is the best form for expressing an algorithm or even a particular design idea, then so be it.

Sirno keeps project design in a queryable lake of small, named Markdown entries. Each entry has a stable id, structural field edges, and witnesses linking back to code, tests, or assets, so the design stays readable, connected, and resistant to drift.

First, in an agent session inside the repo, send this prompt to install Sirno and register the MCP server:

Check that you're in the sirno repository right now.
Use $sirno-bootstrap to install Sirno and setup MCP in this repository if not already done.

Then restart your agent so the sirno MCP server loads, and start the introduction session in the fresh conversation:

Start an introduction session with $sirno-narrative-session based on sirno-lake/introduction.md:
I am new to Sirno. Ask about my background and goals. Guide me through the entries I should care about.

Setup Sirno and Quick Start

cargo install sirno

Setup completion if you like:

source <(sirno util completion zsh)   # or bash, fish, powershell
# or if you want to guard it:
# command -v sirno &>/dev/null && source <(sirno util completion zsh)

To use it, initialize it in your project:

sirno init

which opens an interactive setup plan. The full plan creates:

a lake (documentation directory)
a frost (history store)
Sirno.toml (project level configuration)
Sirno.lock.toml (project state management; don't edit or delete this)
a few wrapper skills that teach your agent how to talk to the MCP server

Use sirno init --all to run the full setup without prompts. Use sirno init --all --claude-skills to also link those wrappers into .claude/skills. You may also recreate them separately later with their own commands.

For LLM: in MCP

For Codex, register the server from the project root:

codex mcp add sirno -- sirno util mcp

For Claude Code:

claude mcp add sirno -- sirno util mcp

For agents that read an MCP config file directly, add an equivalent stdio server:

{
  "mcpServers": {
    "sirno": {
      "command": "sirno",
      "args": ["util", "mcp"]
    }
  }
}

Edit the generated Markdown, then ask the agent to re-query and re-check. Add a sirno:witness:architecture:begin block in code to link evidence back to the entry, and inspect it with sirno_entry_witness.

For Human: in CLI

Start a lake of your own:

sirno init                                   # choose config, lake, frost, skills
sirno new architecture --name "Architecture" \
  --desc "How the system is structured"      # create one entry
sirno check --mode edit                      # check while editing; dangling refs are warnings

Edit the generated Markdown under the lake path, then re-run check. Add a sirno:witness:architecture:begin and sirno:witness:architecture:end block in code to link evidence back to the entry.

Frost is the history layer for the lake: the lake stays mutable while you draft, while frost keeps the frozen snapshots you commit, stored separately over eter. Sirno.lock.toml records whether the lake is current or pinned to a frozen version.

sirno commit                                 # freeze the current lake into a new frost version
sirno checkout <version>                     # materialize a past frost version (read-only)
sirno defrost                                # check the latest version back out as writable

Tide is the design review worklist between frost commits. Editing one entry ripples to its structural neighbors; tide tracks those as workitems you resolve before the next commit, so locally reasonable changes do not freeze into suboptimal design.

sirno tide status                            # entry ids that still need review
sirno tide status --show full                # full open workitems
sirno resolve <entry-id>                     # mark a workitem reviewed
sirno reset                                  # clear all tide resolutions

Explore an existing lake; this repository keeps its current design source in sirno-lake/:

sirno status                                 # project, tide, and commit readiness
sirno check --mode review                    # review boundary; dangling refs are errors
sirno query --columns id,desc                # list entry ids and desc as a table
sirno query --has category=meta              # filter by structural field target
sirno witness readme --full                  # show how this README witnesses its own intention

Minute Motivation

Design work has a familiar failure mode. It begins as a clear explanation, then scatters across code, tests, comments, review threads, and the memory of whoever last touched the project. The next person or agent has to reconstruct the design before making a responsible change.

Sirno gives that missing middle a named form. It keeps design in a lake of compact Markdown entries: prose small enough to read locally, metadata exact enough to query, and ids stable enough to cite from code, review, or automation.

Our Thoughts, Our Ambitions, The Principles We Would Follow.

Sirno follows a few guiding principles that wishes to help the project reach its goal, quoting Melina from Elden Ring.

Concept-Driven Documentation

Sirno makes documentation compressed and comprehensive through concept-driven development. Important ideas become named entries. Each entry is small enough to read in place, but precise enough to connect with other entries through metadata. Comprehensive documentation becomes a graph of durable concepts, not one long page that every reader has to hold in memory.

Repository Witness

Documentation should not float away from the repository. Sirno lets repository artifacts witness entry claims by entry id. The design stays in prose, the evidence stays in code, tests, configuration, generated files, or assets, and the shared id lets a reviewer move between them mechanically.

Meta Documentation

A Sirno-managed project can document its own documentation method. Entries categorized by meta define vocabulary, reader routes, splitting habits, term style, and local rules for how the lake should grow. The documentation paradigm can live inside the project documentation itself.

Interactive Narrative

Understanding is a deeply personalized journey. An interactive narrative turns the lake into a route shaped around the reader's background and goals. It chooses which entries to visit first, which details to defer, and when to stop and assess learning retention.

Try it with our repository-local narrative-session skill:

Use $sirno-narrative-session for an introduction session based on sirno-lake/introduction.md.
I am new to Sirno. Ask about my background and goals. Guide me through the entries I should care about.

Status

Sirno currently provides a Rust library, both CLI and MCP for Markdown entry storage, project configuration, structural checks, generated footers, querying, lake-local ripgrep search, witness lookup over mosaika, entry freezing, and optional frost snapshots over eter.

Future interfaces may add lightweight GUI, or Obsidian integration.

License

Sirno is distributed under either the MIT license or the Apache License, Version 2.0:

sirno 0.0.5