feat(migration): add OSGi Cloud Manager reference and SKILL wiring

.claude-plugin/marketplace.json

@@ -18,6 +18,19 @@
       "description": "All AEM as a Cloud Service skills: component development and Dispatcher, workflows"
     },
     {
+      "name": "aem-best-practices",
+      "source": "./skills/aem/cloud-service/skills/best-practices",
+      "description": "AEM Cloud Service Java/OSGi: pattern modules, Felix SCR→OSGi DS, and ResourceResolver/logging skills (single plugin)"
+    },
+    {
+      "name": "aem-migration",
+      "source": "./skills/aem/cloud-service/skills/migration",
+      "description": "Migrate legacy AEM code to Cloud Service: BPA/CAM workflows; delegates to aem-best-practices plugin"
+    },
+    {
+      "name": "aem-6-5-lts-dispatcher",
+      "source": "./skills/aem/6.5-lts/skills/dispatcher",
+      "description": "Mode-specific Dispatcher skills for AEM 6.5 LTS and AMS workflows"
       "name": "aem-6-5-lts",
       "source": "./skills/aem/6.5-lts",
       "description": "All AEM 6.5 LTS skills: Dispatcher, workflows for AEM 6.5 LTS and AMS environment"

.github/workflows/validate.yml

@@ -19,4 +19,4 @@ jobs:
 
       - run: npm ci
 
-      - run: npm run validate
+      - run: npm test

README.md

@@ -16,6 +16,16 @@ Repository of Adobe skills for AI coding agents.
 # Install all AEM as a Cloud Service skills (create-component + workflow + dispatcher) in one command
 /plugin install aem-cloud-service@adobe-skills
 
+# Install AEM 6.5 LTS Dispatcher plugin
+/plugin install aem-6-5-lts-dispatcher@adobe-skills
+
+# Install AEM Cloud Service best practices (platform + pattern modules)
+/plugin install aem-best-practices@adobe-skills
+
+# For migrations — install migration and best-practices (patterns / refactors live in best-practices; migration delegates to them):
+/plugin install aem-migration@adobe-skills
+/plugin install aem-best-practices@adobe-skills
+
 # Install all AEM 6.5 LTS skills (workflow + dispatcher) in one command
 /plugin install aem-6-5-lts@adobe-skills
 ```
@@ -32,6 +42,18 @@ npx skills add https://github.com/adobe/skills/tree/beta/skills/aem/cloud-servic
 # Install all AEM 6.5 LTS skills (workflow + dispatcher) in one command
 npx skills add https://github.com/adobe/skills/tree/beta/skills/aem/6.5-lts --all
 
+# Install all AEM Cloud Service best-practices skills (pattern modules + SCR→DS + resource/logging)
+npx skills add https://github.com/adobe/skills/tree/main/skills/aem/cloud-service/skills/best-practices --all
+
+# For migrations — install migration and best-practices (patterns / refactors live in best-practices; migration delegates to them):
+npx skills add https://github.com/adobe/skills/tree/main/skills/aem/cloud-service/skills/migration --all
+npx skills add https://github.com/adobe/skills/tree/main/skills/aem/cloud-service/skills/best-practices --all
+
+# Install dispatcher skills for a single agent (pick ONE mode only)
+# AEM as a Cloud Service mode:
+npx skills add https://github.com/adobe/skills/tree/main/skills/aem/cloud-service/skills/dispatcher --all -a cursor -y
+# AEM 6.5 LTS mode:
+npx skills add https://github.com/adobe/skills/tree/main/skills/aem/6.5-lts/skills/dispatcher --all -a cursor -y
 # Install for a single agent (pick ONE flavor only)
 npx skills add https://github.com/adobe/skills/tree/beta/skills/aem/cloud-service -a cursor -y
 npx skills add https://github.com/adobe/skills/tree/beta/skills/aem/6.5-lts -a cursor -y
@@ -60,6 +82,13 @@ gh upskill adobe/skills --path skills/aem/cloud-service --all
 # Install all AEM 6.5 LTS skills (workflow + dispatcher)
 gh upskill adobe/skills --path skills/aem/6.5-lts --all
 
+# Install only AEM Cloud Service best-practices skills
+gh upskill adobe/skills --path skills/aem/cloud-service/skills/best-practices --all
+
+# For migrations — install migration and best-practices (patterns / refactors live in best-practices; migration delegates to them):
+gh upskill adobe/skills --path skills/aem/cloud-service/skills/migration --all
+gh upskill adobe/skills --path skills/aem/cloud-service/skills/best-practices --all
+
 # Install a specific skill
 gh upskill adobe/skills --path skills/aem/edge-delivery-services --skill content-driven-development
 
@@ -139,6 +168,14 @@ Current dispatcher flavors:
 Each flavor contains parallel capability groups (workflow orchestration, config authoring, technical advisory, incident response, performance tuning, and security hardening).
 Shared advisory logic is centralized under each flavor's `dispatcher/shared/references/` to reduce duplication and drift.
 
+### AEM as a Cloud Service — Best Practices & Migration
+
+Under `skills/aem/cloud-service/skills/`, **`aem-best-practices`** (source `best-practices/`) is the **general-purpose** Cloud Service skill: pattern modules, Java baseline references (SCR→OSGi DS, resolver/logging, and related refs), and day-to-day Cloud Service alignment. Use it **on its own** for greenfield or maintainability work on AEM as a Cloud Service. **`aem-migration`** (source `migration/`, BPA/CAM orchestration) is **scoped to legacy AEM → AEM as a Cloud Service** (not Edge Delivery or 6.5 LTS); it **delegates** concrete refactors to **`aem-best-practices`** (`references/`). **For BPA- or CAM-driven bulk migration, install both** (see Installation); use **`aem-migration`** alone only when the agent already has the same best-practices material (for example the full repo open).
+
+**Key features:**
+- **Best practices:** one skill for patterns, SCR→OSGi DS, and resolver/logging — applicable to Cloud Service projects generally, not only migration
+- **Migration:** orchestration-only; pattern and transformation content lives in **`aem-best-practices`**
+
 ## Repository Structure
 
 ```
@@ -155,6 +192,24 @@ skills/
     |   |-- .claude-plugin/
     |   |   \-- plugin.json
     |   \-- skills/
+    |       |-- best-practices/
+    |       |   |-- .claude-plugin/
+    |       |   |   \-- plugin.json
+    |       |   |-- README.md
+    |       |   |-- SKILL.md
+    |       |   \-- references/
+    |       |       |   |-- scheduler.md
+    |       |       |   |-- replication.md
+    |       |       |   |-- scr-to-osgi-ds.md
+    |       |       |   |-- resource-resolver-logging.md
+    |       |       |   \-- ...
+    |       \-- migration/
+    |           |-- .claude-plugin/
+    |           |   \-- plugin.json
+    |           |-- README.md
+    |           |-- SKILL.md
+    |           |-- references/
+    |           \-- scripts/
     |       |-- ensure-agents-md/
     |       |   |-- SKILL.md          <-- bootstrap: creates AGENTS.md + CLAUDE.md if missing
     |       |   \-- references/

package.json

@@ -4,7 +4,8 @@
   "private": true,
   "description": "Adobe skills for AI coding agents",
   "scripts": {
-    "validate": "find skills -name SKILL.md -exec dirname {} \\; | xargs -I {} skills-ref validate {}"
+    "validate": "find skills -name SKILL.md -exec dirname {} \\; | xargs -I {} skills-ref validate {}",
+    "test": "npm run validate && node --test \"skills/aem/cloud-service/skills/migration/scripts/bpa-findings-helper.test.js\" && node -e \"JSON.parse(require('fs').readFileSync('.claude-plugin/marketplace.json','utf8')); console.log('marketplace.json: OK')\""
   },
   "devDependencies": {
     "skills-ref": "^0.1.5"

skills/aem/cloud-service/skills/best-practices/.claude-plugin/plugin.json

@@ -0,0 +1,11 @@
+{
+  "name": "aem-best-practices",
+  "description": "AEM as a Cloud Service Java/OSGi: one skill with pattern modules and Java baseline refs (SCR→OSGi DS, ResourceResolver/logging) under references/. Plugin root: skills/aem/cloud-service/skills/best-practices/.",
+  "version": "1.0.0",
+  "author": {
+    "name": "Adobe"
+  },
+  "repository": "https://github.com/adobe/skills",
+  "license": "Apache-2.0",
+  "keywords": ["aem", "aemaacs", "cloud-service", "best-practices", "osgi", "java", "migration", "adobe"]
+}

skills/aem/cloud-service/skills/best-practices/README.md

@@ -0,0 +1,29 @@
+# AEM as a Cloud Service — Best practices (plugin)
+
+Source: `skills/aem/cloud-service/skills/best-practices/`. Plugin **`aem-best-practices`**: `SKILL.md` and `references/` (patterns: scheduler, replication, events, assets; Java baseline: `scr-to-osgi-ds.md`, `resource-resolver-logging.md`, prerequisites hub).
+
+For **BPA- or CAM-driven bulk migration**, install **`aem-migration`** as well (`skills/aem/cloud-service/skills/migration/`); it supplies targets, this plugin supplies transformation modules.
+
+## Installation
+
+### Claude Code Plugins
+
+```bash
+/plugin install aem-best-practices@adobe-skills
+```
+
+### Vercel Skills
+
+```bash
+npx skills add https://github.com/adobe/skills/tree/main/skills/aem/cloud-service/skills/best-practices --all
+```
+
+### upskill
+
+```bash
+gh upskill adobe/skills --path skills/aem/cloud-service/skills/best-practices --all
+```
+
+## Related
+
+For **BPA/CAM-driven bulk migration**, install **`aem-migration`** (`skills/aem/cloud-service/skills/migration`).

skills/aem/cloud-service/skills/best-practices/SKILL.md

@@ -0,0 +1,84 @@
+---
+name: best-practices
+description: AEM as a Cloud Service Java/OSGi best practices, guardrails, and legacy-to-cloud pattern transformations. Use for Cloud Service–correct bundles, deprecated APIs, schedulers, ResourceChangeListener, replication, Replicator, JCR observation (javax.jcr.observation.EventListener), OSGi Event Admin (org.osgi.service.event.EventHandler), DAM AssetManager, BPA-style fixes, or any time you need the detailed pattern reference modules under this skill.
+---
+
+# AEM as a Cloud Service — Best Practices
+
+Platform guidance for **AEM as a Cloud Service** backend code: what to use, what to avoid, and **how to refactor** known legacy patterns into Cloud-compatible implementations.
+
+This skill holds the **pattern transformation modules** (`references/*.md`). It is intended to be **installable on its own** so Cloud Service guidance is not locked behind a migration-only package.
+
+**Quick pick:** Open the **Pattern Reference Modules** table below → jump to the matching `references/<file>.md` → read it fully before editing Java. For Felix SCR, resolvers, or logging, use **Java / OSGi baseline** links in this file first when those appear in the same change set.
+
+## When to Use This Skill
+
+Use this skill when you need to:
+
+- Apply **AEM as a Cloud Service** constraints to Java/OSGi code (new or existing)
+- Refactor **legacy patterns** into supported APIs (same modules migration uses)
+- Follow **consistent rules** across schedulers, replication, **JCR observation listeners** (`eventListener`), **OSGi event handlers** (`eventHandler`), and DAM assets
+- Read **step-by-step transformation** and validation checklists for a specific pattern
+
+For **BPA/CAM orchestration** (collections, CSV, MCP project selection), use **`aem-migration`** (`skills/aem/cloud-service/skills/migration/`).
+
+## Pattern Reference Modules
+
+Each supported pattern has a dedicated module under `references/` relative to this `SKILL.md`.
+
+| Pattern / topic | BPA Pattern ID | Module file | Status |
+|-----------------|----------------|-------------|--------|
+| Scheduler | `scheduler` | `references/scheduler.md` | Ready |
+| Resource Change Listener | `resourceChangeListener` | `references/resource-change-listener.md` | Ready |
+| Replication | `replication` | `references/replication.md` | Ready |
+| Event listener (JCR observation) | `eventListener` | `references/event-migration.md` | Ready |
+| Event handler (OSGi Event Admin) | `eventHandler` | `references/event-migration.md` | Ready |
+| Asset Manager | `assetApi` | `references/asset-manager.md` | Ready |
+| Felix SCR → OSGi DS | — | `references/scr-to-osgi-ds.md` | Ready |
+| ResourceResolver + SLF4J | — | `references/resource-resolver-logging.md` | Ready |
+| *(Prerequisites hub)* | — | `references/aem-cloud-service-pattern-prerequisites.md` | — |
+
+**Event listener vs event handler (not the same):** **`eventListener`** is **JCR observation** — the JCR API for repository change callbacks (`javax.jcr.observation.EventListener`, `onEvent`). **`eventHandler`** is **OSGi Event Admin** — whiteboard-style OSGi events (`org.osgi.service.event.EventHandler`, `handleEvent`). Both migrate via **`references/event-migration.md`** (Path A vs Path B). **`resourceChangeListener`** is separate: Sling **`ResourceChangeListener`**, module **`references/resource-change-listener.md`**.
+
+**Before changing code for a pattern:** read the module for that pattern in full. Modules include classification criteria, ordered transformation steps, and validation checklists.
+
+## Java / OSGi baseline (same skill; no separate installables)
+
+SCR→DS and `ResourceResolver`/logging are **reference modules** under `references/` — not separate skills. Read them when relevant **instead of** re-embedding the same steps inside each pattern file.
+
+- **Hub:** [`references/aem-cloud-service-pattern-prerequisites.md`](references/aem-cloud-service-pattern-prerequisites.md)
+- **Modules:** [`references/scr-to-osgi-ds.md`](references/scr-to-osgi-ds.md), [`references/resource-resolver-logging.md`](references/resource-resolver-logging.md)
+
+## Critical Rules (All Patterns)
+
+**These rules apply to every pattern module. Violation means incorrect migration or unsafe Cloud Service code.**
+
+- **READ THE PATTERN MODULE FIRST** — never transform code without reading the module
+- **READ** [`scr-to-osgi-ds.md`](references/scr-to-osgi-ds.md) and [`resource-resolver-logging.md`](references/resource-resolver-logging.md) when SCR, `ResourceResolver`, or logging are in scope (pattern modules link via the [prerequisites hub](references/aem-cloud-service-pattern-prerequisites.md); do not duplicate long guides inline)
+- **DO** preserve environment-specific guards (e.g. `isAuthor()` run mode checks)
+- **DO NOT** change business logic inside methods
+- **DO NOT** rename classes unless the pattern module explicitly says to
+- **DO NOT** invent values — extract from existing code
+- **DO NOT** edit files outside the scope agreed with the user (e.g. only BPA targets or paths they named)
+- **DO** keep **searches, discovery, and edits** for the customer’s AEM sources inside the **IDE workspace root(s)** currently open; **DO NOT** grep or walk directories outside that boundary to find Java unless the user explicitly points there
+
+## Manual Pattern Hints (Classification)
+
+When no BPA list exists, scan imports and types to pick a module:
+
+| Look for | Pattern |
+|----------|---------|
+| `org.apache.sling.commons.scheduler.Scheduler` or `scheduler.schedule(` with `Runnable` | `scheduler` |
+| `implements ResourceChangeListener` | `resourceChangeListener` |
+| `com.day.cq.replication.Replicator` or `org.apache.sling.replication.*` | `replication` |
+| **JCR observation:** `javax.jcr.observation.EventListener`, `onEvent(EventIterator)`, `javax.jcr.observation.*` | `eventListener` |
+| **OSGi Event Admin:** `org.osgi.service.event.EventHandler`, substantive `handleEvent` (resolver/session/node work) | `eventHandler` |
+| `com.day.cq.dam.api.AssetManager` create/remove asset APIs | `assetApi` |
+| `org.apache.felix.scr.annotations` | read `references/scr-to-osgi-ds.md` (often combined with a BPA pattern) |
+| `getAdministrativeResourceResolver`, `System.out` / `printStackTrace` | read `references/resource-resolver-logging.md` |
+
+If multiple patterns match, ask which to fix first.
+
+## Relationship to Migration
+
+The **`aem-migration`** skill defines **one-pattern-per-session** workflow, BPA/CAM/MCP flows, and user messaging. It **delegates** all detailed transformation steps to this skill’s `references/` modules. It uses a **`{best-practices}`** repo-root path alias to this folder (see its `SKILL.md`). Keep platform truth here; keep orchestration there.

skills/aem/cloud-service/skills/best-practices/references/aem-cloud-service-pattern-prerequisites.md

@@ -0,0 +1,17 @@
+# Java / OSGi prerequisites (same skill)
+
+Before **pattern-specific** steps in other `references/*.md` pattern files, apply these modules when the code touches SCR, `ResourceResolver`, or logging. **Do not paste** their full procedures into other reference files — link here or to the modules below.
+
+| Topic | Module |
+|-------|--------|
+| Felix SCR → OSGi Declarative Services | [scr-to-osgi-ds.md](scr-to-osgi-ds.md) |
+| `ResourceResolver` + SLF4J logging | [resource-resolver-logging.md](resource-resolver-logging.md) |
+
+**Repository-root paths** (workspace resolution):
+
+- `skills/aem/cloud-service/skills/best-practices/references/scr-to-osgi-ds.md`
+- `skills/aem/cloud-service/skills/best-practices/references/resource-resolver-logging.md`
+
+Main skill hub: [`../SKILL.md`](../SKILL.md).
+
+**Asset API (`assetApi`):** [asset-manager.md](asset-manager.md) and path files only.