This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
Before writing any code, read .minispec/README.md and follow its reading contract. As a minimum, always read .minispec/core/project.md, .minispec/core/conventions.md and .minispec/core/principles.md; read the rest of .minispec/ only on demand (architecture, stack, glossary, the relevant feature or ADR). Keep features small and don't write redundant documentation.
Project knowledge (architecture, conventions, glossary) lives in .minispec/core/, not here. Work in progress (features and bugfixes for GitHub issues) lives in .minispec/features/.
Use the wrapper (./gradlew or gradlew.bat on Windows).
| Command | Purpose |
|---|---|
./gradlew build |
Compile, generate the Maven plugin descriptor and build the jars |
./gradlew clean build |
Rebuild from scratch when the Maven plugin descriptor looks stale |
./gradlew publishToMavenLocal |
Install the plugin into ~/.m2 to test it from a sample Maven/Gradle project |
./gradlew updateNativeJavaApplicationStub |
Re-download the native macOS launchers (nativeJavaApplicationStub*) into src/main/resources/mac from a javapackager/nativeJavaApplicationStub release |
./gradlew updateWhyJavaLauncher |
Re-download JavaLauncher.exe into src/main/resources/windows |
cd docs && npm install && npm start |
Preview the user documentation site (Docusaurus, Node.js 20+); npm run build fails on broken links |
There are no unit tests, so there is no way to run a single test. Changes are verified by the smoke tests in .github/workflows/smoke-tests.yml, which run on every push to devel/main: they package samples/hello-world (one sample with both pom.xml and build.gradle) with Maven on GNU/Linux, Windows and macOS (each macStartup) and with Gradle on each platform, and run .github/scripts/check-*-app.sh. Build with a JDK 17+ (a JRE can't compile).
User documentation is a Docusaurus site: pages in docs/content/, sidebar in docs/sidebars.js. It is published to GitHub Pages (https://javapackager.github.io/JavaPackager/) by .github/workflows/docs.yml on push to main, so it documents the latest release. README.md is only a quick start that links to it.
compileJava triggers generatePluginDescriptor, which runs an embedded Maven against the generated POM to produce META-INF/maven/plugin.xml from the @Mojo/@Parameter annotations.
Publishing uses a Central Portal user token in the ossrhUsername/ossrhPassword properties (~/.gradle/gradle.properties). Snapshots: ./gradlew publish (Central Portal snapshots repo). Releases: ./gradlew releaseToCentral (Portal OSSRH Staging API, then manual Publish in the Portal). The version is set in build.gradle.
| Skill or agent | Use it to |
|---|---|
ci-status |
Wait for the latest smoke tests run and summarize failures per job |
triage-issues (with the issue-triager agent) |
Classify open GitHub issues against devel, in parallel, read-only |
issue-update |
Draft and post "fixed in devel", "please test" or "released" comments, with labels |
check-deps |
Find outdated dependencies, check Java 8 bytecode and declared vs resolved versions |
publish-snapshot |
Publish the current devel build as a -SNAPSHOT (after green CI) and verify it |
release |
Release notes, releaseToCentral, verification and closing issues |
minispec-feature, minispec-bugfix, minispec-adr, minispec-implement |
MiniSpec notes and implementation |