Update agent tooling by cwfitzgerald · Pull Request #10202 · gfx-rs/wgpu

cwfitzgerald · 2026-08-30T03:15:16Z

Connections

Description

Please review this commit-by-commit, these are standalone commits. A lot of this PR is adding duplicate files.

This reworks our agent tooling:

Rewrites our AGENTS.md to include more useful and accurate information for agents.
We had a .claude for skills and an AGENTS.md. Codex/Pi read the AGENTS.md but not the .claude; claude reads the .claude but not the AGENTS.md. We can't use symlinks due to problems on windows, so this wholesale duplicates everything to AGENTS.md. (It is possible to just include references that the LLM evaluates, but that wastes valuable context on extra tool calls, and it doesn't always follow instructions).
We have using an esoteric and never checked nushell script for syncing up files (like broadcast_license.nu) this adds a proper xtask sync-metadata and CI job to check that this stays up to date.
Also updated our copyright date on the MIT license.
This also adds a check for LLM-authored commits, which I vendored in from https://github.com/Jondolf/ai-commit-check

Testing

Checked that new claude sessions have the CLAUDE.md context, checked that Codex has the webgpu-spec skill. Tests exist for the sync-metadata xtask

Squash or Rebase?

Rebase, each commit is standalone.

Checklist

I self-reviewed and fully understand this PR.
WebGPU implementations built with wgpu may be affected behaviorally.
Validation and feature gates are in place to confine behavioral changes.
Tests demonstrate the validation and altered logic works.
CHANGELOG.md entries for the user-facing effects of this change are present.
The PR is minimal, and doesn't make sense to land as multiple PRs.
Commits are logically scoped and individually reviewable.
The PR description has enough context to understand the motivation and solution implemented.

JMS55 · 2026-08-30T18:08:46Z

Imo, you should also add the Vulkan/DirectX/Metal/Spirv/etc specs. I have been asking claude to check its code/design against the specs a lot.

cwfitzgerald · 2026-08-30T18:26:59Z

That sounds good, but can be a follow up, there's already a bunch going on in this PR

ErichDonGubler

Not committing to a full review (but open to it). Some thoughts I had while skimming.

andyleiserson · 2026-09-02T15:23:09Z

Does @AGENTS.md not work as a referral? I have had that in CLAUDE.local.md for a while, and haven't noticed any problems.

cwfitzgerald · 2026-09-02T16:57:04Z

Let me test it, my understanding is that this is a thing that the agent has to explicitly take action on and do a tool call but I could be wrong.

ErichDonGubler

RE: changes requested: This LGTM overall, but I've noticed a number of things that give me pause with immediately merging. I've tried to be explicit about what I consider blocking and what's not, but may have missed something; LMK if anything's unclear, I'm out of time to review on this.

meta: This…was a lot to review. The commits in here were sensible, and following them wasn't difficult (❤️). To recap my understanding, this PR:

Adds an ai-commit-check job in CI
Adds cargo xtask sync-metadata with another new CI job, which enforces:
- Sync'ed skill contents for different LLM tools
- Sync'ed software license files between all crates

I'm not sure I agree that it made sense to keep all of these as a single PR.

I can see some defense for just wanting the unit of review for all the pieces of sync-metadata to be commits, rather than a PR (minus how complicated FS code is, which I definitely didn't have time to review fully).
However, the AI commit check specifically seems entirely orthogonal.

_{I used Conventional Comments in this review! I hope they help with clarity and tone. 🙂}

ErichDonGubler · 2026-09-15T09:05:25Z

+Run `sh .agents/skills/webgpu-specs/download.sh` to download the
+WebGPU and WGSL specifications if they are not present or if they have
+been updated. You do not need to change directory before running the script.
+
+After the specs are downloaded, you can search in `target/claude/webgpu-spec.bs`
+and `target/claude/wgsl-spec.bs` for relevant sections of the specification.
+


nit(non-blocking): I suspect we'll need to include some criteria for invalidating cached copies of the spec., since we're an audience that is sensitive to recent changes.

There's a "if they have been updated" in the previous sentence, we'll see if that's enough. It may or may not be.

ErichDonGubler · 2026-09-15T09:12:19Z

+
+For the WGSL specification, the base URL is <https://gpuweb.github.io/gpuweb/wgsl/>.
+
+If necessary, read additional content from the file to find the header preceding


thought: Do we need to be more specific about using links? We don't provide concrete examples or even Web-centered terminology in what we're expecting here. In order of priority, I'd hope the agent tries to provide:

A link to the header via anchor (i.e., navigating to the id="section" part of the page with #section)

A link to a text fragment (i.e., #:~:text=Some%20specific%20text)

These can be combined (i.e., #section:~:text=Some%20specific%20text) so that (2) is attempted, but if the text isn't found, then it falls back to (1). This seems like a very helpful combination with graceful behavior if the text changes enough to break a text fragment link.

Potentially, though the agent should have some idea how bikeshed works. I'll add this as a potential follow up.

ErichDonGubler · 2026-09-15T15:50:55Z

+## Squash or Rebase?
+
 _If your pull request contains multiple commits, please indicate whether
 they need to be squashed into a single commit before they're merged,
 or if they're ready to rebase onto `trunk` as they stand. In the
 latter case, please ensure that each commit passes all CI tests, so
 that we can continue to bisect along `trunk` to isolate bugs._



thought: After many months of growing to dislike filling out this section of the template, I suspect it would be better if this were enforced with CI or even not at all.

We already have selection of a merge method via a label with Mergify now. Maybe we could use a check to block CI for such a label if all the commits aren't a base plus optional fixup!/FIXUP:/etc. commits?

CC @gfx-rs/wgpu here; I'll raise this in today's maintainers' meeting. ☝🏻

ErichDonGubler · 2026-09-15T15:51:19Z

@@ -1,34 +1,45 @@
-**Connections**
+## Connections


praise: I've long wondered why we didn't use section headers. This feels welcome. ❤️

ErichDonGubler · 2026-09-16T09:49:20Z

+// In `Check` mode errors on any differences, in `Write` mode
+// deletes extra files/directories, copies updated ones, and makes
+// missing ones.
+fn sync_directory(


thought: We're taking on quite a bit of scope here with file synchronization. That's unfortunate, but I'm not sure I see a better way than what's already written (yet).

File synchronization is a notoriously complicated problem, usually with notoriously complicated solutions. This has real tension with wanting to keep xtask fast to compile (viz., simple code). I suspect we're going to be fixing bugs in our own code here for a while, but they'll only as they slowly (and intermittently) show up. I'm concerned about that, but not in a way that makes me want to block.

I don't see anything on Crates.io that looks like a fit with (1) being fast to compile, (2) has the features/behavior we need (particularly with diagnostics), and (3) is trustworthy. If you're interested, we can talk about what exists out there as a potential replacement in an issue.

What gottchas are you thinking of - this doesn't need to be a generic implementation of syncing, it's very well bounded:

No symlinks

One file system

Copies are one direction, with one side having authority (so no diffs)

This is basically glorified rm + cp.

ErichDonGubler · 2026-09-16T09:53:26Z

+    // Both sides of the `strip_prefix` below must be canonical. Windows
+    // canonicalization adds a `\\?\` prefix that `cargo metadata` does not use.


nit: We should use dunce to implement canonicalization, if this is a concern.

I'm not sure what the actual difference here for us - dunce has the advantage of keeping the paths human readable, but NT UNC paths are just as canonical

ErichDonGubler · 2026-09-16T09:54:21Z


+## Repository Metadata
+
+`AGENTS.md` and `.agents/` are the source of truth for agent instructions and skills. `CLAUDE.md` and `.claude/` are generated copies. Do not edit the generated copies directly. After you edit any source-of-truth metadata file or a root license file, run `cargo xtask sync-metadata`. This command also copies the root license files to every publishable default member of the Cargo workspace.


suggestion(non-blocking): As follow-up, it'd be nice to have these disclaimers in the .claude files themselves.

I don't want to take up additional LLM context with this, but we could add a README in the .claude which says don't edit these files. LLMs won't as they have this context, but a human might, but will be caught by CI.

cwfitzgerald · 2026-09-16T10:59:38Z

This is an amazingly thorough and thoughtful review, thank you!!

stuartparmenter

I suspect you could simplify some of the skills a bit for some frontier models, but them being more verbose is probably better for other models -- I generally wouldn't overthink them though as you'll end up just chasing model behavior

cwfitzgerald force-pushed the cf/update-agent-tooling branch 3 times, most recently from 110c19f to aff08ef Compare August 30, 2026 03:29

Vipitis reviewed Aug 30, 2026

View reviewed changes

Comment thread CLAUDE.md Outdated

cwfitzgerald force-pushed the cf/update-agent-tooling branch 4 times, most recently from 03f46e2 to 53f13e5 Compare August 30, 2026 22:50

kpreid reviewed Aug 31, 2026

View reviewed changes

Comment thread CONTRIBUTING.md Outdated

ErichDonGubler reviewed Aug 31, 2026

View reviewed changes

Comment thread .github/pull_request_template.md

Comment thread .github/pull_request_template.md

cwfitzgerald mentioned this pull request Aug 31, 2026

Reconsider PR Checklist #10209

Open

cwfitzgerald force-pushed the cf/update-agent-tooling branch 2 times, most recently from b0180d7 to 5a386c7 Compare August 31, 2026 13:48

cwfitzgerald added this to Triage Aug 31, 2026

github-project-automation Bot moved this to To triage in Triage Aug 31, 2026

inner-daemons self-requested a review September 2, 2026 15:20

cwfitzgerald assigned ErichDonGubler Sep 2, 2026

inner-daemons self-assigned this Sep 2, 2026

ErichDonGubler moved this from To triage to Large in Triage Sep 2, 2026

cwfitzgerald mentioned this pull request Sep 4, 2026

Documentation Coherence Pass #10205

Open

8 tasks

cwfitzgerald force-pushed the cf/update-agent-tooling branch from 5a386c7 to 416f504 Compare September 14, 2026 14:22

github-advanced-security Bot found potential problems Sep 14, 2026

View reviewed changes

Comment thread .github/workflows/ci.yml Fixed

cwfitzgerald added 4 commits September 14, 2026 11:02

Improve agent documentation

8da6b97

Add shared agent skills

f3294e0

Update license copyright year

cc44b6c

Add repository metadata sync

cd4c3b0

cwfitzgerald added 3 commits September 14, 2026 11:02

Sync repository metadata

9f9ae34

Check repository metadata in CI

8521e25

Add check for LLM-authored commits

830977b

cwfitzgerald force-pushed the cf/update-agent-tooling branch from 416f504 to 830977b Compare September 14, 2026 15:02

cwfitzgerald mentioned this pull request Sep 14, 2026

Fix changelog checks when the base branch advances #10342

Merged

10 tasks

ErichDonGubler requested changes Sep 16, 2026

View reviewed changes

cwfitzgerald added 7 commits September 16, 2026 10:57

fixup: Rename sync-metadata to sync-repo-files

ad71cd8

fixup: Extract file synchronization module

a2685b9

fixup: Move git ignore details into implementation

899b908

fixup: Document synchronization modes on variants

db4d713

fixup: Correct CTS result list terminology

fda50d9

fixup: Exclude remote crates from changelog guidance

87999be

fixup: Correct unadulterated spelling

84806c1

stuartparmenter approved these changes Sep 16, 2026

View reviewed changes


		For the WGSL specification, the base URL is <https://gpuweb.github.io/gpuweb/wgsl/>.

		If necessary, read additional content from the file to find the header preceding

		// Both sides of the `strip_prefix` below must be canonical. Windows
		// canonicalization adds a `\\?\` prefix that `cargo metadata` does not use.


		## Repository Metadata

		`AGENTS.md` and `.agents/` are the source of truth for agent instructions and skills. `CLAUDE.md` and `.claude/` are generated copies. Do not edit the generated copies directly. After you edit any source-of-truth metadata file or a root license file, run `cargo xtask sync-metadata`. This command also copies the root license files to every publishable default member of the Cargo workspace.

Conversation

cwfitzgerald commented Aug 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

JMS55 commented Aug 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

cwfitzgerald commented Aug 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

ErichDonGubler left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

andyleiserson commented Sep 2, 2026

Uh oh!

cwfitzgerald commented Sep 2, 2026

Uh oh!

Uh oh!

ErichDonGubler left a comment

Choose a reason for hiding this comment

Uh oh!

ErichDonGubler Sep 15, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

cwfitzgerald commented Sep 16, 2026

Uh oh!

stuartparmenter left a comment

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

9 participants

cwfitzgerald commented Aug 30, 2026 •

edited

Loading

JMS55 commented Aug 30, 2026 •

edited

Loading

cwfitzgerald commented Aug 30, 2026 •

edited

Loading

ErichDonGubler Sep 15, 2026 •

edited

Loading