AI coding agents
rcas agent install teaches an AI coding agent how this project handles business rules, and rcas mcp install gives it the tools to do it.
rcas agent install teaches an AI coding agent how this project handles business rules, and
rcas mcp install gives it the tools to do it. This page is the reference: what is written for which
tool, how the choice is made, and how a team adapts it. The tutorial is
AI coding tools.
What gets written
Every install writes the portable part, which most tools read as it is:
| File | What |
|---|---|
AGENTS.md | A managed block (between rcas:begin and rcas:end): where rules live, how to work (propose, never edit), the engineering rules for rulesets, the commands, and the list of skills. The rest of the file is yours |
.agents/skills/<skill>/SKILL.md | The skills, in the open Agent Skills format |
and, for each chosen tool, what that tool needs on top:
| Tool | --for | Also writes | Reads of the portable part |
|---|---|---|---|
| Claude Code | claude | CLAUDE.md (imports @AGENTS.md), .claude/skills/, sub-agents .claude/agents/rcas-*.md | AGENTS.md only when no CLAUDE.md exists; skills only from .claude/skills |
| OpenAI Codex (CLI, IDE, app) | codex | sub-agents .codex/agents/rcas-*.toml | AGENTS.md, .agents/skills |
| GitHub Copilot (VS Code, cloud agent, CLI) | copilot | .github/instructions/rules-cascade.instructions.md (applies to rulesets), custom agents .github/agents/rcas-*.agent.md unless claude is chosen too | AGENTS.md, .agents/skills, .claude/agents |
| Cursor | cursor | .cursor/rules/rules-cascade.mdc (applies to rulesets), sub-agents .cursor/agents/rcas-*.md unless claude is chosen too | AGENTS.md, .agents/skills, .claude/agents |
| Gemini CLI | gemini | GEMINI.md (a managed block with the instructions) | .agents/skills; AGENTS.md only when configured |
| Kiro (IDE and CLI) | kiro | .kiro/steering/rules-cascade.md (applies to rulesets), .kiro/skills/ | AGENTS.md; skills only from .kiro/skills |
| Devin Desktop and Devin CLI (formerly Windsurf) | devin (alias windsurf) | .devin/rules/rules-cascade.md (applies to rulesets) | AGENTS.md, .agents/skills |
| JetBrains Junie | junie | sub-agents .junie/agents/rcas-*.md | AGENTS.md, .agents/skills |
| Cline | cline | .clinerules/rules-cascade.md (applies to rulesets), .cline/skills/ unless claude is chosen too | AGENTS.md; skills from .cline/skills or .claude/skills |
| OpenCode | opencode | sub-agents .opencode/agents/rcas-*.md | AGENTS.md, .agents/skills |
| Factory Droid | factory | droids .factory/droids/rcas-*.md | AGENTS.md, .agents/skills |
| Amazon Q Developer | amazonq | .amazonq/rules/rules-cascade.md | its own rules folder (Kiro supersedes it) |
| Tabnine | tabnine | .tabnine/guidelines/rules-cascade.md | .agents/skills (CLI) |
| Meta Muse Code, Amp, Goose, Warp, Zed, Kilo Code, Augment Code | muse, amp, goose, warp, zed, kilo, augment | nothing more | AGENTS.md, .agents/skills |
Zed reads only the first instructions file it finds at the root, in this order: .rules,
.cursorrules, .windsurfrules, .clinerules, .github/copilot-instructions.md, AGENT.md,
AGENTS.md. When one of the earlier files exists, add a line to it that points to AGENTS.md.
Aider reads no instructions file by itself: run aider --read AGENTS.md, or add read: AGENTS.md
to .aider.conf.yml.
The sub-agents
Four roles, written for the tools that support sub-agents or custom agents:
| Role | Does | Changes files |
|---|---|---|
rcas-analyst | Inventories the business rules hidden in the code, with file:line evidence | no |
rcas-author | Writes or changes rulesets with golden tests, submits them as proposals | proposals only |
rcas-reviewer | Reviews a change or a proposal against the authoring guide | no |
rcas-tester | Writes golden tests and parity tests between a rule and the code it replaces | proposals, and tests when asked |
The skills
| Skill | Written for | Use it to |
|---|---|---|
rules-cascade | every project | Find decisions in code, write rulesets with golden tests, check, propose |
rules-cascade-review | every project | Review a ruleset change or a proposal |
rules-cascade-migrate | every project | Move checks out of the code step by step, with parity tests |
rules-cascade-typescript | ts | Enforce rules in Node.js (Express, Fastify, NestJS, Next.js) and in browsers or React |
rules-cascade-python | python | Enforce rules in FastAPI, Django, Flask, Celery and batch jobs |
rules-cascade-java | java | Enforce rules on the JVM: Spring Boot, Quarkus, Micronaut, Kotlin, Scala |
rules-cascade-go | go | Enforce rules in Go services: net/http, chi, gin, echo, gRPC |
rules-cascade-engine | other | Enforce rules from any other language with rcas engine or rcas.wasm |
How the tools and languages are chosen
| First match wins | |
|---|---|
| Tools | --for claude,kiro (or all); agents.tools in rcas.yaml; the tools the project already shows signs of (CLAUDE.md or .claude/, .cursor/, .kiro/, .github/copilot-instructions.md, .devin/ or .windsurf/, GEMINI.md, .junie/ ...); none, which writes the portable part only |
| Languages | --stack ts,java; languages in rcas.yaml; the languages found in the project directory and the directories directly below it (package.json, pyproject.toml, pom.xml, build.gradle, go.mod, *.csproj, Cargo.toml ...); none, which writes every language skill |
rcas agent list shows every tool, whether the project uses it, and what an install would write.
rcas doctor warns when a tool the project uses is missing its files.
To fix the choice for everyone who clones the project, commit it:
# rcas.yaml
languages: [ts, java]
agents:
tools: [claude, copilot, kiro]Adapting it to a team
| You want to | Do this |
|---|---|
| Add your own guidance for every tool | Write it in AGENTS.md outside the rcas:begin / rcas:end block |
| Change a skill or a sub-agent for this project | Edit the file and delete its rcas-managed line. rcas agent install then keeps your version, and only --force replaces it |
| Add a team skill (your domain, your framework) | A new folder beside the others, .agents/skills/acme-payments/SKILL.md, with name: acme-payments and a description that says when to use it. rcas never touches folders it did not write |
Get the newest instructions after upgrading rcas | Run rcas agent install again: managed blocks and files that still carry rcas-managed are refreshed, everything else is left alone |
| Use another rules folder | rules.dir and output.dir in rcas.yaml; the instructions name your paths |
| Keep agents from writing at all | mcp.readOnly: true in rcas.yaml (or start the server with rcas mcp --read-only): it has no propose_ruleset tool |
A skill is plain Markdown: anyone can read what the agent is told. Keep a team skill short, specific (the folders, the commands, the conventions of this code base), and test it by asking the agent to do the task.
MCP servers
rcas mcp install <tool> registers the rules-cascade MCP server in each tool's own configuration,
in the shape that tool expects; other servers and settings in the file are kept. See the
CLI reference for the files. Goose (goose configure) and the GitHub Copilot
cloud agent (repository settings, Copilot, MCP servers) are configured by hand: --print shows
the entry.
Sources
The conventions were checked against each tool's documentation in October 2026: Claude Code, Codex, GitHub Copilot, Cursor, Gemini CLI, Kiro, Devin, Junie, Cline, OpenCode, Factory, Amazon Q, Tabnine, Muse Code, Amp, Goose, Warp, Zed, Kilo Code, Augment, Agent Skills.