[jbachorik]

What does this change do?

Adds .claude/skills/steward/SKILL.md. It is repo-specific guidance that a Claude Code agent reads before it acts on CI results or review comments on a PR it is driving. It is also an ordinary invocable skill for Claude Code sessions in this repo. It links to AGENTS.md instead of repeating it, and covers:

• Branches and merging: PRs target develop and are squash-merged with Conventional Commits titles. The agent's own branches take develop in with a merge commit, and are not force-pushed after review.
• Before every push:
  • Run spotlessCheck and the tests of changed modules.
  • Local verification needs JDK 8 (common.gradle), JDK 24 (the java24 source set) and JDK 28 (classFileApiBackendTest). When one is missing, say so in the PR's Testing section instead of ticking the box.
  • Regenerate golden data only with -PupdateTestData.
• CI triage: how to recognize the failures seen on fix(deps): update all non-major dependencies #960, chore(deps): update dependency java-jdk to v25 #958 and fix(deps): update dependency org.junit.jupiter:junit-jupiter to v6 - autoclosed #916 (formatter drift, a missing toolchain, the JUnit 6 / JDK 8 clash) and what to do about each. A Maven Central 429 gets one re-run at most.
• Dependency-bot PRs:
  • Never push to renovate/* branches. Renovate force-rebases them, and dependency-auto-merge.yml would auto-merge the agent's commit under the bot's approval.
  • Fix the root cause in a separate PR from develop: a Renovate rule for an intentional pin, or the code changes a wanted upgrade needs.
• Review follow-up: changes to the masked-JAR layout, class-loader boundaries or the wire protocol never count as small asks. Requests for integration-test coverage are not optional.

Related issue

N/A. Follow-up to #974.

Scope and compatibility

• I identified the affected module(s) and kept unrelated changes out of this PR.
• This preserves the supported Java/runtime compatibility tiers, or the change is documented below.
• This does not change the masked-JAR layout, class-loader boundary, or wire protocol.
• If it does, I updated the relevant architecture documentation and verification plan. (N/A)

Compatibility or migration notes:

Adds one agent-guidance file. No build or runtime change.

Testing

• Unit tests (N/A: no code)
• Integration tests (N/A)
• spotlessCheck (N/A: no Java sources)
• Documentation/link or sample verification

Commands and results:

test -f .claude/skills/steward/../../../AGENTS.md   # relative link resolves
git check-ignore .claude/skills/steward/SKILL.md     # exit 1: not ignored

I checked the facts the skill states against the repo:

• common.gradle:22 resolves the JDK 8 compiler eagerly.
• btrace-agent/build.gradle:38 sets the JDK 24 toolchain, and :184 the JDK 28 launcher, with check.dependsOn classFileApiBackendTest.
• .github/workflows/dependency-auto-merge.yml approves renovate[bot] PRs and merges them after BTrace CI/CD and CodeQL pass.
• Recent develop history consists of (#NNN) squash commits.

Documentation and release impact

• User-facing documentation is updated, or no documentation change is needed.
• Release notes/changelog are updated, or no release-note entry is needed.
• Samples, distribution contents, or published coordinates are updated if affected.
• This change is safe to merge independently of a release, or the dependency is explained below.

Release notes / follow-up work:

The skill's Spotless line works whether or not #974 has merged. Two conventions are worth confirming before merge, because they reflect what I observed rather than a written rule: merge-commit updates on the agent's own branches, and squash-merge as the norm.

Final checklist

• I reviewed the complete diff and removed unrelated changes.
• New or changed behavior has appropriate tests, or the reason for not adding them is explained above.
• User-facing behavior, APIs, samples, and documentation are consistent with this change.
• I did not include generated build output, local configuration, credentials, or other accidental files.

---

Generated by Claude Code

---

This change is