feat(aem-cloud-service): add aem-agentkit v1.0.0-beta — agentic workflow bootstrap for AEM as a Cloud Service

.github/workflows/validate.yml

@@ -21,6 +21,23 @@ jobs:
 
       - run: npm run validate
 
+  test-aem-agentkit-helper:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest]
+        python-version: ['3.10', '3.11', '3.12']
+    steps:
+      - uses: actions/checkout@v6
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Run aem-agentkit-helper unit tests
+        run: bash plugins/aem/cloud-service/skills/aem-agentkit/tests/run-tests.sh
+
   codeowners-coverage:
     runs-on: ubuntu-latest
     steps:

README.md

@@ -184,6 +184,23 @@ If `AGENTS.md` already exists it is never overwritten.
 
 See `plugins/aem/cloud-service/skills/ensure-agents-md/` for the skill, template, and module catalog.
 
+### AEM as a Cloud Service — aem-agentkit (beta)
+
+The `aem-agentkit` skill complements `ensure-agents-md` by layering everything beyond the root `AGENTS.md` needed for agentic workflows across Claude Code, Cursor, GitHub Copilot, Codex, Continue.dev, Cline, Windsurf, and Augment Code. It writes only into agent-meta locations and never modifies customer source code. Scope: **AEM as a Cloud Service only** — the skill exits early on 6.5 LTS / AMS / on-premise layouts.
+
+- Per-module `AGENTS.md` in each detected AEM module (focused context the agent loads only when working in that module, recursive for nested AEM monorepos)
+- Machine-readable codified context under `.aem/context/`: component catalog, OSGi services / Sling Models / Sling Servlets index, derived conventions with evidence pointers, anti-patterns with absolute Cloud Service documentation links, glossary, test patterns, canonical API namespaces, run manifest (every file written + every heuristic decision)
+- Silent IDE detection — writes project-scoped subagents (`.claude/agents/aem-*.md`) and slash commands (`.claude/commands/*.md`) for Claude, rule files (`.cursor/rules/aem-*.mdc`) for Cursor, scoped instructions (`.github/instructions/aem-*.instructions.md`) for GitHub Copilot, rules (`.continue/rules/aem-*.md`) for Continue, plus concatenated rule files for Cline / Windsurf / Augment. A single canonical role-prompt is projected into each format so the content is identical across IDEs.
+- Non-destructive `.mcp.json` / `.cursor/mcp.json` placeholders when missing (inert by construction — no `command` field, `_TODO_` key prefix)
+- Embedded guardrails (search-before-create, verify-before-import, no `/libs` writes, stop-on-red, honor indexes after writing code)
+- Idempotent, marker-based, byte-for-byte non-destructive — `git diff` after a run shows zero changes to pre-existing files. Customer opt-out via a `_disable_agentkit` file at the workspace root, with explicit single-archetype-vs-monorepo handling.
+- Deterministic by construction — realpath + workspace boundary checks, SHA-256 canonical-body marker checksums, atomic `.tmp` + `rename(2)` writes, exhaustive Unicode sanitization, sorted-key JSON, bounded file walks (100,000 files / depth 32 / 10,000 per subtree), advisory workspace lock — all performed by the deterministic helper documented in `references/helpers.md`.
+- Beta. Verify all outputs before applying them to production projects.
+
+`aem-agentkit` does not replace `ensure-agents-md`; the two are complementary. When the root `AGENTS.md` is missing and `ensure-agents-md` is available, `aem-agentkit` defers to it as step 0. When `ensure-agents-md` is not installed, `aem-agentkit` proceeds with everything else and emits a one-line notice.
+
+See `plugins/aem/cloud-service/skills/aem-agentkit/` for the skill, references, templates, and tool-specific projection rules.
+
 ### AEM Workflow
 
 Workflow skills cover the full AEM Granite Workflow Engine lifecycle — from designing and implementing workflows to production debugging and incident triaging. Like Dispatcher, they are split by runtime flavor:

package.json

@@ -5,7 +5,8 @@
   "type": "module",
   "description": "Adobe skills for AI coding agents",
   "scripts": {
-    "validate": "find plugins -name SKILL.md -exec dirname {} \\; | xargs -I {} skills-ref validate {}"
+    "validate": "find plugins -name SKILL.md -exec dirname {} \\; | xargs -I {} skills-ref validate {}",
+    "test:aem-agentkit-helper": "bash plugins/aem/cloud-service/skills/aem-agentkit/tests/run-tests.sh"
   },
   "devDependencies": {
     "@semantic-release/changelog": "^6.0.3",

plugins/aem/cloud-service/skills/aem-agentkit/README.md

@@ -0,0 +1,164 @@
+# aem-agentkit (beta)
+
+Bootstrap an **AEM as a Cloud Service** repository for agentic workflows.
+
+> **Beta Skill**: This skill is in beta and under active development.
+> Results should be reviewed carefully before use in production.
+> Report issues at https://github.com/adobe/skills/issues
+
+This skill writes a small set of agent-meta files at the workspace root and
+inside existing modules so coding agents and any harness on top of them can
+work on the customer's repository with high reliability and low
+hallucination. It never modifies customer source code.
+
+**Scope: AEM as a Cloud Service only.** The skill exits early on AEM 6.5
+LTS, AMS, and on-premise AEM layouts. The generated context is
+Cloud Service-native: it understands `conf.d/`-based dispatcher layouts
+(not legacy `conf/`), Cloud Manager pipelines, RDE (Rapid Development
+Environment), and the AEM SDK. Core Components and anything under `/libs`
+are excluded — indexing covers customer code only.
+
+See [`SKILL.md`](./SKILL.md) for the full contract.
+
+## What gets created
+
+### Universal layer (always written if missing)
+
+| Path | Purpose |
+|---|---|
+| `<module>/AGENTS.md` | Focused per-module context (sized for one task) |
+| `.aem/context/components.json` | Machine-readable component catalog |
+| `.aem/context/osgi-services.json` | Sling Models, OSGi services, Sling Servlets |
+| `.aem/context/conventions.md` | Derived conventions with evidence pointers |
+| `.aem/context/avoid.md` | Anti-patterns detected in the repo |
+| `.aem/context/glossary.md` | Domain disambiguation |
+| `.aem/context/test-patterns.md` | How this project writes tests |
+| `.aem/context/aem-api-namespaces.md` | Canonical AEM as a Cloud Service API package roots (verify-before-import support) |
+| `.aem/context/README.md` | Index of the above |
+| `.aem/context/.agentkit-manifest.json` | Run manifest: every file written, post-write checksum, every heuristic decision |
+| `.aem/context/.agentkit.lock` | Workspace advisory lock so parallel invocations exit cleanly |
+
+### Tool-specific layer (signal-detected, then customer confirms)
+
+Signals are tightened to avoid false positives. The presence of
+`.github/*.yml` workflow files is NOT a Copilot signal; an empty
+`.claude/` directory (often left by IDE installers) is NOT a Claude
+Code signal. The skill prompts the customer to confirm or narrow the
+detected toolchains before materializing artifacts. The single source
+of truth for this table is [`SKILL.md`](./SKILL.md) § "IDE detection
+and selection"; the row below mirrors it.
+
+| Tool | Detection signal (must include the "content" half) | Tool-specific artifacts (when selected) |
+|---|---|---|
+| Claude Code | `.claude/agents/` or `.claude/commands/` is non-empty | `.claude/agents/aem-*.md`, `.claude/commands/<owned>.md`, `.mcp.json` |
+| Cursor | `.cursor/rules/` is non-empty or `.cursor/mcp.json` exists | `.cursor/rules/aem-*.mdc`, `.cursor/mcp.json` |
+| GitHub Copilot | `.github/copilot-instructions.md` exists | `.github/instructions/aem-*.instructions.md` (+ `.github/copilot-instructions.md` only when missing) |
+| Codex | (universal layer is sufficient) | — |
+| Continue.dev | `.continue/rules/` is non-empty | `.continue/rules/aem-*.md` |
+| Cline | `.clinerules` exists or `.vscode/extensions.json` lists `saoudrizwan.claude-dev` | `.clinerules` (only when missing) |
+| Windsurf | `.windsurfrules` exists or `.codeium/` is non-empty | `.windsurfrules` (only when missing) |
+| Augment Code | `.augment/` exists or pre-existing `augment.md` | `augment.md` (only when missing) |
+| Aider, Gemini CLI, Zed, Factory, Jules, Devin, Amp, Kilo, RooCode, Warp, JetBrains Junie, Ona | (universal layer is sufficient — read `AGENTS.md` natively) | — |
+
+A single canonical role-prompt source is projected into each tool's format
+so the content seen by the agent is identical regardless of IDE. The
+deferred-role inline fallback (for the concatenated single-file
+projections — Cline / Windsurf / Augment) writes a sibling
+`<file>.aem-roles-extra.md` so the customer always has every role body on
+disk, not behind a pointer to the published skill bundle.
+
+## What never changes
+
+Customer Java, HTL, JSP, JS/TS/CSS, dispatcher configuration, FileVault XML,
+`pom.xml`, content `.json`, OSGi config files, `README`, `CONTRIBUTING`,
+`LICENSE`, the root `AGENTS.md`, or any other pre-existing file lacking the
+marker comment. See `SKILL.md` § "Hard guarantee" for the exact allow-list.
+
+The one exception is the root `CLAUDE.md`: the skill may add or update an
+"AEM as a Cloud Service" agentic-context section there, but **only after
+the developer explicitly consents** to a prompt (same pattern as the
+IDE-selection prompt). On decline — and as the silent default for
+`--silent` / `AEM_AGENTKIT_SILENT=1` runs — `CLAUDE.md` is left untouched.
+Root `AGENTS.md` is never written by this skill regardless of consent.
+
+## Relationship to `ensure-agents-md`
+
+`aem-agentkit` does not replace `ensure-agents-md`; they are complementary.
+`ensure-agents-md` owns the root `AGENTS.md` and the base `CLAUDE.md`.
+`aem-agentkit` owns everything else. If root `AGENTS.md` is missing and
+`ensure-agents-md` is available, `aem-agentkit` defers to it as step 0. If
+it is not available, `aem-agentkit` proceeds with everything except the
+root `AGENTS.md` and emits a one-line notice.
+
+Root `AGENTS.md` is never written by `aem-agentkit`. Root `CLAUDE.md` is
+the only file the two skills both touch: `ensure-agents-md` creates the
+base `CLAUDE.md`, and `aem-agentkit` then **offers** — with explicit
+developer consent — to append its marked "AEM as a Cloud Service"
+agentic-context section to it. On decline, `CLAUDE.md` stays exactly as
+`ensure-agents-md` left it.
+
+## Status
+
+Beta. Skill version `1.0.0-beta`. Generated JSON files carry
+`schemaVersion: "1"`. Marker contract, migration rules, and the
+deterministic-helper version pin are documented in
+[`references/upgrade-and-migration.md`](./references/upgrade-and-migration.md)
+and [`references/helpers.md`](./references/helpers.md).
+
+Verify all outputs before applying to production projects.
+
+## What "AI-native" means here
+
+After running this skill on an AEM as a Cloud Service repo, any
+AGENTS.md-spec agent (Claude Code, Cursor, Copilot, etc.) works the repo
+with project-specific context: correct module boundaries, real
+component / Sling-Model / OSGi catalogs, verify-before-import via the
+AEM Cloud Service API namespace reference, detected conventions and
+anti-patterns, and `/regen-context` to keep the context fresh after code
+changes. The payoff: lower hallucination, less re-explaining the codebase
+per session, and portable context across agent tools — not locked to one
+IDE. The context is grounded in AEM as a Cloud Service (Cloud Manager,
+RDE, AEM SDK realities are reflected), not back-ported from 6.5 docs. Beta — verify outputs
+before applying to production.
+
+## End-to-end agentic workflow coverage
+
+This skill covers the **bootstrap** phase of an end-to-end agentic
+workflow on AEM as a Cloud Service. Other phases are handled by sibling
+skills already published in the `aem-cloud-service` plugin
+(`plugins/aem/cloud-service/skills/` in [adobe/skills](https://github.com/adobe/skills)):
+
+| Phase | Public sibling skill |
+|---|---|
+| Bootstrap (this skill) | `aem-agentkit` — per-module AGENTS.md, codified context, tool-specific routing |
+| Root context | `ensure-agents-md` — root AGENTS.md + CLAUDE.md |
+| Pattern transformation | `best-practices` — Cloud Service patterns, legacy-to-cloud transformations |
+| Component scaffolding | `create-component` — opinionated component scaffolds |
+| Migration orchestration | `migration` — BPA / CAM orchestration on top of `best-practices` |
+| Workflow authoring | `aem-workflow` — Granite Workflow model design, development, triggering, debugging, triaging |
+| Dispatcher | `dispatcher` — config authoring, advisory, incident response, performance tuning, security hardening |
+| Content distribution | `content-distribution` — Sling distribution and replication |
+| Rapid Development | `aem-rde` — RDE deploy, log inspection, snapshots, troubleshooting via `aio aem rde` |
+
+The bootstrap this skill produces (per-module `AGENTS.md`, codified
+context under `.aem/context/`, project-scoped subagents and rules) is
+read by every later-phase skill. A customer who has installed the
+`aem-cloud-service` plugin (which bundles every skill above) and run
+`aem-agentkit` has end-to-end agentic-workflow coverage on their
+repository.
+
+## Trademarks
+
+This skill is licensed under Apache 2.0. References to third-party IDE
+and agent names (Claude Code, Cursor, GitHub Copilot, Codex, Continue,
+Cline, Windsurf, Augment, Aider, Gemini CLI, Zed, RooCode, JetBrains
+Junie, and others) are nominative and descriptive only — they identify
+the tools the skill produces artifacts for. All such names remain the
+trademarks of their respective owners. This skill is not affiliated with
+or endorsed by any of them. Names removed from the previous edition
+(e.g. agent names without a published product page) have been dropped to
+keep the trademark list to verifiable tools only.
+
+## Reporting issues
+
+https://github.com/adobe/skills/issues