feat(aem-cloud-service): add aem-agentkit skill for agentic workflow bootstrap (beta)

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,123 @@
+# 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.
+
+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 (silent auto-detection)
+
+| Tool | Detection signal | Tool-specific artifacts |
+|---|---|---|
+| Claude Code | `.claude/` dir or `CLAUDE.md` | `.claude/agents/aem-*.md`, `.claude/commands/<owned>.md`, `.mcp.json` |
+| Cursor | `.cursor/` dir | `.cursor/rules/aem-*.mdc`, `.cursor/mcp.json` |
+| GitHub Copilot | `.github/copilot-instructions.md` or `.github/*.yml` workflow | `.github/instructions/aem-*.instructions.md` (Copilot-instructions written only if missing) |
+| Codex | (universal layer is sufficient) | — |
+| Continue.dev | `.continue/` dir | `.continue/rules/aem-*.md` |
+| Cline | `.clinerules` or `.vscode/extensions.json` listing the Cline extension | `.clinerules` (only when missing) |
+| Windsurf | `.windsurfrules` or `.codeium/` directory | `.windsurfrules` (only when missing) |
+| Augment Code | `.augment/` directory or pre-existing `augment.md` | `augment.md` (only when missing) |
+| Aider, Gemini CLI, Zed, Factory, Jules, Devin, Amp, Kilo, RooCode, Warp, JetBrains Junie, Ona, Phoenix | (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` / `CLAUDE.md`, or any other pre-existing file
+lacking the marker comment. See `SKILL.md` § "Hard guarantee" for the exact
+allow-list.
+
+## Relationship to `ensure-agents-md`
+
+`aem-agentkit` does not replace `ensure-agents-md`; they are complementary.
+`ensure-agents-md` owns the root `AGENTS.md` + `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.
+
+## 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.
+
+## 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.
+
+## Reporting issues
+
+https://github.com/adobe/skills/issues