chore: add Claude Code project knowledge and helper skills#291
Conversation
Capture the non-obvious dev workflow so future sessions don't rediscover it: - CLAUDE.md: local verification recipe (mock server, --no-daemon for TEST_GRADLE_VERSION), build/version gotchas (ProjectBuilder Problems-service regression on Gradle 8.12/8.13, Spotless 8.1+/Java 17), the release process (VERSION file + release.yml tag check, dual README), and in-thread review-reply conventions. - .claude/skills/verify-locally: runnable steps to mirror each CI job locally. - .claude/skills/prepare-release: the version/changelog/README release checklist. Version numbers are intentionally not duplicated here; README.md / build.gradle remain the source of truth. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This pull request introduces documentation and instructions for Claude, including release preparation guidelines, local verification steps, and general project-specific knowledge. The review feedback highlights an inaccuracy in CLAUDE.md regarding the Spotless version and its requirements, and suggests removing a redundant publishToMavenLocal task from the local verification command to speed up the process.
Important
The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.
| - **Spotless 8.x** requires Gradle 8.1+ and Java 17. It is applied only on | ||
| Gradle 8.1+ (guard in `build.gradle`) so the lowest acceptance-matrix Gradle | ||
| row still validates the stated minimum. |
There was a problem hiding this comment.
The description of Spotless here is inaccurate. The project actually uses Spotless version 7.2.1 (configured in build.gradle line 10), which requires Java 11 (as noted in the comment on line 267 of build.gradle). Furthermore, there is no guard in build.gradle restricting Spotless to Gradle 8.1+; it is applied unconditionally to allprojects.
| - **Spotless 8.x** requires Gradle 8.1+ and Java 17. It is applied only on | |
| Gradle 8.1+ (guard in `build.gradle`) so the lowest acceptance-matrix Gradle | |
| row still validates the stated minimum. | |
| - **Spotless 7.2.1** is used and requires Java 11 (as noted in build.gradle). It is applied unconditionally to all projects, so Java 11+ is required to run the build/lint tasks. |
| 3. **Pick the job to mirror:** | ||
| | CI job | Command | | ||
| |---|---| | ||
| | `unit-test` | `./gradlew publishToMavenLocal test` | |
There was a problem hiding this comment.
Running publishToMavenLocal is redundant for unit tests. The test task runs unit tests using the plugin's classes directly on the classpath (configured via createClasspathManifest in build.gradle), so publishing to Maven Local is unnecessary and slows down local verification. Consider updating the command to ./gradlew test.
There was a problem hiding this comment.
Pull request overview
Adds Claude Code project assets that capture repository-specific workflow knowledge (local CI reproduction and release prep) to reduce rediscovery overhead for future contributors. No production plugin code changes are included.
Changes:
- Add
CLAUDE.mdwith local verification guidance, build/version gotchas, and release/review conventions. - Add a
verify-locallyskill with runnable, CI-mirroring local commands. - Add a
prepare-releaseskill with a release checklist for version/changelog/README updates.
Reviewed changes
Copilot reviewed 3 out of 3 changed files in this pull request and generated 5 comments.
| File | Description |
|---|---|
CLAUDE.md |
New repo knowledge doc covering local verification, build/release gotchas, and review conventions. |
.claude/skills/verify-locally/SKILL.md |
New helper skill mapping CI jobs to local commands (mock server + test/lint runs). |
.claude/skills/prepare-release/SKILL.md |
New helper skill documenting the release preparation checklist and stopping point for human approval. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| Gradle commands need to write `~/.gradle` and reach the network, so run them | ||
| **outside the command sandbox**. Use a JDK that satisfies the wrapper's Gradle | ||
| version (the build/dev baseline is JDK 17). |
| - **Mock server (required for HTTP specs).** `ApiClientSpec` and the upload | ||
| acceptance specs talk to `TEST_SERVER_URL`; without it they hit | ||
| `https://deploygate.com` and fail with `NetworkFailure` / `Connection reset`. |
| - **Spotless 8.x** requires Gradle 8.1+ and Java 17. It is applied only on | ||
| Gradle 8.1+ (guard in `build.gradle`) so the lowest acceptance-matrix Gradle | ||
| row still validates the stated minimum. |
| - Reply to review comments — **including bots (devin, gemini, Copilot)** — in | ||
| the comment thread with an `@mention` of the author: | ||
| `gh api repos/{owner}/{repo}/pulls/{pr}/comments/{id}/replies -f body=...` | ||
| (not as a top-level PR comment). |
| 1. **Run outside the command sandbox** — Gradle writes `~/.gradle` and hits the | ||
| network. Use a JDK 17 (the build baseline). `export JAVA_HOME=<jdk17>`. |
Summary
Captures the non-obvious development workflow of this repo as Claude Code project assets, so future sessions (and contributors) don't have to rediscover it. No production code changes.
CLAUDE.md(project knowledge)TEST_SERVER_URL), and the--no-daemonrequirement when settingTEST_GRADLE_VERSION(a reused daemon caches env and GradleRunner throws'null' is not a valid Gradle version).Problems service is not initializedregression on Gradle 8.12/8.13 ([Gradle 8.12] "Problems service is not initialized error" in plugin unit tests gradle/gradle#31862, fixed in 8.14); Spotless 8.x needing Gradle 8.1+/Java 17; wrapper Gradle vs minimum user Gradle.src/main/resources/VERSION+release.ymltag check, keeping both READMEs in sync.@mentionreplies (incl. bots).Version numbers are intentionally not duplicated here —
README.md/build.gradlestay the source of truth..claude/skills/verify-locally— runnable steps to mirror each CI job locally.prepare-release— the version/changelog/README release checklist (stops for human approval before committing).These are grounded in the workflows exercised repeatedly while preparing the 2.10.0 release (every documented gotcha was hit and resolved in practice).
🤖 Generated with Claude Code