Start a new project
rcas init creates the project file, a first ruleset with golden tests, CI, and optionally the instructions and MCP configuration for your AI coding tools.
Create the project
In the repository of your application (or an empty directory):
rcas init --name "Acme Payments" --lang ts,javarcas init /work/acme-payments (Acme Payments, ids acme.payments.*)
created rcas.yaml
created rules/example.ruleset.yaml
created rules/order.schema.json
created rules/LOADING.md
created .rcas/.gitignore
created .github/workflows/rules.yml
updated .gitignore (.rcas/)| File | Purpose |
|---|---|
rcas.yaml | The project: where rules live, where bundles go, the languages that load them, the API schemas rules are derived from. See project configuration |
rules/example.ruleset.yaml | A first ruleset: one blocking rule, one warning, a parameter with an override policy, messages and three golden tests |
rules/order.schema.json | The entity the example talks about. In your project, point entities at your API's own schemas |
rules/LOADING.md | How each language you chose loads the compiled bundle |
.rcas/ | Proposals waiting for review, and reports; never committed |
.github/workflows/rules.yml | CI: rcas check and rcas compile --all on every pull request (written when the directory is in a git repository, or with --ci github) |
init never replaces a file that exists and differs, unless you pass --force. --dry-run shows what
it would write.
Check and compile
rcas checkacme.payments.example@0.1.0 sha256:ebacd52bdbea... 2 rules (2 client-safe), 1 params
3 golden tests, 0 failedcheck validates every ruleset against the schema, runs the load-time checks of the
specification (inheritance, override policies, unknown fields, portable patterns and YAML), and runs
the golden tests. Then compile:
rcas compile --allacme.payments.example@0.1.0 sha256:ebacd52bdbeaee8a903fdd0d636c3e38fd5f4f2d4f5cd9fd493406204ee36910 -> acme.payments.example.bundle.json, acme.payments.example.client.manifest.jsonThe bundle goes to backends; the client manifest is the part a browser may see.
Evaluate
echo '{"entity":"Order","operation":"create","data":{"quantity":11}}' \
| rcas evaluate --bundle build/rules/acme.payments.example.bundle.json -The answer is deny: order.quantity.max blocks (11 is over 10), and order.note.recommended adds a
warning, because an order of five or more items has no note. Load the same bundle in your
application with the snippet in rules/LOADING.md:
import { readFileSync } from 'node:fs';
import { RuleSet } from '@rules-cascade/core';
const rules = RuleSet.fromBundle(JSON.parse(readFileSync('build/rules/acme.payments.example.bundle.json', 'utf8')));
const result = rules.evaluate({ entity: 'Order', operation: 'create', data: { quantity: 3 } }, 'server');Connect your AI coding tool (optional)
rcas agent install # AGENTS.md, CLAUDE.md, GEMINI.md, Copilot and Cursor rules, sub-agents, a skill
rcas mcp install claude # or codex, cursor, windsurf, gemini, vscode, allOr in one step: rcas init --agent all --mcp claude. See AI coding tools.
rcas init options
rcas init [dir] [--name <name>] [--id-prefix <prefix>] [--lang ts,python,java,go,other] [--from <path>]
[--agent claude,codex,cursor,copilot,gemini|all] [--mcp <client>|all] [--ci github|none] [--force] [--dry-run]| Flag | Meaning |
|---|---|
dir | where to create the project (default: the current directory) |
--name | the project name (default: the directory name) |
--id-prefix | the prefix of ruleset ids, dot-separated lower case, e.g. acme.payments (default: from the name) |
--lang | the languages that load the rules, for LOADING.md and rcas.yaml |
--from | an existing code base: run rcas analyze on it and propose a ruleset for every API schema found |
--agent | also run rcas agent install --for these tools |
--mcp | also run rcas mcp install for these tools |
--ci | github writes .github/workflows/rules.yml; none writes nothing |
--force | replace files that exist and differ |
--dry-run | print what would be written |
Exit status 0, or 2 for a usage error.
Next: write your own rules, or generate them from existing code.
Install
Install rcas, the Rule Cascade command, on macOS, Linux or Windows, with the install script, npm or Go, and the runtime library for your language.
Rules from an existing project
Find the business rules already in your code, derive the schema rules automatically, have an AI agent draft the rest as proposals, and replace the code checks one at a time.