diff --git a/.agents/plugins/marketplace.json b/.agents/plugins/marketplace.json index ad3ebab1..f0f32940 100644 --- a/.agents/plugins/marketplace.json +++ b/.agents/plugins/marketplace.json @@ -460,6 +460,18 @@ }, "category": "Development" }, + { + "name": "portone", + "source": { + "source": "local", + "path": "./plugins/portone" + }, + "policy": { + "installation": "AVAILABLE", + "authentication": "ON_INSTALL" + }, + "category": "Development" + }, { "name": "please-plugins", "source": { @@ -639,6 +651,18 @@ "authentication": "ON_INSTALL" }, "category": "Development" + }, + { + "name": "java-development", + "source": { + "source": "local", + "path": "./plugins/java-development" + }, + "policy": { + "installation": "AVAILABLE", + "authentication": "ON_INSTALL" + }, + "category": "Language" } ] } diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index cfc518b9..e2a4e905 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -633,6 +633,14 @@ "keywords": ["bun", "runtime", "package-manager", "test-runner", "bundler", "javascript", "typescript"], "tags": ["runtime", "tooling"], "source": "./plugins/bun" + }, + { + "name": "java-development", + "description": "Comprehensive collection of skills for Java development including Spring Boot, Quarkus, testing, documentation, and best practices - imported from github/awesome-copilot", + "category": "language", + "keywords": ["java", "springboot", "quarkus", "jpa", "junit", "javadoc"], + "tags": ["language", "skills"], + "source": "./plugins/java-development" } ] } diff --git a/.please/config.yml b/.please/config.yml index d6e8a6a7..5a7ad8e6 100644 --- a/.please/config.yml +++ b/.please/config.yml @@ -1,4 +1,4 @@ -schema_version: 2 # Config schema version (do not edit manually) +schema_version: 5 # Config schema version (do not edit manually) language: en # Output language (ko | en) @@ -29,3 +29,13 @@ graphite: # When unset, the plugin assumes `none` and uses the direct-merge path. mode: graphite label: "merge-queue" # used only when mode: graphite (must match Graphite settings) + +# Workflow policies (optional) +# Populated by /please:setup when a stack tool is detected and user opts in. +# The `tool` field selects which CLI drives the stack (currently only `graphite`). +# workflow: +# stacked_pr: +# enabled: true # Use stacked PR workflow (one PR per branch in stack) +# tool: graphite # graphite | git-spice | none +# split_phases: true # If plan.md has `### Phase N:` headings, create a stacked branch per phase +# branch_prefix: tracks/ # Branch prefix (single-phase: tracks/{track_id}; multi-phase: tracks/{track_id}/phase-N-{slug}) diff --git a/.please/docs/product-specs/index.json b/.please/docs/product-specs/index.json new file mode 100644 index 00000000..3948b954 --- /dev/null +++ b/.please/docs/product-specs/index.json @@ -0,0 +1,63 @@ +{ + "generated_by": "/please:sync-specs", + "specs": [ + { + "id": "SPEC-001", + "domain": "plugins", + "feature": "marketplace", + "created_at": "2026-05-28T10:00:49.494Z", + "updated_at": "2026-05-28T10:00:49.494Z", + "source_tracks": [ + "awesome-copilot-java-20260528" + ], + "traces": [], + "requirements": [ + { + "id": "REQ-001", + "kind": "functional", + "statement": "A new built-in plugin directory `plugins/java-development/` exists, containing a Claude Code plugin manifest at `plugins/java-development/.claude-plugin/plugin.json` with the plugin name `java-development`, version `1.0.0`, MIT license, and Java-related keywords (java, springboot, junit, javadoc)." + }, + { + "id": "REQ-002", + "kind": "functional", + "statement": "All four upstream skills are copied as-is (no content edits) into `plugins/java-development/skills/{skill-name}/SKILL.md`:" + }, + { + "id": "REQ-003", + "kind": "functional", + "statement": "The plugin is registered in `.claude-plugin/marketplace.json` so it appears in marketplace listings and is installable via `/plugin install java-development@pleaseai`." + }, + { + "id": "REQ-004", + "kind": "functional", + "statement": "A `plugins/java-development/README.md` documents the source (link to upstream), included skills, installation command, and license attribution." + }, + { + "id": "REQ-005", + "kind": "functional", + "statement": "Attribution is preserved: the upstream license file (MIT) is included as `plugins/java-development/LICENSE` (or referenced inline), and `plugin.json` lists the author as Awesome Copilot Community with `repository` pointing to `https://github.com/github/awesome-copilot`." + }, + { + "id": "REQ-006", + "kind": "functional", + "statement": "Multi-runtime artifacts for Codex and Antigravity are generated by running `bun scripts/cli.ts multi-format` so the plugin is installable across all three runtimes — matching the convention established for other built-in plugins." + }, + { + "id": "REQ-007", + "kind": "non-functional", + "statement": "Skill content remains byte-identical to upstream `SKILL.md` files (provenance + future re-sync feasibility); only the plugin manifest is locally authored." + }, + { + "id": "REQ-008", + "kind": "non-functional", + "statement": "Plugin passes `claude plugin validate plugins/java-development/` without errors before being added to the marketplace." + }, + { + "id": "REQ-009", + "kind": "non-functional", + "statement": "License notice and upstream attribution are visible in both `plugin.json` and `README.md` (legal/discoverability requirement for an MIT-licensed third-party import)." + } + ] + } + ] +} diff --git a/.please/docs/product-specs/index.md b/.please/docs/product-specs/index.md index 9ed36dd6..18055690 100644 --- a/.please/docs/product-specs/index.md +++ b/.please/docs/product-specs/index.md @@ -1,6 +1,7 @@ # Product Specs Index -> Auto-maintained by /please:spec --product. +> Auto-maintained by /please:sync-specs and /please:discover-specs. -| Spec | Feature | Created | Related Tracks | -|------|---------|---------|----------------| +| Spec | Domain | Feature | Created | Requirements | Related Tracks | +|------|--------|---------|---------|--------------|----------------| +| SPEC-001 | plugins | marketplace | 2026-05-28 | 9 | ["awesome-copilot-java-20260528"] | diff --git a/.please/docs/product-specs/plugins/marketplace.json b/.please/docs/product-specs/plugins/marketplace.json new file mode 100644 index 00000000..13dfb294 --- /dev/null +++ b/.please/docs/product-specs/plugins/marketplace.json @@ -0,0 +1,88 @@ +{ + "id": "SPEC-001", + "level": "V_M", + "domain": "plugins", + "feature": "marketplace", + "depends": [], + "conflicts": [], + "traces": [], + "created_at": "2026-05-28T10:00:49.494Z", + "updated_at": "2026-05-28T10:00:49.494Z", + "source_tracks": [ + "awesome-copilot-java-20260528" + ], + "requirements": [ + { + "id": "REQ-001", + "kind": "functional", + "statement": "A new built-in plugin directory `plugins/java-development/` exists, containing a Claude Code plugin manifest at `plugins/java-development/.claude-plugin/plugin.json` with the plugin name `java-development`, version `1.0.0`, MIT license, and Java-related keywords (java, springboot, junit, javadoc).", + "source_tracks": [ + "awesome-copilot-java-20260528" + ] + }, + { + "id": "REQ-002", + "kind": "functional", + "statement": "All four upstream skills are copied as-is (no content edits) into `plugins/java-development/skills/{skill-name}/SKILL.md`:", + "source_tracks": [ + "awesome-copilot-java-20260528" + ] + }, + { + "id": "REQ-003", + "kind": "functional", + "statement": "The plugin is registered in `.claude-plugin/marketplace.json` so it appears in marketplace listings and is installable via `/plugin install java-development@pleaseai`.", + "source_tracks": [ + "awesome-copilot-java-20260528" + ] + }, + { + "id": "REQ-004", + "kind": "functional", + "statement": "A `plugins/java-development/README.md` documents the source (link to upstream), included skills, installation command, and license attribution.", + "source_tracks": [ + "awesome-copilot-java-20260528" + ] + }, + { + "id": "REQ-005", + "kind": "functional", + "statement": "Attribution is preserved: the upstream license file (MIT) is included as `plugins/java-development/LICENSE` (or referenced inline), and `plugin.json` lists the author as Awesome Copilot Community with `repository` pointing to `https://github.com/github/awesome-copilot`.", + "source_tracks": [ + "awesome-copilot-java-20260528" + ] + }, + { + "id": "REQ-006", + "kind": "functional", + "statement": "Multi-runtime artifacts for Codex and Antigravity are generated by running `bun scripts/cli.ts multi-format` so the plugin is installable across all three runtimes — matching the convention established for other built-in plugins.", + "source_tracks": [ + "awesome-copilot-java-20260528" + ] + }, + { + "id": "REQ-007", + "kind": "non-functional", + "statement": "Skill content remains byte-identical to upstream `SKILL.md` files (provenance + future re-sync feasibility); only the plugin manifest is locally authored.", + "source_tracks": [ + "awesome-copilot-java-20260528" + ] + }, + { + "id": "REQ-008", + "kind": "non-functional", + "statement": "Plugin passes `claude plugin validate plugins/java-development/` without errors before being added to the marketplace.", + "source_tracks": [ + "awesome-copilot-java-20260528" + ] + }, + { + "id": "REQ-009", + "kind": "non-functional", + "statement": "License notice and upstream attribution are visible in both `plugin.json` and `README.md` (legal/discoverability requirement for an MIT-licensed third-party import).", + "source_tracks": [ + "awesome-copilot-java-20260528" + ] + } + ] +} diff --git a/.please/docs/product-specs/plugins/marketplace.md b/.please/docs/product-specs/plugins/marketplace.md new file mode 100644 index 00000000..6f08781c --- /dev/null +++ b/.please/docs/product-specs/plugins/marketplace.md @@ -0,0 +1,103 @@ +--- +id: SPEC-001 +level: V_M +domain: plugins +feature: marketplace +depends: [] +conflicts: [] +traces: [] +created_at: 2026-05-28T10:00:49.494Z +updated_at: 2026-05-28T10:00:49.494Z +source_tracks: ["awesome-copilot-java-20260528"] +--- + +# Marketplace Specification + +## Purpose + +Marketplace Specification 관련 요구사항. + +## Requirements + +### Requirement: A new built-in plugin directory `plugins/java-development/` exists, containing a Claude Code plugin manifest at `plugins/java-development/.claude-plugin/plugin.json` with the plugin name `java-development`, version `1.0.0`, MIT license, and Java-related keywords (java, springboot, junit, javadoc). + + +The system MUST A new built-in plugin directory `plugins/java-development/` exists, containing a Claude Code plugin manifest at `plugins/java-development/.claude-plugin/plugin.json` with the plugin name `java-development`, version `1.0.0`, MIT license, and Java-related keywords (java, springboot, junit, javadoc). + +#### Scenario: A new built-in plugin directory `plugins/java-development/` exists, containing a Claude Code plugin manifest at `plugins/java-development/.claude-plugin/plugin.json` with the plugin name `java-development`, version `1.0.0`, MIT license, and Java-related keywords (java, springboot, junit, javadoc). + +- GIVEN 시스템이 정상 동작 중일 때 +- WHEN A new built-in plugin directory `plugins/java-development/` exists, containing a Claude Code plugin manifest at `plugins/java-development/.claude-plugin/plugin.json` with the plugin name `java-development`, version `1.0.0`, MIT license, and Java-related keywords (java, springboot, junit, javadoc). +- THEN 해당 기능이 정상적으로 수행된다 + +### Requirement: All four upstream skills are copied as-is (no content edits) into `plugins/java-development/skills/{skill-name}/SKILL.md`: + + +The system MUST All four upstream skills are copied as-is (no content edits) into `plugins/java-development/skills/{skill-name}/SKILL.md`:. + +#### Scenario: All four upstream skills are copied as-is (no content edits) into `plugins/java-development/skills/{skill-name}/SKILL.md`: + +- GIVEN 시스템이 정상 동작 중일 때 +- WHEN All four upstream skills are copied as-is (no content edits) into `plugins/java-development/skills/{skill-name}/SKILL.md`: +- THEN 해당 기능이 정상적으로 수행된다 + +### Requirement: The plugin is registered in `.claude-plugin/marketplace.json` so it appears in marketplace listings and is installable via `/plugin install java-development@pleaseai`. + + +The system MUST The plugin is registered in `.claude-plugin/marketplace.json` so it appears in marketplace listings and is installable via `/plugin install java-development@pleaseai`. + +#### Scenario: The plugin is registered in `.claude-plugin/marketplace.json` so it appears in marketplace listings and is installable via `/plugin install java-development@pleaseai`. + +- GIVEN 시스템이 정상 동작 중일 때 +- WHEN The plugin is registered in `.claude-plugin/marketplace.json` so it appears in marketplace listings and is installable via `/plugin install java-development@pleaseai`. +- THEN 해당 기능이 정상적으로 수행된다 + +### Requirement: A `plugins/java-development/README.md` documents the source (link to upstream), included skills, installation command, and license attribution. + + +The system MUST A `plugins/java-development/README.md` documents the source (link to upstream), included skills, installation command, and license attribution. + +#### Scenario: A `plugins/java-development/README.md` documents the source (link to upstream), included skills, installation command, and license attribution. + +- GIVEN 시스템이 정상 동작 중일 때 +- WHEN A `plugins/java-development/README.md` documents the source (link to upstream), included skills, installation command, and license attribution. +- THEN 해당 기능이 정상적으로 수행된다 + +### Requirement: Attribution is preserved: the upstream license file (MIT) is included as `plugins/java-development/LICENSE` (or referenced inline), and `plugin.json` lists the author as Awesome Copilot Community with `repository` pointing to `https://github.com/github/awesome-copilot`. + + +The system MUST Attribution is preserved: the upstream license file (MIT) is included as `plugins/java-development/LICENSE` (or referenced inline), and `plugin.json` lists the author as Awesome Copilot Community with `repository` pointing to `https://github.com/github/awesome-copilot`. + +#### Scenario: Attribution is preserved: the upstream license file (MIT) is included as `plugins/java-development/LICENSE` (or referenced inline), and `plugin.json` lists the author as Awesome Copilot Community with `repository` pointing to `https://github.com/github/awesome-copilot`. + +- GIVEN 시스템이 정상 동작 중일 때 +- WHEN Attribution is preserved: the upstream license file (MIT) is included as `plugins/java-development/LICENSE` (or referenced inline), and `plugin.json` lists the author as Awesome Copilot Community with `repository` pointing to `https://github.com/github/awesome-copilot`. +- THEN 해당 기능이 정상적으로 수행된다 + +### Requirement: Multi-runtime artifacts for Codex and Antigravity are generated by running `bun scripts/cli.ts multi-format` so the plugin is installable across all three runtimes — matching the convention established for other built-in plugins. + + +The system MUST Multi-runtime artifacts for Codex and Antigravity are generated by running `bun scripts/cli.ts multi-format` so the plugin is installable across all three runtimes — matching the convention established for other built-in plugins. + +#### Scenario: Multi-runtime artifacts for Codex and Antigravity are generated by running `bun scripts/cli.ts multi-format` so the plugin is installable across all three runtimes — matching the convention established for other built-in plugins. + +- GIVEN 시스템이 정상 동작 중일 때 +- WHEN Multi-runtime artifacts for Codex and Antigravity are generated by running `bun scripts/cli.ts multi-format` so the plugin is installable across all three runtimes — matching the convention established for other built-in plugins. +- THEN 해당 기능이 정상적으로 수행된다 + +## Non-functional Requirements + +### Requirement: Skill content remains byte-identical to upstream `SKILL.md` files (provenance + future re-sync feasibility); only the plugin manifest is locally authored. + + +The system SHOULD Skill content remains byte-identical to upstream `SKILL.md` files (provenance + future re-sync feasibility); only the plugin manifest is locally authored. + +### Requirement: Plugin passes `claude plugin validate plugins/java-development/` without errors before being added to the marketplace. + + +The system SHOULD Plugin passes `claude plugin validate plugins/java-development/` without errors before being added to the marketplace. + +### Requirement: License notice and upstream attribution are visible in both `plugin.json` and `README.md` (legal/discoverability requirement for an MIT-licensed third-party import). + + +The system SHOULD License notice and upstream attribution are visible in both `plugin.json` and `README.md` (legal/discoverability requirement for an MIT-licensed third-party import). diff --git a/.please/docs/tracks.jsonl b/.please/docs/tracks.jsonl new file mode 100644 index 00000000..c647f80e --- /dev/null +++ b/.please/docs/tracks.jsonl @@ -0,0 +1 @@ +{"id":"awesome-copilot-java-20260528","type":"feature","status":"review","phase":"finalize","issue":"#190","pr":"#191","created":"2026-05-28","section":"completed"} diff --git a/.please/docs/tracks/completed/awesome-copilot-java-20260528/metadata.json b/.please/docs/tracks/completed/awesome-copilot-java-20260528/metadata.json new file mode 100644 index 00000000..e8011868 --- /dev/null +++ b/.please/docs/tracks/completed/awesome-copilot-java-20260528/metadata.json @@ -0,0 +1,13 @@ +{ + "track_id": "awesome-copilot-java-20260528", + "type": "feature", + "status": "review", + "created_at": "2026-05-28T18:27:00Z", + "updated_at": "2026-05-28T18:45:00Z", + "issue": "#190", + "pr": "#191", + "code_pr": "#191", + "project": "", + "project_item_id": "", + "code_branch": "worktree-ironwood-hogback" +} diff --git a/.please/docs/tracks/completed/awesome-copilot-java-20260528/plan.md b/.please/docs/tracks/completed/awesome-copilot-java-20260528/plan.md new file mode 100644 index 00000000..e314e5dd --- /dev/null +++ b/.please/docs/tracks/completed/awesome-copilot-java-20260528/plan.md @@ -0,0 +1,142 @@ +# Plan: Java Development Plugin (from awesome-copilot) + +> Track: awesome-copilot-java-20260528 +> Spec: [spec.md](./spec.md) + +## Overview + +- **Source**: /please:plan +- **Track**: awesome-copilot-java-20260528 +- **Issue**: (TBD — created in Section 4.0) +- **Created**: 2026-05-28 +- **Approach**: Manual copy as a built-in plugin under `plugins/java-development/`, preserving upstream SKILL.md content byte-for-byte and registering the plugin in `.claude-plugin/marketplace.json`. + +## Purpose + +Make GitHub's awesome-copilot Java Development plugin (4 skills: java-docs, java-junit, java-springboot, create-spring-boot-java-project) installable from the `pleaseai/claude-code-plugins` marketplace via `/plugin install java-development@pleaseai`. + +## Context + +The upstream plugin lives at `github/awesome-copilot/plugins/java-development/` and uses the GitHub Copilot CLI manifest schema (`.github/plugin/plugin.json` rather than Claude Code's `.claude-plugin/plugin.json`). Its four SKILL.md files use the same YAML-frontmatter format Claude Code already accepts, so only the manifest layer needs adaptation. Upstream is MIT-licensed and attribution must be preserved. + +Existing marketplace built-in plugins with `skills/` at root (e.g. `plugins/bun/`) follow this exact pattern: `.claude-plugin/plugin.json` lists `"skills": ["./skills/"]`, the skills directory contains `/SKILL.md` entries, and the marketplace.json entry uses `"source": "./plugins/"`. Multi-runtime manifests for Codex and Antigravity are generated by `bun scripts/cli.ts multi-format`. + +## Architecture Decision + +**Manual copy** was selected over vendor-sync (Type 2) or building a new auto-conversion mechanism for awesome-copilot (Type 5). + +- Trade-off accepted: no automatic upstream updates. Future tracks can refresh the skills by re-copying when upstream changes. +- Rationale: only 4 skills, format already matches Claude Code, and a sync mechanism would add complexity disproportionate to the payoff for a single one-shot import. +- Skill content is preserved byte-identical so a future re-sync (manual or automated) remains trivial. + +## Affected Files & Nodes + +_RPG unavailable in this workspace (`rpg.json` absent) — file-level impact below was derived manually from spec + codebase exploration._ + +- **New**: `plugins/java-development/.claude-plugin/plugin.json` (Claude manifest) +- **New**: `plugins/java-development/skills/java-docs/SKILL.md` +- **New**: `plugins/java-development/skills/java-junit/SKILL.md` +- **New**: `plugins/java-development/skills/java-springboot/SKILL.md` +- **New**: `plugins/java-development/skills/create-spring-boot-java-project/SKILL.md` +- **New**: `plugins/java-development/README.md` +- **New**: `plugins/java-development/LICENSE` +- **Generated** (via `bun scripts/cli.ts multi-format`): `plugins/java-development/.codex-plugin/plugin.json`, `plugins/java-development/plugin.json` (Antigravity) +- **Modified**: `.claude-plugin/marketplace.json` (append new plugin entry) + +## Tasks + +- [x] T001 Fetch all 4 upstream SKILL.md files verbatim from `github/awesome-copilot/plugins/java-development/skills/` and write them to `plugins/java-development/skills/{name}/SKILL.md` (files: `plugins/java-development/skills/java-docs/SKILL.md`, `plugins/java-development/skills/java-junit/SKILL.md`, `plugins/java-development/skills/java-springboot/SKILL.md`, `plugins/java-development/skills/create-spring-boot-java-project/SKILL.md`). Verify SHA256 matches upstream after copy. + +- [x] T002 [P] Create Claude Code plugin manifest at `plugins/java-development/.claude-plugin/plugin.json` with `name=java-development`, `version=1.0.0`, MIT license, author `Awesome Copilot Community`, repository `https://github.com/github/awesome-copilot`, keywords `[java, springboot, quarkus, jpa, junit, javadoc]`, and `"skills": ["./skills/"]`. Mirrors upstream description. + +- [x] T003 [P] Add `LICENSE` file at `plugins/java-development/LICENSE` containing the MIT license text with copyright line attributing the Awesome Copilot Community + a "Portions imported from github/awesome-copilot" notice (file: `plugins/java-development/LICENSE`). + +- [x] T004 [P] Author `plugins/java-development/README.md` documenting: source (link to upstream tree URL pinned to commit/branch), included skills list with descriptions, installation command (`/plugin install java-development@pleaseai`), and attribution notice (file: `plugins/java-development/README.md`). + +- [x] T005 Register the plugin in `.claude-plugin/marketplace.json` by appending an entry with `name=java-development`, description matching upstream, `category=language`, `keywords` matching plugin.json, `tags=["skills", "language"]`, and `"source": "./plugins/java-development"` (file: `.claude-plugin/marketplace.json`) (depends on T002). + +- [x] T006 Run `bun scripts/cli.ts multi-format` to generate Codex (`plugins/java-development/.codex-plugin/plugin.json`) and Antigravity (`plugins/java-development/plugin.json`) artifacts from the Claude manifest. Verify both files are generated and valid JSON (depends on T002, T005). + +- [x] T007 Validate the plugin and marketplace with `claude plugin validate plugins/java-development/` and `claude plugin validate .claude-plugin/marketplace.json`. Both must exit 0 (depends on T001, T002, T005, T006). + +- [x] T008 Final review: read each new/modified file once, confirm no upstream skill content was mutated (diff against fetched originals), confirm marketplace entry follows the project's existing built-in-plugin conventions, and update this plan's Progress checklist (depends on T001-T007). + +## Dependencies + +``` +T001 ──┐ +T002 ──┼─► T005 ─► T006 ─► T007 ─► T008 +T003 ──┤ +T004 ──┘ +``` + +- T001, T002, T003, T004 are independent (parallel-capable; T001 is not marked `[P]` because it produces the same files referenced by T002's manifest and a subtle SHA mismatch could mask a copy error — keep verification sequential). +- T005 depends on T002 (manifest must exist before marketplace entry references it). +- T006 depends on T002 and T005 (multi-format reads both files). +- T007 depends on all generation steps. +- T008 is the final pass. + +## Key Files + +- `plugins/bun/.claude-plugin/plugin.json` — reference manifest pattern (`"skills": ["./skills/"]`, no MCP servers) +- `plugins/bun/skills/use-bun/SKILL.md` — reference skill layout (one directory per skill containing `SKILL.md`) +- `.claude-plugin/marketplace.json` — marketplace registry; built-in plugins use `"source": "./plugins/"` +- `scripts/multi-format.ts` — multi-runtime manifest generator (already supports skills-only plugins) +- `CLAUDE.md` §"Adding a New Plugin to the Marketplace" — project convention reference + +## Verification + +- `claude plugin validate plugins/java-development/` exits 0 +- `claude plugin validate .claude-plugin/marketplace.json` exits 0 +- `bun scripts/cli.ts multi-format` runs without error and generates `.codex-plugin/plugin.json` + root `plugin.json` under `plugins/java-development/` +- Each of the 4 SKILL.md files has matching SHA256 vs upstream (verified during T001 and T008) +- A test install in a Claude Code session (`/plugin install java-development@pleaseai` from local checkout) lists the 4 skills with their upstream descriptions intact — manual smoke test, captured as a screenshot/note in retro + +## Progress + +- [x] T001 — Copy 4 SKILL.md files from upstream (2026-05-28) +- [x] T002 — Author Claude plugin manifest (2026-05-28) +- [x] T003 — Add LICENSE file (2026-05-28) +- [x] T004 — Author README (2026-05-28) +- [x] T005 — Register in marketplace.json (2026-05-28) +- [x] T006 — Run multi-format generator (2026-05-28) +- [x] T007 — Validate plugin + marketplace (2026-05-28) +- [x] T008 — Final review and consistency check (2026-05-28) + +## Decision Log + +- **2026-05-28**: Manual copy chosen over Type 2 vendor-sync. See spec.md "Out of Scope" — automated sync intentionally deferred. +- **2026-05-28**: Plugin name `java-development` chosen to match upstream (rejected `awesome-copilot-java` and `java`). Rationale: marketplace search familiarity for users coming from awesome-copilot docs. +- **2026-05-28**: All 4 upstream skills included (none excluded). Rationale: cohesive Java workflow; partial import would force users to install upstream separately for the missing pieces. + +## Surprises & Discoveries + +- **Upstream LICENSE is GitHub, Inc., not "Awesome Copilot Community"**: spec.md said the LICENSE should attribute the Awesome Copilot Community, but the upstream LICENSE actually says `Copyright GitHub, Inc.`. We preserved the upstream copyright accurately and added an "imported from" notice below it. Author field in plugin.json still uses "Awesome Copilot Community" since that's the community brand for the plugin collection. +- **`bun scripts/cli.ts multi-format` regenerated 93 unrelated plugin manifests**: pre-existing drift (e.g., ai-sdk plugin.json was v1.1.0 in Codex/Antigravity files but v1.2.0 in the Claude source). We reverted those changes to keep this PR focused; a separate chore-track can sync all runtimes when desired. +- **`claude plugin validate .claude-plugin/marketplace.json` warns on `homepage` and `repository`** fields — these are pre-existing schema mismatches not introduced by our entry. Validation still passes with exit 0. +- **jq pretty-print would have churned the entire marketplace.json**: existing entries use inline JSON arrays (`"keywords": ["a", "b"]`) but jq's default reformats them multi-line. Used text-based Edit instead to preserve formatting and keep the diff to +8 lines. + +## Outcomes & Retrospective + +### What Was Shipped + +PR #191 introduces `plugins/java-development/` as a built-in marketplace plugin importing GitHub's awesome-copilot Java Development collection. Four SKILL.md files (java-docs, java-junit, java-springboot, create-spring-boot-java-project) are copied byte-identical from upstream; Claude Code, Codex, and Antigravity manifests are generated and validated; `LICENSE` and `README.md` preserve MIT attribution to GitHub, Inc. and the Awesome Copilot Community. + +### What Went Well + +- One-iteration code review with zero critical/important findings — the structural conformance to `plugins/bun/` paid off. +- SHA-pinned copy verification (git blob SHA vs upstream API) gave a deterministic guarantee that no upstream content was mutated. Worth reusing for future awesome-copilot imports. +- Splitting the workspace schema migration (v2→v5) from the track commits kept the PR diff focused on the actual feature. +- Used text-based `Edit` for `.claude-plugin/marketplace.json` instead of `jq` rewrite, keeping the diff to +8 lines. + +### What Could Improve + +- `bun scripts/cli.ts multi-format` regenerates ALL plugin manifests, not just the new one — needed manual reversion of 93 unrelated files. A `--only ` flag on the script would make targeted imports much cleaner. +- `.claude-plugin/marketplace.json` validation surfaces 2 warnings on `homepage`/`repository` schema mismatches that aren't this PR's concern. Worth a separate chore-track to schema-fix the marketplace.json header. +- Initial spec assumed copyright would be "Awesome Copilot Community" but the upstream LICENSE actually attributes "GitHub, Inc." — should fetch the upstream LICENSE during spec authoring for future third-party imports. + +### Tech Debt Created + +- **Manual sync drift**: This plugin will fall out of sync with upstream over time. No automated mechanism captures upstream updates. Mitigation: future tracks re-copy when meaningful upstream changes land. +- **Unrelated runtime-manifest drift not fixed**: 93 plugins still have stale `.codex-plugin/plugin.json` / root `plugin.json` versions vs the Claude source. Deserves a dedicated `chore(multi-format): re-sync stale runtime manifests` track. +- **`ARCHITECTURE.md` doesn't yet mention `plugins/java-development/`**: not in scope here, but worth a `/standards:architecture-md update` pass during the next architecture refresh. diff --git a/.please/docs/tracks/completed/awesome-copilot-java-20260528/spec.md b/.please/docs/tracks/completed/awesome-copilot-java-20260528/spec.md new file mode 100644 index 00000000..6b30ad12 --- /dev/null +++ b/.please/docs/tracks/completed/awesome-copilot-java-20260528/spec.md @@ -0,0 +1,59 @@ +--- +product_spec_domain: plugins/marketplace +--- + +# Java Development Plugin (from awesome-copilot) + +> Track: awesome-copilot-java-20260528 + +## Overview + +Bring the GitHub Copilot **awesome-copilot Java Development** plugin into the `pleaseai/claude-code-plugins` marketplace so Claude Code users can install Java best-practice skills with `/plugin install java-development@pleaseai`. + +The upstream source — [github/awesome-copilot/plugins/java-development](https://github.com/github/awesome-copilot/tree/main/plugins/java-development) — ships four `SKILL.md` files that use the same YAML-frontmatter format Claude Code already supports, so no skill content needs rewriting. Only the plugin manifest wrapper (`.claude-plugin/plugin.json`) and marketplace registration need adaptation. + +Integration approach (selected by user): **manual copy as a built-in plugin under `plugins/java-development/`**. Upstream is MIT-licensed; attribution to the Awesome Copilot Community and the upstream repository is preserved in `plugin.json` and `README.md`. + +## Requirements + +### Functional Requirements + +- [ ] FR-1: A new built-in plugin directory `plugins/java-development/` exists, containing a Claude Code plugin manifest at `plugins/java-development/.claude-plugin/plugin.json` with the plugin name `java-development`, version `1.0.0`, MIT license, and Java-related keywords (java, springboot, junit, javadoc). +- [ ] FR-2: All four upstream skills are copied as-is (no content edits) into `plugins/java-development/skills/{skill-name}/SKILL.md`: + - `java-docs` — Javadoc best practices + - `java-junit` — JUnit 5 unit testing best practices + - `java-springboot` — Spring Boot best practices + - `create-spring-boot-java-project` — Spring Boot project skeleton creator +- [ ] FR-3: The plugin is registered in `.claude-plugin/marketplace.json` so it appears in marketplace listings and is installable via `/plugin install java-development@pleaseai`. +- [ ] FR-4: A `plugins/java-development/README.md` documents the source (link to upstream), included skills, installation command, and license attribution. +- [ ] FR-5: Attribution is preserved: the upstream license file (MIT) is included as `plugins/java-development/LICENSE` (or referenced inline), and `plugin.json` lists the author as Awesome Copilot Community with `repository` pointing to `https://github.com/github/awesome-copilot`. +- [ ] FR-6: Multi-runtime artifacts for Codex and Antigravity are generated by running `bun scripts/cli.ts multi-format` so the plugin is installable across all three runtimes — matching the convention established for other built-in plugins. + +### Non-functional Requirements + +- [ ] NFR-1: Skill content remains byte-identical to upstream `SKILL.md` files (provenance + future re-sync feasibility); only the plugin manifest is locally authored. +- [ ] NFR-2: Plugin passes `claude plugin validate plugins/java-development/` without errors before being added to the marketplace. +- [ ] NFR-3: License notice and upstream attribution are visible in both `plugin.json` and `README.md` (legal/discoverability requirement for an MIT-licensed third-party import). + +## Acceptance Criteria + +- [ ] AC-1: The plugin appears in the marketplace web UI (`apps/web/`) with name "java-development", description matching upstream, and the four skills listed. +- [ ] AC-2: A fresh Claude Code session can install the plugin with `/plugin install java-development@pleaseai` and, after installation, each of the four skills shows in the available-skills list with its upstream description intact. +- [ ] AC-3: `claude plugin validate plugins/java-development/` exits with status 0. +- [ ] AC-4: `claude plugin validate .claude-plugin/marketplace.json` exits with status 0 after the plugin entry is added. + +## Out of Scope + +- Automated upstream sync (the manual-copy decision intentionally defers any sync pipeline; future tracks can revisit if upstream changes become frequent). +- Authoring net-new Java skills or modifying upstream skill content (`SKILL.md` files are copied verbatim). +- Adding MCP servers, slash commands, hooks, or agents — the upstream plugin contains skills only, and this track mirrors that scope. +- Wiring this plugin into `scripts/meta.ts` (would imply a sync mechanism, which the chosen approach rejects). +- Importing other awesome-copilot plugins (e.g. python-development, go-development) — those are separate future tracks if desired. + +## Assumptions + +- The upstream `SKILL.md` files are stable enough at the chosen commit that a one-shot manual copy is acceptable; if upstream evolves we accept being out of date until a new track refreshes them. +- The upstream MIT license permits redistribution under the marketplace as long as attribution is preserved (verified from upstream `README.md` "License: MIT"). +- The `marketplace.json` schema supports a built-in plugin source pointing at `plugins/java-development/` (consistent with how other entries such as `gatekeeper`, `plugin-dev`, etc. are registered). +- No Java toolchain is required at install time — the skills are documentation/prompt assets, not executable code. +- `bun scripts/cli.ts multi-format` will correctly generate Codex (`.codex-plugin/plugin.json`) and Antigravity (`plugin.json` + `mcp_config.json`) artifacts from the Claude manifest, as it does for other local plugins. diff --git a/.please/docs/tracks/index.md b/.please/docs/tracks/index.md deleted file mode 100644 index 4a251aa0..00000000 --- a/.please/docs/tracks/index.md +++ /dev/null @@ -1,25 +0,0 @@ -# Tracks Index - -> Auto-maintained by /please:plan and /please:finalize. - -## Active - -| Track | Feature | Type | Issue | Started | Status | -|-------|---------|------|-------|---------|--------| -| [nuxt-ui-hook-guidance-20260328](active/nuxt-ui-hook-guidance-20260328/plan.md) | Nuxt UI Hook Guidance | feature | TBD | 2026-03-28 | in_progress | -| [nuxt-session-hook-20260328](active/nuxt-session-hook-20260328/) | Plugin Recommender | feature | — | 2026-03-28 | in_progress | -| [add-code-intelligence-marketplace-20260328](active/add-code-intelligence-marketplace-20260328/plan.md) | Add code-intelligence marketplace | feature | - | 2026-03-28 | planned | -| [hooks-if-field-20260328](active/hooks-if-field-20260328/) | Add `if` field to hooks | feature | — | 2026-03-28 | planned | -| [web-nuxt-update-20260328](active/web-nuxt-update-20260328/plan.md) | Web App Dependency Update | chore | #126 | 2026-03-28 | in_progress | -| [fix-setup-glob-pattern-20260329](active/fix-setup-glob-pattern-20260329/plan.md) | Fix setup command package.json discovery | bugfix | #129 | 2026-03-29 | in_progress | -| [setup-monorepo-scan-20260329](active/setup-monorepo-scan-20260329/plan.md) | Monorepo Workspace Dependency Scanning | feature | #132 | 2026-03-29 | in_progress | -| [gatekeeper-v2-20260331](active/gatekeeper-v2-20260331/plan.md) | Gatekeeper v2: All-Tool Coverage + Auto-Mode Rules | feature | #135 | 2026-03-31 | in_progress | - -## Recently Completed - -| Track | Feature | Type | Issue | Completed | Outcome | -|-------|---------|------|-------|-----------|---------| - -## Tech Debt - -See [tech-debt-tracker.md](tech-debt-tracker.md). diff --git a/.please/docs/tracks/tech-debt-tracker.md b/.please/docs/tracks/tech-debt-tracker.md index 723a4c17..e02faf58 100644 --- a/.please/docs/tracks/tech-debt-tracker.md +++ b/.please/docs/tracks/tech-debt-tracker.md @@ -6,6 +6,10 @@ | ID | Source Track | Description | Priority | Created | |----|------------|-------------|----------|---------| +| TD-001 | awesome-copilot-java-20260528 | `bun scripts/cli.ts multi-format` rewrites ALL plugin manifests instead of accepting a `--only ` filter; forces manual reversion when adding a single plugin | Low | 2026-05-28 | +| TD-002 | awesome-copilot-java-20260528 | 93 plugins have stale Codex/Antigravity manifests vs Claude source — needs a dedicated `chore(multi-format): re-sync stale runtime manifests` track | Medium | 2026-05-28 | +| TD-003 | awesome-copilot-java-20260528 | `.claude-plugin/marketplace.json` schema warns on `homepage` and `repository` fields — pre-existing, needs schema reconciliation | Low | 2026-05-28 | +| TD-004 | awesome-copilot-java-20260528 | No automated upstream-sync for `plugins/java-development/` — manual re-copy required when upstream changes | Low | 2026-05-28 | ## Resolved diff --git a/plugins/java-development/.claude-plugin/plugin.json b/plugins/java-development/.claude-plugin/plugin.json new file mode 100644 index 00000000..f5cf3ff2 --- /dev/null +++ b/plugins/java-development/.claude-plugin/plugin.json @@ -0,0 +1,23 @@ +{ + "name": "java-development", + "version": "1.0.0", + "description": "Comprehensive collection of prompts and instructions for Java development including Spring Boot, Quarkus, testing, documentation, and best practices.", + "author": { + "name": "Awesome Copilot Community", + "url": "https://github.com/github/awesome-copilot" + }, + "homepage": "https://github.com/github/awesome-copilot/tree/main/plugins/java-development", + "repository": "https://github.com/github/awesome-copilot", + "license": "MIT", + "keywords": [ + "java", + "springboot", + "quarkus", + "jpa", + "junit", + "javadoc" + ], + "skills": [ + "./skills/" + ] +} diff --git a/plugins/java-development/.codex-plugin/plugin.json b/plugins/java-development/.codex-plugin/plugin.json new file mode 100644 index 00000000..f145e067 --- /dev/null +++ b/plugins/java-development/.codex-plugin/plugin.json @@ -0,0 +1,35 @@ +{ + "name": "java-development", + "version": "1.0.0", + "description": "Comprehensive collection of prompts and instructions for Java development including Spring Boot, Quarkus, testing, documentation, and best practices.", + "author": { + "name": "Awesome Copilot Community", + "url": "https://github.com/github/awesome-copilot" + }, + "interface": { + "displayName": "Java Development", + "shortDescription": "Comprehensive collection of prompts and instructions for Java development including Spring Boot, Quarkus, testing, documentation, and best practices.", + "longDescription": "Comprehensive collection of prompts and instructions for Java development including Spring Boot, Quarkus, testing, documentation, and best practices.", + "developerName": "Awesome Copilot Community", + "category": "Language", + "capabilities": [ + "Skill" + ], + "defaultPrompt": [ + "Help me use Java Development for my current task." + ], + "websiteURL": "https://github.com/github/awesome-copilot/tree/main/plugins/java-development" + }, + "homepage": "https://github.com/github/awesome-copilot/tree/main/plugins/java-development", + "repository": "https://github.com/github/awesome-copilot", + "license": "MIT", + "keywords": [ + "java", + "springboot", + "quarkus", + "jpa", + "junit", + "javadoc" + ], + "skills": "./skills/" +} diff --git a/plugins/java-development/LICENSE b/plugins/java-development/LICENSE new file mode 100644 index 00000000..8263194b --- /dev/null +++ b/plugins/java-development/LICENSE @@ -0,0 +1,29 @@ +MIT License + +Copyright GitHub, Inc. + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. + +--- + +Portions of this directory are imported from +https://github.com/github/awesome-copilot/tree/main/plugins/java-development +and redistributed under the MIT license above. The original upstream skills +(`skills/java-docs/`, `skills/java-junit/`, `skills/java-springboot/`, +`skills/create-spring-boot-java-project/`) are preserved byte-for-byte. diff --git a/plugins/java-development/README.md b/plugins/java-development/README.md new file mode 100644 index 00000000..0517f7f0 --- /dev/null +++ b/plugins/java-development/README.md @@ -0,0 +1,30 @@ +# Java Development + +Comprehensive collection of skills for Java development including Spring Boot, JUnit, and Javadoc best practices. Imported from GitHub's [awesome-copilot](https://github.com/github/awesome-copilot/tree/main/plugins/java-development) community plugin. + +## Installation + +```bash +/plugin marketplace add pleaseai/claude-code-plugins +/plugin install java-development@pleaseai +``` + +## Included skills + +| Skill | Description | +|---|---| +| `java-docs` | Ensure Java types are documented with Javadoc and follow documentation best practices. | +| `java-junit` | Best practices for JUnit 5 unit testing, including data-driven tests. | +| `java-springboot` | Best practices for developing Spring Boot applications. | +| `create-spring-boot-java-project` | Create a Spring Boot Java project skeleton. | + +## Source & attribution + +This plugin is a direct import of the [`java-development`](https://github.com/github/awesome-copilot/tree/main/plugins/java-development) plugin from GitHub's [Awesome Copilot](https://github.com/github/awesome-copilot) community collection. The `skills/*/SKILL.md` files are byte-identical to upstream — only the plugin manifest (`.claude-plugin/plugin.json`) is adapted to Claude Code's schema. + +Upstream is MIT-licensed; the original license text is preserved in [`LICENSE`](./LICENSE). + +## Notes + +- This plugin contains **skills only** — no MCP servers, slash commands, or hooks. Each skill activates contextually when Claude detects relevant Java work (Spring Boot endpoints, JUnit tests, Javadoc comments, etc.). +- To refresh against upstream, re-run the manual copy step from track `awesome-copilot-java-20260528` or open a new track for the refresh. diff --git a/plugins/java-development/plugin.json b/plugins/java-development/plugin.json new file mode 100644 index 00000000..071bb9ee --- /dev/null +++ b/plugins/java-development/plugin.json @@ -0,0 +1,20 @@ +{ + "name": "java-development", + "version": "1.0.0", + "description": "Comprehensive collection of prompts and instructions for Java development including Spring Boot, Quarkus, testing, documentation, and best practices.", + "author": { + "name": "Awesome Copilot Community", + "url": "https://github.com/github/awesome-copilot" + }, + "homepage": "https://github.com/github/awesome-copilot/tree/main/plugins/java-development", + "repository": "https://github.com/github/awesome-copilot", + "license": "MIT", + "keywords": [ + "java", + "springboot", + "quarkus", + "jpa", + "junit", + "javadoc" + ] +} diff --git a/plugins/java-development/skills/create-spring-boot-java-project/SKILL.md b/plugins/java-development/skills/create-spring-boot-java-project/SKILL.md new file mode 100644 index 00000000..dbe9e3d7 --- /dev/null +++ b/plugins/java-development/skills/create-spring-boot-java-project/SKILL.md @@ -0,0 +1,163 @@ +--- +name: create-spring-boot-java-project +description: 'Create Spring Boot Java Project Skeleton' +--- + +# Create Spring Boot Java project prompt + +- Please make sure you have the following software installed on your system: + + - Java 21 + - Docker + - Docker Compose + +- If you need to custom the project name, please change the `artifactId` and the `packageName` in [download-spring-boot-project-template](#download-spring-boot-project-template) + +- If you need to update the Spring Boot version, please change the `bootVersion` in [download-spring-boot-project-template](#download-spring-boot-project-template) + +## Check Java version + +- Run following command in terminal and check the version of Java + +```shell +java -version +``` + +## Download Spring Boot project template + +- Run following command in terminal to download a Spring Boot project template + +```shell +curl https://start.spring.io/starter.zip \ + -d artifactId=${input:projectName:demo-java} \ + -d bootVersion=3.4.5 \ + -d dependencies=lombok,configuration-processor,web,data-jpa,postgresql,data-redis,data-mongodb,validation,cache,testcontainers \ + -d javaVersion=21 \ + -d packageName=com.example \ + -d packaging=jar \ + -d type=maven-project \ + -o starter.zip +``` + +## Unzip the downloaded file + +- Run following command in terminal to unzip the downloaded file + +```shell +unzip starter.zip -d ./${input:projectName:demo-java} +``` + +## Remove the downloaded zip file + +- Run following command in terminal to delete the downloaded zip file + +```shell +rm -f starter.zip +``` + +## Change directory to the project root + +- Run following command in terminal to change directory to the project root + +```shell +cd ${input:projectName:demo-java} +``` + +## Add additional dependencies + +- Insert `springdoc-openapi-starter-webmvc-ui` and `archunit-junit5` dependency into `pom.xml` file + +```xml + + org.springdoc + springdoc-openapi-starter-webmvc-ui + 2.8.6 + + + com.tngtech.archunit + archunit-junit5 + 1.2.1 + test + +``` + +## Add SpringDoc, Redis, JPA and MongoDB configurations + +- Insert SpringDoc configurations into `application.properties` file + +```properties +# SpringDoc configurations +springdoc.swagger-ui.doc-expansion=none +springdoc.swagger-ui.operations-sorter=alpha +springdoc.swagger-ui.tags-sorter=alpha +``` + +- Insert Redis configurations into `application.properties` file + +```properties +# Redis configurations +spring.data.redis.host=localhost +spring.data.redis.port=6379 +spring.data.redis.password=rootroot +``` + +- Insert JPA configurations into `application.properties` file + +```properties +# JPA configurations +spring.datasource.driver-class-name=org.postgresql.Driver +spring.datasource.url=jdbc:postgresql://localhost:5432/postgres +spring.datasource.username=postgres +spring.datasource.password=rootroot +spring.jpa.hibernate.ddl-auto=update +spring.jpa.show-sql=true +spring.jpa.properties.hibernate.format_sql=true +``` + +- Insert MongoDB configurations into `application.properties` file + +```properties +# MongoDB configurations +spring.data.mongodb.host=localhost +spring.data.mongodb.port=27017 +spring.data.mongodb.authentication-database=admin +spring.data.mongodb.username=root +spring.data.mongodb.password=rootroot +spring.data.mongodb.database=test +``` + +## Add `docker-compose.yaml` with Redis, PostgreSQL and MongoDB services + +- Create `docker-compose.yaml` at project root and add following services: `redis:6`, `postgresql:17` and `mongo:8`. + + - redis service should have + - password `rootroot` + - mapping port 6379 to 6379 + - mounting volume `./redis_data` to `/data` + - postgresql service should have + - password `rootroot` + - mapping port 5432 to 5432 + - mounting volume `./postgres_data` to `/var/lib/postgresql/data` + - mongo service should have + - initdb root username `root` + - initdb root password `rootroot` + - mapping port 27017 to 27017 + - mounting volume `./mongo_data` to `/data/db` + +## Add `.gitignore` file + +- Insert `redis_data`, `postgres_data` and `mongo_data` directories in `.gitignore` file + +## Run Maven test command + +- Run maven clean test command to check if the project is working + +```shell +./mvnw clean test +``` + +## Run Maven run command (Optional) + +- (Optional) `docker-compose up -d` to start the services, `./mvnw spring-boot:run` to run the Spring Boot project, `docker-compose rm -sf` to stop the services. + +## Let's do this step by step diff --git a/plugins/java-development/skills/java-docs/SKILL.md b/plugins/java-development/skills/java-docs/SKILL.md new file mode 100644 index 00000000..72ceae42 --- /dev/null +++ b/plugins/java-development/skills/java-docs/SKILL.md @@ -0,0 +1,23 @@ +--- +name: java-docs +description: 'Ensure that Java types are documented with Javadoc comments and follow best practices for documentation.' +--- + +# Java Documentation (Javadoc) Best Practices + +- Public and protected members should be documented with Javadoc comments. +- It is encouraged to document package-private and private members as well, especially if they are complex or not self-explanatory. +- The first sentence of the Javadoc comment is the summary description. It should be a concise overview of what the method does and end with a period. +- Use `@param` for method parameters. The description starts with a lowercase letter and does not end with a period. +- Use `@return` for method return values. +- Use `@throws` or `@exception` to document exceptions thrown by methods. +- Use `@see` for references to other types or members. +- Use `{@inheritDoc}` to inherit documentation from base classes or interfaces. + - Unless there is major behavior change, in which case you should document the differences. +- Use `@param ` for type parameters in generic types or methods. +- Use `{@code}` for inline code snippets. +- Use `
{@code ... }
` for code blocks. +- Use `@since` to indicate when the feature was introduced (e.g., version number). +- Use `@version` to specify the version of the member. +- Use `@author` to specify the author of the code. +- Use `@deprecated` to mark a member as deprecated and provide an alternative. diff --git a/plugins/java-development/skills/java-junit/SKILL.md b/plugins/java-development/skills/java-junit/SKILL.md new file mode 100644 index 00000000..b5da58d1 --- /dev/null +++ b/plugins/java-development/skills/java-junit/SKILL.md @@ -0,0 +1,63 @@ +--- +name: java-junit +description: 'Get best practices for JUnit 5 unit testing, including data-driven tests' +--- + +# JUnit 5+ Best Practices + +Your goal is to help me write effective unit tests with JUnit 5, covering both standard and data-driven testing approaches. + +## Project Setup + +- Use a standard Maven or Gradle project structure. +- Place test source code in `src/test/java`. +- Include dependencies for `junit-jupiter-api`, `junit-jupiter-engine`, and `junit-jupiter-params` for parameterized tests. +- Use build tool commands to run tests: `mvn test` or `gradle test`. + +## Test Structure + +- Test classes should have a `Test` suffix, e.g., `CalculatorTest` for a `Calculator` class. +- Use `@Test` for test methods. +- Follow the Arrange-Act-Assert (AAA) pattern. +- Name tests using a descriptive convention, like `methodName_should_expectedBehavior_when_scenario`. +- Use `@BeforeEach` and `@AfterEach` for per-test setup and teardown. +- Use `@BeforeAll` and `@AfterAll` for per-class setup and teardown (must be static methods). +- Use `@DisplayName` to provide a human-readable name for test classes and methods. + +## Standard Tests + +- Keep tests focused on a single behavior. +- Avoid testing multiple conditions in one test method. +- Make tests independent and idempotent (can run in any order). +- Avoid test interdependencies. + +## Data-Driven (Parameterized) Tests + +- Use `@ParameterizedTest` to mark a method as a parameterized test. +- Use `@ValueSource` for simple literal values (strings, ints, etc.). +- Use `@MethodSource` to refer to a factory method that provides test arguments as a `Stream`, `Collection`, etc. +- Use `@CsvSource` for inline comma-separated values. +- Use `@CsvFileSource` to use a CSV file from the classpath. +- Use `@EnumSource` to use enum constants. + +## Assertions + +- Use the static methods from `org.junit.jupiter.api.Assertions` (e.g., `assertEquals`, `assertTrue`, `assertNotNull`). +- For more fluent and readable assertions, consider using a library like AssertJ (`assertThat(...).is...`). +- Use `assertThrows` or `assertDoesNotThrow` to test for exceptions. +- Group related assertions with `assertAll` to ensure all assertions are checked before the test fails. +- Use descriptive messages in assertions to provide clarity on failure. + +## Mocking and Isolation + +- Use a mocking framework like Mockito to create mock objects for dependencies. +- Use `@Mock` and `@InjectMocks` annotations from Mockito to simplify mock creation and injection. +- Use interfaces to facilitate mocking. + +## Test Organization + +- Group tests by feature or component using packages. +- Use `@Tag` to categorize tests (e.g., `@Tag("fast")`, `@Tag("integration")`). +- Use `@TestMethodOrder(MethodOrderer.OrderAnnotation.class)` and `@Order` to control test execution order when strictly necessary. +- Use `@Disabled` to temporarily skip a test method or class, providing a reason. +- Use `@Nested` to group tests in a nested inner class for better organization and structure. diff --git a/plugins/java-development/skills/java-springboot/SKILL.md b/plugins/java-development/skills/java-springboot/SKILL.md new file mode 100644 index 00000000..39ae2e5f --- /dev/null +++ b/plugins/java-development/skills/java-springboot/SKILL.md @@ -0,0 +1,65 @@ +--- +name: java-springboot +description: 'Get best practices for developing applications with Spring Boot.' +--- + +# Spring Boot Best Practices + +Your goal is to help me write high-quality Spring Boot applications by following established best practices. + +## Project Setup & Structure + +- **Build Tool:** Use Maven (`pom.xml`) or Gradle (`build.gradle`) for dependency management. +- **Starters:** Use Spring Boot starters (e.g., `spring-boot-starter-web`, `spring-boot-starter-data-jpa`) to simplify dependency management. +- **Package Structure:** Organize code by feature/domain (e.g., `com.example.app.order`, `com.example.app.user`) rather than by layer (e.g., `com.example.app.controller`, `com.example.app.service`). + +## Dependency Injection & Components + +- **Constructor Injection:** Always use constructor-based injection for required dependencies. This makes components easier to test and dependencies explicit. +- **Immutability:** Declare dependency fields as `private final`. +- **Component Stereotypes:** Use `@Component`, `@Service`, `@Repository`, and `@Controller`/`@RestController` annotations appropriately to define beans. + +## Configuration + +- **Externalized Configuration:** Use `application.yml` (or `application.properties`) for configuration. YAML is often preferred for its readability and hierarchical structure. +- **Type-Safe Properties:** Use `@ConfigurationProperties` to bind configuration to strongly-typed Java objects. +- **Profiles:** Use Spring Profiles (`application-dev.yml`, `application-prod.yml`) to manage environment-specific configurations. +- **Secrets Management:** Do not hardcode secrets. Use environment variables, or a dedicated secret management tool like HashiCorp Vault or AWS Secrets Manager. + +## Web Layer (Controllers) + +- **RESTful APIs:** Design clear and consistent RESTful endpoints. +- **DTOs (Data Transfer Objects):** Use DTOs to expose and consume data in the API layer. Do not expose JPA entities directly to the client. +- **Validation:** Use Java Bean Validation (JSR 380) with annotations (`@Valid`, `@NotNull`, `@Size`) on DTOs to validate request payloads. +- **Error Handling:** Implement a global exception handler using `@ControllerAdvice` and `@ExceptionHandler` to provide consistent error responses. + +## Service Layer + +- **Business Logic:** Encapsulate all business logic within `@Service` classes. +- **Statelessness:** Services should be stateless. +- **Transaction Management:** Use `@Transactional` on service methods to manage database transactions declaratively. Apply it at the most granular level necessary. + +## Data Layer (Repositories) + +- **Spring Data JPA:** Use Spring Data JPA repositories by extending `JpaRepository` or `CrudRepository` for standard database operations. +- **Custom Queries:** For complex queries, use `@Query` or the JPA Criteria API. +- **Projections:** Use DTO projections to fetch only the necessary data from the database. + +## Logging + +- **SLF4J:** Use the SLF4J API for logging. +- **Logger Declaration:** `private static final Logger logger = LoggerFactory.getLogger(MyClass.class);` +- **Parameterized Logging:** Use parameterized messages (`logger.info("Processing user {}...", userId);`) instead of string concatenation to improve performance. + +## Testing + +- **Unit Tests:** Write unit tests for services and components using JUnit 5 and a mocking framework like Mockito. +- **Integration Tests:** Use `@SpringBootTest` for integration tests that load the Spring application context. +- **Test Slices:** Use test slice annotations like `@WebMvcTest` (for controllers) or `@DataJpaTest` (for repositories) to test specific parts of the application in isolation. +- **Testcontainers:** Consider using Testcontainers for reliable integration tests with real databases, message brokers, etc. + +## Security + +- **Spring Security:** Use Spring Security for authentication and authorization. +- **Password Encoding:** Always encode passwords using a strong hashing algorithm like BCrypt. +- **Input Sanitization:** Prevent SQL injection by using Spring Data JPA or parameterized queries. Prevent Cross-Site Scripting (XSS) by properly encoding output.