Reviews

reviews/ tells code-review bots what to check in this project: the layering rule, the error handling, the migrations that need a second look. Review bots read guidance from their own files; a review spec feeds each of them from one source.

Project rules in every review. The bot flags what your team cares about, not only generic issues.
Scoped guidance. A review under reviews/services/api/ applies only to changes in that directory.
No copies. An @path line pulls a folder's README.md into its review, so the docs and the review stay one text.

Target	Reads
Cursor (Bugbot)	`.cursor/BUGBOT.md`, and `<scope>/.cursor/BUGBOT.md` for scoped specs
Codex (code review)	a `## Code Review Rules` section of the root or scoped `AGENTS.md`
Goose (`goose review`)	`.agents/REVIEW.md`, and `<scope>/.agents/REVIEW.md` for scoped specs

Other targets report review specs as unsupported.

Write one

Markdown with optional YAML frontmatter, one file per group of code-review-bot guidance.

---
scope: backend
---

Flag any handler that talks to the database directly instead of going through a repository.

Reviews honor scope and the source layout like rules do. Specs with the same scope concatenate into one review file, written as a plain body without frontmatter. For Codex the section sits in AGENTS.md, which every AGENTS.md reader loads; a targets: filter that omits codex keeps a spec out of it.

Include a file

A line holding only @path includes that file, read from the project root, so a folder's README.md can serve as its review without a symlink or a copy:

---
scope: services/billing
target: cursor
---

@services/billing/README.md

Sync writes the file's text where the line stood, so a change to the README shows up in sync --check. A missing file, an absolute path, or a path that leaves the project fails the load (AAI-001). A line inside a fenced code block stays as written, and an included file is not searched for further includes. Only reviews take @path lines; on AGNOSTIC_AI.md the resolve-imports setting governs them.