coding

# Coding (Micronaut Committer) Use this skill for maintainer-facing Java implementation work in Micronaut repositories. Do not default to end-user application shortcuts. ## Goal Deliver minimal, source-backed Java changes that preserve framework quality: binary compatibility, JSpecify null-safety, reflection-free behavior, and full Gradle verification (`check`, `docs`, and compatibility checks when API-facing). ## Trigger Examples Should trigger: - "Implement this Micronaut Java feature in `src/main/java` and keep API compatibility." - "Refactor this module internals and mark non-public APIs correctly." - "Fix failing framework tests and prepare committer-ready validation output." - "Add configuration support using Micronaut conventions, not app-level shortcuts." Should not trigger: - "Explain Micronaut basics to a beginner." - "Create an end-user sample app from scratch." - "Only edit release notes/changelog text." ## Procedure 1. Establish scope and API impact. 2. Implement Java code with Micronaut maintainer conventions. 3. Enforce API boundaries and binary compatibility. 4. Keep Gradle/build changes aligned with repository conventions. 5. Verify with maintainer-grade checks before completion. ### 1) Establish scope and API impact - Identify affected modules and whether any change is public API or internal-only. - Inspect existing package patterns before editing (imports, nullability style, tests, naming). - For API-facing edits, plan compatibility checks up front (`japiCmp`). - Keep change surface minimal; avoid opportunistic refactors unless required. ### 2) Implement Java with Micronaut maintainer conventions - Prefer modern Java idioms where they improve clarity (records, sealed types, pattern matching, `var` for local inference), but only when supported by the repository toolchain/target level. - Do not use fully qualified class names unless import conflicts force it. - Micronaut Java code uses JSpecify nullness annotations from `org.jspecify.annotations`; use JSpecify for new or modified nullability contracts. - New Java packages must include `package-info.java` with `@NullMarked` and `import org.jspecify.annotations.NullMarked`; when touching an existing package without `@NullMarked`, add it unless the local code has an explicit exception. - Use `org.jspecify.annotations.Nullable` for nullable values, including nullable parameters, return values, fields, array/component positions such as `String @Nullable []`, nullable collection elements such as `List<@Nullable T>`, and nullable type bounds such as `<T extends @Nullable Object>`. - Preserve existing nullability intent when editing older code. Use JSpecify for new or modified contracts, but do not rewrite deliberate compatibility annotations such as `io.micronaut.core.annotation.Nullable` or `jakarta.annotation.Nullable` unless the task is specifically a nullability migration and compatibility impact has been checked. - Avoid reflection-oriented implementations in framework code paths; prefer Micronaut compile-time/introspection mechanisms. - Use `jakarta.inject` APIs for DI, not `javax.inject`. - Prefer constructor injection and immutable state over field injection. - For configuration models, prefer `@ConfigurationProperties` over scattered `@Value` usage. ### 3) Enforce API boundaries and compatibility - Treat all public-facing changes through a Semantic Versioning lens (`https://semver.org/`) before implementation. - Classify impact explicitly: patch for backward-compatible fixes, minor for backward-compatible feature additions, major for breaking API/behavioral changes. - Keep public API binary compatible unless a major-version change explicitly allows breaks. - Prefer non-breaking API evolution first: deprecate existing methods and add replacement variants/overloads instead of deleting methods or changing signatures in place. - When using the deprecate-and-add path, keep deprecated APIs functional, point to replacements in Javadoc, and schedule removals only for the next major version. - If breaking public-facing changes are explicitly allowed, document them in the user guide under `src/main/docs/guide` with migration notes, and update `toc.yml` when adding new guide sections. - Mark non-user-facing APIs with `@io.micronaut.core.annotation.Internal`. - Mark unstable public APIs with `@io.micronaut.core.annotation.Experimental` and avoid presenting them as stable contracts. - Mark members directly called by generated code with `@io.micronaut.core.annotation.UsedByGeneratedCode`; preserve those signatures unless the generated-code callers are updated in the same change. - Keep visibility as narrow as possible for non-public internals. - When deprecating API, provide migration-friendly Javadoc and avoid silent behavioral breaks. ### 4) Keep Gradle/build changes convention-aligned - Use `./gradlew` for all Gradle execution. - Use Gradle version catalogs (`gradle/libs.versions.toml`) instead of hard-coded dependency versions. - Use appropriate scopes (`api`, `implementation`, `compileOnly`, `runtimeOnly`) based on API exposure. - Do not add custom build logic directly in module build files when it belongs in convention plugins. - When uncertain about module paths, use `./gradlew projects` and prefer canonical `micronaut-*` project names. ### 5) Verify before completion First confirm canonical verification tasks from `CONTRIBUTING.md` and existing CI/build files, then run the repository equivalents from root. Common sequence in Micronaut repositories: ```bash ./gradlew :<module>:compileTestJava # If module includes Groovy tests: ./gradlew :<module>:compileTestGroovy ./gradlew :<module>:test --tests 'pkg.ClassTest' ./gradlew :<module>:test # If repository documents cM alias/checkstyle aggregate task: ./gradlew -q cM ./gradlew -q spotlessCheck ./gradlew check ./gradlew docs ``` For API-affecting changes, also run if configured in the repository: ```bash ./gradlew japiCmp ``` If Spotless fails, run `./gradlew -q spotlessApply` and re-run `spotlessCheck`. ## Guardrails - Do not introduce `javax.inject` usage. - Do not introduce legacy or third-party nullability annotations for new or modified Micronaut Java contracts when JSpecify is available, except for deliberate compatibility annotations whose impact has been checked. - Do not hard-code dependency versions in module build files. - Do not break public APIs without explicit major-version intent. - Do not skip tests or docs verification for code changes. - Do not use reflection as a convenience in framework internals. ## Delivery Contract When finishing implementation work, report: 1. Exactly which files changed and why. 2. Whether the change is API-facing or internal-only. 3. Semantic Versioning impact classification (patch/minor/major) for any public-facing change. 4. For deprecate-and-add API evolution, which elements were deprecated and which replacement variants were introduced. 5. For breaking public-facing changes, which user guide files were updated and what migration guidance was added. 6. Commands executed for verification and outcomes. 7. Any follow-up risk (for example compatibility implications). ## Validation Checklist - [ ] `SKILL.md` frontmatter is valid and `name` matches directory (`coding`). - [ ] Guidance is maintainer-focused (not end-user app guidance). - [ ] Java conventions include JSpecify nullability (`@NullMarked`, `@Nullable`), DI, and reflection-free guidance. - [ ] API boundary guidance includes `@Internal`, `@Experimental`, `@UsedByGeneratedCode`, and compatibility checks. - [ ] For public API evolution without breaking changes, deprecations include clear replacement guidance and functional compatibility is preserved. - [ ] If breaking changes are allowed, user guide docs in `src/main/docs/guide` are updated with migration notes. - [ ] Verification includes tests, style checks, `check`, and `docs`. ## References - `CONTRIBUTING.md` - `MAINTAINING.md` - `.agents/skills/gradle/SKILL.md` - `.agents/skills/docs/SKILL.md` - `.agents/skills/skill-creator/references/spec-checklist.md`