Rimsky

rimsky-docs

Agent-facing documentation for rimsky, the reactive node-graph orchestration platform — packaged so a coding agent can install it as a skill or read it as docs. This repository is both the documentation corpus and a Claude Code plugin marketplace that ships it.

The corpus is reconciled against a pinned rimsky release (the version is recorded in rimsky/.claude-plugin/plugin.json). The skill is that version: install the skill for rimsky X.Y.Z and you get docs that describe rimsky X.Y.Z.

Two ways to consume it

Either way, the corpus is the same files under rimsky/skills/rimsky/.

1. Install it as a Claude Code skill (entry point: SKILL.md):

   /plugin marketplace add rimsky-ai/rimsky-docs
   /plugin install rimsky@rimsky-docs
   

   The rimsky skill is a read-only knowledge router. It loads when a task looks rimsky-shaped (or on /rimsky:rimsky), carries the mental model, and points at the right corpus file on demand. It does not drive your design process, so it composes alongside your own planning workflow or plan mode.

2. Read it as docs (entry point: llms.txt). Point any coding agent at this repo and tell it the docs live under rimsky/skills/rimsky/. SKILL.md is the Claude Code entry point; rimsky/skills/rimsky/docs/agents/llms.txt is the llms.txt-style entry point for other agents.

Layout

.claude-plugin/marketplace.json   # marketplace manifest — lists one plugin, "rimsky"
rimsky/                           # the plugin
  .claude-plugin/plugin.json      # plugin manifest — version tracks the rimsky release
  skills/rimsky/
    SKILL.md                      # the skill router (entry point #1)
    docs/                         # the corpus (concepts, protocols, reference, cookbook,
                                  #   patterns, services, images, agents/{examples,errors}, …)
    docs/agents/llms.txt          # compact agent index (entry point #2)
    docs/agents/llms-full.txt     # whole corpus concatenated for single-file retrieval
cmd/                              # Go tooling (own go.mod; stdlib + gopkg.in/yaml.v3 only)
llms.txt, llms-full.txt           # repo-root mirror copies of the canonical agents/ files,
                                  #   regenerated by rimsky-docs-llms-full
.claude/skills/{build-docs,refine-docs}   # project-local skills that MAINTAIN this corpus
                                  #   (not part of the distributed plugin)

Note the nesting: a marketplace lists plugins, a plugin can't sit at the marketplace root, and a plugin's skills live under skills/. So the corpus is at rimsky/skills/rimsky/docs/, not at the repo root.

Tooling (cmd/)

A single Go module (stdlib + gopkg.in/yaml.v3) with eight binaries. The generators write into the corpus under rimsky/skills/rimsky/docs/; the lint binary validates it.

• rimsky-docs-lint — five structural lints (all runs every one): concept/error frontmatter, glossary parity, citation drift, internal link validity, and llms.txt validity. Mechanical correctness only; word choice and user-facing clarity are the doc-writing skills' judgment.
• rimsky-docs-llms-full — concatenates the rimsky concept bodies and the docs/protocols/*.md guides into docs/agents/llms-full.txt, plus the repo-root llms-full.txt mirror.
• rimsky-docs-glossary — publishes docs/glossary.md as a verbatim copy of rimsky's concept catalog.
• rimsky-docs-proto, -gopkg, -template-ref, -rest-ref, -cli-ref — generate the definitive reference surfaces (wire protocol, Go helper packages, the rimsky.yml/template schema, the REST control-API routes, and the CLI command tree) from rimsky source. Never hand-edit their output.

The RIMSKY_REPO convention

Every binary under cmd/ requires the RIMSKY_REPO environment variable to point at a local rimsky checkout; they exit non-zero with a helpful message when it is unset. The convention is load-bearing for the pre-release reconciliation gate: rimsky's release script invokes this tooling from a pinned rimsky-docs checkout with RIMSKY_REPO set to the about-to-release rimsky tip, so drift between docs and source surfaces before any tag is cut.

Typical invocation from a rimsky-docs checkout sitting next to a local rimsky-core checkout:

cd cmd && RIMSKY_REPO=$(pwd)/../../rimsky-core go run ./rimsky-docs-lint all
cd cmd && RIMSKY_REPO=$(pwd)/../../rimsky-core go run ./rimsky-docs-llms-full
cd cmd && RIMSKY_REPO=$(pwd)/../../rimsky-core go run ./rimsky-docs-glossary

Building and testing

cd cmd && go build ./... && go test ./...

The cmd test suite is self-contained (it uses fixtures under testdata/ and does not require RIMSKY_REPO or a Docker daemon). The reconciliation gate — running the generators and rimsky-docs-lint all against a real RIMSKY_REPO — is what requires a rimsky checkout.

Maintaining the corpus

Two project-local skills (under .claude/skills/, in-repo, not shipped in the plugin) keep the published corpus current against rimsky:

• /build-docs — full reconcile pass over every surface against the latest rimsky release, then build / test / generate / lint until green.
• /refine-docs — the review → fix → converge loop, run standalone or invoked by build-docs.

Both also keep the skill itself current: the SKILL.md router and the plugin.json version stamp are reconciled surfaces, not set-and-forget files.