From c4fbdbcbec9a863c3ea3f28972549520d06f30b8 Mon Sep 17 00:00:00 2001 From: Abhishek Garg Date: Thu, 4 Jun 2026 16:48:57 +0530 Subject: [PATCH 1/7] feat(aem-cloud-service): add aem-agentkit skill for agentic workflow bootstrap (beta) aem-agentkit complements (does not replace) ensure-agents-md by layering everything beyond root AGENTS.md that an AEM as a Cloud Service repo needs to be ready for agentic workflows across Claude Code, Cursor, GitHub Copilot, Codex, and Continue.dev - without modifying customer source code. What it writes (all under the workspace root, never on customer source): Universal layer (always written if missing): - Per-module AGENTS.md, recursively placed for nested AEM monorepos (sub-project overview at the nested root, per-archetype-leaf at each leaf so monorepo customers like twilio-reactor get focused context at twilio-com/core/AGENTS.md, twilio-com/ui.apps/AGENTS.md, etc.) - .aem/context/{components,osgi-services,conventions,avoid,glossary, test-patterns,aem-api-namespaces,README}, written at the workspace root AND scoped per nested AEM sub-project so a sub-project agent loads only its own context. Tool-specific layer (silent IDE auto-detection): - Claude Code (.claude/): agents/aem-*.md (component, sling-model, htl, dispatcher, osgi-config, integration- test, ui-test, content-fragment authors; guardrails); commands/*.md (new-component, new-sling-model, validate-dispatcher, regen-context, agents-md-check); .mcp.json placeholder - Cursor (.cursor/): rules/aem-*.mdc with the same role set, glob-scoped per role; mcp.json placeholder - GitHub Copilot (.github):instructions/aem-*.instructions.md with applyTo globs per role; copilot- instructions.md only if missing - Codex: universal AGENTS.md layer is sufficient - Continue.dev (.continue):rules/aem-*.md per role A single canonical role-prompt source in references/templates/roles/ is projected into each IDE's format so the content seen by the agent is identical regardless of tool. Only the frontmatter and file extension differ. Hard guarantees: - Customer source files are never modified. The skill writes only into the agent-meta allow-list documented in SKILL.md. git diff after a run shows zero changes to any pre-existing tracked or untracked file. - Never modifies the root AGENTS.md or CLAUDE.md owned by ensure-agents-md. - Stub-over-hallucinate: derived rules require 3+ evidence pointers or become TODO markers. - Atomic writes (.tmp + rename), sorted-key JSON, LF endings, evidence- pointered conventions. - Marker-based idempotency: a file lacking the marker is human-curated and never touched; matching marker + drifted checksum writes to .agentkit-new (never destructive). - Schema versioning + upgrade path for future skill versions. - Privacy deny-list: never reads .env*, .cloudmanager/secrets*, **/credentials*, **/*creds*, **/*secret*, **/*.pem/*.key/*.p12. - Customer opt-out via a _disable_agentkit file at the workspace root. Relationship to ensure-agents-md: - ensure-agents-md remains the canonical bootstrap for root AGENTS.md + CLAUDE.md per Adobe Experience League public documentation. - aem-agentkit defers to it as step 0 when root AGENTS.md is missing and ensure-agents-md is available; when it is not, aem-agentkit proceeds with everything else and emits a one-line notice. Status: beta (per cloud-service/CLAUDE.md beta markers - frontmatter metadata.status: beta, [BETA] description prefix, body blockquote). --- README.md | 16 ++ .../skills/aem-agentkit/README.md | 103 +++++++ .../skills/aem-agentkit/SKILL.md | 217 ++++++++++++++ .../references/codified-context.md | 242 ++++++++++++++++ .../references/collision-rules.md | 61 ++++ .../aem-agentkit/references/guardrails.md | 61 ++++ .../aem-agentkit/references/mcp-wiring.md | 48 ++++ .../aem-agentkit/references/module-catalog.md | 67 +++++ .../references/per-module-agents-md.md | 130 +++++++++ .../references/per-tool-artifacts.md | 272 ++++++++++++++++++ .../AGENTS.module.analysis.md.template | 22 ++ .../AGENTS.module.code-quality.md.template | 22 ++ .../templates/AGENTS.module.core.md.template | 34 +++ .../AGENTS.module.dispatcher.md.template | 34 +++ .../AGENTS.module.generic.md.template | 26 ++ .../AGENTS.module.it.tests.md.template | 32 +++ .../AGENTS.module.ui.apps.md.template | 34 +++ .../AGENTS.module.ui.frontend.md.template | 29 ++ .../AGENTS.module.ui.tests.md.template | 30 ++ .../templates/AGENTS.subproject.md.template | 30 ++ .../templates/aem-api-namespaces.md.template | 61 ++++ .../references/templates/avoid.md.template | 10 + .../command.agents-md-check.md.template | 27 ++ .../command.new-component.md.template | 18 ++ .../command.new-sling-model.md.template | 16 ++ .../command.regen-context.md.template | 19 ++ .../command.validate-dispatcher.md.template | 14 + .../templates/components.json.template | 8 + .../templates/context.README.md.template | 24 ++ .../templates/conventions.md.template | 38 +++ .../references/templates/glossary.md.template | 6 + .../references/templates/mcp.json.template | 25 ++ .../templates/osgi-services.json.template | 10 + .../templates/roles/role.component-author.md | 35 +++ .../roles/role.content-fragment-author.md | 23 ++ .../templates/roles/role.dispatcher-editor.md | 31 ++ .../templates/roles/role.guardrails.md | 21 ++ .../templates/roles/role.htl-author.md | 25 ++ .../roles/role.integration-test-author.md | 27 ++ .../roles/role.osgi-config-author.md | 25 ++ .../roles/role.sling-model-author.md | 30 ++ .../templates/roles/role.ui-test-author.md | 27 ++ .../templates/test-patterns.md.template | 24 ++ .../references/upgrade-and-migration.md | 69 +++++ 44 files changed, 2123 insertions(+) create mode 100644 plugins/aem/cloud-service/skills/aem-agentkit/README.md create mode 100644 plugins/aem/cloud-service/skills/aem-agentkit/SKILL.md create mode 100644 plugins/aem/cloud-service/skills/aem-agentkit/references/codified-context.md create mode 100644 plugins/aem/cloud-service/skills/aem-agentkit/references/collision-rules.md create mode 100644 plugins/aem/cloud-service/skills/aem-agentkit/references/guardrails.md create mode 100644 plugins/aem/cloud-service/skills/aem-agentkit/references/mcp-wiring.md create mode 100644 plugins/aem/cloud-service/skills/aem-agentkit/references/module-catalog.md create mode 100644 plugins/aem/cloud-service/skills/aem-agentkit/references/per-module-agents-md.md create mode 100644 plugins/aem/cloud-service/skills/aem-agentkit/references/per-tool-artifacts.md create mode 100644 plugins/aem/cloud-service/skills/aem-agentkit/references/templates/AGENTS.module.analysis.md.template create mode 100644 plugins/aem/cloud-service/skills/aem-agentkit/references/templates/AGENTS.module.code-quality.md.template create mode 100644 plugins/aem/cloud-service/skills/aem-agentkit/references/templates/AGENTS.module.core.md.template create mode 100644 plugins/aem/cloud-service/skills/aem-agentkit/references/templates/AGENTS.module.dispatcher.md.template create mode 100644 plugins/aem/cloud-service/skills/aem-agentkit/references/templates/AGENTS.module.generic.md.template create mode 100644 plugins/aem/cloud-service/skills/aem-agentkit/references/templates/AGENTS.module.it.tests.md.template create mode 100644 plugins/aem/cloud-service/skills/aem-agentkit/references/templates/AGENTS.module.ui.apps.md.template create mode 100644 plugins/aem/cloud-service/skills/aem-agentkit/references/templates/AGENTS.module.ui.frontend.md.template create mode 100644 plugins/aem/cloud-service/skills/aem-agentkit/references/templates/AGENTS.module.ui.tests.md.template create mode 100644 plugins/aem/cloud-service/skills/aem-agentkit/references/templates/AGENTS.subproject.md.template create mode 100644 plugins/aem/cloud-service/skills/aem-agentkit/references/templates/aem-api-namespaces.md.template create mode 100644 plugins/aem/cloud-service/skills/aem-agentkit/references/templates/avoid.md.template create mode 100644 plugins/aem/cloud-service/skills/aem-agentkit/references/templates/command.agents-md-check.md.template create mode 100644 plugins/aem/cloud-service/skills/aem-agentkit/references/templates/command.new-component.md.template create mode 100644 plugins/aem/cloud-service/skills/aem-agentkit/references/templates/command.new-sling-model.md.template create mode 100644 plugins/aem/cloud-service/skills/aem-agentkit/references/templates/command.regen-context.md.template create mode 100644 plugins/aem/cloud-service/skills/aem-agentkit/references/templates/command.validate-dispatcher.md.template create mode 100644 plugins/aem/cloud-service/skills/aem-agentkit/references/templates/components.json.template create mode 100644 plugins/aem/cloud-service/skills/aem-agentkit/references/templates/context.README.md.template create mode 100644 plugins/aem/cloud-service/skills/aem-agentkit/references/templates/conventions.md.template create mode 100644 plugins/aem/cloud-service/skills/aem-agentkit/references/templates/glossary.md.template create mode 100644 plugins/aem/cloud-service/skills/aem-agentkit/references/templates/mcp.json.template create mode 100644 plugins/aem/cloud-service/skills/aem-agentkit/references/templates/osgi-services.json.template create mode 100644 plugins/aem/cloud-service/skills/aem-agentkit/references/templates/roles/role.component-author.md create mode 100644 plugins/aem/cloud-service/skills/aem-agentkit/references/templates/roles/role.content-fragment-author.md create mode 100644 plugins/aem/cloud-service/skills/aem-agentkit/references/templates/roles/role.dispatcher-editor.md create mode 100644 plugins/aem/cloud-service/skills/aem-agentkit/references/templates/roles/role.guardrails.md create mode 100644 plugins/aem/cloud-service/skills/aem-agentkit/references/templates/roles/role.htl-author.md create mode 100644 plugins/aem/cloud-service/skills/aem-agentkit/references/templates/roles/role.integration-test-author.md create mode 100644 plugins/aem/cloud-service/skills/aem-agentkit/references/templates/roles/role.osgi-config-author.md create mode 100644 plugins/aem/cloud-service/skills/aem-agentkit/references/templates/roles/role.sling-model-author.md create mode 100644 plugins/aem/cloud-service/skills/aem-agentkit/references/templates/roles/role.ui-test-author.md create mode 100644 plugins/aem/cloud-service/skills/aem-agentkit/references/templates/test-patterns.md.template create mode 100644 plugins/aem/cloud-service/skills/aem-agentkit/references/upgrade-and-migration.md diff --git a/README.md b/README.md index 730001fe..176f3cda 100644 --- a/README.md +++ b/README.md @@ -184,6 +184,22 @@ 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, and Continue.dev. It writes only into agent-meta locations and never modifies customer source code. + +- Per-module `AGENTS.md` in each detected AEM module (focused context the agent loads only when working in that module) +- Machine-readable codified context under `.aem/context/`: component catalog, OSGi services / Sling Models / Sling Servlets index, derived conventions with evidence pointers, anti-patterns with pointers to the `best-practices` skill, glossary, test patterns +- 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, and rules (`.continue/rules/aem-*.md`) for Continue. 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 +- Embedded guardrails (search-before-create, verify-before-import, no `/libs` writes, stop-on-red) +- 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. +- 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: diff --git a/plugins/aem/cloud-service/skills/aem-agentkit/README.md b/plugins/aem/cloud-service/skills/aem-agentkit/README.md new file mode 100644 index 00000000..7dc0e798 --- /dev/null +++ b/plugins/aem/cloud-service/skills/aem-agentkit/README.md @@ -0,0 +1,103 @@ +# aem-agentkit (beta) + +Bootstrap an AEM as a Cloud Service repository for agentic workflows. + +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. + +See [`SKILL.md`](./SKILL.md) for the full contract. + +## What gets created + +### Universal layer (always written if missing) + +| Path | Purpose | +|---|---| +| `/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/README.md` | Index of the above | + +### 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/.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` | + +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. + +## 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. Verify all outputs before applying to production projects. + +Skill version: `0.1.0-beta`. Generated JSON files carry +`schemaVersion: "1"`. Upgrade rules in +[`references/upgrade-and-migration.md`](./references/upgrade-and-migration.md). + +## 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 diff --git a/plugins/aem/cloud-service/skills/aem-agentkit/SKILL.md b/plugins/aem/cloud-service/skills/aem-agentkit/SKILL.md new file mode 100644 index 00000000..64b5910e --- /dev/null +++ b/plugins/aem/cloud-service/skills/aem-agentkit/SKILL.md @@ -0,0 +1,217 @@ +--- +name: aem-agentkit +description: | + [BETA] Bootstrap an AEM as a Cloud Service repository for agentic workflows + across Claude Code, Cursor, GitHub Copilot, Codex, and Continue. Generates + per-module AGENTS.md, machine-readable codified context under .aem/context/, + project-scoped subagents / slash commands / rule files / Copilot instructions, + MCP wiring, and guardrail rules — without modifying customer source code. + Detects installed agent stacks silently and writes only matching tool-specific + artifacts. Defers root AGENTS.md to ensure-agents-md when present; works + standalone when not. + This skill is in beta. Verify all outputs before applying them to production + projects. +license: Apache-2.0 +compatibility: AEM as a Cloud Service projects (Java stack, Maven, Dispatcher). +metadata: + status: beta + version: "0.1.0-beta" + aem_version: "Cloud Service" + complements: ensure-agents-md +--- + +# aem-agentkit — bootstrap for agentic workflows on AEM as a Cloud Service + +> **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 + +## What this skill does, in one sentence + +Writes a small set of agent-meta files at the workspace root and inside +existing modules so coding agents (Claude Code, Cursor, GitHub Copilot, Codex, +Continue, and any agentic harness on top of them) can perform agentic +workflows on the customer's AEM as a Cloud Service repository with high +reliability and low hallucination — without ever modifying customer source +code. + +## Hard guarantee — never modifies customer source + +This skill writes **only** into the following paths, all relative to the +workspace root: + +- `/AGENTS.md` for each detected AEM module (recursively, including nested AEM sub-projects) +- `.aem/context/` (`components.json`, `osgi-services.json`, `conventions.md`, + `avoid.md`, `glossary.md`, `test-patterns.md`, `aem-api-namespaces.md`, `README.md`) — written at the workspace root **and** scoped per nested AEM sub-project +- `.claude/agents/aem-*.md`, `.claude/commands/.md`, + `.mcp.json` *(only when `.claude/` is detected and the file is missing)* +- `.cursor/rules/aem-*.mdc`, `.cursor/mcp.json` *(only when `.cursor/` is + detected and the file is missing)* +- `.github/copilot-instructions.md` *(only when missing and Copilot is + detected)*, `.github/instructions/aem-*.instructions.md` +- `.continue/rules/aem-*.md` *(only when `.continue/` is detected)* + +Every other file is read-only. The root `AGENTS.md` and `CLAUDE.md` are +owned by `ensure-agents-md` and are never modified by this skill. Every +generated artifact carries a marker comment so the customer can identify, +delete, or regenerate them safely. + +## Relationship to `ensure-agents-md` + +`aem-agentkit` complements `ensure-agents-md` — they are not replacements +for each other. + +| Skill | Owns | Outputs | +|---|---|---| +| `ensure-agents-md` (stable) | Root `AGENTS.md` + `CLAUDE.md` | 2 files | +| `aem-agentkit` (beta) | Per-module `AGENTS.md`, `.aem/context/`, tool-specific files | Everything else | + +| Customer state | `aem-agentkit` behavior | +|---|---| +| Root `AGENTS.md` present (any author) | Use it as-is, never modify | +| Root `AGENTS.md` missing AND `ensure-agents-md` installed | Defer to `ensure-agents-md` as step 0, then continue | +| Root `AGENTS.md` missing AND `ensure-agents-md` not installed | Proceed with everything else; one-line notice asks user to add a root `AGENTS.md` | + +## Trigger and invocation + +This skill is **opt-in** — it does not auto-bootstrap like `ensure-agents-md`. +It runs when: + +- The user invokes it by name ("set up agentic context", "bootstrap aem-agentkit", "make this repo agentic-ready", etc.). +- The host routes here because the user is doing component / Sling Model / dispatcher work and codified context would reduce hallucination, AND the repo has root `AGENTS.md` but no `.aem/context/`. +- The slash commands it installs are invoked: `/regen-context`, `/agents-md-check`. + +The skill skips silently and exits cleanly when: + +- Root `pom.xml` is missing or the repo is not an AEM as a Cloud Service project. +- A `_disable_agentkit` file exists at the workspace root. +- Every universal-layer artifact already exists with a matching marker checksum and no tool-specific layer is missing. + +## Silent IDE detection + +The skill does **not** prompt the user. It detects installed agent stacks +from filesystem signals and writes only the matching tool-specific layer. + +| Tool | Detection signal | Tool-specific artifacts | +|---|---|---| +| Claude Code | `.claude/` directory or `CLAUDE.md` at root | `.claude/agents/aem-*.md`, `.claude/commands/.md`, `.mcp.json` placeholder | +| Cursor | `.cursor/` directory | `.cursor/rules/aem-*.mdc`, `.cursor/mcp.json` placeholder | +| GitHub Copilot | `.github/copilot-instructions.md` present, or `.github/` with any workflow file | `.github/instructions/aem-*.instructions.md`; `.github/copilot-instructions.md` only if missing | +| Codex | (always — reads `AGENTS.md` natively per the open standard) | (none — universal layer is sufficient) | +| Continue.dev | `.continue/` directory | `.continue/rules/aem-*.md` | + +If **no** signal is detected, only the universal layer is written and the +summary block lists what would be generated if each tool were detected, +so the customer can opt in later by creating the corresponding directory +and re-running the skill. + +## Generation order (fixed) + +The skill writes artifacts in this order. Earlier outputs are read by later +steps so cross-references stay consistent. + +1. `.aem/context/components.json` — see [references/codified-context.md](./references/codified-context.md). Written at the workspace root **and** at each detected nested AEM sub-project root (scoped to that sub-project). +2. `.aem/context/osgi-services.json` — same per-scope rule. +3. `.aem/context/conventions.md` — derived rules with evidence pointers. +4. `.aem/context/avoid.md` — anti-patterns with evidence pointers. +5. `.aem/context/glossary.md` — domain disambiguation. +6. `.aem/context/test-patterns.md` — testing conventions. +7. `.aem/context/aem-api-namespaces.md` — canonical AEM API namespace reference (static guardrail support for "verify before import"). +8. `.aem/context/README.md` — human-readable index of the above. +8. Per-module `AGENTS.md` (recursive — supports nested AEM monorepos where a top-level module is itself a full archetype) — see [references/per-module-agents-md.md](./references/per-module-agents-md.md) +9. Tool-specific artifacts (Claude / Cursor / Copilot / Continue) — see [references/per-tool-artifacts.md](./references/per-tool-artifacts.md) +10. `.mcp.json` and `.cursor/mcp.json` — see [references/mcp-wiring.md](./references/mcp-wiring.md) + +After step 10, run the **self-validation pass**: + +- Every evidence pointer in `conventions.md`, `avoid.md`, `glossary.md`, `test-patterns.md` resolves to an existing file (and line, when given). +- Every `slingModelFqcn` in `components.json` resolves to an existing `.java` file. +- Every per-module `AGENTS.md` corresponds to an existing directory. +- Every tool-specific file carries the marker. +- Failure aborts with a one-line diagnostic; no partial outputs (atomic write per `.tmp` + rename). + +## Reference files + +| File | Purpose | +|---|---| +| [references/per-module-agents-md.md](./references/per-module-agents-md.md) | Rules, templates, and size budgets for per-module `AGENTS.md` files | +| [references/codified-context.md](./references/codified-context.md) | `.aem/context/*` schemas, discovery rules, evidence-pointer format, schema versioning | +| [references/per-tool-artifacts.md](./references/per-tool-artifacts.md) | Tool detection signals, canonical role-prompt source, projection into Claude / Cursor / Copilot / Continue formats | +| [references/mcp-wiring.md](./references/mcp-wiring.md) | `.mcp.json` and `.cursor/mcp.json` non-destructive merge rules | +| [references/guardrails.md](./references/guardrails.md) | Guardrail rule text (search-before-create, verify-API, etc.) | +| [references/module-catalog.md](./references/module-catalog.md) | Module descriptions and add-on detection table | +| [references/collision-rules.md](./references/collision-rules.md) | Complete pre-existing-state behavior table (25+ scenarios) | +| [references/upgrade-and-migration.md](./references/upgrade-and-migration.md) | Skill version bump + JSON schema migration rules | + +## Idempotency + +- **Never overwrite** any pre-existing file lacking our marker. +- Each generated artifact's first content line is a marker: + - Markdown / `.mdc`: `` + - JSON: leading top-level fields `"_generatedBy": "aem-agentkit"`, `"_skillVersion": "0.1.0-beta"`, `"schemaVersion": "1"`. +- Re-running the skill is a no-op when nothing has drifted. +- A file lacking the marker is treated as **human-curated**; the skill never touches it. When the skill would otherwise write to such a path, it writes to `.agentkit-new` instead and surfaces a one-line diff summary. +- A marker-bearing file with a different checksum (because we ship new templates) is **not** overwritten — the new content goes to `.agentkit-new`; the customer chooses whether to swap. + +## Modes + +| Mode | Trigger | Behavior | +|---|---|---| +| Default | Skill invoked, opt-out signals absent | Step 0: defer to `ensure-agents-md` if root `AGENTS.md` missing and that skill is available. Step 1+: generate missing universal + matching tool-specific artifacts. | +| Refresh | `/regen-context` slash command (per detected tool) or skill argument | Regenerate only `.aem/context/*`. Diffs go to `.agentkit-new` per § Idempotency. | +| Check | `/agents-md-check` slash command or `--check` | Read-only drift report. Non-zero exit when stale. | + +## What this skill never does + +- Modify customer source code (Java, HTL, JSP, JS/TS/CSS, dispatcher `.conf`/`.any`/`.farm`, FileVault XML, `pom.xml`, content `.json`, OSGi config, `README`, `CONTRIBUTING`, `LICENSE`, or any other pre-existing file lacking the marker). +- Modify the root `AGENTS.md` or `CLAUDE.md`. +- Write into `.git/`, `target/`, `node_modules/`, `dist/`, `build/`, `out/`. +- Read `.cloudmanager/env*.json`, `.cloudmanager/secrets*`, `.env`, `.env.*`, `**/credentials*`, `**/*creds*`, `**/*secret*`, `**/*.pem`, `**/*.key`, `**/*.p12`. Only `.cloudmanager/java-version` is read from `.cloudmanager/`. +- Mention specific MCP server packages by name in the bodies of generated AGENTS.md / per-module AGENTS.md files. Server names live in `.mcp.json` / `.cursor/mcp.json` only. +- Use marketing language in any generated artifact. Generated content frames itself as agentic workflow context. +- Embed AEM 6.5 documentation URLs. All resource links use the Cloud Service namespace. +- Prompt the customer for input. IDE detection is silent. + +## Communication contract + +The skill writes only at three points to the user: + +**Before any writes — one line:** + +> Bootstrapping agentic workflow context for this AEM as a Cloud Service repository. No source files will be modified. + +**After all writes — concise deterministic summary:** + +``` +aem-agentkit: complete + Universal layer: + Per-module AGENTS.md: across [] + Indexes: components.json (N), osgi-services.json (N) + Derived: conventions.md (N rules, T TODOs), avoid.md (N entries), + glossary.md, test-patterns.md + Tool-specific layer (detected: ): + Claude: agents, commands, mcp.json (existing|new) + Cursor: rules, mcp.json (existing|new) + Copilot: instructions + Continue: rules + TODO markers: items pending human review + Refresh: /regen-context + Drift: /agents-md-check +``` + +**On any error:** a single line describing the failure plus the diagnostic path. The skill never leaves partial outputs (atomic write: `.tmp` + rename). + +After the summary, the skill yields back so the user's original request proceeds with the new context loaded. + +## Rules + +- **Never overwrite** any pre-existing file (§ Idempotency). +- **Never hallucinate.** Only emit a derived rule when ≥ 3 evidence points exist; otherwise emit a TODO marker. +- **Never read** files in § "What this skill never does". +- **Never write** outside the allow-list in § "Hard guarantee". +- **Customer-only discovery.** Components, models, and services are discovered from the customer's source modules. Do not index Core Components or anything under `/libs`. +- **Workspace boundary.** Only walk paths under the workspace root. Do not follow symlinks pointing outside the workspace. +- **Output stability.** JSON sorted-keys + 2-space indent + LF + final newline + UTF-8 no BOM. Markdown LF + final newline + no trailing whitespace. Discovery enumerates with sorted directory listings. +- **Evidence-pointer format.** `:<1-based-line>`. Path uses `/` separators on every platform. +- **Atomic write.** Every output goes to `.tmp` and is renamed to `` on success. Orphan `.tmp` files from a previous interrupted run are deleted at startup. +- **Equivalence guarantee.** A single canonical role-prompt source is projected into Claude / Cursor / Copilot / Continue formats so the content seen by the agent is identical regardless of IDE. diff --git a/plugins/aem/cloud-service/skills/aem-agentkit/references/codified-context.md b/plugins/aem/cloud-service/skills/aem-agentkit/references/codified-context.md new file mode 100644 index 00000000..fe9ddab3 --- /dev/null +++ b/plugins/aem/cloud-service/skills/aem-agentkit/references/codified-context.md @@ -0,0 +1,242 @@ +# Codified context — `.aem/context/*` + +> **Beta Skill:** Outputs must be reviewed before applying to production. + +This reference defines the schemas, discovery rules, and stability rules for +every file under `.aem/context/`. + +## 1. Discovery scope + +- **Components.** Walk `**/src/main/content/jcr_root/apps/**/components/**` + in every FileVault content-package module (typically `ui.apps`, optionally + `ui.apps.*` siblings). Do **not** index Core Components or anything under + `/libs`. Key by full JCR path (e.g. `/apps/wknd/components/byline`) so + duplicates across component groups stay distinguishable. +- **Sling Models, OSGi services, Sling Servlets.** Walk every module + containing `src/main/java/**`. Exclude `target/`, `generated-sources/`, + `out/`, `build/`, `node_modules/`. +- **Multiple HTL files per component.** Index the primary HTL file + (`.html` matching directory name) under `htlPath`; list + others under `siblingHtmlFiles`. +- **Dialogs.** Index both `cq:dialog` and `cq:editConfig` when present. +- **Multi-adaptable Sling Models.** Include every adaptable in the entry. +- **Multi-impl services.** Each impl is its own entry; entries include + `siblingImpls` (count of other impls of the same interface). +- **Symlinks.** Walk by logical path. Do not follow symlinks pointing + outside the workspace root. Deduplicate inside-workspace symlinks via + canonical inode. +- **Off-limits.** Never read `.cloudmanager/env*.json`, + `.cloudmanager/secrets*`, `.env`, `.env.*`, `**/credentials*`, + `**/*creds*`, `**/*secret*`, `**/*.pem`, `**/*.key`, `**/*.p12`, or + anything inside `.git/` besides top-of-tree state. +- **Zero-X sanity.** If a `ui.apps` module exists but discovery returns + zero components, treat as discovery error: emit a clear warning and + do **not** overwrite an existing `components.json`. Same rule for + `core/` with zero Java files. +- **Multi-module repos.** Discover from each module that exists. Repo + with no `ui.apps` (decoupled / EDS) → `components.json` is an empty list + with a `warningStubs` entry noting the layout. + +## 2. Output stability + +- JSON: 2-space indent, sorted keys at every level, LF line endings, final + newline, UTF-8 no BOM. +- Markdown: LF line endings, final newline, UTF-8 no BOM, no trailing + whitespace. +- `generatedAt` is ISO-8601 in UTC. +- Discovery enumerates with sorted directory listings. + +## 3. `components.json` + +```json +{ + "_generatedBy": "aem-agentkit", + "_skillVersion": "0.1.0-beta", + "schemaVersion": "1", + "generatedAt": "2026-06-04T00:00:00Z", + "warningStubs": [], + "components": [ + { + "componentGroup": "WKND - Content", + "dialogFieldNames": ["name", "occupations"], + "dialogPath": "ui.apps/src/main/content/jcr_root/apps/wknd/components/byline/_cq_dialog/.content.xml", + "editConfigPath": null, + "htlPath": "ui.apps/src/main/content/jcr_root/apps/wknd/components/byline/byline.html", + "jcrPath": "/apps/wknd/components/byline", + "resourceType": "wknd/components/byline", + "siblingHtmlFiles": [], + "slingModelFqcn": "com.adobe.aem.guides.wknd.core.models.Byline", + "title": "Byline" + } + ] +} +``` + +Notes: +- `slingModelFqcn` is the interface (not impl) when both exist. +- `dialogFieldNames` is best-effort: extract `name="./"` attributes + from `cq:dialog`'s `.content.xml`. + +## 4. `osgi-services.json` + +```json +{ + "_generatedBy": "aem-agentkit", + "_skillVersion": "0.1.0-beta", + "schemaVersion": "1", + "generatedAt": "2026-06-04T00:00:00Z", + "warningStubs": [], + "services": [ + { + "configPids": [], + "dsAnnotationsPackage": "org.osgi.service.component.annotations", + "dsGeneration": "R7", + "implFqcn": "com.adobe.aem.guides.wknd.core.services.impl.SomeServiceImpl", + "implPath": "core/src/main/java/com/adobe/aem/guides/wknd/core/services/impl/SomeServiceImpl.java", + "interfaceFqcn": "com.adobe.aem.guides.wknd.core.services.SomeService", + "references": [ + {"interface": "org.apache.sling.api.resource.ResourceResolverFactory", "name": "resourceResolverFactory"} + ], + "siblingImpls": 0 + } + ], + "servlets": [ + { + "implFqcn": "com.adobe.aem.guides.wknd.core.servlets.PermissionCheckServlet", + "implPath": "core/src/main/java/com/adobe/aem/guides/wknd/core/servlets/PermissionCheckServlet.java", + "registration": { + "sling.servlet.methods": ["GET"], + "sling.servlet.paths": ["/bin/wknd/permission-check"], + "sling.servlet.resourceTypes": [] + } + } + ], + "slingModels": [ + { + "adaptables": ["org.apache.sling.api.SlingHttpServletRequest"], + "modelFqcn": "com.adobe.aem.guides.wknd.core.models.Byline", + "modelImplFqcn": "com.adobe.aem.guides.wknd.core.models.impl.BylineImpl", + "modelPath": "core/src/main/java/com/adobe/aem/guides/wknd/core/models/impl/BylineImpl.java", + "resourceType": "wknd/components/byline" + } + ] +} +``` + +DS generation detection: +- `org.osgi.service.component.annotations` → `R7` +- `org.apache.felix.scr.annotations` → `R6` +- Both in the same impl → `R6`, emit a TODO to migrate. + +## 5. `conventions.md` + +Sections (each cites ≥ 3 evidence pointers, otherwise becomes a TODO): + +1. Package naming +2. Sling Model annotation style +3. OSGi DS annotation style +4. HTL naming +5. Logging style +6. Dispatcher includes +7. Build / verify commands (derived from Maven wrapper detection and + `.cloudmanager/java-version`) + +Evidence-pointer format: `:<1-based-line>`. + +Soft size limit: 80 lines. Hard: 150. If derived rules exceed the budget, +truncate per-rule evidence to 3 pointers and append a TODO pointing at +`.aem/context/components.json` / `osgi-services.json` for the full sample +set. + +## 6. `avoid.md` + +Detected anti-patterns. Each entry has: +- Pattern name and one-line description. +- Where it was found (evidence pointer). +- Pointer to the supported replacement in the existing `best-practices` + skill — do not duplicate that guidance. + +Detection signals (initial set): + +| Pattern | Signal | +|---|---| +| `Scheduler` + `Runnable` | imports `org.apache.sling.commons.scheduler.Scheduler` + `Runnable` in same class | +| JCR observation `EventListener` | implements `javax.jcr.observation.EventListener` | +| OSGi `EventHandler` (substantive) | implements `org.osgi.service.event.EventHandler` with non-trivial body | +| Direct `Replicator` call | uses `com.day.cq.replication.Replicator` | +| Legacy `AssetManager` create/remove | uses deprecated `com.day.cq.dam.api.AssetManager` ops | +| `getAdministrativeResourceResolver` | direct call | +| Felix SCR annotations | `org.apache.felix.scr.annotations` import | +| HTL redundant constant comparison | `data-sly-test` containing `== 'something'` or `=== 'something'` | + +For each match, link to the existing pattern module in +`../best-practices/references/.md`. + +Soft: 60 lines. Hard: 120. + +## 7. `glossary.md` + +Domain disambiguation only. Extracted terms: +- Component `cq:title` values from `.content.xml` under + `ui.apps/.../components/**/.content.xml`. +- Content Fragment model titles from + `/conf/*/settings/dam/cfm/models/**/.content.xml`. +- Taxonomy node names from `ui.content/.../tags/**`. + +Soft: 60. Hard: 120. + +## 8. `test-patterns.md` + +How this project writes tests. Derive from existing test sources: +- Test framework (JUnit 4 vs JUnit 5). +- AemContext usage (`io.wcm.testing.mock.aem.junit5.AemContextExtension` + vs `SlingContextRule`). +- Mocking (Mockito vs other). +- Integration test client (`org.apache.sling.testing.clients`). + +Each derivation cites ≥ 2 evidence pointers (tests are usually uniform so +fewer samples are needed). + +Soft: 60. Hard: 120. + +## 9. `aem-api-namespaces.md` + +Static reference of canonical AEM as a Cloud Service API package roots +(`com.adobe.aem.*`, `com.adobe.cq.*`, `com.adobe.granite.*`, +`com.day.cq.*`, `org.apache.sling.*`, `org.osgi.service.component.annotations.*`, +SLF4J, JCR, etc.). Used by the "verify before import" guardrail so the +agent can sanity-check imports against a static list before fabricating +class names. Complements (does not replace) live Javadoc lookup. + +Rendered from [`templates/aem-api-namespaces.md.template`](./templates/aem-api-namespaces.md.template). +The template is project-agnostic, so the rendered file is byte-identical +across repos — but it still carries a checksum-bearing marker so +idempotency rules apply uniformly. + +## 10. `README.md` (context index) + +Plain Markdown pointing at the indexes and the derived files. No +evidence pointers; just a navigation aid for humans. + +## 11. Per-sub-project scope (nested AEM monorepos) + +When `per-module-agents-md.md` detects a nested AEM project, the skill +also writes a scoped `.aem/context/` at that sub-project root. The +scoped indexes contain only that sub-project's components / services / +models / conventions. The shared root `.aem/context/` continues to +cover the whole monorepo for cross-cutting queries. + +Subagents and rules reference whichever `.aem/context/` is closest to +the file under edit (sub-project context when working inside a +sub-project, root context otherwise). + +## 12. Self-validation (this step only) + +After writing all `.aem/context/*` files: +- Every evidence pointer resolves to an existing file (and line when given). +- Every `slingModelFqcn` in `components.json` resolves to an existing + `.java` file. +- Every `implFqcn` in `osgi-services.json` resolves to an existing `.java` file. +- No file contains marketing language; framing stays factual. + +Failure aborts the entire skill run; no partial outputs are left on disk. diff --git a/plugins/aem/cloud-service/skills/aem-agentkit/references/collision-rules.md b/plugins/aem/cloud-service/skills/aem-agentkit/references/collision-rules.md new file mode 100644 index 00000000..a46f3f78 --- /dev/null +++ b/plugins/aem/cloud-service/skills/aem-agentkit/references/collision-rules.md @@ -0,0 +1,61 @@ +# Collision rules — every pre-existing state + +> **Beta Skill:** Outputs must be reviewed before applying to production. + +This table is the single source of truth for what the skill does when a +target path already exists. Every target falls into exactly one row. + +| Pre-existing state | Skill behavior | +|---|---| +| Root `AGENTS.md` present (any author) | Never modified. Read-only consult. | +| Root `CLAUDE.md` present | Never modified. | +| `/AGENTS.md` present, **no** marker | Treated as human-curated. Never modified. The skill emits a TODO entry to `warningStubs`: `"human-curated ; skipping per-module generation"`. | +| `/AGENTS.md` present, marker + **same** checksum | Skip silently (idempotent). | +| `/AGENTS.md` present, marker + **different** checksum | Write new content to `.agentkit-new`. Print a one-line diff summary. Original untouched. | +| `/AGENTS.md` missing | Generate. | +| `.aem/context/` directory missing | Create. | +| `.aem/context/` missing | Generate. | +| `.aem/context/` present, **no** marker | Never overwrite. Write new content to `.agentkit-new` and warn. | +| `.aem/context/` present, marker + same checksum | Skip. | +| `.aem/context/` present, marker + different checksum | Write `.agentkit-new`. | +| `.aem/context/` present, marker + **older `schemaVersion`** | Run schema migration ([`upgrade-and-migration.md`](./upgrade-and-migration.md) § Schema migration). Write migrated content to `.agentkit-new`. | +| `.claude/agents/aem-.md` missing | Generate (if Claude tool detected). | +| `.claude/agents/aem-.md` present, no marker | Never touched. | +| `.claude/agents/aem-.md` present, marker | Idempotency rules above. | +| `.claude/agents/.md` (non-`aem-*` filename) | Never read, never touched. The skill only writes files matching `aem-*`. | +| `.claude/commands/.md` for a name we own (`new-component`, `new-sling-model`, `validate-dispatcher`, `regen-context`, `agents-md-check`) | Idempotency rules. | +| `.claude/commands/.md` for any other name | Never touched. | +| `.cursor/rules/aem-*.mdc` | Idempotency rules. | +| `.cursor/rules/.mdc` for non-`aem-*` filename | Never touched. | +| `.cursor/mcp.json` present, valid JSON | Never modified. | +| `.cursor/mcp.json` present, invalid JSON | Skip MCP wiring; log warning; do not touch the file. | +| `.cursor/mcp.json` missing **and** `.cursor/` directory exists | Write placeholder. | +| `.github/copilot-instructions.md` present | **Never modified** — customer-owned global instruction file. | +| `.github/copilot-instructions.md` missing | Create with a single-line pointer to `AGENTS.md` (only when `.github/` is detected as Copilot-active). | +| `.github/instructions/aem-.instructions.md` | Idempotency rules. | +| `.github/instructions/.instructions.md` | Never touched. | +| `.continue/rules/aem-.md` | Idempotency rules. | +| `.continue/rules/.md` | Never touched. | +| `.mcp.json` present | Never modified. | +| `.mcp.json` missing AND `.claude/` detected | Write placeholder. | +| `.aem/constitution.md`, `.aem/specs/`, `.aem/plans/`, `.aem/tasks/`, `.aem/templates/` (from aem-orchestration-workflow) | Never touched. The skill writes only inside `.aem/context/`. | +| `_disable_agentkit` file at root | Skill skips entirely (exit 0, no writes). | + +## Marker check + +A file is marker-bearing when **all** of: +- Its first content line (Markdown / `.mdc`) starts with ` +--- +name: aem- +description: +model: sonnet +tools: Read, Glob, Grep, Edit, Write, Bash +--- + + +``` + +Plus slash commands at `.claude/commands/`: + +| File | Owns name | +|---|---| +| `new-component.md` | `/new-component ` | +| `new-sling-model.md` | `/new-sling-model ` | +| `validate-dispatcher.md` | `/validate-dispatcher` (only if `dispatcher/` exists) | +| `regen-context.md` | `/regen-context` | +| `agents-md-check.md` | `/agents-md-check` | + +Plus MCP wiring at `.mcp.json` (see [`mcp-wiring.md`](./mcp-wiring.md)). + +### 3.2 Cursor — `.cursor/rules/aem-.mdc` + +```markdown + +--- +description: +globs: + - +alwaysApply: false +--- + + +``` + +Globs per role: + +| Role | `globs:` | +|---|---| +| component-author | `**/ui.apps/**` | +| sling-model-author | `**/src/main/java/**` | +| htl-author | `**/*.html` | +| dispatcher-editor | `dispatcher/**` | +| osgi-config-author | `**/ui.config/**`, `**/jcr_root/apps/*/config*/**` | +| integration-test-author | `**/it.tests/**` | +| ui-test-author | `**/ui.tests/**` | +| content-fragment-author | `**/conf/**/settings/dam/cfm/**`, `**/content/dam/**` | +| guardrails | `**/*` with `alwaysApply: true` | + +Plus MCP wiring at `.cursor/mcp.json`. + +### 3.3 GitHub Copilot — `.github/instructions/aem-.instructions.md` + +```markdown + +--- +applyTo: "" +--- + + +``` + +`applyTo` patterns mirror the Cursor `globs:` above. Guardrails use +`applyTo: "**/*"`. + +If `.github/copilot-instructions.md` is missing **and** Copilot is detected, +write a minimal version: + +```markdown + +# Repository-wide Copilot instructions + +This repository follows the conventions documented in [`AGENTS.md`](../AGENTS.md) +and `.aem/context/`. Honor every guardrail in [`AGENTS.md`](../AGENTS.md) and +the scoped instructions in `.github/instructions/`. +``` + +If it already exists, the skill never touches it. + +### 3.4 Continue.dev — `.continue/rules/aem-.md` + +```markdown + +# aem- + + +``` + +Continue rules under `.continue/rules/` are always-on; no frontmatter +required. If Continue uses `.continue/config.json` for agent registration, +the skill does not modify it. + +### 3.5 Codex (OpenAI) + +No tool-specific files. Codex reads `AGENTS.md` (root + per-module) and +queries the indexes natively per the open standard. + +### 3.6 Cline (VS Code) — `.clinerules` + +Single Markdown file at the workspace root. Cline concatenates all rules +into its system prompt. + +```markdown + +# AEM as a Cloud Service — agent rules + +Read AGENTS.md, the relevant per-module AGENTS.md, and the indexes under +.aem/context/ before generating any code. Apply every rule under +"Agentic workflow guardrails" in AGENTS.md. + + + +--- + + + +--- + + + +(… all detected roles concatenated …) +``` + +A single file works for Cline because it ingests one rules document, not +per-file or per-glob rules. The same content blocks are reused from the +canonical role sources. + +### 3.7 Windsurf — `.windsurfrules` + +Same shape as `.clinerules`. Single file at the workspace root with all +detected roles concatenated. + +### 3.8 Aider + +No tool-specific files. Aider reads `AGENTS.md` natively. If the customer +maintains an `.aider.conf.yml`, the skill does not touch it. + +### 3.9 Augment Code + +Single file at `augment.md` (project root) — same concatenation pattern +as Cline / Windsurf. Created only when `.augment/` directory or existing +`augment.md` signal is detected. + +## 4. Conditional generation + +| Role / artifact | Condition | +|---|---| +| component-author | Always (universal author role) | +| sling-model-author | Any module with `src/main/java/**` contains `@Model` classes | +| htl-author | `ui.apps` module present (any nesting level) | +| dispatcher-editor | `dispatcher/` module present | +| osgi-config-author | `ui.config` module present (any nesting level) | +| integration-test-author | `it.tests/` module present | +| ui-test-author | `ui.tests/` module present | +| content-fragment-author | Content Fragment models present under `/conf/*/settings/dam/cfm/models/` | +| guardrails | Always (every IDE that is detected) | +| `/new-component` | `ui.apps` module present | +| `/new-sling-model` | Any module with `src/main/java/**` | +| `/validate-dispatcher` | `dispatcher/` module present | +| `/regen-context` | Always | +| `/agents-md-check` | Always | + +## 5. Index self-update rule (embedded in every author role) + +Every authoring role's canonical source ends with this section: + +```markdown +## Index self-update (mandatory final step) + +After your changes are on disk: + +1. Append the new entry to the relevant `.aem/context/*.json` file. +2. Recompute the marker checksum on the JSON file. +3. Add the new entry to the per-module `AGENTS.md` "Common entry points" + list only when the list is below its soft size budget (40 lines). + +This keeps indexes from going stale between explicit `/regen-context` runs. +``` + +This single section appears verbatim in Claude, Cursor, Copilot, and +Continue artifacts. Same content, four IDE shapes. + +## 6. Size budgets + +| Artifact | Soft | Hard | +|---|---|---| +| Claude subagent | 50 lines | 100 lines | +| Cursor `.mdc` rule | 50 lines | 100 lines | +| Copilot `.instructions.md` | 50 lines | 100 lines | +| Continue rule | 50 lines | 100 lines | +| Any slash command | 30 lines | 60 lines | + +## 7. Self-validation + +After writing all tool-specific files: +- Every generated file carries the marker. +- The canonical role-source body appears verbatim across all tool projections (byte-identical inside each role across IDEs). +- No file contains marketing language; framing uses "agentic workflow" terminology only. diff --git a/plugins/aem/cloud-service/skills/aem-agentkit/references/templates/AGENTS.module.analysis.md.template b/plugins/aem/cloud-service/skills/aem-agentkit/references/templates/AGENTS.module.analysis.md.template new file mode 100644 index 00000000..b2481625 --- /dev/null +++ b/plugins/aem/cloud-service/skills/aem-agentkit/references/templates/AGENTS.module.analysis.md.template @@ -0,0 +1,22 @@ + +# {{MODULE_NAME}} + +Analysis / scripting / tooling module. Contains scripts, generators, or analysis utilities that run alongside the reactor build but do not ship application code. + +## Agentic workflow guardrails + +- This module's outputs are developer tools, not production code. Do not import its contents from production modules. +- Match the existing scripting style (bash / Groovy / Python — whichever is already present). + +## Common entry points + +{{ENTRY_POINTS}} + +## What to avoid in this module + +- Embedding production-only dependencies. +- Hard-coded paths outside the reactor root. + +## Build + +- `{{MVN_CMD}} -pl {{MODULE_NAME}} install` diff --git a/plugins/aem/cloud-service/skills/aem-agentkit/references/templates/AGENTS.module.code-quality.md.template b/plugins/aem/cloud-service/skills/aem-agentkit/references/templates/AGENTS.module.code-quality.md.template new file mode 100644 index 00000000..ea6dff33 --- /dev/null +++ b/plugins/aem/cloud-service/skills/aem-agentkit/references/templates/AGENTS.module.code-quality.md.template @@ -0,0 +1,22 @@ + +# {{MODULE_NAME}} + +Code-quality / build-enforcement module. Carries `maven-checkstyle-plugin`, `maven-enforcer-plugin`, or similar build-time enforcement rules used by sibling modules. + +## Agentic workflow guardrails + +- This module ships rules, not application code. Do not add Sling Models, HTL, or content here. +- Update rules with care — they apply to the whole reactor. + +## Common entry points + +{{ENTRY_POINTS}} + +## What to avoid in this module + +- Adding application code (Java, HTL, content). +- Loosening enforcement rules to make a build pass; fix the offending module instead. + +## Build + +- `{{MVN_CMD}} -pl {{MODULE_NAME}} install` diff --git a/plugins/aem/cloud-service/skills/aem-agentkit/references/templates/AGENTS.module.core.md.template b/plugins/aem/cloud-service/skills/aem-agentkit/references/templates/AGENTS.module.core.md.template new file mode 100644 index 00000000..522ebd91 --- /dev/null +++ b/plugins/aem/cloud-service/skills/aem-agentkit/references/templates/AGENTS.module.core.md.template @@ -0,0 +1,34 @@ + +# core + +OSGi bundle. Backend services, Sling Models, business logic. Built with Maven, tested with JUnit and AEM Mocks. + +## Agentic workflow guardrails + +- Search `.aem/context/osgi-services.json` before creating a service / model / servlet. +- Verify AEM class names in the Cloud Service Javadoc before importing. +- Use the project's logging style and DS annotations as derived in `.aem/context/conventions.md`. +- Update `.aem/context/osgi-services.json` after adding anything indexable. + +## Common entry points + +{{ENTRY_POINTS}} + +## Module-local conventions + +{{CONVENTIONS}} + +## What to avoid in this module + +See `.aem/context/avoid.md` for the full list with evidence pointers. + +## Where to look + +- Services and models: `.aem/context/osgi-services.json` +- Conventions: `.aem/context/conventions.md` +- Test patterns: `.aem/context/test-patterns.md` + +## Build + +- Bundle-only build + deploy: `{{MVN_CMD}} clean install -pl core -PautoInstallBundle` +- Unit tests only: `{{MVN_CMD}} -pl core test` diff --git a/plugins/aem/cloud-service/skills/aem-agentkit/references/templates/AGENTS.module.dispatcher.md.template b/plugins/aem/cloud-service/skills/aem-agentkit/references/templates/AGENTS.module.dispatcher.md.template new file mode 100644 index 00000000..2047dd63 --- /dev/null +++ b/plugins/aem/cloud-service/skills/aem-agentkit/references/templates/AGENTS.module.dispatcher.md.template @@ -0,0 +1,34 @@ + +# dispatcher + +Cloud-optimized Dispatcher configuration. Caching, security, virtual hosts. Validated locally by the Dispatcher SDK. + +Layout detected: **{{DISPATCHER_LAYOUT}}** (`{{DISPATCHER_LAYOUT_PATH}}`). + +## Agentic workflow guardrails + +- Never mutate immutable files in `dispatcher/src/conf.d/` (cloud layout). +- Customer changes go in `dispatcher/src/conf.dispatcher.d/`. +- Run `dispatcher/bin/validate.sh src` before every commit. + +## Common entry points + +{{ENTRY_POINTS}} + +## Module-local conventions + +{{CONVENTIONS}} + +## What to avoid in this module + +- Adding `allow` rules without a corresponding `deny` baseline. +- Editing under `conf.d/` (cloud layout — immutable). +- Bypassing the SDK validation step. + +## Validate + +```bash +cd dispatcher && ./bin/validate.sh src +``` + +The change is not complete until validation passes. diff --git a/plugins/aem/cloud-service/skills/aem-agentkit/references/templates/AGENTS.module.generic.md.template b/plugins/aem/cloud-service/skills/aem-agentkit/references/templates/AGENTS.module.generic.md.template new file mode 100644 index 00000000..5d383955 --- /dev/null +++ b/plugins/aem/cloud-service/skills/aem-agentkit/references/templates/AGENTS.module.generic.md.template @@ -0,0 +1,26 @@ + +# {{MODULE_NAME}} + +{{MODULE_DESCRIPTION}} + +## Agentic workflow guardrails + +- Honor the cross-cutting rules in the root `AGENTS.md`. +- Consult `.aem/context/conventions.md` before introducing new patterns. + +## Common entry points + +{{ENTRY_POINTS}} + +## Module-local conventions + +{{CONVENTIONS}} + +## What to avoid in this module + +{{AVOID_FOR_MODULE}} + +## Where to look + +- Cross-cutting conventions: `.aem/context/conventions.md` +- Indexes: `.aem/context/components.json`, `.aem/context/osgi-services.json` diff --git a/plugins/aem/cloud-service/skills/aem-agentkit/references/templates/AGENTS.module.it.tests.md.template b/plugins/aem/cloud-service/skills/aem-agentkit/references/templates/AGENTS.module.it.tests.md.template new file mode 100644 index 00000000..5e861df3 --- /dev/null +++ b/plugins/aem/cloud-service/skills/aem-agentkit/references/templates/AGENTS.module.it.tests.md.template @@ -0,0 +1,32 @@ + +# it.tests + +Integration tests against a running AEM instance. AEM Testing clients. Executed by Cloud Manager during *Custom Functional Testing*. + +## Agentic workflow guardrails + +- Match the project's test client and assertion style derived in `.aem/context/test-patterns.md`. +- No hardcoded base URLs; resolve from the testing-client configuration. +- Every side-effecting test has a teardown. + +## Common entry points + +{{ENTRY_POINTS}} + +## Module-local conventions + +{{CONVENTIONS}} + +## What to avoid in this module + +- Admin-credential dependencies. Use configured test service users. +- Flaky waits. Use the testing-client's polling primitives. + +## Run + +- All: `{{MVN_CMD}} -pl it.tests verify -Pintegration-tests` +- One class: `{{MVN_CMD}} -pl it.tests verify -Pintegration-tests -Dit.test=` + +## Where to look + +- `.aem/context/test-patterns.md` diff --git a/plugins/aem/cloud-service/skills/aem-agentkit/references/templates/AGENTS.module.ui.apps.md.template b/plugins/aem/cloud-service/skills/aem-agentkit/references/templates/AGENTS.module.ui.apps.md.template new file mode 100644 index 00000000..e012218d --- /dev/null +++ b/plugins/aem/cloud-service/skills/aem-agentkit/references/templates/AGENTS.module.ui.apps.md.template @@ -0,0 +1,34 @@ + +# ui.apps + +FileVault content package. Application code: components, templates, client libraries, content structure. HTL is the scripting engine. + +## Agentic workflow guardrails + +- Search `.aem/context/components.json` before creating a new component. +- Never write under `/libs`; use `/apps//...` overlays. +- Honor the project's HTL conventions in `.aem/context/conventions.md`. +- Update `.aem/context/components.json` after adding a component. + +## Common entry points + +{{ENTRY_POINTS}} + +## Module-local conventions + +{{CONVENTIONS}} + +## What to avoid in this module + +- HTL `data-sly-test` with redundant constant comparison (Cloud SDK lint warning). +- Hard-coded component groups; reuse the project's component-group naming. +- Mutating `/libs` paths. + +## Where to look + +- Components: `.aem/context/components.json` +- Conventions: `.aem/context/conventions.md` + +## Build + +- Content package build + deploy: `{{MVN_CMD}} clean install -pl ui.apps -PautoInstallPackage` diff --git a/plugins/aem/cloud-service/skills/aem-agentkit/references/templates/AGENTS.module.ui.frontend.md.template b/plugins/aem/cloud-service/skills/aem-agentkit/references/templates/AGENTS.module.ui.frontend.md.template new file mode 100644 index 00000000..6453a65c --- /dev/null +++ b/plugins/aem/cloud-service/skills/aem-agentkit/references/templates/AGENTS.module.ui.frontend.md.template @@ -0,0 +1,29 @@ + +# ui.frontend + +{{FRONTEND_VARIANT_DESCRIPTION}} + +## Agentic workflow guardrails + +- Do not call `/libs/*` paths from the frontend. Use `/apps//*` or the JSON Model API. +- Reuse the project's webpack and TypeScript config; do not introduce a new build chain. +- Inline `