chore(docs): recreate CLAUDE.md, add /release skill, drop stale docs#207
Conversation
Remove doc/ai-rules.md and doc/commands.md (and the local .claude/run-configuration.md)
and recreate CLAUDE.md as a lean, self-contained, accurate guide — folding in only the
genuinely-enforced constraints (CuiLogger, forbidden Mockito/PowerMock/Hamcrest,
pre-commit gate, JSpecify direction, deprecation policy, cui-test-generator) and dropping
the verbose AI-framework prose and {STANDARDS_BASE_URL} indirection. Fixes stale content
along the way (logging ranges stop at ERROR — no FATAL level).
Add a project-specific /release skill under .claude/skills/release/, adapted from the
cui-http release skill (PR #83) to cui-java-tools: repo/coords, the three-segment X.Y.Z
patch-line scheme (pom floats on X.Y-SNAPSHOT), Java 21+25 build matrix, and this
library's release-note themes.
.gitignore: track .claude/skills/ (shared) while keeping local .claude settings ignored;
ignore the plan-marshall .plan/ working directory.
Co-Authored-By: Claude <noreply@anthropic.com>
📝 WalkthroughWalkthroughThis PR adds a new AI-agent release skill document, updates .gitignore for Claude skills/plan directories, substantially rewrites CLAUDE.md's engineering and workflow guidance, and removes two legacy documentation files (doc/ai-rules.md, doc/commands.md). ChangesAI Tooling Documentation and Release Workflow
Estimated code review effort: 2 (Simple) | ~15 minutes Possibly related PRs
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![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 a new release skill markdown file (.claude/skills/release/SKILL.md) outlining the automated release workflow, updates .gitignore to track shared Claude skills while ignoring local settings and the .plan/ directory, refactors CLAUDE.md to provide clearer, more structured guidance for Claude Code, and removes obsolete AI development guidelines and command configuration files. The reviewer suggested avoiding hardcoding the specific version 2.6-SNAPSHOT in CLAUDE.md to prevent the documentation from becoming stale.
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.
Address Gemini review: replace the hardcoded '2.6-SNAPSHOT' current-version with a reference to pom.xml plus the generic 'X.Y-SNAPSHOT' minor-line note, so the file doesn't go stale on the next version bump. Co-Authored-By: Claude <noreply@anthropic.com>
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 2
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In @.claude/skills/release/SKILL.md:
- Around line 101-111: The release commit example in SKILL.md is missing the
required Co-Authored-By trailer because the current git commit example only
provides a subject line. Update the example around the release workflow steps
and the git commit invocation so it shows how to include the trailer correctly,
using the commit example itself (and its git commit line) as the reference
point; prefer a second message paragraph or a trailer option so copy/paste
preserves the documented convention.
In `@CLAUDE.md`:
- Around line 103-105: The PR checks command in the CI guidance uses a redundant
while loop around gh pr checks --watch, which can loop forever on failures.
Update the instructions in CLAUDE.md to reference gh pr checks --watch directly
without the while ! wrapper, and keep the surrounding review-step wording
aligned with the command in that section.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro Plus
Run ID: 1dc89bbe-a303-427d-ac93-84abf1e2d76f
📒 Files selected for processing (5)
.claude/skills/release/SKILL.md.gitignoreCLAUDE.mddoc/ai-rules.mddoc/commands.md
💤 Files with no reviewable changes (2)
- doc/commands.md
- doc/ai-rules.md
| ```bash | ||
| git add .github/project.yml | ||
| git commit -m "chore(release): prepare release <version>" | ||
| git push -u origin chore/release_<version> | ||
| gh pr create --repo cuioss/cui-java-tools --base main \ | ||
| --title "chore(release): prepare release <version>" \ | ||
| --body "Bump current-version to <version>. Triggers the automated Release workflow on merge." | ||
| ``` | ||
|
|
||
| Use the project commit convention: `Co-Authored-By: Claude <noreply@anthropic.com>` (no | ||
| model name / no "Generated with Claude Code" footer). |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
set -euo pipefail
file=".claude/skills/release/SKILL.md"
echo "== file info =="
wc -l "$file"
echo
echo "== outline =="
ast-grep outline "$file" --view expanded || true
echo
echo "== lines 85-125 =="
sed -n '85,125p' "$file" | cat -nRepository: cuioss/cui-java-tools
Length of output: 2128
Include the Co-Authored-By trailer in the commit example. git commit -m only adds the subject line here, so a copy/paste of this snippet will miss the required trailer. Use a second -m paragraph or --trailer so the example matches the documented convention.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In @.claude/skills/release/SKILL.md around lines 101 - 111, The release commit
example in SKILL.md is missing the required Co-Authored-By trailer because the
current git commit example only provides a subject line. Update the example
around the release workflow steps and the git commit invocation so it shows how
to include the trailer correctly, using the commit example itself (and its git
commit line) as the reference point; prefer a second message paragraph or a
trailer option so copy/paste preserves the documented convention.
| 5. Wait for CI + Gemini review: | ||
| `while ! gh pr checks --repo cuioss/cui-java-tools <pr> --watch; do sleep 60; done`. | ||
| 6. Address every review comment (fix or explain, then resolve). If uncertain about a |
There was a problem hiding this comment.
🩺 Stability & Availability | 🟡 Minor | ⚡ Quick win
Drop the while ! wrapper around gh pr checks --watch. --watch already waits for completion; retrying on a red PR just loops forever and hides the failure state.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@CLAUDE.md` around lines 103 - 105, The PR checks command in the CI guidance
uses a redundant while loop around gh pr checks --watch, which can loop forever
on failures. Update the instructions in CLAUDE.md to reference gh pr checks
--watch directly without the while ! wrapper, and keep the surrounding
review-step wording aligned with the command in that section.
1 participant
Summary
Repo-hygiene PR bundling two related pieces of local tooling/docs (per agreed grouping).
CLAUDE.md recreation + doc removal
doc/ai-rules.mdanddoc/commands.md(and the local, untracked.claude/run-configuration.md).CLAUDE.mdas a lean, self-contained guide: folds in only the genuinely-enforced constraints (CuiLogger, forbidden Mockito/PowerMock/Hamcrest, pre-commit gate, JSpecify direction, deprecation policy, cui-test-generator) and drops the verbose "AI framework" prose and{STANDARDS_BASE_URL}indirection.ToolsLogMessages), and the two dangling references to the removed docs are gone./release skill (from cui-http PR #83)
.claude/skills/release/SKILL.md, adapted from the cui-http release skill to cui-java-tools:cuioss/cui-java-tools, coordsde.cuioss:cui-java-tools;X.Y.Zpatch-line scheme (release = patch-bumpcurrent-version, e.g.2.6.2→2.6.3; the pom floats permanently on2.6-SNAPSHOT, sonext-versionis left unchanged for patch releases) — this differs from cui-http'sX.Yscheme;.github/project.ymlbump that triggers.github/workflows/release.yml; it never hand-runs Maven release goals..gitignore
.claude/was fully ignored, which would make a tracked skill impossible. Now ignores local.claude/*settings but un-ignores.claude/skills/so shared skills are versioned (matching cui-http)..plan/working directory.Verification
./mvnw -Ppre-commit clean verify -DskipTests— BUILD SUCCESS, clean working tree (no rewrite churn). No Java sources changed.Summary by CodeRabbit