n8n/.agents/review-rules/README.md

Review rules

Rules the AI reviewer (cubic) enforces on pull requests. One rule per file, grouped by the agent that loads it. cubic.yaml links these files via file_paths; the prose in cubic.yaml stays thin so the rules are reviewable as normal markdown.

These files hold what to look for. How to review — the bar a comment must clear, when to stay silent, what never to say — lives once in custom_instructions in cubic.yaml, because it reaches every agent.

Layout

Directory	Agent	Scope
security/	Security	backend packages, nodes, and the frontend render surface
backend/	Backend	cli, @n8n/db, core, workflow, node packages
db-migrations/	DB migrations	@n8n/db migrations + their tests in cli
frontend/	Frontend	packages/frontend
qa-dx/	QA & DX	.github, docker, scripts, patches, packages/quality, the lint/test/TS config packages, baselines
testing/	Backend + Frontend	any package with a test suite

A directory maps to one agent unless, like testing/, the policy is identical across domains — then it is one file listed in several agents' file_paths, never a copy per directory. Security and QA & DX deliberately don't link testing/: coverage nagging on a credential fix or a Dockerfile is noise those agents shouldn't be able to produce.

All five slots are used, so a new domain now merges into an existing agent. QA & DX covers the build, test, and CI surface — the same paths .github/OWNERS assigns to @n8n-io/qa-dx. Code-quality rules that happen to apply broadly (error classes, any, lazy imports) are backend rules, not QA & DX ones. DB migrations is split out of Backend because a migration is permanent and runs unattended on every instance, so it is judged against a different bar.

Limits that bite

cubic fails silently on all three of these, which is why pnpm check:cubic-config enforces them in CI:

• 5 enabled agents per repository. Rules past the fifth never run and cubic says nothing. All five are in use.
• 10,000 characters per agent, counting the description, every linked file, and custom_instructions — concatenated in the listed order. Everything past the limit is dropped from the review prompt. The shared block is prepended to every agent, so a line added there is spent against all of their ceilings, not one; check:cubic-config prints the own/shared split.
• Repo-relative file paths only. Globs, directories, parent-directory traversal, and absolute paths are all rejected — list each file explicitly. The schema caps file_paths at 10 entries per agent.

Adding a rule

1. Pick the level of reach first. Guidance about how to review goes in custom_instructions, not here. A policy that is word-for-word the same in two domains becomes one file linked by both agents. Everything else goes in the directory of the agent that owns it.
2. Open with a one-line "Applies to:" so the reviewer skips it on unrelated files — a backend PR still loads the node rules, since include globs are per-agent.
3. Add its path to every file_paths that should load it in cubic.yaml. Keep each agent's list ordered by how often the class it covers actually shows up — the ceiling truncates from the end, so the last file listed is the one that silently disappears first.
4. Run pnpm check:cubic-config. It validates cubic.yaml against cubic's published JSON schema, then fails on a missing path, an over-budget agent, or a rule file nobody links, and warns at 80% of the ceiling.

The schema is vendored at .github/scripts/quality/cubic-config.schema.json so the check needs no network. util-refresh-cubic-schema.yml re-pulls it on the 1st of each month and opens a PR when it changed — review that diff for new cubic options worth adopting. To refresh by hand: node .github/scripts/quality/check-cubic-config.mjs --refresh.

Don't restate something CI already fails on — see the "Don't repeat what CI already fails on" section in cubic.yaml. Write what static analysis cannot see.

Working with cubic on a PR

Tag @cubic-dev-ai in a PR comment (GitHub autocomplete won't offer it — type it). Replying to one of cubic's own comments needs no tag, but a bare reply never authorises code changes.

Ask	Comment
Re-review everything	@cubic-dev-ai review this PR
Review only what changed since its last pass	@cubic-dev-ai incremental review
Deeper pass with the stronger models	@cubic-dev-ai ultrareview — or ultrareview: focus on <topic>
Fix a finding on this branch	@cubic-dev-ai fix this issue in this branch
One-off context for this run only	@cubic-dev-ai review this and use <url>
Ask about a finding	reply in the thread

Two things worth knowing:

• Ultrareview is billed at 3× a normal review, which is why it is manual rather than automatic here.
• A PR over 10,000 changed lines, or carrying one of the ignored automation labels, gets no automatic review. @cubic-dev-ai review this PR overrides that when you want it.

Disagreeing in a thread is not wasted: cubic turns feedback into team-scoped learnings, so a well-argued "this is fine because X" shapes later reviews. Vague replies ("done", "thanks") don't.