rigortype/rigor/rigor-project-init

Rigor Project Init

End-to-end onboarding for a project that has never run Rigor. The output is a committed .rigor.dist.yml, an explicit adoption mode, and — if the project chooses it — a .rigor-baseline.yml snapshot.

This skill is for users adopting Rigor on their own project. It uses the published rigor executable, installed standalone — Rigor is a tool, not a library, so it does not go in the project's Gemfile. For the install channels (mise recommended) see the manual's Installing Rigor chapter — rigor docs manual/01-installation once any rigor is on PATH, or (pre-install) <https://github.com/rigortype/rigor/blob/master/docs/manual/01-installation.md>. This skill references only public CLI flags and config keys — the same surface rigor --help documents.

First: load the version-current copy

This skill's step detail lives in its references/ files, and its exact commands, flags, and config keys drift between Rigor releases — so 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-project-init

If you already loaded this skill via rigor skill you have the current copy — just proceed. If rigor is not on PATH, this task needs it: run `rigor-next-steps` to install Rigor first, then come back.

Phase 0 — When to use this skill

Trigger when the user says "set up Rigor here", "configure rigor for this app", "add type checking", or runs rigor check in a project that has no .rigor.yml / .rigor.dist.yml.

Do NOT trigger for:

• An existing baseline the user wants to shrink — that is the

rigor-baseline-reduce skill.

• Writing a Rigor plugin for the project's own DSL /

metaprogramming — that is the rigor-plugin-author skill. (This skill points at plugin authoring as an escalation in Phase 8; it does not do it.)

• Tweaking an already-configured project — ordinary edits to an

existing .rigor.yml; no onboarding pipeline needed.

Note — plugin installation

All rigor-* plugins ship bundled inside the `rigortype` gem. No separate installation is needed. Listing a plugin under plugins: in .rigor.dist.yml is sufficient to activate it. The project's Gemfile is untouched by this workflow. See `references/02-configure.md` § "No separate installation needed" for detail.

The central decision — adoption mode

A mature Ruby codebase routinely reports hundreds to thousands of diagnostics the first time rigor check runs. Most are not fresh bugs: some are real-but-empirically-safe (T | nil that production always initialises), some are project style, a minority are genuine latent bugs. Forcing every site to zero before adoption blocks adoption entirely.

So before writing any config, present the user with two modes and let them choose. The mode drives the severity profile, whether a baseline is generated, and how Phase 8 frames the leftover diagnostics.

Both modes give the same core guarantee: a change that introduces a new diagnostic is caught. They differ only in what happens to the diagnostics that exist today. Acknowledge mode parenthesises them behind a baseline and leans on the test suite; strict mode refuses to parenthesise anything.

Recommend acknowledge mode for every project, including new and small ones. Rigor's inference still has gaps, so even a fresh project meets diagnostics on correct code. Under strict mode each one needs a sig/ fix, an RBS workaround, or a reasoned # rigor:disable — work that takes type theory and RBS. Without that knowledge, users rewrite correct code for the tool or scatter suppressions. Acknowledge mode keeps the same regression guard with an exit: a new diagnostic still fails the check, and once it is confirmed as an inference gap, the baseline can absorb it (report the false positive upstream). rigor baseline regenerate rewrites the baseline from every live diagnostic, so run it only when a whole-project rigor check (no path arguments) shows nothing but confirmed false positives; otherwise it silences a real bug alongside them.

Present strict mode as an opt-in for users who know type theory and RBS, want the zero-diagnostic gate, and accept resolving inference gaps themselves — never as the recommendation, and never because the project is new, small, or a library. If the user picks it, tell them how to move to acknowledge mode later: optionally relax severity_profile, re-run triage, then run Phase 7 (generate a baseline and wire baseline:). The profile change comes first because it changes which rules fire.

For a large first run (more than ~100 errors), acknowledge mode also suggests severity_profile: lenient; see Phase 4.

Note the ordering: the error count that feeds the severity_profile choice in Phase 4 is only measured in Phase 6's triage run. Any profile written in Phase 4 is therefore provisional — Phase 6 revisits it against the measured count (see `references/02-configure.md` § "Severity profile").

Non-interactive / agent-driven runs

This skill has several ask-the-user points (the mode choice, the RBS collection install, the final gitignore-and-commit confirmation). A delegation is the user asking, before the run, for the onboarding to proceed without these questions ("set it up, don't ask me"). An ordinary request to set Rigor up is not one: ask as usual. Under a delegation those points resolve without blocking:

• The mode the user pre-declared is settled; record it and skip the

Phase 2 presentation. If the delegation names no mode, choose acknowledge mode and say so in the report — never strict.

• Low-risk, reversible, in-repo confirmations (`rbs collection

install, the .gitignore` addition) are covered by the delegation — act, and note each self-answer in your report.

• Never commit or push under a general delegation. Run the Final

step's file inventory as a report (what was created, what to commit) instead of a question, and leave the commits to the user.

Phase outline

Load each reference when you reach its phase. Phases run in order; the only branch is Phase 7 (acknowledge mode runs it, strict mode skips it). Phase 5 is also optional if the project already has a committed sig/ directory.

Reading order — modules

Escalation paths (Phase 8 preview)

Some diagnostic clusters are neither a quick fix nor honest baseline material. Two of them have a dedicated answer this skill hands off to: