rigortype/rigor/rigor-plugin-author

Rigor Plugin Author (external)

Author a Rigor plugin in your own repository — to teach Rigor a DSL, framework convention, or metaprogramming pattern its core analyzer cannot follow. The result is either a standalone rigor-<id> gem or a project-private plugin.

This skill targets external authors: you depend on the published rigortype gem (bundle add rigortype) and use the public plugin API surface — Rigor::Plugin::Base and friends. It does not assume the rigor monorepo's Makefile, spec/integration/ helpers, or Nix environment.

Authoring inside the rigor monorepo instead? If you are adding

a plugin to rigor's own plugins/ or examples/ tree, use the

contributor rigor-plugin-author skill bundled in that repo — it

covers the in-repo layout, plugin_helpers.rb, and make verify.

This skill is for plugins that live in your project.

First: load the version-current copy

The plugin contract is pre-1.0 and moving (see the next section), so this skill's step detail — in its references/ files — is exactly the kind that drifts between releases. Follow the copy that ships with the installed Rigor rather than any vendored or frozen copy of this file. Get the complete current procedure (body + all references, inline) in one call:

rigor skill --full rigor-plugin-author

If you already loaded this skill via rigor skill you have the current copy — just proceed. If the rigor command is not available, run `rigor-next-steps` to install Rigor first, then come back.

The plugin contract is pre-1.0

Rigor's plugin contract (ADR-2) freezes at rigortype v1.0.0. Until then, treat each rigortype minor release as potentially contract-changing:

• Pin `rigortype` to the minor you built against — "~> X.Y.0"

in your gemspec or Gemfile, where X.Y comes from rigor --version.

• Expect to revisit your plugin when you move to the next minor.

The node-rule block signature, the Diagnostic shape, and the type carriers may shift.

Tell the user this up front: a plugin written today is valuable but not yet on a frozen foundation.

Read a real plugin — rigor plugin

You do not have to learn the Rigor::Plugin::Base surface from this prose alone. Because Rigor is installed on disk (mise / gem install), every plugin bundled in the toolchain is readable source. Use it as a worked-example library throughout this skill:

rigor plugin                                     # all bundled + example plugins, with paths
rigor plugin rigor-activesupport-core-ext        # a plugin's main source, inline
rigor plugin --path rigor-units                  # the dir, to browse with your file tool
rigor plugin --root                              # gem root + public API (lib/rigor/plugin.rb)

rigor plugin (singular) browses the toolchain's plugins; rigor plugins (plural) reports your own .rigor.yml activation — different commands. When a step below is thinner than you need, read a shipped plugin that does the same thing. (Paths are local to where rigor runs — see the command's own note about containers.)

Phase 0 — Standalone gem or project-private?

Decide where the plugin lives before scaffolding anything.

Both produce the same plugin class and walker; they differ only in packaging and activation (Phase 1). When unsure, default to project-private — it is less ceremony, and a plugin can always be extracted into a gem later.

Do NOT use this skill for:

• Onboarding a project to Rigor (writing .rigor.yml, choosing

plugins) → rigor-project-init.

• Reducing a baseline → rigor-baseline-reduce.
• Editing an existing, already-working plugin — that is ordinary

code work; modify the plugin class directly.

How a plugin works — the one-paragraph model

A Rigor plugin is a Ruby class that subclasses Rigor::Plugin::Base, declares a manifest(id:, version:, …), and calls Rigor::Plugin.register(self) at load time. When .rigor.yml lists the plugin under plugins:, Rigor requires it and runs its node rules: the plugin declares node_rule(Prism::CallNode) { |node, scope, path, _fc, context| … }, and the engine — which owns the single AST walk per file — hands every matching node to the block along with a scope it can query for inferred types. The block returns an array of Rigor::Analysis::Diagnostic (built via the diagnostic helper). Optionally the plugin also declares dynamic_return(receivers:) / narrowing_facts(methods:) to supply a return type or narrowing facts for call sites the core analyzer types as Dynamic. #diagnostics_for_file is the file-rule surface for whole-file diagnostics a per-node walk can't express. See Phase 2.

Phase outline

Reading order — modules