Add AGENTS.md, skills README, and individual skill guides.

.cursor/rules/README.md

@@ -0,0 +1,5 @@
+# Cursor (optional)
+
+**Cursor** users: start at **[AGENTS.md](../../AGENTS.md)**. All conventions live in **`skills/*/SKILL.md`**.
+
+This folder only points contributors to **`AGENTS.md`** so editor-specific config does not duplicate the canonical docs.

AGENTS.md

@@ -0,0 +1,49 @@
+# Contentstack DataSync Boilerplate – Agent guide
+
+**Universal entry point** for contributors and AI agents. Detailed conventions live in **`skills/*/SKILL.md`**.
+
+## What this repo is
+
+| Field | Detail |
+|--------|--------|
+| **Name:** | [contentstack/datasync-boilerplate](https://github.com/contentstack/datasync-boilerplate) |
+| **Purpose:** | Skeleton app to run Contentstack DataSync: webhook listener, asset/content stores (filesystem or MongoDB), and `@contentstack/datasync-manager` wiring. |
+| **Out of scope (if any):** | Not a published npm library; product behavior lives in Contentstack DataSync packages (`package.json` dependencies). |
+
+## Tech stack (at a glance)
+
+| Area | Details |
+|------|---------|
+| Language | JavaScript (CommonJS), Node.js **20+** |
+| Build | npm; entry `index.js`; config under `config/` |
+| Tests | No automated test runner or `test` script in this repo |
+| Lint / coverage | ESLint (`.eslintrc.js`); no coverage tooling configured |
+| Runtime | Long-running DataSync process; `NODE_ENV` selects `config/<env>.js` when present |
+
+## Commands (quick reference)
+
+| Command type | Command |
+|--------------|---------|
+| Install | `npm install` |
+| Run (clean + start) | `npm start` |
+| Run without clean | `npm run continue` |
+| Clean synced output | `npm run clean` |
+| Lint | `npx eslint .` |
+
+**CI:** [`.github/workflows/sca-scan.yml`](.github/workflows/sca-scan.yml) (Snyk), [`.github/workflows/policy-scan.yml`](.github/workflows/policy-scan.yml), [`.github/workflows/codeql-analysis.yml`](.github/workflows/codeql-analysis.yml), [`.github/workflows/issues-jira.yml`](.github/workflows/issues-jira.yml).
+
+## Where the documentation lives: skills
+
+| Skill | Path | What it covers |
+|-------|------|----------------|
+| Dev workflow | [`skills/dev-workflow/SKILL.md`](skills/dev-workflow/SKILL.md) | Branches, CI touchpoints, npm scripts |
+| DataSync app | [`skills/datasync-boilerplate/SKILL.md`](skills/datasync-boilerplate/SKILL.md) | Entry flow, config, DataSync modules |
+| JavaScript / Node | [`skills/javascript-node/SKILL.md`](skills/javascript-node/SKILL.md) | Linting and code style for this repo |
+| Testing | [`skills/testing/SKILL.md`](skills/testing/SKILL.md) | How verification works here (no test suite) |
+| Code review | [`skills/code-review/SKILL.md`](skills/code-review/SKILL.md) | PR expectations |
+
+An index with “when to use” hints is in [`skills/README.md`](skills/README.md).
+
+## Using Cursor (optional)
+
+If you use **Cursor**, [`.cursor/rules/README.md`](.cursor/rules/README.md) only points to **`AGENTS.md`**—same docs as everyone else.

skills/README.md

@@ -0,0 +1,13 @@
+# Skills – Contentstack DataSync Boilerplate
+
+Source of truth for detailed guidance. Read [`AGENTS.md`](../AGENTS.md) first, then open the skill that matches your task.
+
+| Skill folder | Use when |
+|--------------|----------|
+| [`dev-workflow`](dev-workflow/SKILL.md) | CI, npm scripts, or repo workflow |
+| [`datasync-boilerplate`](datasync-boilerplate/SKILL.md) | `index.js`, `config/`, DataSync or Contentstack integration |
+| [`javascript-node`](javascript-node/SKILL.md) | ESLint, formatting, or JS/Node conventions |
+| [`testing`](testing/SKILL.md) | Verification, credentials, or adding tests |
+| [`code-review`](code-review/SKILL.md) | Opening or reviewing a PR |
+
+Each folder contains `SKILL.md` with YAML frontmatter (`name`, `description`).

skills/code-review/SKILL.md

@@ -0,0 +1,18 @@
+---
+name: code-review
+description: Use when authoring or reviewing pull requests for this repository.
+---
+
+# Code review – Contentstack DataSync Boilerplate
+
+## When to use
+
+- Preparing a PR or reviewing someone else’s changes
+- Ensuring security and operational expectations are met
+
+## Instructions
+
+- **Scope**: Keep changes focused; this repo is a thin composition layer over Contentstack DataSync packages—avoid unrelated refactors.
+- **Quality**: Run `npx eslint .`; ensure config edits don’t encourage committing secrets; document user-visible behavior changes in the PR description.
+- **CI**: PRs trigger Snyk, policy, CodeQL, and related workflows—fix or explain new findings.
+- **Severity (optional)**: **Blocker** — broken startup, leaked credentials, unsafe defaults; **Major** — incorrect DataSync wiring or config contract; **Minor** — style, comments, non-user-facing cleanup.

skills/datasync-boilerplate/SKILL.md

@@ -0,0 +1,19 @@
+---
+name: datasync-boilerplate
+description: Use for DataSync wiring—index.js, config, listener, asset/content stores, and Contentstack settings.
+---
+
+# DataSync boilerplate app – Contentstack DataSync Boilerplate
+
+## When to use
+
+- Editing startup, checkpoint, or plugin behavior
+- Choosing or configuring content store, asset store, or listener modules
+- Documenting or fixing integration with Contentstack delivery API / webhooks
+
+## Instructions
+
+- **Entry point**: `index.js` loads `config/all.js`, merges `config/<NODE_ENV>.js` when that file exists (else `config/development.js`), optionally reads a checkpoint file for `sync_token`, then wires `datasyncManager` with listener, asset store, and content store from **module paths in config** (`listenerModule`, `assetStoreModule`, `contentStoreModule`).
+- **Configuration**: Put stack credentials and module names in `config/`—see product docs in root [`README.md`](../../README.md) for `apiKey`, delivery token, `host`, and webhook setup (ngrok, `/notify`, publish actions).
+- **Published packages**: Behavior is implemented in `@contentstack/datasync-manager`, `@contentstack/webhook-listener`, and the filesystem/MongoDB store packages listed in `package.json`; this repo only composes them.
+- **Plugins**: Custom plugins live under `plugins/` per patterns already described in `config/all.js`.

skills/dev-workflow/SKILL.md

@@ -0,0 +1,18 @@
+---
+name: dev-workflow
+description: Use for npm scripts, GitHub Actions, branching, and day-to-day repo workflow.
+---
+
+# Dev workflow – Contentstack DataSync Boilerplate
+
+## When to use
+
+- Changing or documenting how the app is run or cleaned
+- Touching CI or security scanning behavior
+- Aligning with how PRs are validated in this repository
+
+## Instructions
+
+- **Scripts** (from `package.json`): `npm start` runs `clean` then `node index.js`; `npm run continue` runs `index.js` without cleaning; `npm run clean` runs `clean.js`.
+- **CI** (`.github/workflows/`): SCA via Snyk on PRs; policy checks (e.g. `SECURITY.md`, license) for public repos; CodeQL on PRs; Jira integration for issues. No dedicated workflow runs `npm test` (there is no test script).
+- **Dependencies**: Managed with npm; `overrides` in `package.json` pins `lodash` for supply-chain consistency—coordinate changes with security tooling expectations.

skills/javascript-node/SKILL.md

@@ -0,0 +1,17 @@
+---
+name: javascript-node
+description: Use for ESLint, formatting, and JavaScript/Node conventions in this repository.
+---
+
+# JavaScript / Node – Contentstack DataSync Boilerplate
+
+## When to use
+
+- Editing `.eslintrc.js` or fixing lint findings
+- Keeping new files consistent with existing CommonJS style
+
+## Instructions
+
+- **Lint**: Run `npx eslint .` from the repo root (no `lint` npm script). Config is [`.eslintrc.js`](../../.eslintrc.js): `eslint:recommended` plus indent, linebreak, quotes, and `semi` rules—match ESLint output and the style of files you edit.
+- **Modules**: Use CommonJS (`require` / `module.exports`) to match `index.js`, `config/`, and dependencies.
+- **Environment**: Target Node; match `ecmaVersion` / parser options to `.eslintrc.js` when changing tooling.

skills/testing/SKILL.md

@@ -0,0 +1,18 @@
+---
+name: testing
+description: Use for verification strategy, secrets handling, and any future automated tests.
+---
+
+# Testing – Contentstack DataSync Boilerplate
+
+## When to use
+
+- Checking changes before merge without a dedicated test suite
+- Deciding how to handle API tokens, webhooks, or local tunnels
+
+## Instructions
+
+- **Current state**: There is no `npm test` script or standard test directory. Rely on `npx eslint .`, manual runs (`npm start` / `npm run continue`) against non-production stacks, and CI security scans on PRs.
+- **Secrets**: Never commit real `apiKey`, delivery tokens, or checkpoint files with live tokens. Use environment-appropriate `config/*.js` or secure injection per team practice.
+- **Local integration**: Webhooks require a public URL (e.g. ngrok) and Contentstack webhook configuration—see root [`README.md`](../../README.md) prerequisites.
+- **Adding tests**: If introducing a runner, add scripts to `package.json` and document them in [`AGENTS.md`](../../AGENTS.md) and [`dev-workflow/SKILL.md`](../dev-workflow/SKILL.md).