Engineering standards that agents can apply.
You write your standards as short RFC 2119 rules. shall finds the rules that apply to a change and checks the change against them.

Quick start · Review · Write standards · Hooks · How it works · Results

---

A standard is a Markdown file with numbered rules, for example "Every outbound call MUST set a timeout". shall checks pull requests, design specs, documents, existing code and the tool calls of an agent against these rules.

• People write and own the standards. They review them like code.
• Jev (TypeSafe) finds the rules that apply to each file of a change. It gives a calibrated probability for each rule.
• Claude reviews the change against only those rules and writes inline comments.
• Deterministic code validates each comment and checks blocking findings against the rest of the repository. Then it posts the comments to the pull request.

pull request ─► split per file ─► rules that apply (Jev) ─► review (Claude, no tools)
             ─► validate + verify against the repo (code) ─► PR comments + exit code

shall is a proof of concept. The idea comes from Cloudflare's engineering standards enforcement. Read what we measured and the known limits.

What you can do with it

Task	Command	Page
Find the rules that apply to a change or a task	shall select	Review
Review a pull request, a spec or a document	shall review	Review
Review each pull request in CI and block merges	shall-pr-review	CI
Check the tool calls of an agent while it works	Claude Code hooks	Hooks
Lint existing files	shall scan	Scan
Sort the comments of other AI reviewers	shall triage	Triage
Write, change and retire standards	shall new, lint, build	Standards

Quick start

You need git, make, uv and a TYPESAFE_API_KEY. A full review also needs Claude Code. Read Installation for the full list.

Important

A review sends the diff to TypeSafe and to Anthropic. Make sure that your organisation permits this before you use shall on private code.

Clone the repository and run the checks. These steps do not need a key:

git clone https://github.com/gabe4coding/shall.git
cd shall
make check
make test

Put the CLI on your PATH and set the key:

export PATH="$PWD/plugins/shall/bin:$PATH"
export TYPESAFE_API_KEY=...

Find the rules that apply to a sample change (Jev, approximately 2 seconds):

shall --config shall.yaml select eval/cases/01-booking-endpoint.diff
shall --config shall.yaml select --text "add an endpoint to refund a payment"

Review the sample change (Jev and Claude, approximately 1 minute):

shall --config shall.yaml review eval/cases/01-booking-endpoint.diff --out-dir .shall-out/demo
cat .shall-out/demo/review.md

--config shall.yaml selects the example organisation corpus in this repository. Without it, shall uses the rules of this repository for its own code (.shall/).

With the Claude Code plugin

claude plugin marketplace add gabe4coding/shall
claude plugin install shall@shall

The plugin gives Claude Code the shall command, the skills, the reviewer agents and the hooks. In a repository with shall standards, Claude finds the rules that apply before it writes code. Ask "check this PR against our standards" or "write a standard for idempotent retries". The hooks check each tool call of the agent with Jev when TYPESAFE_API_KEY is set, and with Claude (Haiku) when it is not set. Read Hooks.

Use it in your repository

Point shall at the corpus of your organisation, pinned to a tag. Then review a branch:

export SHALL_EXTENDS=your-org/engineering-standards@v2026.09
git diff origin/main...HEAD > /tmp/pr.diff
shall review /tmp/pr.diff --out-dir .shall-out/pr

To add rules for one repository only, read Review → Local rules. To create the corpus of your organisation, read Standards → Create a corpus.

Documentation

Page	Content
Installation	Requirements, the CLI, the Claude Code plugin
Review	Select and review, local rules, outputs, exit codes
CI	Review each pull request in GitHub Actions or another CI, cost
Hooks	Check the tool calls of an agent while it works
Scan	Lint whole files with the judgment of the hooks
Triage	Sort the comments of Copilot, CodeRabbit and other AI reviewers
Standards	Write and maintain standards, known effects, your own corpus
Configuration	Configuration layers, settings, environment variables
Commands	Every shall command
Architecture	How selection, review, verification and hooks work
Results	Measurements and lessons
Known limits	What shall does not do yet
Development	Repository layout, tests, evals, releases

License

MIT. See LICENSE.