From 6830a959d78d12a52d699ceb3c6d0f64d740b294 Mon Sep 17 00:00:00 2001
From: reeshika-h <reeshika.hosmani@contentstack.com>
Date: Mon, 6 Apr 2026 10:54:48 +0530
Subject: [PATCH 1/2] Added cursor rules and skills

---
 .cursor/rules/README.md                   | 23 +++++++++
 .cursor/rules/code-review.mdc             | 35 +++++++++++++
 .cursor/rules/contentstack-utils-java.mdc | 29 +++++++++++
 .cursor/rules/dev-workflow.md             | 36 +++++++++++++
 .cursor/rules/java.mdc                    | 44 ++++++++++++++++
 .cursor/rules/testing.mdc                 | 31 ++++++++++++
 AGENTS.md                                 | 62 +++++++++++++++++++++++
 skills/README.md                          | 21 ++++++++
 skills/code-review/SKILL.md               | 58 +++++++++++++++++++++
 skills/contentstack-utils-java/SKILL.md   | 29 +++++++++++
 skills/framework/SKILL.md                 | 52 +++++++++++++++++++
 skills/testing/SKILL.md                   | 38 ++++++++++++++
 12 files changed, 458 insertions(+)
 create mode 100644 .cursor/rules/README.md
 create mode 100644 .cursor/rules/code-review.mdc
 create mode 100644 .cursor/rules/contentstack-utils-java.mdc
 create mode 100644 .cursor/rules/dev-workflow.md
 create mode 100644 .cursor/rules/java.mdc
 create mode 100644 .cursor/rules/testing.mdc
 create mode 100644 AGENTS.md
 create mode 100644 skills/README.md
 create mode 100644 skills/code-review/SKILL.md
 create mode 100644 skills/contentstack-utils-java/SKILL.md
 create mode 100644 skills/framework/SKILL.md
 create mode 100644 skills/testing/SKILL.md

diff --git a/.cursor/rules/README.md b/.cursor/rules/README.md
new file mode 100644
index 0000000..41d1272
--- /dev/null
+++ b/.cursor/rules/README.md
@@ -0,0 +1,23 @@
+# Cursor Rules – Contentstack Utils (Java)
+
+This directory contains Cursor AI rules for **contentstack-utils-java**. Rules give persistent context so the AI follows project conventions and Contentstack RTE / embedded-item patterns.
+
+## How rules are applied
+
+- **File-specific rules** use the `globs` frontmatter: they apply when you open or edit files matching that pattern.
+- **Always-on rules** use `alwaysApply: true`: they are included in every conversation in this project.
+
+## Rule index
+
+| File | Applies when | Purpose |
+|------|--------------|---------|
+| **dev-workflow.md** | (Reference only; no glob) | Development workflow: branches, running tests, PR expectations, optional TDD. |
+| **java.mdc** | Editing any `**/*.java` file | Java 17 standards: naming, package layout under `com.contentstack.utils`, JSON/Jsoup, Javadoc, dependencies. |
+| **contentstack-utils-java.mdc** | Editing `src/main/java/**/*.java` | Utils-specific patterns: `Utils` / `GQL`, RTE and embedded JSON, `DefaultOption` / callbacks; alignment with entry JSON shapes (no HTTP client in this module). |
+| **testing.mdc** | Editing `src/test/**/*.java` | Testing patterns: JUnit 4, fixtures, JaCoCo, Surefire (including `testFailureIgnore`). |
+| **code-review.mdc** | Always | PR / review checklist: API stability, error handling, backward compatibility, dependencies and security (e.g. SCA), tests. |
+
+## Related
+
+- **AGENTS.md** (repo root) – Main entry point for AI agents: project overview, entry points, commands, pointers to rules and skills.
+- **skills/** – Reusable skill docs (`contentstack-utils-java`, `testing`, `code-review`, `framework`) for deeper guidance on specific tasks.
diff --git a/.cursor/rules/code-review.mdc b/.cursor/rules/code-review.mdc
new file mode 100644
index 0000000..ff57ffe
--- /dev/null
+++ b/.cursor/rules/code-review.mdc
@@ -0,0 +1,35 @@
+---
+description: PR and code review checklist – API stability, errors, compatibility, security, tests
+alwaysApply: true
+---
+
+# Code review checklist – Contentstack Utils (Java)
+
+Use this checklist when reviewing pull requests or before opening a PR.
+
+## API design and stability
+
+- [ ] **Public API:** New or changed public methods on `Utils`, `GQL`, `DefaultOption`, or `interfaces` are necessary, documented (Javadoc), and justified for `com.contentstack.sdk:utils` consumers.
+- [ ] **Backward compatibility:** No breaking changes unless explicitly versioned (e.g. major) and noted in `Changelog.md`.
+- [ ] **Naming:** Consistent with existing Utils style and Contentstack RTE / embedded terminology.
+
+## Error handling and robustness
+
+- [ ] **JSON safety:** Missing keys / `_embedded_items` handled predictably; no new NPEs or silent behavior changes without rationale.
+- [ ] **Null safety:** `JSONObject` / `JSONArray` access uses `opt*` / `has` patterns consistent with existing code.
+
+## Dependencies and security
+
+- [ ] **Dependencies:** New or upgraded dependencies in `pom.xml` are justified; versions do not introduce known regressions for SDK consumers.
+- [ ] **SCA:** Address security findings (e.g. Snyk on PRs, `.github/workflows/sca-scan.yml`) in scope or track with a follow-up.
+
+## Testing
+
+- [ ] **Coverage:** New or modified behavior has tests under `src/test/java/com/contentstack/utils/` and fixtures under `src/test/resources/` when needed.
+- [ ] **Surefire:** Because `testFailureIgnore` is enabled, confirm results in **`target/surefire-reports/`**, not only exit code.
+
+## Severity (optional)
+
+- **Blocker:** Must fix before merge (e.g. breaking public API without approval, critical vulnerability, no tests for new behavior).
+- **Major:** Should fix (e.g. undocumented HTML/JSON behavior change, missing Javadoc on new public API).
+- **Minor:** Nice to fix (e.g. style, typos in comments).
diff --git a/.cursor/rules/contentstack-utils-java.mdc b/.cursor/rules/contentstack-utils-java.mdc
new file mode 100644
index 0000000..21770ee
--- /dev/null
+++ b/.cursor/rules/contentstack-utils-java.mdc
@@ -0,0 +1,29 @@
+---
+description: Contentstack Utils patterns — RTE, embedded items, GraphQL JSON; no in-module HTTP client
+globs:
+  - "src/main/java/**/*.java"
+---
+
+# Contentstack Utils (Java) – SDK rules
+
+Apply when editing the Utils library. Behavior should stay aligned with [Content Delivery API](https://www.contentstack.com/docs/apis/content-delivery-api/) entry JSON and with how the [Java Delivery SDK](https://www.contentstack.com/docs/developers/sdks/content-delivery-sdk/java) fetches entries (this module does **not** perform HTTP calls itself).
+
+## Entry points
+
+- **`com.contentstack.utils.Utils`** — `render`, `renderContent`, `renderContents`, `jsonToHTML` for REST/CDA-style JSON with `_embedded_items`; dot-paths into the entry (e.g. `group.field`).
+- **`com.contentstack.utils.GQL`** — `jsonToHTML` for GraphQL-shaped responses (`embedded_itemsConnection`, `edges`, `node`, JSON RTE under `json`). Do not instantiate `GQL` (private constructor).
+
+## Rendering and options
+
+- Implement **`com.contentstack.utils.interfaces.Option`** or extend **`com.contentstack.utils.render.DefaultOption`** for custom embedded HTML, marks, and nodes.
+- Use **`com.contentstack.utils.interfaces.NodeCallback`** and metadata helpers where the codebase already does.
+- **`com.contentstack.utils.helper.Metadata`**, **`embedded.StyleType`**, **`embedded.ItemType`** classify embedded content.
+
+## Data flow
+
+- **No standalone HTTP client:** this library transforms **already-fetched** JSON. API keys, delivery tokens, and `includeEmbeddedItems()` belong to the Java SDK or app code, documented in root `README.md`.
+- Shared traversal lives in **`AutomateCommon`**; JSON RTE trees in **`NodeToHTML`**. Preserve JSON key assumptions (`_embedded_items`, HTML classes such as `embedded-entry`) unless versioning a breaking change.
+
+## Errors
+
+- Prefer null-safe `opt*` / `has` on `JSONObject` / `JSONArray` consistent with existing code.
diff --git a/.cursor/rules/dev-workflow.md b/.cursor/rules/dev-workflow.md
new file mode 100644
index 0000000..f54c747
--- /dev/null
+++ b/.cursor/rules/dev-workflow.md
@@ -0,0 +1,36 @@
+# Development workflow – Contentstack Utils (Java)
+
+Use this as the standard workflow when contributing to **contentstack-utils-java**. For Java style and test conventions, see **java.mdc** and **testing.mdc**.
+
+## Branches
+
+- Default integration for PRs is often **`staging`**; merging into **`master`** may be restricted (see `.github/workflows/check-branch.yml`).
+- Feature/fix branches often use ticket-style names (e.g. `fix/DX-5734`).
+
+## Running tests
+
+- **All tests:** `mvn test`
+- **Build only:** `mvn clean compile`
+- **Sample module** (after installing the parent JAR): `mvn -f sample/pom.xml compile` — see `sample/README.md` for credentials and env vars if using the Delivery SDK.
+
+Run tests before opening a PR. Review **`target/surefire-reports/`** if anything looks flaky (`testFailureIgnore` is set in `pom.xml`).
+
+## Pull requests
+
+- Ensure the build passes: `mvn clean test` (and sample compile if you changed `sample/`).
+- Follow the **code-review** rule (`.cursor/rules/code-review.mdc`) for the PR checklist.
+- Keep public API backward-compatible unless releasing a breaking version; update `Changelog.md` when behavior changes.
+
+## Optional: TDD
+
+If the team uses TDD, follow RED–GREEN–REFACTOR: failing test first, then implementation, then refactor. The **testing** rule and **skills/testing** describe structure and Surefire/JaCoCo behavior.
+
+## CI and security
+
+- **Java 17** in publish workflow (`.github/workflows/maven-publish.yml`).
+- **Snyk** Maven scan on PRs (`.github/workflows/sca-scan.yml`).
+- **Javadoc:** `mvn javadoc:javadoc` (optional locally); attach phase may use `-Xdoclint:none` per `pom.xml`.
+
+## Lint / format
+
+- No Checkstyle/Spotless in repo — match existing style in surrounding files.
diff --git a/.cursor/rules/java.mdc b/.cursor/rules/java.mdc
new file mode 100644
index 0000000..8dd08ff
--- /dev/null
+++ b/.cursor/rules/java.mdc
@@ -0,0 +1,44 @@
+---
+description: Java 17 and com.contentstack.utils conventions for the Utils SDK
+globs:
+  - "**/*.java"
+---
+
+# Java standards – Contentstack Utils (Java)
+
+Apply these conventions when editing Java code in this repository.
+
+## Language and runtime
+
+- **Java 17** via `maven-compiler-plugin` `<release>17</release>` in `pom.xml`. Ignore legacy `maven.compiler.source/target` `1.8` properties; the compiler plugin is authoritative.
+- Avoid raw types; use proper generics where applicable.
+
+## Package and layout
+
+- Production code lives under **`com.contentstack.utils`** and subpackages (`render`, `node`, `embedded`, `helper`, `interfaces`).
+- Keep the existing package structure; do not introduce new top-level packages without team alignment.
+
+## Naming
+
+- **Classes:** PascalCase (e.g. `Utils`, `DefaultOption`, `AutomateCommon`).
+- **Methods / variables:** camelCase.
+- **Test classes:** Mix of `*Tests`, `*Test`, `Test*` already in use (see **testing.mdc**).
+
+## JSON and HTML
+
+- Prefer **`org.json`** (`JSONObject`, `JSONArray`) for public APIs and internals, consistent with `Utils` and `GQL`.
+- Use **Jsoup** for RTE HTML parsing; follow patterns in `AutomateCommon` and `Utils`.
+
+## Validation and utility types
+
+- `javax.validation.constraints` (e.g. `@NotNull`) appear on some public methods; keep Javadoc aligned with actual null behavior.
+- Hide construction with private constructors where the codebase already does (e.g. `GQL`, `AutomateCommon`).
+
+## Dependencies
+
+- This artifact is a small JAR (`com.contentstack.sdk:utils`) consumed by the Contentstack Java SDK. Prefer minimal, well-scoped dependencies; justify new ones in `pom.xml`.
+- This repo does **not** use Lombok; do not introduce it without an explicit team decision.
+
+## General
+
+- Document public API with Javadoc; keep examples in line with real usage (`Utils.render`, `GQL.jsonToHTML`, `DefaultOption`).
diff --git a/.cursor/rules/testing.mdc b/.cursor/rules/testing.mdc
new file mode 100644
index 0000000..4cbc6fe
--- /dev/null
+++ b/.cursor/rules/testing.mdc
@@ -0,0 +1,31 @@
+---
+description: JUnit 4 testing patterns, fixtures, Surefire, JaCoCo for contentstack-utils-java
+globs:
+  - "src/test/**/*.java"
+---
+
+# Testing rules – Contentstack Utils (Java)
+
+Apply when writing or editing tests. The project uses **JUnit 4** and **JaCoCo** (see `pom.xml`).
+
+## Test naming and layout
+
+- **Unit tests** use class names such as `UtilTests`, `DefaultOptionTests`, `AssetLinkTest`, `TestRte`, `TestMetadata`, or prefixes/suffixes `Test*`, `*Test`, `*Tests`. Place code under `src/test/java/com/contentstack/utils/` (mirror of main).
+- There is **no** separate `*IT` integration suite in this repo; all tests are standard Maven Surefire tests. Optional **`sample/`** may use the Delivery SDK with env vars (see `sample/README.md`).
+
+## JUnit 4 usage
+
+- Use **`org.junit.Test`**, **`Assert`**, **`@BeforeClass`**, **`@FixMethodOrder`** where appropriate (match surrounding test class style).
+
+## Fixtures and data
+
+- JSON fixtures live under **`src/test/resources/`** (e.g. `multiple_rich_text_content.json`, `reports/`). Load via paths relative to the module root or classpath as existing tests do (`ReadResource`, `UtilTests`).
+- Keep tests **offline** — no API keys or network required for default unit tests.
+
+## Surefire
+
+- **`testFailureIgnore`** is set to **`true`** in `pom.xml`. Always check **`target/surefire-reports/`** when investigating failures; do not rely only on Maven’s exit code.
+
+## Coverage
+
+- **JaCoCo** runs on `test`; reports under **`target/site/jacoco/`**. Maintain or improve coverage when changing production code in `Utils`, `GQL`, or `AutomateCommon`.
diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..426a8b3
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,62 @@
+# Contentstack Utils (Java) – Agent guide
+
+This document is the main entry point for AI agents working in **contentstack-utils-java**. Repo: [contentstack-utils-java](https://github.com/contentstack/contentstack-utils-java).
+
+## Project
+
+- **Name:** Contentstack Utils (Java) — Maven artifact `com.contentstack.sdk:utils`.
+- **Purpose:** Library for **rendering Rich Text Editor (RTE) content and embedded items** from Contentstack entry JSON (REST/CDA-style with `_embedded_items`) and GraphQL-shaped responses. It does **not** perform HTTP calls or manage API keys; use it with the [Contentstack Java Delivery SDK](https://www.contentstack.com/docs/developers/sdks/content-delivery-sdk/java) after fetching entries.
+
+## Tech stack
+
+- **Language:** Java **17** (`maven-compiler-plugin` `<release>17</release>` in `pom.xml`).
+- **Build:** Maven.
+- **Testing:** JUnit 4, Maven Surefire, JaCoCo (see `pom.xml`; Surefire uses `testFailureIgnore`).
+- **JSON / HTML:** `org.json`, Jsoup, `commons-text`; `javax.validation` API; `spring-web` is a compile dependency (not a public HTTP client surface for this module).
+
+## Main entry points
+
+- **`Contentstack.stack(...)`** — Not in this repo; provided by the Java SDK (see root `README.md`).
+- **`com.contentstack.utils.Utils`** — `render`, `renderContent`, `jsonToHTML`, variant helpers, etc.
+- **`com.contentstack.utils.GQL`** — GraphQL entry `jsonToHTML`.
+- **`com.contentstack.utils.render.DefaultOption`** / **`interfaces.Option`** — custom RTE/embedded rendering.
+- **Paths:** `src/main/java/com/contentstack/utils/` (production), `src/test/java/com/contentstack/utils/` (tests). Optional **`sample/`** demonstrates Delivery SDK + Utils together.
+
+## Commands
+
+- **Build and test:** `mvn clean test`
+- **Compile only:** `mvn clean compile`
+- **Single test class:** `mvn test -Dtest=UtilTests`
+- **Javadoc (optional):** `mvn javadoc:javadoc`
+
+CI uses Java **17** (`.github/workflows/maven-publish.yml`). **Snyk** runs on PRs (`.github/workflows/sca-scan.yml`).
+
+## Rules and skills
+
+### `.cursor/rules/`
+
+| Resource | Role |
+|----------|------|
+| **README.md** | Index of all rules and when they apply |
+| **dev-workflow.md** | Branches, tests, PRs, optional TDD |
+| **java.mdc** | Applies to `**/*.java`: Java 17, `com.contentstack.utils`, JSON/Jsoup |
+| **contentstack-utils-java.mdc** | Applies to `src/main/java/**/*.java`: Utils/GQL, RTE, embedded JSON |
+| **testing.mdc** | Applies to `src/test/**/*.java`: JUnit 4, fixtures, JaCoCo |
+| **code-review.mdc** | Always applied: PR checklist |
+
+### `skills/`
+
+| Skill | Use when |
+|-------|----------|
+| **contentstack-utils-java** | Changing RTE, embedded items, `Utils` / `GQL`, `DefaultOption`, callbacks |
+| **testing** | Adding or refactoring tests and fixtures |
+| **code-review** | Reviewing PRs or pre-merge self-review |
+| **framework** | Editing `pom.xml`, plugins, publishing, or `sample/` dependency management |
+
+See **`skills/README.md`** for details. For editor-wide Cursor user skills (if configured), this repo’s project skills live only under **`./skills/`**.
+
+## Official documentation
+
+- [Contentstack Developers](https://www.contentstack.com/docs/)
+- [Content Delivery API](https://www.contentstack.com/docs/apis/content-delivery-api/)
+- Root **`README.md`** — Maven coordinates and embedded-items examples
diff --git a/skills/README.md b/skills/README.md
new file mode 100644
index 0000000..71a65d2
--- /dev/null
+++ b/skills/README.md
@@ -0,0 +1,21 @@
+# Skills – Contentstack Utils (Java)
+
+This directory contains **skills**: reusable guidance for AI agents (and developers) on specific tasks. Each skill is a folder with a `SKILL.md` file (YAML frontmatter: `name`, `description`).
+
+## When to use which skill
+
+| Skill | Use when |
+|-------|----------|
+| **contentstack-utils-java** | Implementing or changing RTE/embedded behavior: `Utils`, `GQL`, `DefaultOption`, callbacks, JSON shapes for CDA/GraphQL entries. |
+| **testing** | Writing or refactoring tests: JUnit 4, fixtures, Surefire, JaCoCo, offline unit tests. |
+| **code-review** | Reviewing a PR or preparing your own: API stability, compatibility, dependencies/security, tests. |
+| **framework** | Changing `pom.xml`, Java release level, plugins (Surefire, JaCoCo, javadoc, GPG, Central publishing), or sample module dependency management. |
+
+## How agents should use skills
+
+- **contentstack-utils-java:** Apply when editing `src/main/java/com/contentstack/utils/**` or adding RTE/embedded-related behavior. Follow existing JSON/HTML contracts and public API rules.
+- **testing:** Apply when creating or modifying `src/test/**`. Respect `testFailureIgnore` and JaCoCo layout.
+- **code-review:** Apply when simulating or performing a PR review; use the checklist and optional severity levels.
+- **framework:** Apply when touching build or release tooling; keep consumer impact (Java SDK) in mind.
+
+Each skill’s `SKILL.md` contains more detail and cross-links to `.cursor/rules/`.
diff --git a/skills/code-review/SKILL.md b/skills/code-review/SKILL.md
new file mode 100644
index 0000000..2ac7e1f
--- /dev/null
+++ b/skills/code-review/SKILL.md
@@ -0,0 +1,58 @@
+---
+name: code-review
+description: Use when reviewing PRs or before opening a PR — API design, compatibility, dependencies, security, tests
+---
+
+# Code review – Contentstack Utils (Java)
+
+Use this skill when performing or preparing a pull request review for this repository.
+
+## When to use
+
+- Reviewing another contributor’s PR.
+- Self-review before submission.
+- Verifying changes meet API, compatibility, security, and test standards.
+
+## Instructions
+
+Work through the checklist below. Optionally tag items with **Blocker**, **Major**, or **Minor**.
+
+### 1. API design and stability
+
+- [ ] **Public API:** New or changed public surface on `Utils`, `GQL`, `DefaultOption`, or `interfaces` is documented and justified for Maven consumers.
+- [ ] **Backward compatibility:** Breaking changes only with version/changelog alignment.
+- [ ] **Naming:** Consistent with existing Utils and RTE terminology.
+
+**Severity:** Unapproved breaking API change = Blocker. Missing Javadoc on new public API = Major.
+
+### 2. Robustness
+
+- [ ] **JSON:** No unintended behavior change for `_embedded_items` / GraphQL shapes without tests and release notes.
+- [ ] **HTML output:** Customer-visible markup changes are documented.
+
+**Severity:** Silent breaking HTML/JSON behavior = Major.
+
+### 3. Dependencies and security
+
+- [ ] **Dependencies:** Version bumps in `pom.xml` are intentional; consider Snyk/SCA.
+- [ ] **SCA:** Address or defer security findings with a ticket.
+
+**Severity:** New critical/high CVE in scope = Blocker.
+
+### 4. Testing
+
+- [ ] **Coverage:** New logic has tests; Surefire reports reviewed when using global `testFailureIgnore`.
+- [ ] **Quality:** Tests are deterministic and assert meaningful behavior.
+
+**Severity:** No tests for new behavior = Blocker.
+
+### 5. Optional severity summary
+
+- **Blocker:** Breaking API without approval, security issue, missing tests for new code.
+- **Major:** Missing docs, risky dependency bump, unclear JSON/HTML behavior.
+- **Minor:** Style, typos, minor refactors.
+
+## References
+
+- Project rule: `.cursor/rules/code-review.mdc`
+- Testing skill: `skills/testing/SKILL.md`
diff --git a/skills/contentstack-utils-java/SKILL.md b/skills/contentstack-utils-java/SKILL.md
new file mode 100644
index 0000000..d2d43c1
--- /dev/null
+++ b/skills/contentstack-utils-java/SKILL.md
@@ -0,0 +1,29 @@
+---
+name: contentstack-utils-java
+description: Use when implementing RTE, embedded items, Utils/GQL, DefaultOption — JSON shapes and no HTTP client in-module
+---
+
+# Contentstack Utils (Java) – skill
+
+Use this skill when changing **`Utils`**, **`GQL`**, **`DefaultOption`**, callbacks, or embedded/RTE behavior in this repository.
+
+## Scope
+
+This artifact (`com.contentstack.sdk:utils`) **renders** RTE and embedded content from JSON already obtained from Contentstack. **Authentication, stack keys, delivery tokens, and `includeEmbeddedItems()`** are handled by the **[Contentstack Java SDK](https://www.contentstack.com/docs/developers/sdks/content-delivery-sdk/java)** (or your own HTTP layer), not by this repo.
+
+## Core types
+
+- **`com.contentstack.utils.Utils`** — `render`, `renderContent`, `renderContents`, `jsonToHTML` (CDA-style JSON with `_embedded_items`).
+- **`com.contentstack.utils.GQL`** — `jsonToHTML` for GraphQL entry shapes.
+- **`com.contentstack.utils.render.DefaultOption`** / **`interfaces.Option`** — custom rendering; see root `README.md`.
+- **`com.contentstack.utils.helper.Metadata`** — embedded metadata.
+
+## JSON contracts
+
+- REST: `_embedded_items`; RTE HTML classes such as `embedded-entry`, `embedded-asset`.
+- GraphQL: `embedded_itemsConnection`, `edges`, `node`, `uid` matching metadata.
+
+## References
+
+- Project rule: `.cursor/rules/contentstack-utils-java.mdc`
+- Root `README.md` for usage with `Contentstack.stack`, `Entry`, `Query`.
diff --git a/skills/framework/SKILL.md b/skills/framework/SKILL.md
new file mode 100644
index 0000000..1eefc07
--- /dev/null
+++ b/skills/framework/SKILL.md
@@ -0,0 +1,52 @@
+---
+name: framework
+description: Use when changing Maven build, Java release, plugins, publishing, or dependency hygiene
+---
+
+# Framework (build & tooling) – Contentstack Utils (Java)
+
+Use this skill when editing **`pom.xml`**, CI-related Maven config, or release/publishing behavior — analogous to HTTP/config layers in the Java CDA SDK repo, but here the “framework” is **Maven**, **JaCoCo**, **Surefire**, and **Central publishing**.
+
+## Build commands
+
+```bash
+mvn clean compile
+mvn test
+mvn package
+```
+
+Local install without GPG/Javadoc (common for dev):
+
+```bash
+mvn install -DskipTests -Dmaven.javadoc.skip=true -Dgpg.skip=true
+```
+
+## Java version
+
+- **`maven-compiler-plugin`** — **`<release>17</release>`**. Align local JDK and CI (`.github/workflows/maven-publish.yml`) with **Java 17**.
+
+## Key plugins
+
+| Plugin | Role |
+|--------|------|
+| `maven-surefire-plugin` | Runs JUnit; note `testFailureIgnore` |
+| `jacoco-maven-plugin` | Coverage; `target/site/jacoco/` |
+| `maven-javadoc-plugin` | Javadoc JAR (`-Xdoclint:none` in execution) |
+| `central-publishing-maven-plugin` | Maven Central on release |
+| `maven-gpg-plugin` | Signs artifacts for release |
+
+## Coordinates
+
+- **groupId:** `com.contentstack.sdk`
+- **artifactId:** `utils`
+- **version:** from root `pom.xml`
+
+## Dependency hygiene
+
+- Minimal dependencies; this JAR is consumed by the Contentstack Java SDK.
+- **Snyk** on PRs: `.github/workflows/sca-scan.yml`.
+- **`sample/pom.xml`:** Keep `contentstack.utils.version` aligned with the root version when bumping releases; use `dependencyManagement` for transitive CVE overrides as needed.
+
+## Formatting
+
+- No repo-wide Checkstyle/Spotless — match existing style.
diff --git a/skills/testing/SKILL.md b/skills/testing/SKILL.md
new file mode 100644
index 0000000..b67b040
--- /dev/null
+++ b/skills/testing/SKILL.md
@@ -0,0 +1,38 @@
+---
+name: testing
+description: Use when adding or refactoring tests — JUnit 4, fixtures, Surefire testFailureIgnore, JaCoCo
+---
+
+# Testing – Contentstack Utils (Java)
+
+Use this skill when creating or modifying test classes under `src/test/java` or fixtures under `src/test/resources`.
+
+## Framework
+
+- **JUnit 4** (`junit:junit` in `pom.xml`).
+- **Maven Surefire** runs tests from `src/test/java`.
+
+## Surefire
+
+`pom.xml` sets **`testFailureIgnore`** to **`true`**. Check **`target/surefire-reports/`**; a green Maven exit code does not guarantee all tests passed.
+
+## Naming and layout
+
+- Mirror package **`com.contentstack.utils`**; examples: `UtilTests`, `DefaultOptionTests`, `AssetLinkTest`, `TestRte`.
+- Helpers: `ReadResource`, `DefaultOptionClass`, etc.
+
+## Fixtures
+
+- JSON under **`src/test/resources/`**. Paths are often relative to the module root (see `UtilTests`).
+
+## Coverage
+
+- **JaCoCo** — report at **`target/site/jacoco/index.html`** after `mvn test`.
+
+## Credentials
+
+- Default unit tests are **offline**. The **`sample/`** project may require stack env vars — see `sample/README.md`.
+
+## References
+
+- Project rule: `.cursor/rules/testing.mdc`

From 8ed862a0e07e317c4750c3fdabd8b498d25a76d0 Mon Sep 17 00:00:00 2001
From: reeshika-h <reeshika.hosmani@contentstack.com>
Date: Mon, 6 Apr 2026 12:34:57 +0530
Subject: [PATCH 2/2] Refactored agent.md and skills

---
 .cursor/rules/README.md                   | 24 +------
 .cursor/rules/code-review.mdc             | 35 ---------
 .cursor/rules/contentstack-utils-java.mdc | 29 --------
 .cursor/rules/dev-workflow.md             | 36 ----------
 .cursor/rules/java.mdc                    | 44 ------------
 .cursor/rules/testing.mdc                 | 31 --------
 AGENTS.md                                 | 87 ++++++++++-------------
 skills/README.md                          | 25 +++----
 skills/code-review/SKILL.md               | 61 +++++++---------
 skills/contentstack-utils-java/SKILL.md   | 45 ++++++++----
 skills/dev-workflow/SKILL.md              | 52 ++++++++++++++
 skills/framework/SKILL.md                 | 48 ++++++++-----
 skills/java/SKILL.md                      | 54 ++++++++++++++
 skills/testing/SKILL.md                   | 43 ++++++-----
 14 files changed, 270 insertions(+), 344 deletions(-)
 delete mode 100644 .cursor/rules/code-review.mdc
 delete mode 100644 .cursor/rules/contentstack-utils-java.mdc
 delete mode 100644 .cursor/rules/dev-workflow.md
 delete mode 100644 .cursor/rules/java.mdc
 delete mode 100644 .cursor/rules/testing.mdc
 create mode 100644 skills/dev-workflow/SKILL.md
 create mode 100644 skills/java/SKILL.md

diff --git a/.cursor/rules/README.md b/.cursor/rules/README.md
index 41d1272..f5c1f87 100644
--- a/.cursor/rules/README.md
+++ b/.cursor/rules/README.md
@@ -1,23 +1,5 @@
-# Cursor Rules – Contentstack Utils (Java)
+# Cursor (optional)
 
-This directory contains Cursor AI rules for **contentstack-utils-java**. Rules give persistent context so the AI follows project conventions and Contentstack RTE / embedded-item patterns.
+**Cursor** users: start at **[AGENTS.md](../../AGENTS.md)**. All conventions live in **`skills/*/SKILL.md`**.
 
-## How rules are applied
-
-- **File-specific rules** use the `globs` frontmatter: they apply when you open or edit files matching that pattern.
-- **Always-on rules** use `alwaysApply: true`: they are included in every conversation in this project.
-
-## Rule index
-
-| File | Applies when | Purpose |
-|------|--------------|---------|
-| **dev-workflow.md** | (Reference only; no glob) | Development workflow: branches, running tests, PR expectations, optional TDD. |
-| **java.mdc** | Editing any `**/*.java` file | Java 17 standards: naming, package layout under `com.contentstack.utils`, JSON/Jsoup, Javadoc, dependencies. |
-| **contentstack-utils-java.mdc** | Editing `src/main/java/**/*.java` | Utils-specific patterns: `Utils` / `GQL`, RTE and embedded JSON, `DefaultOption` / callbacks; alignment with entry JSON shapes (no HTTP client in this module). |
-| **testing.mdc** | Editing `src/test/**/*.java` | Testing patterns: JUnit 4, fixtures, JaCoCo, Surefire (including `testFailureIgnore`). |
-| **code-review.mdc** | Always | PR / review checklist: API stability, error handling, backward compatibility, dependencies and security (e.g. SCA), tests. |
-
-## Related
-
-- **AGENTS.md** (repo root) – Main entry point for AI agents: project overview, entry points, commands, pointers to rules and skills.
-- **skills/** – Reusable skill docs (`contentstack-utils-java`, `testing`, `code-review`, `framework`) for deeper guidance on specific tasks.
+This folder only points contributors to **`AGENTS.md`** so editor-specific config does not duplicate the canonical docs.
diff --git a/.cursor/rules/code-review.mdc b/.cursor/rules/code-review.mdc
deleted file mode 100644
index ff57ffe..0000000
--- a/.cursor/rules/code-review.mdc
+++ /dev/null
@@ -1,35 +0,0 @@
----
-description: PR and code review checklist – API stability, errors, compatibility, security, tests
-alwaysApply: true
----
-
-# Code review checklist – Contentstack Utils (Java)
-
-Use this checklist when reviewing pull requests or before opening a PR.
-
-## API design and stability
-
-- [ ] **Public API:** New or changed public methods on `Utils`, `GQL`, `DefaultOption`, or `interfaces` are necessary, documented (Javadoc), and justified for `com.contentstack.sdk:utils` consumers.
-- [ ] **Backward compatibility:** No breaking changes unless explicitly versioned (e.g. major) and noted in `Changelog.md`.
-- [ ] **Naming:** Consistent with existing Utils style and Contentstack RTE / embedded terminology.
-
-## Error handling and robustness
-
-- [ ] **JSON safety:** Missing keys / `_embedded_items` handled predictably; no new NPEs or silent behavior changes without rationale.
-- [ ] **Null safety:** `JSONObject` / `JSONArray` access uses `opt*` / `has` patterns consistent with existing code.
-
-## Dependencies and security
-
-- [ ] **Dependencies:** New or upgraded dependencies in `pom.xml` are justified; versions do not introduce known regressions for SDK consumers.
-- [ ] **SCA:** Address security findings (e.g. Snyk on PRs, `.github/workflows/sca-scan.yml`) in scope or track with a follow-up.
-
-## Testing
-
-- [ ] **Coverage:** New or modified behavior has tests under `src/test/java/com/contentstack/utils/` and fixtures under `src/test/resources/` when needed.
-- [ ] **Surefire:** Because `testFailureIgnore` is enabled, confirm results in **`target/surefire-reports/`**, not only exit code.
-
-## Severity (optional)
-
-- **Blocker:** Must fix before merge (e.g. breaking public API without approval, critical vulnerability, no tests for new behavior).
-- **Major:** Should fix (e.g. undocumented HTML/JSON behavior change, missing Javadoc on new public API).
-- **Minor:** Nice to fix (e.g. style, typos in comments).
diff --git a/.cursor/rules/contentstack-utils-java.mdc b/.cursor/rules/contentstack-utils-java.mdc
deleted file mode 100644
index 21770ee..0000000
--- a/.cursor/rules/contentstack-utils-java.mdc
+++ /dev/null
@@ -1,29 +0,0 @@
----
-description: Contentstack Utils patterns — RTE, embedded items, GraphQL JSON; no in-module HTTP client
-globs:
-  - "src/main/java/**/*.java"
----
-
-# Contentstack Utils (Java) – SDK rules
-
-Apply when editing the Utils library. Behavior should stay aligned with [Content Delivery API](https://www.contentstack.com/docs/apis/content-delivery-api/) entry JSON and with how the [Java Delivery SDK](https://www.contentstack.com/docs/developers/sdks/content-delivery-sdk/java) fetches entries (this module does **not** perform HTTP calls itself).
-
-## Entry points
-
-- **`com.contentstack.utils.Utils`** — `render`, `renderContent`, `renderContents`, `jsonToHTML` for REST/CDA-style JSON with `_embedded_items`; dot-paths into the entry (e.g. `group.field`).
-- **`com.contentstack.utils.GQL`** — `jsonToHTML` for GraphQL-shaped responses (`embedded_itemsConnection`, `edges`, `node`, JSON RTE under `json`). Do not instantiate `GQL` (private constructor).
-
-## Rendering and options
-
-- Implement **`com.contentstack.utils.interfaces.Option`** or extend **`com.contentstack.utils.render.DefaultOption`** for custom embedded HTML, marks, and nodes.
-- Use **`com.contentstack.utils.interfaces.NodeCallback`** and metadata helpers where the codebase already does.
-- **`com.contentstack.utils.helper.Metadata`**, **`embedded.StyleType`**, **`embedded.ItemType`** classify embedded content.
-
-## Data flow
-
-- **No standalone HTTP client:** this library transforms **already-fetched** JSON. API keys, delivery tokens, and `includeEmbeddedItems()` belong to the Java SDK or app code, documented in root `README.md`.
-- Shared traversal lives in **`AutomateCommon`**; JSON RTE trees in **`NodeToHTML`**. Preserve JSON key assumptions (`_embedded_items`, HTML classes such as `embedded-entry`) unless versioning a breaking change.
-
-## Errors
-
-- Prefer null-safe `opt*` / `has` on `JSONObject` / `JSONArray` consistent with existing code.
diff --git a/.cursor/rules/dev-workflow.md b/.cursor/rules/dev-workflow.md
deleted file mode 100644
index f54c747..0000000
--- a/.cursor/rules/dev-workflow.md
+++ /dev/null
@@ -1,36 +0,0 @@
-# Development workflow – Contentstack Utils (Java)
-
-Use this as the standard workflow when contributing to **contentstack-utils-java**. For Java style and test conventions, see **java.mdc** and **testing.mdc**.
-
-## Branches
-
-- Default integration for PRs is often **`staging`**; merging into **`master`** may be restricted (see `.github/workflows/check-branch.yml`).
-- Feature/fix branches often use ticket-style names (e.g. `fix/DX-5734`).
-
-## Running tests
-
-- **All tests:** `mvn test`
-- **Build only:** `mvn clean compile`
-- **Sample module** (after installing the parent JAR): `mvn -f sample/pom.xml compile` — see `sample/README.md` for credentials and env vars if using the Delivery SDK.
-
-Run tests before opening a PR. Review **`target/surefire-reports/`** if anything looks flaky (`testFailureIgnore` is set in `pom.xml`).
-
-## Pull requests
-
-- Ensure the build passes: `mvn clean test` (and sample compile if you changed `sample/`).
-- Follow the **code-review** rule (`.cursor/rules/code-review.mdc`) for the PR checklist.
-- Keep public API backward-compatible unless releasing a breaking version; update `Changelog.md` when behavior changes.
-
-## Optional: TDD
-
-If the team uses TDD, follow RED–GREEN–REFACTOR: failing test first, then implementation, then refactor. The **testing** rule and **skills/testing** describe structure and Surefire/JaCoCo behavior.
-
-## CI and security
-
-- **Java 17** in publish workflow (`.github/workflows/maven-publish.yml`).
-- **Snyk** Maven scan on PRs (`.github/workflows/sca-scan.yml`).
-- **Javadoc:** `mvn javadoc:javadoc` (optional locally); attach phase may use `-Xdoclint:none` per `pom.xml`.
-
-## Lint / format
-
-- No Checkstyle/Spotless in repo — match existing style in surrounding files.
diff --git a/.cursor/rules/java.mdc b/.cursor/rules/java.mdc
deleted file mode 100644
index 8dd08ff..0000000
--- a/.cursor/rules/java.mdc
+++ /dev/null
@@ -1,44 +0,0 @@
----
-description: Java 17 and com.contentstack.utils conventions for the Utils SDK
-globs:
-  - "**/*.java"
----
-
-# Java standards – Contentstack Utils (Java)
-
-Apply these conventions when editing Java code in this repository.
-
-## Language and runtime
-
-- **Java 17** via `maven-compiler-plugin` `<release>17</release>` in `pom.xml`. Ignore legacy `maven.compiler.source/target` `1.8` properties; the compiler plugin is authoritative.
-- Avoid raw types; use proper generics where applicable.
-
-## Package and layout
-
-- Production code lives under **`com.contentstack.utils`** and subpackages (`render`, `node`, `embedded`, `helper`, `interfaces`).
-- Keep the existing package structure; do not introduce new top-level packages without team alignment.
-
-## Naming
-
-- **Classes:** PascalCase (e.g. `Utils`, `DefaultOption`, `AutomateCommon`).
-- **Methods / variables:** camelCase.
-- **Test classes:** Mix of `*Tests`, `*Test`, `Test*` already in use (see **testing.mdc**).
-
-## JSON and HTML
-
-- Prefer **`org.json`** (`JSONObject`, `JSONArray`) for public APIs and internals, consistent with `Utils` and `GQL`.
-- Use **Jsoup** for RTE HTML parsing; follow patterns in `AutomateCommon` and `Utils`.
-
-## Validation and utility types
-
-- `javax.validation.constraints` (e.g. `@NotNull`) appear on some public methods; keep Javadoc aligned with actual null behavior.
-- Hide construction with private constructors where the codebase already does (e.g. `GQL`, `AutomateCommon`).
-
-## Dependencies
-
-- This artifact is a small JAR (`com.contentstack.sdk:utils`) consumed by the Contentstack Java SDK. Prefer minimal, well-scoped dependencies; justify new ones in `pom.xml`.
-- This repo does **not** use Lombok; do not introduce it without an explicit team decision.
-
-## General
-
-- Document public API with Javadoc; keep examples in line with real usage (`Utils.render`, `GQL.jsonToHTML`, `DefaultOption`).
diff --git a/.cursor/rules/testing.mdc b/.cursor/rules/testing.mdc
deleted file mode 100644
index 4cbc6fe..0000000
--- a/.cursor/rules/testing.mdc
+++ /dev/null
@@ -1,31 +0,0 @@
----
-description: JUnit 4 testing patterns, fixtures, Surefire, JaCoCo for contentstack-utils-java
-globs:
-  - "src/test/**/*.java"
----
-
-# Testing rules – Contentstack Utils (Java)
-
-Apply when writing or editing tests. The project uses **JUnit 4** and **JaCoCo** (see `pom.xml`).
-
-## Test naming and layout
-
-- **Unit tests** use class names such as `UtilTests`, `DefaultOptionTests`, `AssetLinkTest`, `TestRte`, `TestMetadata`, or prefixes/suffixes `Test*`, `*Test`, `*Tests`. Place code under `src/test/java/com/contentstack/utils/` (mirror of main).
-- There is **no** separate `*IT` integration suite in this repo; all tests are standard Maven Surefire tests. Optional **`sample/`** may use the Delivery SDK with env vars (see `sample/README.md`).
-
-## JUnit 4 usage
-
-- Use **`org.junit.Test`**, **`Assert`**, **`@BeforeClass`**, **`@FixMethodOrder`** where appropriate (match surrounding test class style).
-
-## Fixtures and data
-
-- JSON fixtures live under **`src/test/resources/`** (e.g. `multiple_rich_text_content.json`, `reports/`). Load via paths relative to the module root or classpath as existing tests do (`ReadResource`, `UtilTests`).
-- Keep tests **offline** — no API keys or network required for default unit tests.
-
-## Surefire
-
-- **`testFailureIgnore`** is set to **`true`** in `pom.xml`. Always check **`target/surefire-reports/`** when investigating failures; do not rely only on Maven’s exit code.
-
-## Coverage
-
-- **JaCoCo** runs on `test`; reports under **`target/site/jacoco/`**. Maintain or improve coverage when changing production code in `Utils`, `GQL`, or `AutomateCommon`.
diff --git a/AGENTS.md b/AGENTS.md
index 426a8b3..95bc73e 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -1,62 +1,53 @@
 # Contentstack Utils (Java) – Agent guide
 
-This document is the main entry point for AI agents working in **contentstack-utils-java**. Repo: [contentstack-utils-java](https://github.com/contentstack/contentstack-utils-java).
+**Universal entry point** for contributors and AI agents. Detailed conventions live in **`skills/*/SKILL.md`**.
 
-## Project
+## What this repo is
 
-- **Name:** Contentstack Utils (Java) — Maven artifact `com.contentstack.sdk:utils`.
-- **Purpose:** Library for **rendering Rich Text Editor (RTE) content and embedded items** from Contentstack entry JSON (REST/CDA-style with `_embedded_items`) and GraphQL-shaped responses. It does **not** perform HTTP calls or manage API keys; use it with the [Contentstack Java Delivery SDK](https://www.contentstack.com/docs/developers/sdks/content-delivery-sdk/java) after fetching entries.
+| Field | Detail |
+|--------|--------|
+| **Name:** | [contentstack-utils-java](https://github.com/contentstack/contentstack-utils-java) — Maven `com.contentstack.sdk:utils` |
+| **Purpose:** | Library for rendering **Rich Text Editor (RTE)** content and **embedded items** from Contentstack entry JSON (REST/CDA-style with `_embedded_items`) and GraphQL-shaped responses. Consumed by the [Contentstack Java Delivery SDK](https://www.contentstack.com/docs/developers/sdks/content-delivery-sdk/java) and apps that already hold entry JSON. |
+| **Out of scope (if any):** | **No HTTP client** in this package: no stack API calls, tokens, or `includeEmbeddedItems()` — those belong to the Delivery SDK or your app. Optional **`sample/`** wires the SDK + Utils for manual testing only. |
 
-## Tech stack
+## Tech stack (at a glance)
 
-- **Language:** Java **17** (`maven-compiler-plugin` `<release>17</release>` in `pom.xml`).
-- **Build:** Maven.
-- **Testing:** JUnit 4, Maven Surefire, JaCoCo (see `pom.xml`; Surefire uses `testFailureIgnore`).
-- **JSON / HTML:** `org.json`, Jsoup, `commons-text`; `javax.validation` API; `spring-web` is a compile dependency (not a public HTTP client surface for this module).
+| Area | Details |
+|------|---------|
+| **Language** | Java **17** — `maven-compiler-plugin` `<release>17</release>` in root `pom.xml` (legacy `1.8` properties in `pom.xml` are not authoritative). |
+| **Build** | **Maven** — root `pom.xml`; optional module `sample/pom.xml`. |
+| **Tests** | **JUnit 4**, Maven **Surefire** (`src/test/java/com/contentstack/utils/**/*.java`). Surefire **`testFailureIgnore`** is `true` — check `target/surefire-reports/`. |
+| **Lint / coverage** | No Checkstyle/Spotless in repo — match existing style. **JaCoCo** (`target/site/jacoco/` after `mvn test`). |
+| **Other** | JSON: `org.json`, `json-simple` (provided). HTML: **Jsoup**. `spring-web` compile dependency — not a public REST client API for this module. **Snyk** on PRs (`.github/workflows/sca-scan.yml`). |
 
-## Main entry points
+## Commands (quick reference)
 
-- **`Contentstack.stack(...)`** — Not in this repo; provided by the Java SDK (see root `README.md`).
-- **`com.contentstack.utils.Utils`** — `render`, `renderContent`, `jsonToHTML`, variant helpers, etc.
-- **`com.contentstack.utils.GQL`** — GraphQL entry `jsonToHTML`.
-- **`com.contentstack.utils.render.DefaultOption`** / **`interfaces.Option`** — custom RTE/embedded rendering.
-- **Paths:** `src/main/java/com/contentstack/utils/` (production), `src/test/java/com/contentstack/utils/` (tests). Optional **`sample/`** demonstrates Delivery SDK + Utils together.
+| Command type | Command |
+|--------------|---------|
+| **Build** | `mvn clean compile` |
+| **Test** | `mvn clean test` |
+| **Lint** | *(none configured — rely on IDE and code review)* |
 
-## Commands
+| Optional | Command / location |
+|----------|---------------------|
+| Single test class | `mvn test -Dtest=UtilTests` |
+| Javadoc | `mvn javadoc:javadoc` |
+| Sample (after `mvn install` with skips if needed) | `mvn -f sample/pom.xml compile` |
+| **CI** | Java **17** publish: `.github/workflows/maven-publish.yml` · SCA: `.github/workflows/sca-scan.yml` · branch rules: `.github/workflows/check-branch.yml` |
 
-- **Build and test:** `mvn clean test`
-- **Compile only:** `mvn clean compile`
-- **Single test class:** `mvn test -Dtest=UtilTests`
-- **Javadoc (optional):** `mvn javadoc:javadoc`
+## Where the documentation lives: skills
 
-CI uses Java **17** (`.github/workflows/maven-publish.yml`). **Snyk** runs on PRs (`.github/workflows/sca-scan.yml`).
+| Skill | Path | What it covers |
+|-------|------|----------------|
+| **Development workflow** | [`skills/dev-workflow/SKILL.md`](skills/dev-workflow/SKILL.md) | Branches, CI, build/test commands, PR expectations, optional TDD. |
+| **Java (language & layout)** | [`skills/java/SKILL.md`](skills/java/SKILL.md) | Java 17, `com.contentstack.utils` packages, naming, JSON/Jsoup, dependencies. |
+| **Contentstack Utils API** | [`skills/contentstack-utils-java/SKILL.md`](skills/contentstack-utils-java/SKILL.md) | Public API: `Utils`, `GQL`, `DefaultOption`, JSON contracts, RTE/embedded boundaries. |
+| **Testing** | [`skills/testing/SKILL.md`](skills/testing/SKILL.md) | JUnit 4, fixtures, Surefire/JaCoCo, offline tests vs `sample/`. |
+| **Code review** | [`skills/code-review/SKILL.md`](skills/code-review/SKILL.md) | PR checklist, optional Blocker/Major/Minor. |
+| **Framework (build & tooling)** | [`skills/framework/SKILL.md`](skills/framework/SKILL.md) | Maven plugins, publishing, GPG, Central, `sample/` dependency hygiene. |
 
-## Rules and skills
+An index with **when to use** hints is in [`skills/README.md`](skills/README.md).
 
-### `.cursor/rules/`
+## Using Cursor (optional)
 
-| Resource | Role |
-|----------|------|
-| **README.md** | Index of all rules and when they apply |
-| **dev-workflow.md** | Branches, tests, PRs, optional TDD |
-| **java.mdc** | Applies to `**/*.java`: Java 17, `com.contentstack.utils`, JSON/Jsoup |
-| **contentstack-utils-java.mdc** | Applies to `src/main/java/**/*.java`: Utils/GQL, RTE, embedded JSON |
-| **testing.mdc** | Applies to `src/test/**/*.java`: JUnit 4, fixtures, JaCoCo |
-| **code-review.mdc** | Always applied: PR checklist |
-
-### `skills/`
-
-| Skill | Use when |
-|-------|----------|
-| **contentstack-utils-java** | Changing RTE, embedded items, `Utils` / `GQL`, `DefaultOption`, callbacks |
-| **testing** | Adding or refactoring tests and fixtures |
-| **code-review** | Reviewing PRs or pre-merge self-review |
-| **framework** | Editing `pom.xml`, plugins, publishing, or `sample/` dependency management |
-
-See **`skills/README.md`** for details. For editor-wide Cursor user skills (if configured), this repo’s project skills live only under **`./skills/`**.
-
-## Official documentation
-
-- [Contentstack Developers](https://www.contentstack.com/docs/)
-- [Content Delivery API](https://www.contentstack.com/docs/apis/content-delivery-api/)
-- Root **`README.md`** — Maven coordinates and embedded-items examples
+If you use **Cursor**, [`.cursor/rules/README.md`](.cursor/rules/README.md) only points to **`AGENTS.md`** — same docs as everyone else.
diff --git a/skills/README.md b/skills/README.md
index 71a65d2..c6774a7 100644
--- a/skills/README.md
+++ b/skills/README.md
@@ -1,21 +1,16 @@
 # Skills – Contentstack Utils (Java)
 
-This directory contains **skills**: reusable guidance for AI agents (and developers) on specific tasks. Each skill is a folder with a `SKILL.md` file (YAML frontmatter: `name`, `description`).
+Source of truth for detailed guidance. Read **`AGENTS.md`** first, then open the skill that matches your task.
 
 ## When to use which skill
 
-| Skill | Use when |
-|-------|----------|
-| **contentstack-utils-java** | Implementing or changing RTE/embedded behavior: `Utils`, `GQL`, `DefaultOption`, callbacks, JSON shapes for CDA/GraphQL entries. |
-| **testing** | Writing or refactoring tests: JUnit 4, fixtures, Surefire, JaCoCo, offline unit tests. |
-| **code-review** | Reviewing a PR or preparing your own: API stability, compatibility, dependencies/security, tests. |
-| **framework** | Changing `pom.xml`, Java release level, plugins (Surefire, JaCoCo, javadoc, GPG, Central publishing), or sample module dependency management. |
+| Skill folder | Use when |
+|--------------|----------|
+| **dev-workflow** | Branches, CI, how to run build/test, PR expectations, optional TDD. |
+| **java** | Java 17 conventions, package layout under `com.contentstack.utils`, JSON/Jsoup, Javadoc, dependency discipline. |
+| **contentstack-utils-java** | Changing `Utils`, `GQL`, `DefaultOption`, callbacks, embedded/RTE behavior or JSON contracts. |
+| **testing** | Writing or refactoring tests, fixtures, Surefire/JaCoCo, offline tests. |
+| **code-review** | Reviewing a PR or self-review before merge. |
+| **framework** | Editing `pom.xml`, plugins, release signing, Maven Central, or `sample/` dependency versions. |
 
-## How agents should use skills
-
-- **contentstack-utils-java:** Apply when editing `src/main/java/com/contentstack/utils/**` or adding RTE/embedded-related behavior. Follow existing JSON/HTML contracts and public API rules.
-- **testing:** Apply when creating or modifying `src/test/**`. Respect `testFailureIgnore` and JaCoCo layout.
-- **code-review:** Apply when simulating or performing a PR review; use the checklist and optional severity levels.
-- **framework:** Apply when touching build or release tooling; keep consumer impact (Java SDK) in mind.
-
-Each skill’s `SKILL.md` contains more detail and cross-links to `.cursor/rules/`.
+Each folder contains **`SKILL.md`** with YAML frontmatter (`name`, `description`).
diff --git a/skills/code-review/SKILL.md b/skills/code-review/SKILL.md
index 2ac7e1f..8f3e938 100644
--- a/skills/code-review/SKILL.md
+++ b/skills/code-review/SKILL.md
@@ -1,58 +1,49 @@
 ---
 name: code-review
-description: Use when reviewing PRs or before opening a PR — API design, compatibility, dependencies, security, tests
+description: PR checklist and optional Blocker/Major/Minor — use when reviewing or before submitting a PR
 ---
 
 # Code review – Contentstack Utils (Java)
 
-Use this skill when performing or preparing a pull request review for this repository.
-
 ## When to use
 
-- Reviewing another contributor’s PR.
-- Self-review before submission.
-- Verifying changes meet API, compatibility, security, and test standards.
+- Reviewing another contributor’s pull request.
+- Self-review before merge.
+- Auditing API, security, or test coverage for a change set.
 
 ## Instructions
 
-Work through the checklist below. Optionally tag items with **Blocker**, **Major**, or **Minor**.
-
-### 1. API design and stability
-
-- [ ] **Public API:** New or changed public surface on `Utils`, `GQL`, `DefaultOption`, or `interfaces` is documented and justified for Maven consumers.
-- [ ] **Backward compatibility:** Breaking changes only with version/changelog alignment.
-- [ ] **Naming:** Consistent with existing Utils and RTE terminology.
-
-**Severity:** Unapproved breaking API change = Blocker. Missing Javadoc on new public API = Major.
-
-### 2. Robustness
-
-- [ ] **JSON:** No unintended behavior change for `_embedded_items` / GraphQL shapes without tests and release notes.
-- [ ] **HTML output:** Customer-visible markup changes are documented.
+### API design and stability
 
-**Severity:** Silent breaking HTML/JSON behavior = Major.
+- [ ] **Public API:** New or changed methods on `Utils`, `GQL`, `DefaultOption`, or `interfaces` are necessary, Javadoc’d, and safe for `com.contentstack.sdk:utils` consumers.
+- [ ] **Backward compatibility:** Breaking changes only with major version / **`Changelog.md`** plan.
+- [ ] **Naming:** Consistent with existing Utils and RTE/embedded terminology.
 
-### 3. Dependencies and security
+### Error handling and robustness
 
-- [ ] **Dependencies:** Version bumps in `pom.xml` are intentional; consider Snyk/SCA.
-- [ ] **SCA:** Address or defer security findings with a ticket.
+- [ ] **JSON:** Missing keys / `_embedded_items` behave predictably; no accidental NPEs or silent semantic changes.
+- [ ] **Null safety:** `JSONObject` / `JSONArray` access follows existing `opt*` / `has` patterns.
 
-**Severity:** New critical/high CVE in scope = Blocker.
+### Dependencies and security
 
-### 4. Testing
+- [ ] **Dependencies:** `pom.xml` changes are justified; consider downstream Java SDK consumers.
+- [ ] **SCA:** Snyk / team process (`.github/workflows/sca-scan.yml`) — address or defer with a ticket.
 
-- [ ] **Coverage:** New logic has tests; Surefire reports reviewed when using global `testFailureIgnore`.
-- [ ] **Quality:** Tests are deterministic and assert meaningful behavior.
+### Testing
 
-**Severity:** No tests for new behavior = Blocker.
+- [ ] **Coverage:** New behavior has tests and fixtures under `src/test/java` / `src/test/resources` as needed.
+- [ ] **Surefire:** With `testFailureIgnore`, verify **`target/surefire-reports/`**, not only exit code.
 
-### 5. Optional severity summary
+### Severity (optional)
 
-- **Blocker:** Breaking API without approval, security issue, missing tests for new code.
-- **Major:** Missing docs, risky dependency bump, unclear JSON/HTML behavior.
-- **Minor:** Style, typos, minor refactors.
+| Level | Examples |
+|-------|----------|
+| **Blocker** | Unapproved breaking public API; critical CVE; no tests for new behavior. |
+| **Major** | Undocumented HTML/JSON behavior change; missing Javadoc on new public API; risky dependency bump. |
+| **Minor** | Style, typos, internal refactor with equivalent coverage. |
 
 ## References
 
-- Project rule: `.cursor/rules/code-review.mdc`
-- Testing skill: `skills/testing/SKILL.md`
+- **`skills/testing/SKILL.md`** — test conventions and Surefire.
+- **`skills/contentstack-utils-java/SKILL.md`** — API boundaries.
+- **`AGENTS.md`** — stack and commands.
diff --git a/skills/contentstack-utils-java/SKILL.md b/skills/contentstack-utils-java/SKILL.md
index d2d43c1..d5973b2 100644
--- a/skills/contentstack-utils-java/SKILL.md
+++ b/skills/contentstack-utils-java/SKILL.md
@@ -1,29 +1,44 @@
 ---
 name: contentstack-utils-java
-description: Use when implementing RTE, embedded items, Utils/GQL, DefaultOption — JSON shapes and no HTTP client in-module
+description: Public API — Utils, GQL, DefaultOption, RTE/embedded JSON; use when changing SDK behavior or contracts
 ---
 
-# Contentstack Utils (Java) – skill
+# Contentstack Utils API – Contentstack Utils (Java)
 
-Use this skill when changing **`Utils`**, **`GQL`**, **`DefaultOption`**, callbacks, or embedded/RTE behavior in this repository.
+## When to use
 
-## Scope
+- Changing **`Utils`**, **`GQL`**, **`DefaultOption`**, **`Option`**, callbacks, or embedded/RTE logic.
+- Reviewing JSON shape assumptions for CDA or GraphQL responses.
 
-This artifact (`com.contentstack.sdk:utils`) **renders** RTE and embedded content from JSON already obtained from Contentstack. **Authentication, stack keys, delivery tokens, and `includeEmbeddedItems()`** are handled by the **[Contentstack Java SDK](https://www.contentstack.com/docs/developers/sdks/content-delivery-sdk/java)** (or your own HTTP layer), not by this repo.
+## Instructions
 
-## Core types
+### Scope
 
-- **`com.contentstack.utils.Utils`** — `render`, `renderContent`, `renderContents`, `jsonToHTML` (CDA-style JSON with `_embedded_items`).
-- **`com.contentstack.utils.GQL`** — `jsonToHTML` for GraphQL entry shapes.
-- **`com.contentstack.utils.render.DefaultOption`** / **`interfaces.Option`** — custom rendering; see root `README.md`.
-- **`com.contentstack.utils.helper.Metadata`** — embedded metadata.
+- Artifact **`com.contentstack.sdk:utils`** only **transforms** JSON that apps or the [Java Delivery SDK](https://www.contentstack.com/docs/developers/sdks/content-delivery-sdk/java) already fetched.
+- **Authentication, API keys, delivery tokens, and `includeEmbeddedItems()`** are out of scope here — handled by the SDK or app code.
 
-## JSON contracts
+### Entry points
 
-- REST: `_embedded_items`; RTE HTML classes such as `embedded-entry`, `embedded-asset`.
-- GraphQL: `embedded_itemsConnection`, `edges`, `node`, `uid` matching metadata.
+- **`com.contentstack.utils.Utils`** — `render`, `renderContent`, `renderContents`, `jsonToHTML` for REST/CDA-style JSON with `_embedded_items`; dot-paths into entries (e.g. `group.field`). Variant-related helpers as documented in `Utils`.
+- **`com.contentstack.utils.GQL`** — `jsonToHTML` for GraphQL-shaped entries (`embedded_itemsConnection`, `edges`, `node`, JSON RTE under `json`). Do not instantiate `GQL` (private constructor).
+
+### Rendering and options
+
+- Implement **`com.contentstack.utils.interfaces.Option`** or extend **`com.contentstack.utils.render.DefaultOption`** for custom embedded HTML, marks, and nodes.
+- Use **`com.contentstack.utils.interfaces.NodeCallback`** and **`com.contentstack.utils.helper.Metadata`** with **`embedded.StyleType`** / **`embedded.ItemType`** as in existing code.
+
+### Data flow and compatibility
+
+- Shared traversal: **`AutomateCommon`**; JSON RTE trees: **`NodeToHTML`**.
+- Preserve keys and HTML class names (`_embedded_items`, `embedded-entry`, etc.) unless shipping a **breaking** version with changelog.
+- Prefer null-safe **`opt*`** / **`has`** on `JSONObject` / `JSONArray`.
+
+### Alignment with Contentstack
+
+- Entry JSON shapes align with the [Content Delivery API](https://www.contentstack.com/docs/apis/content-delivery-api/) as consumed by the Java SDK; root **`README.md`** shows `Contentstack.stack`, `Entry`, `Query` usage **outside** this JAR.
 
 ## References
 
-- Project rule: `.cursor/rules/contentstack-utils-java.mdc`
-- Root `README.md` for usage with `Contentstack.stack`, `Entry`, `Query`.
+- **`skills/java/SKILL.md`** — language and package conventions.
+- **`skills/testing/SKILL.md`** — tests for API changes.
+- Root **`README.md`** — Maven coordinates and embedded-items examples.
diff --git a/skills/dev-workflow/SKILL.md b/skills/dev-workflow/SKILL.md
new file mode 100644
index 0000000..3a988df
--- /dev/null
+++ b/skills/dev-workflow/SKILL.md
@@ -0,0 +1,52 @@
+---
+name: dev-workflow
+description: Branches, CI, build and test commands, PR expectations, optional TDD — use when onboarding or before a PR
+---
+
+# Development workflow – Contentstack Utils (Java)
+
+## When to use
+
+- Starting work in this repository or onboarding.
+- Before opening or updating a pull request.
+- You need the canonical commands for build, test, sample, and CI pointers.
+
+## Instructions
+
+### Branches
+
+- Default integration for PRs is often **`staging`**; merging into **`master`** may be restricted (see `.github/workflows/check-branch.yml`).
+- Feature/fix branches often use ticket-style names (e.g. `fix/DX-5734`).
+
+### Running tests and builds
+
+- **All tests:** `mvn test`
+- **Compile only:** `mvn clean compile`
+- **Full check before PR:** `mvn clean test` (and `mvn -f sample/pom.xml compile` if you changed `sample/` — install parent first; see `skills/framework/SKILL.md`).
+- Review **`target/surefire-reports/`** when debugging: **`testFailureIgnore`** is `true` in `pom.xml` (see `skills/testing/SKILL.md`).
+
+### Pull requests
+
+- Describe the change; link issues/tickets when applicable.
+- Keep public API backward-compatible unless releasing a breaking version; update **`Changelog.md`** for user-visible behavior.
+- Use **`skills/code-review/SKILL.md`** as the review checklist.
+
+### Optional: TDD
+
+- If the team uses TDD: RED → GREEN → REFACTOR. Structure and Surefire behavior are in **`skills/testing/SKILL.md`**.
+
+### CI and security
+
+- **Java 17** in `.github/workflows/maven-publish.yml`.
+- **Snyk** Maven scan on PRs: `.github/workflows/sca-scan.yml`.
+- **Javadoc:** optional locally `mvn javadoc:javadoc`; attach phase uses `-Xdoclint:none` per `pom.xml`.
+
+### Lint / format
+
+- No repo-wide Checkstyle/Spotless — match existing style (`skills/java/SKILL.md`).
+
+## References
+
+- **`skills/testing/SKILL.md`** — Surefire, JaCoCo, fixtures.
+- **`skills/framework/SKILL.md`** — Maven install skips, publishing, `sample/pom.xml`.
+- **`AGENTS.md`** — commands quick reference.
diff --git a/skills/framework/SKILL.md b/skills/framework/SKILL.md
index 1eefc07..43d679f 100644
--- a/skills/framework/SKILL.md
+++ b/skills/framework/SKILL.md
@@ -1,13 +1,19 @@
 ---
 name: framework
-description: Use when changing Maven build, Java release, plugins, publishing, or dependency hygiene
+description: Maven, plugins, Java 17, publishing, sample module deps — use when editing pom.xml or release tooling
 ---
 
 # Framework (build & tooling) – Contentstack Utils (Java)
 
-Use this skill when editing **`pom.xml`**, CI-related Maven config, or release/publishing behavior — analogous to HTTP/config layers in the Java CDA SDK repo, but here the “framework” is **Maven**, **JaCoCo**, **Surefire**, and **Central publishing**.
+## When to use
 
-## Build commands
+- Editing root **`pom.xml`** or **`sample/pom.xml`**.
+- Changing release/publish flow, signing, or CI-related Maven settings.
+- Aligning **`sample/`** `contentstack.utils.version` with a new library release.
+
+## Instructions
+
+### Build commands
 
 ```bash
 mvn clean compile
@@ -15,38 +21,44 @@ mvn test
 mvn package
 ```
 
-Local install without GPG/Javadoc (common for dev):
+Local install without GPG/Javadoc (common for dev before `sample/`):
 
 ```bash
 mvn install -DskipTests -Dmaven.javadoc.skip=true -Dgpg.skip=true
 ```
 
-## Java version
+### Java version
 
-- **`maven-compiler-plugin`** — **`<release>17</release>`**. Align local JDK and CI (`.github/workflows/maven-publish.yml`) with **Java 17**.
+- **`maven-compiler-plugin`** — **`<release>17</release>`**. Match **Java 17** locally and in `.github/workflows/maven-publish.yml`.
 
-## Key plugins
+### Key plugins (root `pom.xml`)
 
 | Plugin | Role |
 |--------|------|
 | `maven-surefire-plugin` | Runs JUnit; note `testFailureIgnore` |
-| `jacoco-maven-plugin` | Coverage; `target/site/jacoco/` |
-| `maven-javadoc-plugin` | Javadoc JAR (`-Xdoclint:none` in execution) |
-| `central-publishing-maven-plugin` | Maven Central on release |
-| `maven-gpg-plugin` | Signs artifacts for release |
+| `jacoco-maven-plugin` | Coverage → `target/site/jacoco/` |
+| `maven-javadoc-plugin` | Javadoc JAR; `-Xdoclint:none` in execution |
+| `central-publishing-maven-plugin` | Maven Central publishing |
+| `maven-gpg-plugin` | Signs artifacts on release |
 
-## Coordinates
+### Coordinates
 
 - **groupId:** `com.contentstack.sdk`
 - **artifactId:** `utils`
-- **version:** from root `pom.xml`
+- **version:** root `pom.xml` `<version>`
 
-## Dependency hygiene
+### Dependency hygiene
 
-- Minimal dependencies; this JAR is consumed by the Contentstack Java SDK.
+- Keep the dependency set small; this JAR is pulled in by the Contentstack Java SDK.
 - **Snyk** on PRs: `.github/workflows/sca-scan.yml`.
-- **`sample/pom.xml`:** Keep `contentstack.utils.version` aligned with the root version when bumping releases; use `dependencyManagement` for transitive CVE overrides as needed.
+- **`sample/pom.xml`:** Keep **`contentstack.utils.version`** in sync when bumping the root version; use **`dependencyManagement`** for transitive CVE overrides when needed.
+
+### Formatting
+
+- No Checkstyle/Spotless — match surrounding code (`skills/java/SKILL.md`).
 
-## Formatting
+## References
 
-- No repo-wide Checkstyle/Spotless — match existing style.
+- **`skills/dev-workflow/SKILL.md`** — when to run full build/test.
+- **`skills/testing/SKILL.md`** — Surefire/JaCoCo behavior.
+- **`AGENTS.md`** — CI file pointers.
diff --git a/skills/java/SKILL.md b/skills/java/SKILL.md
new file mode 100644
index 0000000..494e745
--- /dev/null
+++ b/skills/java/SKILL.md
@@ -0,0 +1,54 @@
+---
+name: java
+description: Java 17, package layout, naming, JSON/Jsoup, Javadoc — use when editing any production or test Java in this repo
+---
+
+# Java – Contentstack Utils (Java)
+
+## When to use
+
+- Editing any `.java` file under this repository.
+- Adding dependencies or debating style vs other Contentstack SDKs.
+
+## Instructions
+
+### Language and runtime
+
+- **Java 17** via `maven-compiler-plugin` `<release>17</release>` in `pom.xml`. Ignore legacy `maven.compiler.source/target` `1.8` — the compiler plugin wins.
+- Avoid raw types; use generics where applicable.
+
+### Package and layout
+
+- Production code lives under **`com.contentstack.utils`** and subpackages: `render`, `node`, `embedded`, `helper`, `interfaces`.
+- Do not add new top-level packages without team alignment.
+
+### Naming
+
+- **Classes:** PascalCase (`Utils`, `DefaultOption`, `AutomateCommon`).
+- **Methods / variables:** camelCase.
+- **Tests:** Mixed conventions already in use — see **`skills/testing/SKILL.md`**.
+
+### JSON and HTML
+
+- Prefer **`org.json`** (`JSONObject`, `JSONArray`) for APIs and internals used by `Utils` and `GQL`.
+- Use **Jsoup** for RTE HTML; follow patterns in `AutomateCommon` and `Utils`.
+
+### Validation and utility types
+
+- `javax.validation.constraints` (e.g. `@NotNull`) on some public methods — keep Javadoc aligned with null behavior.
+- Private constructors for non-instantiable types where the codebase already does (`GQL`, `AutomateCommon`).
+
+### Dependencies
+
+- Small JAR consumed by the Contentstack Java SDK — prefer minimal dependencies; justify additions in `pom.xml`.
+- **No Lombok** in this repo unless explicitly adopted by the team.
+
+### Documentation
+
+- Javadoc on public API; examples must match real entry points (`Utils.render`, `GQL.jsonToHTML`, `DefaultOption`).
+
+## References
+
+- **`skills/contentstack-utils-java/SKILL.md`** — RTE, embedded, GraphQL shapes.
+- **`skills/testing/SKILL.md`** — test naming and layout.
+- **`AGENTS.md`** — tech stack summary.
diff --git a/skills/testing/SKILL.md b/skills/testing/SKILL.md
index b67b040..d2dc2d7 100644
--- a/skills/testing/SKILL.md
+++ b/skills/testing/SKILL.md
@@ -1,38 +1,47 @@
 ---
 name: testing
-description: Use when adding or refactoring tests — JUnit 4, fixtures, Surefire testFailureIgnore, JaCoCo
+description: JUnit 4, Surefire, JaCoCo, fixtures, offline policy — use when adding or changing tests
 ---
 
 # Testing – Contentstack Utils (Java)
 
-Use this skill when creating or modifying test classes under `src/test/java` or fixtures under `src/test/resources`.
+## When to use
 
-## Framework
+- Creating or editing tests under `src/test/java/com/contentstack/utils/`.
+- Adding JSON under `src/test/resources/`.
+- Investigating CI failures or coverage gaps.
 
-- **JUnit 4** (`junit:junit` in `pom.xml`).
-- **Maven Surefire** runs tests from `src/test/java`.
+## Instructions
 
-## Surefire
+### Framework
 
-`pom.xml` sets **`testFailureIgnore`** to **`true`**. Check **`target/surefire-reports/`**; a green Maven exit code does not guarantee all tests passed.
+- **JUnit 4** (`junit:junit`, test scope in `pom.xml`).
+- **Maven Surefire** runs classes from `src/test/java`.
 
-## Naming and layout
+### Surefire caveat
 
-- Mirror package **`com.contentstack.utils`**; examples: `UtilTests`, `DefaultOptionTests`, `AssetLinkTest`, `TestRte`.
-- Helpers: `ReadResource`, `DefaultOptionClass`, etc.
+- **`testFailureIgnore`** is **`true`** in `pom.xml`. Always inspect **`target/surefire-reports/`** — a successful Maven exit code does not guarantee all tests passed.
 
-## Fixtures
+### Naming and layout
 
-- JSON under **`src/test/resources/`**. Paths are often relative to the module root (see `UtilTests`).
+- Mirror package **`com.contentstack.utils`**.
+- Existing patterns: `UtilTests`, `DefaultOptionTests`, `AssetLinkTest`, `TestRte`, `TestMetadata`, `Test*`, `*Test`, `*Tests`.
+- No separate `*IT` Maven profile in this repo; optional **`sample/`** uses the Delivery SDK with env vars (see `sample/README.md`).
 
-## Coverage
+### Fixtures
 
-- **JaCoCo** — report at **`target/site/jacoco/index.html`** after `mvn test`.
+- JSON and assets under **`src/test/resources/`** (e.g. `multiple_rich_text_content.json`, `reports/`). Loading patterns: `ReadResource`, `UtilTests` `@BeforeClass`.
 
-## Credentials
+### Helpers
 
-- Default unit tests are **offline**. The **`sample/`** project may require stack env vars — see `sample/README.md`.
+- `ReadResource`, `DefaultOptionClass`, and similar helpers — keep tests **deterministic** and **offline** (no live API for default unit tests).
+
+### Coverage
+
+- **JaCoCo** on `mvn test`; HTML report **`target/site/jacoco/index.html`**.
 
 ## References
 
-- Project rule: `.cursor/rules/testing.mdc`
+- **`skills/dev-workflow/SKILL.md`** — when to run tests before PRs.
+- **`skills/framework/SKILL.md`** — Maven/Surefire configuration.
+- **`skills/code-review/SKILL.md`** — test expectations for reviews.