feat(java-core): add /java-adr Architecture Decision Records skill

Create, list, show, and supersede ADRs in docs/adr/.
Includes Java-specific ADR templates (build tools, JPA provider,
database migrations, testing strategy, API versioning, logging,
Java version). Auto-maintains index in docs/adr/README.md.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: ducpm2303

plugins/java-core/skills/java-adr/SKILL.md

@@ -0,0 +1,183 @@
+---
+description: Create, list, or update Architecture Decision Records (ADRs) for your Java project
+argument-hint: "[new <title> | list | show <id> | supersede <id> <title>]"
+---
+
+# /java-adr — Architecture Decision Records
+
+You are an architecture documentation specialist. Help Java teams capture, browse, and maintain Architecture Decision Records (ADRs).
+
+## What is an ADR?
+
+An ADR is a short document capturing one architectural decision: the context that forced the decision, the decision itself, and the consequences. ADRs live in source control alongside the code they describe.
+
+## Step 1 — Detect ADR directory
+
+Check for an existing ADR directory in this order:
+1. `docs/adr/`
+2. `docs/decisions/`
+3. `adr/`
+
+If none exists, ask:
+> "No ADR directory found. Create `docs/adr/`? (yes/no)"
+
+If yes, create the directory and a `README.md` index file:
+
+**File:** `docs/adr/README.md`
+```markdown
+# Architecture Decision Records
+
+This directory contains Architecture Decision Records (ADRs) for this project.
+
+An ADR documents a significant architectural decision: the context, the decision, and its consequences.
+
+## Records
+
+<!-- ADR index — updated automatically by /java-adr -->
+| ID | Title | Status | Date |
+|---|---|---|---|
+```
+
+## Step 2 — Parse the command
+
+| Argument | Action |
+|---|---|
+| `new <title>` | Create a new ADR |
+| `list` | Show all ADRs with status |
+| `show <id>` | Display a specific ADR |
+| `supersede <id> <title>` | Create a new ADR that supersedes an existing one |
+| *(no argument)* | Ask the user what they want to do |
+
+---
+
+## Command: new
+
+### Gather context
+
+Ask the user (one question at a time if not provided in the arguments):
+
+1. **What is the architectural decision?** (e.g., "Use Testcontainers instead of H2 for integration tests")
+2. **What context or problem forced this decision?** (constraints, alternatives considered)
+3. **What are the consequences?** (trade-offs, follow-up work required)
+4. **Status:** `Accepted` / `Proposed` / `Deprecated` (default: `Accepted`)
+
+### Detect next ID
+
+Scan existing ADR files matching `NNNN-*.md` in the ADR directory. Use the next sequential number, zero-padded to 4 digits (e.g., `0001`, `0002`).
+
+### Generate the file
+
+**File:** `docs/adr/{NNNN}-{kebab-case-title}.md`
+
+```markdown
+# {NNNN}. {Title}
+
+**Date:** {YYYY-MM-DD}
+**Status:** {Accepted | Proposed | Deprecated | Superseded by [{MMMM}]({MMMM}-*.md)}
+
+## Context
+
+{Context: the forces at play, the problem being solved, why a decision was needed.
+Include alternatives that were considered.}
+
+## Decision
+
+{The decision that was made. State it clearly and directly.}
+
+## Consequences
+
+### Positive
+- {benefit 1}
+- {benefit 2}
+
+### Negative / Trade-offs
+- {trade-off 1}
+- {trade-off 2}
+
+### Neutral
+- {neutral consequence, e.g., "requires updating CI pipeline"}
+```
+
+### Java-specific templates
+
+Offer these pre-filled templates based on common Java decisions:
+
+**Build tool choice (Maven vs Gradle):**
+- Context: Team familiarity, CI tooling, multi-module requirements
+- Consequences: Maven = verbose XML but universal tooling; Gradle = flexible DSL but steeper learning curve
+
+**JPA provider (Hibernate vs EclipseLink):**
+- Context: Spring Boot default, community support, performance needs
+
+**Database migration tool (Flyway vs Liquibase):**
+- Context: SQL vs XML/YAML migrations, team preference, rollback support
+
+**Testing strategy (H2 vs Testcontainers):**
+- Context: Speed vs production fidelity trade-off
+- Consequences: H2 = fast but dialect differences; Testcontainers = real DB but slower CI
+
+**API versioning strategy (URL path vs header vs content negotiation):**
+- Context: Client compatibility, REST maturity, API gateway constraints
+
+**Logging framework (Logback vs Log4j2):**
+- Context: Spring Boot default, async logging needs, configuration format preference
+
+**Java version for project:**
+- Context: LTS versions (8, 11, 17, 21), library compatibility, team tooling
+
+### Update the index
+
+After creating the file, append a row to `docs/adr/README.md`:
+```
+| {NNNN} | [{Title}]({NNNN}-{slug}.md) | {Status} | {Date} |
+```
+
+---
+
+## Command: list
+
+Read all `*.md` files in the ADR directory (excluding `README.md`). Output:
+
+```
+Architecture Decision Records — docs/adr/
+
+ID    Status      Date        Title
+----  ----------  ----------  -----------------------------------------
+0001  Accepted    2026-01-15  Use Testcontainers for integration tests
+0002  Accepted    2026-02-03  Adopt Flyway for database migrations
+0003  Superseded  2026-03-01  Use H2 for integration tests
+0004  Proposed    2026-04-03  Migrate to Java 21 virtual threads
+
+4 records (2 accepted · 1 proposed · 1 superseded)
+```
+
+---
+
+## Command: show
+
+Read and display the requested ADR formatted cleanly. If the ID is not found, list available IDs.
+
+---
+
+## Command: supersede
+
+1. Open the existing ADR (`<id>`)
+2. Change its status line to: `Superseded by [MMMM](MMMM-*.md)`
+3. Create the new ADR (same flow as `new`) with status `Accepted`
+4. Add a line to the new ADR: `Supersedes [{id}]({id}-*.md)`
+
+---
+
+## Step 3 — Commit prompt
+
+After creating or updating an ADR, suggest:
+```bash
+git add docs/adr/
+git commit -m "docs(adr): add ADR-{NNNN} — {title}"
+```
+
+## Step 4 — Next Steps
+
+After creating an ADR, offer:
+- *"Run `/java-adr list` to see all decisions"*
+- *"Use the `java-architect` agent to review the architectural approach in this ADR"*