From 27ff5ce0ba7756e66ba493f743c766fd065c0acc Mon Sep 17 00:00:00 2001 From: Alex Skrypnyk Date: Fri, 30 Oct 2026 09:57:15 +1100 Subject: [PATCH 01/13] [#3145] Added a 'review-code' skill that reviews the local branch or a pull request against the project rules and a team checklist. --- .claude/skills/review-code/SKILL.md | 118 ++++++++++++++++++++++++ .claude/skills/review-code/checklist.md | 63 +++++++++++++ 2 files changed, 181 insertions(+) create mode 100644 .claude/skills/review-code/SKILL.md create mode 100644 .claude/skills/review-code/checklist.md diff --git a/.claude/skills/review-code/SKILL.md b/.claude/skills/review-code/SKILL.md new file mode 100644 index 0000000000..85a832b1a0 --- /dev/null +++ b/.claude/skills/review-code/SKILL.md @@ -0,0 +1,118 @@ +--- +name: review-code +description: Use when asked to review code, review the current branch, check changes before opening a pull request, or review a GitHub pull request from its URL or number. +--- + +# Review code + +Review a change the way a senior developer on this project would: against +the project's own rules first, then the team checklist, then general +engineering judgement. + +The review is read-only. Never edit files, check out branches, push, or +post to GitHub. Print the report in the conversation and stop. + +Run every command from the project root. + +## 1. Get the diff + +**Pull request** (a URL, or a number such as `123` or `#123`): + +1. `gh pr view --json number,title,body,url,state,baseRefName,headRefOid` +2. `gh pr diff ` + +Pass the full URL as `` whenever the developer gave one, so `gh` reads +the right repository. To read a changed file in full at the PR head, take +`/` from the PR URL and run +`gh api -H "Accept: application/vnd.github.raw" "repos///contents/?ref="`. +When the PR head is checked out locally, read the files from disk instead. + +When `state` is `MERGED` or `CLOSED`, say so at the top of the report and +present the findings as follow-ups. + +**Local branch** (no argument): + +1. Find the base: the branch the developer names, otherwise + `gh repo view --json defaultBranchRef --jq .defaultBranchRef.name`. +2. `git fetch origin ` +3. `git merge-base origin/ HEAD` and copy the hash it prints. +4. `git diff ` - this includes uncommitted changes. +5. `git status --short` - read untracked files as new files. +6. `git log --oneline origin/..HEAD` for the intent of the change. + +When the diff is empty or the base does not resolve, reply with 1 line +that says which and stop. When the developer expected changes, also run +`git status --short --ignored` and name any ignored files that match. + +## 2. Load the rules + +Apply them in this order. An earlier source wins over a later one. + +1. `AGENTS.md`, any `AGENTS.md` or `CLAUDE.md` in a directory the change + touches, and the files in `docs/` - the decisions this project made. + When they allow something the checklist would flag, do not flag it. +2. `checklist.md` in this directory - the team's review checklist. +3. General judgement: correctness, security, data loss, error handling, + and missing tests. + +Skip anything the project's linters already enforce: `ahoy lint` and any +other lint command that `AGENTS.md` lists. Flag a change that disables or +bypasses a linter. + +## 3. Review + +- Read each changed file in full, not only the diff hunks. Open the + callers, services, routes and config that the change relies on. +- Spot-check generated files, such as lock files and test fixtures, + instead of reading them in full. +- Check every finding against the code before reporting it. Drop it when + the code already handles the case. +- A claim that cannot be checked from the code goes in **Questions**, not + in a severity section. + +## 4. Report + +Use this format and leave out empty sections: + +```markdown +## Review: + +**Verdict:** Ready to merge | Ready after fixes | Needs work + +### Critical +- `path/to/file.php:42` - What is wrong. Why it matters. How to fix it. + +### Important +- ... + +### Minor +- ... + +### Questions +- Things the author needs to confirm. +``` + +Point each finding at `path:line`. Use the path alone when the finding is +about something missing, such as a test. + +| Severity | Use for | +|-----------|------------------------------------------------------------------------------------------| +| Critical | Security holes, data loss, broken behavior, a change that fails the build or deployment | +| Important | Bugs in edge cases, missing tests for changed behavior, checklist violations | +| Minor | Readability and maintainability. Report at most 5. | + +| Verdict | When | +|-------------------|--------------------------------------------------------------| +| Needs work | Any Critical finding, or a question that blocks the merge | +| Ready after fixes | Important findings and no Critical ones | +| Ready to merge | Only Minor findings, non-blocking questions, or no findings | + +When there are findings, offer to fix them or post them to the pull +request. Do neither unless the developer asks. + +## Customizing + +- Change what the review checks: edit `checklist.md`. +- Change a project rule: edit `AGENTS.md` or `docs/`. The review reads + them on every run. +- Change the procedure or the report format: edit this file. diff --git a/.claude/skills/review-code/checklist.md b/.claude/skills/review-code/checklist.md new file mode 100644 index 0000000000..d92d1ebb50 --- /dev/null +++ b/.claude/skills/review-code/checklist.md @@ -0,0 +1,63 @@ +# Review checklist + +The team owns this file. Add, change or remove items to match how the +project works. `AGENTS.md` and `docs/` override anything here. + +## Security + +- User input reaches SQL only through placeholders or the query builder, + never through string concatenation. +- Render arrays use `#plain_text` or a template for values that are not + trusted, not `#markup` with variables. +- Twig templates do not apply `|raw` to values that users can change. +- `t()` and `$this->t()` pass user values through `@` or `%` + placeholders. +- Every new route declares `requirements` such as `_permission`. A route + with `_access: 'TRUE'` is intentionally public. +- Entity queries call `accessCheck()` explicitly. `accessCheck(FALSE)` + appears only where the code checks access itself. +- State-changing actions use Form API forms or a route with + `_csrf_token: 'TRUE'`. +- Secrets come from environment variables, not from code, config or + settings files. + +## Drupal APIs + +- Classes receive services through dependency injection. `\Drupal::` + static calls appear only in procedural code such as `.module` and + `.install` files. +- Code loads entities with `loadMultiple()` instead of `load()` inside a + loop. +- New hooks follow the style the module already uses. + +## Caching + +- Output that varies by user, role, route or query parameter declares the + matching `#cache` contexts. +- Output built from entities or config declares their cache tags. +- Code sets `max-age` to `0` only with a comment that explains why. + +## Configuration and updates + +- Configuration changes are exported to `config/default`. +- Custom modules that add configuration ship a schema in + `config/schema/`. +- Changes that need existing data or configuration transformed ship a + `hook_update_N()`, `hook_post_update_NAME()` or a deploy hook in + `*.deploy.php`. +- Settings for a contributed module go in + `web/sites/default/includes/modules/`. + +## Tests + +- Changed behavior has a test: PHPUnit in the module's `tests/` + directory, a Behat scenario in `tests/behat/features/`, or a test in + the suite that already covers the changed code. +- Behat scenarios wait for conditions, not for a fixed number of seconds. + +## Front end + +- JavaScript attaches through `Drupal.behaviors` and uses `once()`. +- Libraries are attached where they are used, not globally. +- Twig marks user-facing strings for translation with `|t` or + `{% trans %}`. From 57648e473b9b8acddeb90a488e8b7199b580f368 Mon Sep 17 00:00:00 2001 From: Alex Skrypnyk Date: Fri, 30 Oct 2026 09:57:53 +1100 Subject: [PATCH 02/13] [#3145] Documented the 'review-code' skill and how a team adapts it. --- .vortex/docs/content/development/ai.mdx | 50 ++++++++++++++++++++++++- .vortex/docs/content/features.mdx | 2 + 2 files changed, 50 insertions(+), 2 deletions(-) diff --git a/.vortex/docs/content/development/ai.mdx b/.vortex/docs/content/development/ai.mdx index 28f4515889..b89047569d 100644 --- a/.vortex/docs/content/development/ai.mdx +++ b/.vortex/docs/content/development/ai.mdx @@ -12,8 +12,9 @@ lives. This page is for developers who work on a **Vortex** project with an AI coding agent such as Claude Code. It explains what each instruction file -gives the agent, how to add skills of your own and how to tune automated -code review. +gives the agent and how to review code with the shipped `review-code` +skill. It also covers adding skills of your own and tuning automated code +review. The installer adds the instruction files unless you answer no to its **Provide AI agent instructions?** prompt. Answering no leaves out the @@ -107,6 +108,51 @@ installer removes those entries, so your project gets only the Personal, machine-local settings belong in `.claude/settings.local.json`, which Git ignores. +## Review code + +The `review-code` skill in `.claude/skills/review-code/` reviews a change +on your machine before a teammate sees it. It reads the code and reports +findings. It doesn't edit files or post to GitHub. + +Ask your agent for a review in either of these forms: + +- "Review my branch" reviews the current branch against the default + branch. The review includes uncommitted and untracked files. +- "Review https://github.com/your-org/your-site/pull/123" reviews a pull + request without checking out its branch. The skill reads it with the + GitHub CLI, so `gh` must be installed and signed in. + +In Claude Code, you can also run `/review-code` with the same argument. + +The review checks the change against 3 sources, in this order: + +1. `AGENTS.md`, the files in `docs/`, and any `AGENTS.md` or `CLAUDE.md` + in a directory the change touches. These record your project's + decisions and win over the other 2 sources. +2. `.claude/skills/review-code/checklist.md`, the team's review checklist. + It covers Drupal security, Drupal APIs, caching, configuration and + updates, tests, and front-end code. +3. General engineering judgement. + +The review skips anything `ahoy lint` already enforces. It sorts findings +into **Critical**, **Important**, and **Minor**, points each one at a file +and line, and ends with a verdict: **Ready to merge**, **Ready after +fixes**, or **Needs work**. + +### Adapt the review to your team + +Edit the file that owns the rule you want to change, then commit it: + +| To change | Edit | +|---|---| +| What the review checks | `.claude/skills/review-code/checklist.md` | +| A project rule the review enforces | `AGENTS.md` or the matching file in `docs/` | +| The procedure or the report format | `.claude/skills/review-code/SKILL.md` | + +For example, to stop the review flagging `\Drupal::` calls in a legacy +module, record that decision in `AGENTS.md`. The review reads it on every +run and doesn't flag what it allows. + ## Custom skills A skill is a reusable instruction set for a repeatable, project-specific diff --git a/.vortex/docs/content/features.mdx b/.vortex/docs/content/features.mdx index 3beeed2a8b..34c635dcc8 100644 --- a/.vortex/docs/content/features.mdx +++ b/.vortex/docs/content/features.mdx @@ -341,6 +341,8 @@ import { ### AI code review + - A `review-code` skill that reviews the local branch or a pull request + against the project's rules and a checklist the team edits - Opt-in [CodeRabbit](https://www.coderabbit.ai/) configuration that reviews pull requests against the project's documented conventions - Comments limited to correctness, security, performance and From 129c6b8935536c0cdda6acd84c8ba12ac34b67fb Mon Sep 17 00:00:00 2001 From: Alex Skrypnyk Date: Fri, 30 Oct 2026 12:20:02 +1100 Subject: [PATCH 03/13] [#3145] Made 'review-code' use the target repository's rules for external pull requests and drop the verdict for merged ones. --- .claude/skills/review-code/SKILL.md | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/.claude/skills/review-code/SKILL.md b/.claude/skills/review-code/SKILL.md index 85a832b1a0..4c3b4baba1 100644 --- a/.claude/skills/review-code/SKILL.md +++ b/.claude/skills/review-code/SKILL.md @@ -27,8 +27,12 @@ the right repository. To read a changed file in full at the PR head, take `gh api -H "Accept: application/vnd.github.raw" "repos///contents/?ref="`. When the PR head is checked out locally, read the files from disk instead. -When `state` is `MERGED` or `CLOSED`, say so at the top of the report and -present the findings as follow-ups. +When `state` is `MERGED` or `CLOSED`, say so at the top of the report, +leave out the verdict, and present the findings as follow-ups. + +When the pull request belongs to another repository, the rules in step 2 +come from that repository: read its `AGENTS.md`, `CLAUDE.md` and +contributing docs with `gh api`, and skip `checklist.md`. **Local branch** (no argument): From 3f99e3c9709211d46f023a2df0c6f9281367f068 Mon Sep 17 00:00:00 2001 From: Alex Skrypnyk Date: Fri, 30 Oct 2026 12:21:19 +1100 Subject: [PATCH 04/13] [#3145] Stopped the installer removing '.claude/skills' so 'review-code' ships to consumer sites, and listed it in 'AGENTS.md'. --- .claude/skills/review-code/SKILL.md | 6 +++--- .vortex/docs/content/development/ai.mdx | 2 +- .vortex/installer/src/Prompts/Handlers/Internal.php | 4 ---- .../Handlers/AiCodeInstructionsHandlerProcessTest.php | 2 ++ AGENTS.md | 2 ++ 5 files changed, 8 insertions(+), 8 deletions(-) diff --git a/.claude/skills/review-code/SKILL.md b/.claude/skills/review-code/SKILL.md index 4c3b4baba1..fedf1d1d15 100644 --- a/.claude/skills/review-code/SKILL.md +++ b/.claude/skills/review-code/SKILL.md @@ -7,7 +7,7 @@ description: Use when asked to review code, review the current branch, check cha Review a change the way a senior developer on this project would: against the project's own rules first, then the team checklist, then general -engineering judgement. +engineering judgment. The review is read-only. Never edit files, check out branches, push, or post to GitHub. Print the report in the conversation and stop. @@ -18,7 +18,7 @@ Run every command from the project root. **Pull request** (a URL, or a number such as `123` or `#123`): -1. `gh pr view --json number,title,body,url,state,baseRefName,headRefOid` +1. `gh pr view --json number,title,body,url,state,headRefOid` 2. `gh pr diff ` Pass the full URL as `` whenever the developer gave one, so `gh` reads @@ -56,7 +56,7 @@ Apply them in this order. An earlier source wins over a later one. touches, and the files in `docs/` - the decisions this project made. When they allow something the checklist would flag, do not flag it. 2. `checklist.md` in this directory - the team's review checklist. -3. General judgement: correctness, security, data loss, error handling, +3. General judgment: correctness, security, data loss, error handling, and missing tests. Skip anything the project's linters already enforce: `ahoy lint` and any diff --git a/.vortex/docs/content/development/ai.mdx b/.vortex/docs/content/development/ai.mdx index b89047569d..bdafecfd23 100644 --- a/.vortex/docs/content/development/ai.mdx +++ b/.vortex/docs/content/development/ai.mdx @@ -132,7 +132,7 @@ The review checks the change against 3 sources, in this order: 2. `.claude/skills/review-code/checklist.md`, the team's review checklist. It covers Drupal security, Drupal APIs, caching, configuration and updates, tests, and front-end code. -3. General engineering judgement. +3. General engineering judgment. The review skips anything `ahoy lint` already enforces. It sorts findings into **Critical**, **Important**, and **Minor**, points each one at a file diff --git a/.vortex/installer/src/Prompts/Handlers/Internal.php b/.vortex/installer/src/Prompts/Handlers/Internal.php index fae07a1164..a9666617da 100644 --- a/.vortex/installer/src/Prompts/Handlers/Internal.php +++ b/.vortex/installer/src/Prompts/Handlers/Internal.php @@ -91,10 +91,6 @@ public function process(): void { // Remove Vortex internal files. File::remove($t . '/.vortex'); - // The template at the installed reference, such as 'stable', can ship - // maintenance skills in '.claude/skills'. - File::remove($t . '/.claude/skills'); - File::remove($t . '/.github/FUNDING.yml'); File::remove($t . '/CODE_OF_CONDUCT.md'); File::remove($t . '/CONTRIBUTING.md'); diff --git a/.vortex/installer/tests/Functional/Prompts/Handlers/AiCodeInstructionsHandlerProcessTest.php b/.vortex/installer/tests/Functional/Prompts/Handlers/AiCodeInstructionsHandlerProcessTest.php index c604a5a3aa..0c42b5b014 100644 --- a/.vortex/installer/tests/Functional/Prompts/Handlers/AiCodeInstructionsHandlerProcessTest.php +++ b/.vortex/installer/tests/Functional/Prompts/Handlers/AiCodeInstructionsHandlerProcessTest.php @@ -19,6 +19,8 @@ public static function dataProviderHandlerProcess(): \Iterator { $test->assertFileExists(static::$sut . '/.claude/settings.json'); $test->assertFileNotContainsString(static::$sut . '/.claude/settings.json', 'extraKnownMarketplaces'); $test->assertFileNotContainsString(static::$sut . '/.claude/settings.json', 'enabledPlugins'); + $test->assertFileExists(static::$sut . '/.claude/skills/review-code/SKILL.md'); + $test->assertFileExists(static::$sut . '/.claude/skills/review-code/checklist.md'); }), ]; yield 'ai_instructions_disabled' => [ diff --git a/AGENTS.md b/AGENTS.md index b86f1d43eb..1310767a61 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -124,6 +124,8 @@ ahoy test-bdd -- --tags=@tagname # Run Behat tests with specific tag - `config/default/` - Drupal configuration - `scripts/` - Project scripts - `patches/` - Module patches +- `.claude/skills/` - Project skills, such as `review-code` for reviewing + a branch or a pull request ## Documentation From 528f96ee378c88ee9b11b53fd0eac71ef660e628 Mon Sep 17 00:00:00 2001 From: Alex Skrypnyk Date: Fri, 30 Oct 2026 12:21:29 +1100 Subject: [PATCH 05/13] Updated baseline. --- .../tests/Fixtures/handler_process/_baseline/AGENTS.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/.vortex/installer/tests/Fixtures/handler_process/_baseline/AGENTS.md b/.vortex/installer/tests/Fixtures/handler_process/_baseline/AGENTS.md index 85a4390c41..079a1abac4 100644 --- a/.vortex/installer/tests/Fixtures/handler_process/_baseline/AGENTS.md +++ b/.vortex/installer/tests/Fixtures/handler_process/_baseline/AGENTS.md @@ -103,6 +103,8 @@ ahoy test-bdd -- --tags=@tagname # Run Behat tests with specific tag - `config/default/` - Drupal configuration - `scripts/` - Project scripts - `patches/` - Module patches +- `.claude/skills/` - Project skills, such as `review-code` for reviewing + a branch or a pull request ## Documentation From d622cac474d7abbbed84bcff8612fb46f0623001 Mon Sep 17 00:00:00 2001 From: Alex Skrypnyk Date: Fri, 30 Oct 2026 12:24:38 +1100 Subject: [PATCH 06/13] [#3145] Put each test rule in 'review-code' on its own line so the installer removes the PHPUnit and Behat rules cleanly. --- .claude/skills/review-code/checklist.md | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/.claude/skills/review-code/checklist.md b/.claude/skills/review-code/checklist.md index d92d1ebb50..bb6c0a0d4c 100644 --- a/.claude/skills/review-code/checklist.md +++ b/.claude/skills/review-code/checklist.md @@ -50,10 +50,9 @@ project works. `AGENTS.md` and `docs/` override anything here. ## Tests -- Changed behavior has a test: PHPUnit in the module's `tests/` - directory, a Behat scenario in `tests/behat/features/`, or a test in - the suite that already covers the changed code. -- Behat scenarios wait for conditions, not for a fixed number of seconds. +- Changed behavior has a test in the suite that covers the changed code. +- PHPUnit tests sit in the suites that `phpunit.xml` defines. +- Behat scenarios sit in `tests/behat/features/` and wait for conditions. ## Front end From cadcb120915c59a9f6742f3f0247226f3d2f914e Mon Sep 17 00:00:00 2001 From: Alex Skrypnyk Date: Fri, 30 Oct 2026 12:29:59 +1100 Subject: [PATCH 07/13] Updated snapshots. --- .../.claude/skills/review-code/SKILL.md | 122 ++++++++++++++++++ .../.claude/skills/review-code/checklist.md | 62 +++++++++ .../.claude/skills/review-code/-SKILL.md | 0 .../.claude/skills/review-code/-checklist.md | 0 .../.claude/skills/review-code/checklist.md | 9 ++ .../.claude/skills/review-code/checklist.md | 9 ++ .../.claude/skills/review-code/checklist.md | 9 ++ .../.claude/skills/review-code/checklist.md | 9 ++ .../.claude/skills/review-code/checklist.md | 8 ++ .../.claude/skills/review-code/checklist.md | 8 ++ .../.claude/skills/review-code/checklist.md | 8 ++ .../.claude/skills/review-code/checklist.md | 8 ++ .../.claude/skills/review-code/checklist.md | 9 ++ 13 files changed, 261 insertions(+) create mode 100644 .vortex/installer/tests/Fixtures/handler_process/_baseline/.claude/skills/review-code/SKILL.md create mode 100644 .vortex/installer/tests/Fixtures/handler_process/_baseline/.claude/skills/review-code/checklist.md create mode 100644 .vortex/installer/tests/Fixtures/handler_process/ai_instructions_disabled/.claude/skills/review-code/-SKILL.md create mode 100644 .vortex/installer/tests/Fixtures/handler_process/ai_instructions_disabled/.claude/skills/review-code/-checklist.md create mode 100644 .vortex/installer/tests/Fixtures/handler_process/hosting_acquia/.claude/skills/review-code/checklist.md create mode 100644 .vortex/installer/tests/Fixtures/handler_process/hosting_project_name___acquia/.claude/skills/review-code/checklist.md create mode 100644 .vortex/installer/tests/Fixtures/handler_process/tools_groups_no_be_tests/.claude/skills/review-code/checklist.md create mode 100644 .vortex/installer/tests/Fixtures/handler_process/tools_groups_no_be_tests_circleci/.claude/skills/review-code/checklist.md create mode 100644 .vortex/installer/tests/Fixtures/handler_process/tools_no_behat/.claude/skills/review-code/checklist.md create mode 100644 .vortex/installer/tests/Fixtures/handler_process/tools_no_behat_circleci/.claude/skills/review-code/checklist.md create mode 100644 .vortex/installer/tests/Fixtures/handler_process/tools_no_phpunit/.claude/skills/review-code/checklist.md create mode 100644 .vortex/installer/tests/Fixtures/handler_process/tools_no_phpunit_circleci/.claude/skills/review-code/checklist.md create mode 100644 .vortex/installer/tests/Fixtures/handler_process/tools_none/.claude/skills/review-code/checklist.md diff --git a/.vortex/installer/tests/Fixtures/handler_process/_baseline/.claude/skills/review-code/SKILL.md b/.vortex/installer/tests/Fixtures/handler_process/_baseline/.claude/skills/review-code/SKILL.md new file mode 100644 index 0000000000..d62ec3c32b --- /dev/null +++ b/.vortex/installer/tests/Fixtures/handler_process/_baseline/.claude/skills/review-code/SKILL.md @@ -0,0 +1,122 @@ +--- +name: review-code +description: Use when asked to review code, review the current branch, check changes before opening a pull request, or review a GitHub pull request from its URL or number. +--- + +# Review code + +Review a change the way a senior developer on this project would: against +the project's own rules first, then the team checklist, then general +engineering judgment. + +The review is read-only. Never edit files, check out branches, push, or +post to GitHub. Print the report in the conversation and stop. + +Run every command from the project root. + +## 1. Get the diff + +**Pull request** (a URL, or a number such as `123` or `#123`): + +1. `gh pr view --json number,title,body,url,state,headRefOid` +2. `gh pr diff ` + +Pass the full URL as `` whenever the developer gave one, so `gh` reads +the right repository. To read a changed file in full at the PR head, take +`/` from the PR URL and run +`gh api -H "Accept: application/vnd.github.raw" "repos///contents/?ref="`. +When the PR head is checked out locally, read the files from disk instead. + +When `state` is `MERGED` or `CLOSED`, say so at the top of the report, +leave out the verdict, and present the findings as follow-ups. + +When the pull request belongs to another repository, the rules in step 2 +come from that repository: read its `AGENTS.md`, `CLAUDE.md` and +contributing docs with `gh api`, and skip `checklist.md`. + +**Local branch** (no argument): + +1. Find the base: the branch the developer names, otherwise + `gh repo view --json defaultBranchRef --jq .defaultBranchRef.name`. +2. `git fetch origin ` +3. `git merge-base origin/ HEAD` and copy the hash it prints. +4. `git diff ` - this includes uncommitted changes. +5. `git status --short` - read untracked files as new files. +6. `git log --oneline origin/..HEAD` for the intent of the change. + +When the diff is empty or the base does not resolve, reply with 1 line +that says which and stop. When the developer expected changes, also run +`git status --short --ignored` and name any ignored files that match. + +## 2. Load the rules + +Apply them in this order. An earlier source wins over a later one. + +1. `AGENTS.md`, any `AGENTS.md` or `CLAUDE.md` in a directory the change + touches, and the files in `docs/` - the decisions this project made. + When they allow something the checklist would flag, do not flag it. +2. `checklist.md` in this directory - the team's review checklist. +3. General judgment: correctness, security, data loss, error handling, + and missing tests. + +Skip anything the project's linters already enforce: `ahoy lint` and any +other lint command that `AGENTS.md` lists. Flag a change that disables or +bypasses a linter. + +## 3. Review + +- Read each changed file in full, not only the diff hunks. Open the + callers, services, routes and config that the change relies on. +- Spot-check generated files, such as lock files and test fixtures, + instead of reading them in full. +- Check every finding against the code before reporting it. Drop it when + the code already handles the case. +- A claim that cannot be checked from the code goes in **Questions**, not + in a severity section. + +## 4. Report + +Use this format and leave out empty sections: + +```markdown +## Review: + +**Verdict:** Ready to merge | Ready after fixes | Needs work + +### Critical +- `path/to/file.php:__VERSION__` - What is wrong. Why it matters. How to fix it. + +### Important +- ... + +### Minor +- ... + +### Questions +- Things the author needs to confirm. +``` + +Point each finding at `path:line`. Use the path alone when the finding is +about something missing, such as a test. + +| Severity | Use for | +|-----------|------------------------------------------------------------------------------------------| +| Critical | Security holes, data loss, broken behavior, a change that fails the build or deployment | +| Important | Bugs in edge cases, missing tests for changed behavior, checklist violations | +| Minor | Readability and maintainability. Report at most 5. | + +| Verdict | When | +|-------------------|--------------------------------------------------------------| +| Needs work | Any Critical finding, or a question that blocks the merge | +| Ready after fixes | Important findings and no Critical ones | +| Ready to merge | Only Minor findings, non-blocking questions, or no findings | + +When there are findings, offer to fix them or post them to the pull +request. Do neither unless the developer asks. + +## Customizing + +- Change what the review checks: edit `checklist.md`. +- Change a project rule: edit `AGENTS.md` or `docs/`. The review reads + them on every run. +- Change the procedure or the report format: edit this file. diff --git a/.vortex/installer/tests/Fixtures/handler_process/_baseline/.claude/skills/review-code/checklist.md b/.vortex/installer/tests/Fixtures/handler_process/_baseline/.claude/skills/review-code/checklist.md new file mode 100644 index 0000000000..bb6c0a0d4c --- /dev/null +++ b/.vortex/installer/tests/Fixtures/handler_process/_baseline/.claude/skills/review-code/checklist.md @@ -0,0 +1,62 @@ +# Review checklist + +The team owns this file. Add, change or remove items to match how the +project works. `AGENTS.md` and `docs/` override anything here. + +## Security + +- User input reaches SQL only through placeholders or the query builder, + never through string concatenation. +- Render arrays use `#plain_text` or a template for values that are not + trusted, not `#markup` with variables. +- Twig templates do not apply `|raw` to values that users can change. +- `t()` and `$this->t()` pass user values through `@` or `%` + placeholders. +- Every new route declares `requirements` such as `_permission`. A route + with `_access: 'TRUE'` is intentionally public. +- Entity queries call `accessCheck()` explicitly. `accessCheck(FALSE)` + appears only where the code checks access itself. +- State-changing actions use Form API forms or a route with + `_csrf_token: 'TRUE'`. +- Secrets come from environment variables, not from code, config or + settings files. + +## Drupal APIs + +- Classes receive services through dependency injection. `\Drupal::` + static calls appear only in procedural code such as `.module` and + `.install` files. +- Code loads entities with `loadMultiple()` instead of `load()` inside a + loop. +- New hooks follow the style the module already uses. + +## Caching + +- Output that varies by user, role, route or query parameter declares the + matching `#cache` contexts. +- Output built from entities or config declares their cache tags. +- Code sets `max-age` to `0` only with a comment that explains why. + +## Configuration and updates + +- Configuration changes are exported to `config/default`. +- Custom modules that add configuration ship a schema in + `config/schema/`. +- Changes that need existing data or configuration transformed ship a + `hook_update_N()`, `hook_post_update_NAME()` or a deploy hook in + `*.deploy.php`. +- Settings for a contributed module go in + `web/sites/default/includes/modules/`. + +## Tests + +- Changed behavior has a test in the suite that covers the changed code. +- PHPUnit tests sit in the suites that `phpunit.xml` defines. +- Behat scenarios sit in `tests/behat/features/` and wait for conditions. + +## Front end + +- JavaScript attaches through `Drupal.behaviors` and uses `once()`. +- Libraries are attached where they are used, not globally. +- Twig marks user-facing strings for translation with `|t` or + `{% trans %}`. diff --git a/.vortex/installer/tests/Fixtures/handler_process/ai_instructions_disabled/.claude/skills/review-code/-SKILL.md b/.vortex/installer/tests/Fixtures/handler_process/ai_instructions_disabled/.claude/skills/review-code/-SKILL.md new file mode 100644 index 0000000000..e69de29bb2 diff --git a/.vortex/installer/tests/Fixtures/handler_process/ai_instructions_disabled/.claude/skills/review-code/-checklist.md b/.vortex/installer/tests/Fixtures/handler_process/ai_instructions_disabled/.claude/skills/review-code/-checklist.md new file mode 100644 index 0000000000..e69de29bb2 diff --git a/.vortex/installer/tests/Fixtures/handler_process/hosting_acquia/.claude/skills/review-code/checklist.md b/.vortex/installer/tests/Fixtures/handler_process/hosting_acquia/.claude/skills/review-code/checklist.md new file mode 100644 index 0000000000..27351db639 --- /dev/null +++ b/.vortex/installer/tests/Fixtures/handler_process/hosting_acquia/.claude/skills/review-code/checklist.md @@ -0,0 +1,9 @@ +@@ -46,7 +46,7 @@ + `hook_update_N()`, `hook_post_update_NAME()` or a deploy hook in + `*.deploy.php`. + - Settings for a contributed module go in +- `web/sites/default/includes/modules/`. ++ `docroot/sites/default/includes/modules/`. + + ## Tests + diff --git a/.vortex/installer/tests/Fixtures/handler_process/hosting_project_name___acquia/.claude/skills/review-code/checklist.md b/.vortex/installer/tests/Fixtures/handler_process/hosting_project_name___acquia/.claude/skills/review-code/checklist.md new file mode 100644 index 0000000000..27351db639 --- /dev/null +++ b/.vortex/installer/tests/Fixtures/handler_process/hosting_project_name___acquia/.claude/skills/review-code/checklist.md @@ -0,0 +1,9 @@ +@@ -46,7 +46,7 @@ + `hook_update_N()`, `hook_post_update_NAME()` or a deploy hook in + `*.deploy.php`. + - Settings for a contributed module go in +- `web/sites/default/includes/modules/`. ++ `docroot/sites/default/includes/modules/`. + + ## Tests + diff --git a/.vortex/installer/tests/Fixtures/handler_process/tools_groups_no_be_tests/.claude/skills/review-code/checklist.md b/.vortex/installer/tests/Fixtures/handler_process/tools_groups_no_be_tests/.claude/skills/review-code/checklist.md new file mode 100644 index 0000000000..06f44ca2d8 --- /dev/null +++ b/.vortex/installer/tests/Fixtures/handler_process/tools_groups_no_be_tests/.claude/skills/review-code/checklist.md @@ -0,0 +1,9 @@ +@@ -51,8 +51,6 @@ + ## Tests + + - Changed behavior has a test in the suite that covers the changed code. +-- PHPUnit tests sit in the suites that `phpunit.xml` defines. +-- Behat scenarios sit in `tests/behat/features/` and wait for conditions. + + ## Front end + diff --git a/.vortex/installer/tests/Fixtures/handler_process/tools_groups_no_be_tests_circleci/.claude/skills/review-code/checklist.md b/.vortex/installer/tests/Fixtures/handler_process/tools_groups_no_be_tests_circleci/.claude/skills/review-code/checklist.md new file mode 100644 index 0000000000..06f44ca2d8 --- /dev/null +++ b/.vortex/installer/tests/Fixtures/handler_process/tools_groups_no_be_tests_circleci/.claude/skills/review-code/checklist.md @@ -0,0 +1,9 @@ +@@ -51,8 +51,6 @@ + ## Tests + + - Changed behavior has a test in the suite that covers the changed code. +-- PHPUnit tests sit in the suites that `phpunit.xml` defines. +-- Behat scenarios sit in `tests/behat/features/` and wait for conditions. + + ## Front end + diff --git a/.vortex/installer/tests/Fixtures/handler_process/tools_no_behat/.claude/skills/review-code/checklist.md b/.vortex/installer/tests/Fixtures/handler_process/tools_no_behat/.claude/skills/review-code/checklist.md new file mode 100644 index 0000000000..1b284fa460 --- /dev/null +++ b/.vortex/installer/tests/Fixtures/handler_process/tools_no_behat/.claude/skills/review-code/checklist.md @@ -0,0 +1,8 @@ +@@ -52,7 +52,6 @@ + + - Changed behavior has a test in the suite that covers the changed code. + - PHPUnit tests sit in the suites that `phpunit.xml` defines. +-- Behat scenarios sit in `tests/behat/features/` and wait for conditions. + + ## Front end + diff --git a/.vortex/installer/tests/Fixtures/handler_process/tools_no_behat_circleci/.claude/skills/review-code/checklist.md b/.vortex/installer/tests/Fixtures/handler_process/tools_no_behat_circleci/.claude/skills/review-code/checklist.md new file mode 100644 index 0000000000..1b284fa460 --- /dev/null +++ b/.vortex/installer/tests/Fixtures/handler_process/tools_no_behat_circleci/.claude/skills/review-code/checklist.md @@ -0,0 +1,8 @@ +@@ -52,7 +52,6 @@ + + - Changed behavior has a test in the suite that covers the changed code. + - PHPUnit tests sit in the suites that `phpunit.xml` defines. +-- Behat scenarios sit in `tests/behat/features/` and wait for conditions. + + ## Front end + diff --git a/.vortex/installer/tests/Fixtures/handler_process/tools_no_phpunit/.claude/skills/review-code/checklist.md b/.vortex/installer/tests/Fixtures/handler_process/tools_no_phpunit/.claude/skills/review-code/checklist.md new file mode 100644 index 0000000000..0e3efd865d --- /dev/null +++ b/.vortex/installer/tests/Fixtures/handler_process/tools_no_phpunit/.claude/skills/review-code/checklist.md @@ -0,0 +1,8 @@ +@@ -51,7 +51,6 @@ + ## Tests + + - Changed behavior has a test in the suite that covers the changed code. +-- PHPUnit tests sit in the suites that `phpunit.xml` defines. + - Behat scenarios sit in `tests/behat/features/` and wait for conditions. + + ## Front end diff --git a/.vortex/installer/tests/Fixtures/handler_process/tools_no_phpunit_circleci/.claude/skills/review-code/checklist.md b/.vortex/installer/tests/Fixtures/handler_process/tools_no_phpunit_circleci/.claude/skills/review-code/checklist.md new file mode 100644 index 0000000000..0e3efd865d --- /dev/null +++ b/.vortex/installer/tests/Fixtures/handler_process/tools_no_phpunit_circleci/.claude/skills/review-code/checklist.md @@ -0,0 +1,8 @@ +@@ -51,7 +51,6 @@ + ## Tests + + - Changed behavior has a test in the suite that covers the changed code. +-- PHPUnit tests sit in the suites that `phpunit.xml` defines. + - Behat scenarios sit in `tests/behat/features/` and wait for conditions. + + ## Front end diff --git a/.vortex/installer/tests/Fixtures/handler_process/tools_none/.claude/skills/review-code/checklist.md b/.vortex/installer/tests/Fixtures/handler_process/tools_none/.claude/skills/review-code/checklist.md new file mode 100644 index 0000000000..06f44ca2d8 --- /dev/null +++ b/.vortex/installer/tests/Fixtures/handler_process/tools_none/.claude/skills/review-code/checklist.md @@ -0,0 +1,9 @@ +@@ -51,8 +51,6 @@ + ## Tests + + - Changed behavior has a test in the suite that covers the changed code. +-- PHPUnit tests sit in the suites that `phpunit.xml` defines. +-- Behat scenarios sit in `tests/behat/features/` and wait for conditions. + + ## Front end + From a2bd533ca0a86c90f29518a90de3b3c653b5bc93 Mon Sep 17 00:00:00 2001 From: Alex Skrypnyk Date: Fri, 30 Oct 2026 12:41:15 +1100 Subject: [PATCH 08/13] [#3145] Allowed 'review-code' to write the git-ignored documentation cache while staying read-only for project files. --- .claude/skills/review-code/SKILL.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/.claude/skills/review-code/SKILL.md b/.claude/skills/review-code/SKILL.md index fedf1d1d15..4bdc8926af 100644 --- a/.claude/skills/review-code/SKILL.md +++ b/.claude/skills/review-code/SKILL.md @@ -9,8 +9,10 @@ Review a change the way a senior developer on this project would: against the project's own rules first, then the team checklist, then general engineering judgment. -The review is read-only. Never edit files, check out branches, push, or -post to GitHub. Print the report in the conversation and stop. +The review is read-only. Never edit the project's files, check out +branches, push, or post to GitHub. Writing to the git-ignored `.artifacts/` +directory, such as the documentation cache `AGENTS.md` describes, is +allowed. Print the report in the conversation and stop. Run every command from the project root. From 4179578d6a9442582bf8ce1ed56cfe513e2c2925 Mon Sep 17 00:00:00 2001 From: Alex Skrypnyk Date: Fri, 30 Oct 2026 12:41:24 +1100 Subject: [PATCH 09/13] Updated baseline. --- .../_baseline/.claude/skills/review-code/SKILL.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/.vortex/installer/tests/Fixtures/handler_process/_baseline/.claude/skills/review-code/SKILL.md b/.vortex/installer/tests/Fixtures/handler_process/_baseline/.claude/skills/review-code/SKILL.md index d62ec3c32b..c43eb55a54 100644 --- a/.vortex/installer/tests/Fixtures/handler_process/_baseline/.claude/skills/review-code/SKILL.md +++ b/.vortex/installer/tests/Fixtures/handler_process/_baseline/.claude/skills/review-code/SKILL.md @@ -9,8 +9,10 @@ Review a change the way a senior developer on this project would: against the project's own rules first, then the team checklist, then general engineering judgment. -The review is read-only. Never edit files, check out branches, push, or -post to GitHub. Print the report in the conversation and stop. +The review is read-only. Never edit the project's files, check out +branches, push, or post to GitHub. Writing to the git-ignored `.artifacts/` +directory, such as the documentation cache `AGENTS.md` describes, is +allowed. Print the report in the conversation and stop. Run every command from the project root. From 0bdef0a08269a23e16ea5186e3106d1274ab0e05 Mon Sep 17 00:00:00 2001 From: Alex Skrypnyk Date: Fri, 30 Oct 2026 12:56:58 +1100 Subject: [PATCH 10/13] [#3145] Fixed the prose lint error and long sentence on the AI docs page. --- .vortex/docs/content/development/ai.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/.vortex/docs/content/development/ai.mdx b/.vortex/docs/content/development/ai.mdx index bdafecfd23..3c3e7ed0bb 100644 --- a/.vortex/docs/content/development/ai.mdx +++ b/.vortex/docs/content/development/ai.mdx @@ -116,9 +116,9 @@ findings. It doesn't edit files or post to GitHub. Ask your agent for a review in either of these forms: -- "Review my branch" reviews the current branch against the default +- `Review my branch` reviews the current branch against the default branch. The review includes uncommitted and untracked files. -- "Review https://github.com/your-org/your-site/pull/123" reviews a pull +- `Review https://github.com/your-org/your-site/pull/123` reviews a pull request without checking out its branch. The skill reads it with the GitHub CLI, so `gh` must be installed and signed in. From 1a6c163f0d8ae332fc26e5d0e1f5a15768ca2924 Mon Sep 17 00:00:00 2001 From: Alex Skrypnyk Date: Fri, 30 Oct 2026 12:57:50 +1100 Subject: [PATCH 11/13] Addressed code review: stripped '#' from PR numbers, read PR files from the head commit, resolved the base without 'gh', and counted untracked files in the empty check. --- .claude/skills/review-code/SKILL.md | 16 +++++++++++----- 1 file changed, 11 insertions(+), 5 deletions(-) diff --git a/.claude/skills/review-code/SKILL.md b/.claude/skills/review-code/SKILL.md index 4bdc8926af..3d93a68f67 100644 --- a/.claude/skills/review-code/SKILL.md +++ b/.claude/skills/review-code/SKILL.md @@ -18,7 +18,9 @@ Run every command from the project root. ## 1. Get the diff -**Pull request** (a URL, or a number such as `123` or `#123`): +**Pull request** (a URL, or a number such as `123`). Drop a leading `#` +from a number first, because the shell reads `#` as the start of a +comment. 1. `gh pr view --json number,title,body,url,state,headRefOid` 2. `gh pr diff ` @@ -27,7 +29,9 @@ Pass the full URL as `` whenever the developer gave one, so `gh` reads the right repository. To read a changed file in full at the PR head, take `/` from the PR URL and run `gh api -H "Accept: application/vnd.github.raw" "repos///contents/?ref="`. -When the PR head is checked out locally, read the files from disk instead. +When `git cat-file -e ` succeeds, `git show :` +reads the same content locally. Never read a PR file from the working +tree, which can hold uncommitted edits. When `state` is `MERGED` or `CLOSED`, say so at the top of the report, leave out the verdict, and present the findings as follow-ups. @@ -38,7 +42,9 @@ contributing docs with `gh api`, and skip `checklist.md`. **Local branch** (no argument): -1. Find the base: the branch the developer names, otherwise +1. Find the base: the branch the developer names, otherwise the default + branch from `git symbolic-ref --short refs/remotes/origin/HEAD` + without its `origin/` prefix. When that command fails, use `gh repo view --json defaultBranchRef --jq .defaultBranchRef.name`. 2. `git fetch origin ` 3. `git merge-base origin/ HEAD` and copy the hash it prints. @@ -46,8 +52,8 @@ contributing docs with `gh api`, and skip `checklist.md`. 5. `git status --short` - read untracked files as new files. 6. `git log --oneline origin/..HEAD` for the intent of the change. -When the diff is empty or the base does not resolve, reply with 1 line -that says which and stop. When the developer expected changes, also run +When the base does not resolve, or both the diff and the untracked files +are empty, reply with 1 line that says which and stop. When the developer expected changes, also run `git status --short --ignored` and name any ignored files that match. ## 2. Load the rules From 863fb7920d956f8c1b9ae2ffc6e16f29bfd8c980 Mon Sep 17 00:00:00 2001 From: Alex Skrypnyk Date: Fri, 30 Oct 2026 12:59:05 +1100 Subject: [PATCH 12/13] Updated snapshots. --- .../.claude/skills/review-code/SKILL.md | 16 +++++++++++----- 1 file changed, 11 insertions(+), 5 deletions(-) diff --git a/.vortex/installer/tests/Fixtures/handler_process/_baseline/.claude/skills/review-code/SKILL.md b/.vortex/installer/tests/Fixtures/handler_process/_baseline/.claude/skills/review-code/SKILL.md index c43eb55a54..1269f48556 100644 --- a/.vortex/installer/tests/Fixtures/handler_process/_baseline/.claude/skills/review-code/SKILL.md +++ b/.vortex/installer/tests/Fixtures/handler_process/_baseline/.claude/skills/review-code/SKILL.md @@ -18,7 +18,9 @@ Run every command from the project root. ## 1. Get the diff -**Pull request** (a URL, or a number such as `123` or `#123`): +**Pull request** (a URL, or a number such as `123`). Drop a leading `#` +from a number first, because the shell reads `#` as the start of a +comment. 1. `gh pr view --json number,title,body,url,state,headRefOid` 2. `gh pr diff ` @@ -27,7 +29,9 @@ Pass the full URL as `` whenever the developer gave one, so `gh` reads the right repository. To read a changed file in full at the PR head, take `/` from the PR URL and run `gh api -H "Accept: application/vnd.github.raw" "repos///contents/?ref="`. -When the PR head is checked out locally, read the files from disk instead. +When `git cat-file -e ` succeeds, `git show :` +reads the same content locally. Never read a PR file from the working +tree, which can hold uncommitted edits. When `state` is `MERGED` or `CLOSED`, say so at the top of the report, leave out the verdict, and present the findings as follow-ups. @@ -38,7 +42,9 @@ contributing docs with `gh api`, and skip `checklist.md`. **Local branch** (no argument): -1. Find the base: the branch the developer names, otherwise +1. Find the base: the branch the developer names, otherwise the default + branch from `git symbolic-ref --short refs/remotes/origin/HEAD` + without its `origin/` prefix. When that command fails, use `gh repo view --json defaultBranchRef --jq .defaultBranchRef.name`. 2. `git fetch origin ` 3. `git merge-base origin/ HEAD` and copy the hash it prints. @@ -46,8 +52,8 @@ contributing docs with `gh api`, and skip `checklist.md`. 5. `git status --short` - read untracked files as new files. 6. `git log --oneline origin/..HEAD` for the intent of the change. -When the diff is empty or the base does not resolve, reply with 1 line -that says which and stop. When the developer expected changes, also run +When the base does not resolve, or both the diff and the untracked files +are empty, reply with 1 line that says which and stop. When the developer expected changes, also run `git status --short --ignored` and name any ignored files that match. ## 2. Load the rules From b1e343df4d32b19fce4371d94147d3245729b682 Mon Sep 17 00:00:00 2001 From: Alex Skrypnyk Date: Fri, 30 Oct 2026 14:19:02 +1100 Subject: [PATCH 13/13] [#3145] Dropped serial commas from the 'review-code' docs section to match the docs style. --- .vortex/docs/content/development/ai.mdx | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/.vortex/docs/content/development/ai.mdx b/.vortex/docs/content/development/ai.mdx index 3c3e7ed0bb..3d72f56158 100644 --- a/.vortex/docs/content/development/ai.mdx +++ b/.vortex/docs/content/development/ai.mdx @@ -126,18 +126,18 @@ In Claude Code, you can also run `/review-code` with the same argument. The review checks the change against 3 sources, in this order: -1. `AGENTS.md`, the files in `docs/`, and any `AGENTS.md` or `CLAUDE.md` +1. `AGENTS.md`, the files in `docs/` and any `AGENTS.md` or `CLAUDE.md` in a directory the change touches. These record your project's decisions and win over the other 2 sources. 2. `.claude/skills/review-code/checklist.md`, the team's review checklist. It covers Drupal security, Drupal APIs, caching, configuration and - updates, tests, and front-end code. + updates, tests and front-end code. 3. General engineering judgment. The review skips anything `ahoy lint` already enforces. It sorts findings -into **Critical**, **Important**, and **Minor**, points each one at a file -and line, and ends with a verdict: **Ready to merge**, **Ready after -fixes**, or **Needs work**. +into **Critical**, **Important** and **Minor** and points each one at a +file and line. It ends with a verdict: **Ready to merge**, **Ready after +fixes** or **Needs work**. ### Adapt the review to your team