Merge pull request #161 from javaevolved/brunoborges-modern-java-agent-plugin

Add version-aware modern Java agent plugin

Author: brunoborges

.gitignore

@@ -19,6 +19,7 @@ site/data/snippets.json
 
 # Generated index page (built from templates/index.html by html-generators/)
 site/index.html
+site/agent-plugin.html
 
 # Generated locale directories (built by html-generators/ for non-English locales)
 site/[a-z][a-z]/

README.md

@@ -50,6 +50,13 @@ This site uses a **JSON/YAML-first** build pipeline:
 - **Translations**: `translations/strings/{locale}.yaml` for UI strings, `translations/content/{locale}/` for pattern content (YAML)
 - **Deploy**: GitHub Actions runs the generator and deploys to GitHub Pages
 
+### Agent plugin
+
+[`agent-plugins/modern-java-development`](agent-plugins/modern-java-development/)
+is a portable Agent Plugins 1.0 package for version-aware Java development. Its
+skill detects a project's effective compilation target, then limits guidance to
+final language features and APIs available in that Java release.
+
 Generated files (`site/category/*.html`, `site/{locale}/`, and `site/data/snippets.json`) are in `.gitignore` — never edit them directly.
 
 ### Internationalization

agent-plugins/modern-java-development/README.md

@@ -0,0 +1,50 @@
+# Modern Java Development agent plugin
+
+A portable [Agent Plugins 1.0](https://agent-plugins.org/specification) package
+for version-aware Java development.
+
+The plugin contributes the `modern-java` skill. The skill detects the project's
+effective Java compilation target before recommending language features, APIs,
+tooling, or modernization changes. Guidance is cumulative and grouped by the
+Java release in which each capability became final.
+
+## Package layout
+
+```text
+modern-java-development/
+├── plugin.json
+└── skills/
+    └── modern-java/
+        ├── SKILL.md
+        ├── references/
+        │   ├── core-practices.md
+        │   └── release-practices.md
+        └── scripts/
+            ├── detect_java_version.py
+            └── test_detect_java_version.py
+```
+
+## Use
+
+Install or copy this directory into any Agent Plugins-compatible client. When
+the skill is active, the agent runs the detector from the Java project root:
+
+```bash
+python3 skills/modern-java/scripts/detect_java_version.py .
+```
+
+Pass an explicit target when build metadata is unavailable:
+
+```bash
+python3 skills/modern-java/scripts/detect_java_version.py . --java-version 21
+```
+
+The detector emits JSON so an agent can distinguish the selected target from
+lower-confidence runtime evidence and report conflicting build configuration.
+
+## Validate
+
+```bash
+python3 -m unittest \
+  skills/modern-java/scripts/test_detect_java_version.py
+```

agent-plugins/modern-java-development/plugin.json

@@ -0,0 +1,20 @@
+{
+  "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
+  "name": "modern-java-development",
+  "version": "1.0.0",
+  "description": "Version-aware guidance for writing, reviewing, and modernizing Java projects.",
+  "author": {
+    "name": "java.evolved",
+    "url": "https://javaevolved.github.io"
+  },
+  "homepage": "https://javaevolved.github.io",
+  "repository": "https://github.com/javaevolved/javaevolved.github.io",
+  "license": "MIT",
+  "keywords": [
+    "java",
+    "modern-java",
+    "jdk",
+    "code-review",
+    "modernization"
+  ]
+}

agent-plugins/modern-java-development/skills/modern-java/SKILL.md

@@ -0,0 +1,78 @@
+---
+name: modern-java
+description: Detects a project's effective Java version and provides release-appropriate guidance for writing, reviewing, refactoring, upgrading, and modernizing Java code. Use for Java implementation, architecture, code review, build configuration, migration, performance, concurrency, testing, or API design tasks.
+license: MIT
+compatibility: Requires Python 3 to run the bundled detector; an agent may inspect the same project files directly when Python is unavailable.
+metadata:
+  author: java.evolved
+  version: "1.0.0"
+---
+
+# Modern Java
+
+Determine the project's effective compilation target before proposing code.
+An installed JDK is only fallback evidence; it does not prove which language
+features or APIs the build accepts.
+
+## Workflow
+
+1. From the project or module root, run:
+
+   ```bash
+   python3 <skill-directory>/scripts/detect_java_version.py .
+   ```
+
+   If the user explicitly supplied Java version X, pass
+   `--java-version X`. Explicit user intent takes precedence over project files.
+
+2. Read the JSON result:
+   - Use `selected.version` as the target.
+   - Treat `maven-release`, `gradle-release`, and explicit overrides as stronger
+     evidence than toolchains, source compatibility, version-manager files, CI,
+     environment variables, or the installed runtime.
+   - If `ambiguous` is true, inspect the listed files and determine which module
+     or build profile is in scope. Do not silently choose the newest version.
+   - If no version is selected, inspect build and CI configuration. If still
+     unknown, state the assumption before writing version-sensitive code.
+
+3. Read [core practices](references/core-practices.md), then read the target
+   release and all earlier applicable groups in
+   [release practices](references/release-practices.md). Recommendations are
+   cumulative: Java 21 code may use final features from Java 21 and below.
+
+4. Inspect whether preview is explicitly enabled (`--enable-preview` in both
+   compile and runtime/test configuration). Do not recommend preview features
+   by default. Never use a feature finalized after the detected target.
+
+5. Tailor the work:
+   - **New code:** prefer the clearest final API available at the target.
+   - **Review:** flag needless legacy patterns only when the replacement is
+     available at the target and fits the behavior.
+   - **Modernization:** separate behavior-preserving refactors from Java target
+     upgrades. Do not raise the target unless requested.
+   - **Libraries:** respect the published minimum Java version, not the
+     maintainer's local JDK.
+   - **Multi-release or multi-module builds:** evaluate each affected source set
+     or module against its own target.
+
+6. Validate with the project's existing build using its configured toolchain.
+   Compile and run tests with the same `--release` and preview settings used by
+   production. Do not treat a successful compile on a newer local JDK as proof
+   of compatibility.
+
+## Recommendation format
+
+When version matters, briefly name the basis:
+
+> Detected Java 17 from `maven.compiler.release`; recommendations are limited to
+> final Java 17 APIs and language features.
+
+For upgrades, distinguish:
+
+- **Usable now:** supported by the current target.
+- **Available after upgrade:** requires a specific newer target.
+- **Preview:** experimental for a specific release and opt-in only.
+
+Prefer small, behavior-preserving changes. Do not mechanically replace every
+older construct: readability, API contracts, allocation behavior, framework
+constraints, and team conventions still apply.

agent-plugins/modern-java-development/skills/modern-java/references/core-practices.md

@@ -0,0 +1,85 @@
+# Core modern Java practices
+
+Apply these practices at every supported Java version, using only APIs and
+syntax available at the detected compilation target.
+
+## Build and compatibility
+
+- Treat `--release`, Maven `maven.compiler.release`, or Gradle
+  `options.release` as the compatibility contract.
+- Pin a reproducible toolchain in the build and CI. Do not rely solely on
+  `JAVA_HOME` or a developer's installed JDK.
+- For libraries, test the minimum supported Java release. Avoid accidentally
+  linking to APIs from the JDK used to run the build.
+- Keep preview features out of production defaults. If adopted deliberately,
+  enable preview consistently for compilation, tests, execution, packaging,
+  IDEs, and CI, and plan migration at the next release.
+- Prefer supported LTS releases for long-lived production systems unless the
+  organization intentionally follows the six-month release cadence.
+
+## Language and API design
+
+- Model invalid states out of the type system where practical. Use small value
+  types, enums, and sealed hierarchies when the target supports them.
+- Prefer immutable state and explicit ownership. Make defensive copies at
+  mutable boundaries; do not expose modifiable internal collections.
+- Use `Optional` primarily as a return type for an absent single value, not for
+  fields, parameters, collections, or serialization contracts by default.
+- Use exceptions for exceptional failure, with actionable messages and
+  preserved causes. Do not catch broad exceptions or silently continue.
+- Prefer standard JDK APIs over dependencies when they are equally clear and
+  capable, but do not rewrite mature library functionality merely to remove a
+  dependency.
+- Keep public APIs unsurprising. Modern syntax is not a reason to break binary,
+  source, serialization, or framework compatibility.
+
+## Collections, streams, and nullness
+
+- Return empty collections instead of `null`. State mutability and encounter
+  order in API contracts.
+- Use streams for declarative transformations, not for control flow with hidden
+  side effects. Prefer a loop when it is clearer or permits early exit.
+- Do not parallelize streams without measurement and a suitable workload.
+- Establish an explicit nullness policy. Prefer JSpecify annotations when the
+  surrounding ecosystem and tooling support them.
+
+## Concurrency
+
+- Prefer structured ownership of tasks and resources. Always define
+  cancellation, timeout, interruption, and failure propagation behavior.
+- Preserve interruption (`Thread.currentThread().interrupt()`) when an
+  `InterruptedException` cannot be propagated.
+- Use concurrent collections and high-level synchronization utilities before
+  hand-written locking. Document invariants protected by locks.
+- Measure before selecting executors, pool sizes, lock-free structures, or
+  virtual-thread migration. CPU-bound and I/O-bound workloads need different
+  strategies.
+
+## Security and reliability
+
+- Validate untrusted input at boundaries. Avoid native Java serialization for
+  untrusted data; apply deserialization filters where legacy use remains.
+- Use modern TLS defaults, authenticated encryption, `SecureRandom`, and
+  purpose-built password/key derivation APIs. Never invent cryptography.
+- Use try-with-resources for every `AutoCloseable` whose lifetime is locally
+  owned.
+- Add timeouts to network calls and bounded behavior to queues, retries,
+  payloads, and caches.
+
+## Performance and observability
+
+- Measure with JFR, JDK tools, and a representative workload before optimizing.
+- Use JMH for microbenchmarks; include warmup, forks, and consumed results.
+- Prefer simple allocation-friendly code, but do not trade correctness or
+  clarity for speculative micro-optimizations.
+- Include enough context in logs to diagnose failures without exposing secrets
+  or personal data.
+
+## Testing
+
+- Test externally visible behavior and edge cases, not implementation details.
+- Use the project's existing test framework and build. Keep tests deterministic;
+  control clocks, randomness, concurrency, locale, timezone, and filesystem
+  dependencies where relevant.
+- Add focused regression tests for bug fixes and compatibility tests for public
+  APIs or serialized formats.