Add agent skills configuration (#1048)

* Add agent skills configuration

Scaffold AGENTS.md, CLAUDE.md, and docs/agents/ so AI agent skills
(triage, to-issues, diagnose, tdd, etc.) know where issues live, which
triage labels to apply, and how to read domain docs in this repo.

- AGENTS.md: top-level agent instructions with the Agent skills block
- CLAUDE.md: re-exports AGENTS.md via @AGENTS.md syntax
- docs/agents/issue-tracker.md: GitHub conventions (gh CLI)
- docs/agents/triage-labels.md: canonical triage label mapping
- docs/agents/domain.md: single-context CONTEXT.md / docs/adr layout

* Move pnpm onlyBuiltDependencies to pnpm-workspace.yaml

pnpm 11 no longer reads the "pnpm" field from package.json and warns
"The 'pnpm' field in package.json is no longer read by pnpm." Because
unrs-resolver's build script was no longer approved, pnpm 11 treated the
ignored build as fatal (ERR_PNPM_IGNORED_BUILDS) and failed the install.

Move the setting to pnpm-workspace.yaml (pnpm 11's new home for it) and
drop the now-dead pnpm field from package.json.

* Revert "Move pnpm onlyBuiltDependencies to pnpm-workspace.yaml"

This reverts commit a8b3c3a.

* Pin pnpm to v10 in E2E workflow

pnpm/action-setup@v4 was set to version: latest, which now pulls pnpm 11.
pnpm 11 changed where onlyBuiltDependencies is read from (moved out of
package.json) and made ignored builds a fatal install error
(ERR_PNPM_IGNORED_BUILDS), breaking the E2E install step.

Pin to pnpm v10 so the existing package.json "pnpm" field is honored and
the install completes. Avoids chasing pnpm 11's evolving config surface.

Author: donnchawp

.github/workflows/e2e-tests.yml

@@ -16,7 +16,7 @@ jobs:
 
       - uses: pnpm/action-setup@v4
         with:
-          version: latest
+          version: 10
 
       - uses: actions/setup-node@v4
         with:

AGENTS.md

@@ -0,0 +1,17 @@
+# AGENTS.md
+
+Agent instructions for the wp-super-cache repository.
+
+## Agent skills
+
+### Issue tracker
+
+Issues live on GitHub at `Automattic/wp-super-cache` and are managed with the `gh` CLI. See `docs/agents/issue-tracker.md`.
+
+### Triage labels
+
+Five canonical triage labels (`needs-triage`, `needs-info`, `ready-for-agent`, `ready-for-human`, `wontfix`) plus categories `bug` and `enhancement`. See `docs/agents/triage-labels.md`.
+
+### Domain docs
+
+Single-context layout — one `CONTEXT.md` and `docs/adr/` at the repo root. See `docs/agents/domain.md`.

CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md

docs/agents/domain.md

@@ -0,0 +1,51 @@
+# Domain Docs
+
+How the engineering skills should consume this repo's domain documentation when exploring the codebase.
+
+## Before exploring, read these
+
+- **`CONTEXT.md`** at the repo root, or
+- **`CONTEXT-MAP.md`** at the repo root if it exists — it points at one `CONTEXT.md` per context. Read each one relevant to the topic.
+- **`docs/adr/`** — read ADRs that touch the area you're about to work in. In multi-context repos, also check `src/<context>/docs/adr/` for context-scoped decisions.
+
+If any of these files don't exist, **proceed silently**. Don't flag their absence; don't suggest creating them upfront. The producer skill (`/grill-with-docs`) creates them lazily when terms or decisions actually get resolved.
+
+## File structure
+
+Single-context repo (this repo):
+
+```
+/
+├── CONTEXT.md
+├── docs/adr/
+│   ├── 0001-event-sourced-orders.md
+│   └── 0002-postgres-for-write-model.md
+└── src/
+```
+
+Multi-context repo (presence of `CONTEXT-MAP.md` at the root):
+
+```
+/
+├── CONTEXT-MAP.md
+├── docs/adr/                          ← system-wide decisions
+└── src/
+    ├── ordering/
+    │   ├── CONTEXT.md
+    │   └── docs/adr/                  ← context-specific decisions
+    └── billing/
+        ├── CONTEXT.md
+        └── docs/adr/
+```
+
+## Use the glossary's vocabulary
+
+When your output names a domain concept (in an issue title, a refactor proposal, a hypothesis, a test name), use the term as defined in `CONTEXT.md`. Don't drift to synonyms the glossary explicitly avoids.
+
+If the concept you need isn't in the glossary yet, that's a signal — either you're inventing language the project doesn't use (reconsider) or there's a real gap (note it for `/grill-with-docs`).
+
+## Flag ADR conflicts
+
+If your output contradicts an existing ADR, surface it explicitly rather than silently overriding:
+
+> _Contradicts ADR-0007 (event-sourced orders) — but worth reopening because…_

docs/agents/issue-tracker.md

@@ -0,0 +1,22 @@
+# Issue tracker: GitHub
+
+Issues and PRDs for this repo live as GitHub issues at `Automattic/wp-super-cache`. Use the `gh` CLI for all operations.
+
+## Conventions
+
+- **Create an issue**: `gh issue create --title "..." --body "..."`. Use a heredoc for multi-line bodies.
+- **Read an issue**: `gh issue view <number> --comments`, filtering comments by `jq` and also fetching labels.
+- **List issues**: `gh issue list --state open --json number,title,body,labels,comments --jq '[.[] | {number, title, body, labels: [.labels[].name], comments: [.comments[].body]}]'` with appropriate `--label` and `--state` filters.
+- **Comment on an issue**: `gh issue comment <number> --body "..."`
+- **Apply / remove labels**: `gh issue edit <number> --add-label "..."` / `--remove-label "..."`
+- **Close**: `gh issue close <number> --comment "..."`
+
+Infer the repo from `git remote -v` — `gh` does this automatically when run inside a clone.
+
+## When a skill says "publish to the issue tracker"
+
+Create a GitHub issue.
+
+## When a skill says "fetch the relevant ticket"
+
+Run `gh issue view <number> --comments`.

docs/agents/triage-labels.md

@@ -0,0 +1,21 @@
+# Triage Labels
+
+The skills speak in terms of five canonical triage roles. This file maps those roles to the actual label strings used in this repo's issue tracker.
+
+| Canonical role     | Label in our tracker | Meaning                                  |
+| ------------------ | -------------------- | ---------------------------------------- |
+| `needs-triage`     | `needs-triage`       | Maintainer needs to evaluate this issue  |
+| `needs-info`       | `needs-info`         | Waiting on reporter for more information |
+| `ready-for-agent`  | `ready-for-agent`    | Fully specified, ready for an AFK agent  |
+| `ready-for-human`  | `ready-for-human`    | Requires human implementation            |
+| `wontfix`          | `wontfix`            | Will not be actioned                     |
+
+Category labels (applied alongside one state label): `bug`, `enhancement`.
+
+When a skill mentions a role (e.g. "apply the AFK-ready triage label"), use the corresponding label string from this table.
+
+## Repo-specific notes
+
+- `wontfix`, `bug`, `enhancement` already exist in the repo.
+- `needs-triage`, `needs-info`, `ready-for-agent`, `ready-for-human` were created during setup.
+- The repo has other historical labels (`Needs Review`, `reporter feedback`, `PRIORITY`, `[Status] In Progress`, etc.) that are **not** part of the triage state machine. Leave them alone unless asked.