From 64e8ee78f14de7c0757cdbc19f176c40cc75ada1 Mon Sep 17 00:00:00 2001
From: JuanMa <juanma.garrido@gmail.com>
Date: Thu, 6 Aug 2026 09:44:04 +0200
Subject: [PATCH] Make the agent instructions canonical in AGENTS.md
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

CLAUDE.md was the only place the project's constraints were written down, so
every agent other than Claude Code started from nothing — on a codebase whose
whole premise (zero host prerequisites, no git binary, one persistence layer)
is invisible from the code alone.

AGENTS.md is now canonical and CLAUDE.md points at it, keeping only what is
genuinely Claude Code specific. AGENTS.md also carries the directive to run
the review before opening a pull request, and is explicit that nothing
enforces it.

No Copilot file: the review standard already sits at a path Copilot reads
natively, and everything else here is something it can be pointed at. Adding
one would have meant a second copy of the invariants with nothing keeping the
two in step.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
---
 AGENTS.md | 64 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 CLAUDE.md | 27 ++++++-----------------
 2 files changed, 71 insertions(+), 20 deletions(-)
 create mode 100644 AGENTS.md

diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..f22c934
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,64 @@
+# AGENTS.md
+
+Instructions for AI coding agents working in this repository. Tool-neutral and canonical —
+`CLAUDE.md` points here rather than repeating it.
+
+The review standard is separate, in
+[`.github/instructions/code-review.instructions.md`](.github/instructions/code-review.instructions.md).
+It lives at that path because Copilot code review reads `.github/instructions/*.instructions.md`
+natively and follows no links, so that is the only way it gets the standard without a second copy
+being maintained alongside it.
+
+## What this is
+
+An Electron desktop app ("WordPress Contributor Toolkit") that sets up a full WordPress core
+(`wordpress-develop`) dev environment with zero prerequisites — no Git, Node, npm, or Docker
+required on the host. Everything is bundled and run as JS/WASM inside the Electron process. Built
+to fix a Contributor Day problem: newcomers burning the whole session on local setup instead of
+contributing. Still labeled "experimental."
+
+## Before opening a pull request
+
+Run the review in `.github/instructions/code-review.instructions.md` against the branch, and fix or
+consciously defer every finding. Summarise the outcome in the pull request description — counts,
+what was fixed, what was left as a follow-up and why.
+
+Nothing enforces this. There is no automated review on pull requests, by design: it would mean
+storing an AI provider credential as a secret in a public repository. This pass is what stands in
+its place, so skipping it means a human reviewer is the first reader of the diff.
+
+That file carries the procedure as well as the standard. Follow it rather than improvising a
+review.
+
+## Commands
+
+See `package.json` scripts. To run a single test file (not exposed as a script):
+`node --test test/azure-sign.test.cjs`.
+
+## Architecture notes (non-obvious)
+
+- **Child processes run on Electron's own Node, not the system Node.** `npm install`,
+  `npm run <script>`, and the Playground server are spawned via `process.execPath` +
+  `ELECTRON_RUN_AS_NODE=1` — this is the mechanism behind "zero prerequisites." On Windows this
+  requires shimming `node`/`npm`/`npx` into `PATH` so child `npm` processes can find a `node` binary
+  at all.
+- **Git has no system dependency** — all Git ops go through `isomorphic-git`, not a shelled-out
+  `git` binary. Patch/diff generation is done by hand in `main.js` (stage untracked files, diff
+  working tree vs `HEAD` — the cloned trunk snapshot, kept deliberately as the diff base; see #94),
+  not `git diff`.
+- **`electron-store` is the only persistence layer** — no separate DB. It holds the site registry
+  and per-site metadata; treat it as the single source of truth for "known sites."
+- Long-running child-process output (installs, scripts, server) is streamed to the renderer via
+  correlated IDs (`installId`/`runId`), not returned synchronously — expect async event handlers,
+  not return values, when tracing that flow.
+
+## Signing & CI
+
+- **Buildkite builds signed Windows, Linux and macOS artifacts for every branch that has an open
+  PR.** So a branch is testable on a real machine without building locally — and for a stacked PR,
+  the artifact from the topmost branch exercises the whole stack. Force-pushing a branch invalidates
+  earlier artifacts: check the build corresponds to the current head commit before testing.
+- Windows signing (Azure Trusted Signing via `scripts/azure-sign.cjs`) is skipped automatically when
+  its required env vars aren't set — this is intentional for local dev, not a bug.
+- macOS signing/notarization uses fastlane + match against Automattic's Developer ID;
+  `verify_code_signing` lane must pass before shipping.
diff --git a/CLAUDE.md b/CLAUDE.md
index 2ea9558..0b7c004 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -1,24 +1,11 @@
 # CLAUDE.md
 
-This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+Read **[AGENTS.md](AGENTS.md)** — it holds the instructions for this repository, and is written to
+be read by any agent. Nothing that belongs there should be duplicated here.
 
-## What this is
+Claude Code specifics only:
 
-An Electron desktop app ("WordPress Contributor Toolkit") that sets up a full WordPress core (`wordpress-develop`) dev environment with zero prerequisites — no Git, Node, npm, or Docker required on the host. Everything is bundled and run as JS/WASM inside the Electron process. Built to fix a Contributor Day problem: newcomers burning the whole session on local setup instead of contributing. Still labeled "experimental."
-
-## Commands
-
-See `package.json` scripts. To run a single test file (not exposed as a script): `node --test test/azure-sign.test.cjs`.
-
-## Architecture notes (non-obvious)
-
-- **Child processes run on Electron's own Node, not the system Node.** `npm install`, `npm run <script>`, and the Playground server are spawned via `process.execPath` + `ELECTRON_RUN_AS_NODE=1` — this is the mechanism behind "zero prerequisites." On Windows this requires shimming `node`/`npm`/`npx` into `PATH` so child `npm` processes can find a `node` binary at all.
-- **Git has no system dependency** — all Git ops go through `isomorphic-git`, not a shelled-out `git` binary. Patch/diff generation is done by hand in `main.js` (stage untracked files, diff working tree vs `HEAD` — the cloned trunk snapshot, kept deliberately as the diff base; see #94), not `git diff`.
-- **`electron-store` is the only persistence layer** — no separate DB. It holds the site registry and per-site metadata; treat it as the single source of truth for "known sites."
-- Long-running child-process output (installs, scripts, server) is streamed to the renderer via correlated IDs (`installId`/`runId`), not returned synchronously — expect async event handlers, not return values, when tracing that flow.
-
-## Signing & CI
-
-- **Buildkite builds signed Windows, Linux and macOS artifacts for every branch that has an open PR.** So a branch is testable on a real machine without building locally — and for a stacked PR, the artifact from the topmost branch exercises the whole stack. Force-pushing a branch invalidates earlier artifacts: check the build corresponds to the current head commit before testing.
-- Windows signing (Azure Trusted Signing via `scripts/azure-sign.cjs`) is skipped automatically when its required env vars aren't set — this is intentional for local dev, not a bug.
-- macOS signing/notarization uses fastlane + match against Automattic's Developer ID; `verify_code_signing` lane must pass before shipping.
+- `/self-review` (`.claude/skills/self-review/SKILL.md`) is the entry point for the pre-PR review
+  that AGENTS.md asks for. It runs the procedure in
+  `.github/instructions/code-review.instructions.md` and dispatches the judgement pass to a
+  subagent, so the session that wrote the change is not the one grading it.