Ritual

A Claude Code plugin that turns every mistake into a lesson, every lesson into a rule, and every rule, when it can, into a test or a guard.

English · Español · Português · Français · 中文 · 日本語 · 한국어

Other tools write down what was learned; Ritual goes as far as checking it, because a rule that only lives in text gets forgotten in a long session, and one that checks itself does not.

It ships 86 field lessons, each born from a real mistake; packages per kind of project, whose lessons come from real mistakes in that kind of project or from watching a model build one and break it; and one command, /ritual, that turns the mistakes of your session into your own lessons, and your lessons into rules that enforce themselves.

Measured: a web task Ritual never learned from, built four times without Ritual and four with it, every build reviewed blind. The mistakes that get decided while writing (the error path, keyboard focus, a damaged data file), a group set before the runs, showed up 11 times without Ritual and once with its lessons at the start, as it ships (5 times with the close on too). The mistakes only seen by running did not drop, nor did new mistakes or the total, by the rule set before the runs: Ritual stops the mistakes it has a lesson for, while the code is being written. A build with Ritual and no review ended with no more of the package's mistakes than a build without Ritual after a review and a fix (3.5 against 4.5 on average, within the spread), for $0.61 against $2.64. One task, four builds per arm, one model: the data and the method are in simulations.

Install

claude plugin marketplace add Zurishadday/Ritual
claude plugin install ritual@ritual

Then, in your project, type /ritual. The first time, it works out what you are building from your dependencies and your README, and asks you a single thing: what the project is, which lesson packages to turn on and why, and in which language. Then it creates the .ritual/ folder. That's all the setup there is.

It needs Node 20.17 or newer (node --version). If something doesn't work, type /ritual doctor: it checks Node, your setup and whether the hooks are really running, and says what to fix.

Turn on auto-update once. New lessons arrive often, and Claude Code leaves auto-update off for marketplaces that aren't Anthropic's. Type /plugin, open Marketplaces, choose ritual and Enable auto-update. In the desktop app, ask Claude to "turn on auto-update for the ritual marketplace": it adds "autoUpdate": true to the ritual entry of your Claude Code settings.json. Until you do, Ritual reminds you once a week. To update by hand: claude plugin update ritual@ritual, then start a new session.

claude not found? That happens when you only have the Claude desktop app, which brings its own copy. Install the command line (how): it shares plugins with the app. Then restart the app.

See it in action

Real output from Ritual's own tests, in a web project.

The guard blocks a command your project has already seen fail, and says what to do instead:

$ git push --force origin main
Ritual guard (force-push-to-main): A forced push to main rewrites shared history. Push to a branch and open a pull request.

The first time Claude edits a component, it gets that group's detector questions, once per session (trimmed):

Ritual · Interface and design. Before you continue, run through these detector questions for what you
are about to do. If one applies, act on it and say so in one line; if none applies, just continue.
- 32 · Right after using the control, without moving from where it is, does the user see what changed?
- 45 · If the user does the most likely wrong thing (a typo, an empty answer, two clicks), what do they
       see, and can they keep going?
- WEB-2 · If a thousand fake messages arrive tomorrow, how does the owner find the one real one, and how
          do they delete the rest?
- WEB-4 · After submitting, whether it succeeded or failed, where does focus end up and where does the
          next Tab go?

/ritual starts from what actually happened, not from memory (excerpt):

Log: 1 failed command(s), 1 correction(s), 0 agent report(s)
  10-12 20:05 cmd  npm run build  →  Exit code 1 Type error: Property 'email' does not exist on type 'FormData'
  10-12 20:05 fix  «that is wrong, the form still loses the message»  while Edit src/components/ContactForm.tsx

Guard: 2 block(s) · force-push-to-main ×1, python-c ×1 (details: hooks/guard.mjs --log)

Groups touched in 1 session(s): interface-and-design (1)

How it works

Five things work without you doing anything, through Claude Code's hooks, and a sixth is there when you want it:

This is the beginning of the README. Read the rest at the original. Read the full README ↗