contentstack · cs-raj · Apr 20, 2026 · Apr 19, 2026
@@ -1,16 +1,5 @@
-# Cursor rules for `contentstack-cli-tsgen`
+# Cursor (optional)
 
-This folder contains project-specific rules. Each `.mdc` file uses YAML frontmatter (`description`, `globs`, `alwaysApply`).
+**Cursor** users: start at **[AGENTS.md](../../AGENTS.md)**. All conventions live in **`skills/*/SKILL.md`**.
 
-| Rule file | `alwaysApply` | Globs | When it applies | Related skill |
-| --- | --- | --- | --- | --- |
-| [dev-workflow.mdc](dev-workflow.mdc) | No | `package.json`, `package-lock.json`, `.github/workflows/**/*`, `tsconfig.json`, `jest.config.js`, `.eslintrc.js`, `AGENTS.md` | Workflow, CI, release, package scripts | [testing](../../skills/testing/SKILL.md), [code-review](../../skills/code-review/SKILL.md) |
-| [typescript.mdc](typescript.mdc) | No | `src/**/*.ts`, `tests/**/*.ts` | TypeScript and ESLint conventions | [typescript-cli-tsgen](../../skills/typescript-cli-tsgen/SKILL.md) |
-| [oclif-tsgen.mdc](oclif-tsgen.mdc) | No | `src/commands/**`, `src/lib/**` | OCLIF command, flags, delegation to `@contentstack/types-generator` | [typescript-cli-tsgen](../../skills/typescript-cli-tsgen/SKILL.md) |
-| [testing.mdc](testing.mdc) | No | `tests/**`, `jest.config.js` | Jest and integration tests with `csdx` | [testing](../../skills/testing/SKILL.md) |
-| [code-review.mdc](code-review.mdc) | **Yes** | — | Every change | [code-review](../../skills/code-review/SKILL.md) |
-
-## Referencing rules in Cursor
-
-- Use **@** in chat (e.g. `@oclif-tsgen`, `@dev-workflow`) to pull in rule context.
-- `code-review.mdc` applies automatically (`alwaysApply: true`); others match globs or manual @-mentions.
+This folder only points contributors to **`AGENTS.md`** so editor-specific config does not duplicate the canonical docs.
@@ -3,9 +3,17 @@ fileignoreconfig:
     ignore_detectors:
       - filecontent
   - filename: package-lock.json
-    checksum: 9cf2ec1b73a078e9f3c974f1a9b7f70864f0307115d1f965b57752ba5a9dcdf2
-  - filename: .cursor/rules/oclif-tsgen.mdc
-    checksum: 83d43465e1b0d7d8c4fd3a13ca4cde13fc5ea2b578186891e3b268ede0e7d97c
+    checksum: 40cf1a77a8277c0236bdb74dee168a8ca9e0d4fc56706e0006b7ce69743319d7
   - filename: AGENTS.md
-    checksum: 7cce7645c9ebd051f971ea157fc85b691b23c963211debf31729d9ee607c081f
+    checksum: e442f35176d7263bc2ea3e7f5e112bfb4cbf6aad30f1a768d9695578b1b19636
+  - filename: skills/dev-workflow/SKILL.md
+    checksum: 036381e0d336cec14d0f83ba784f101a12ceaa9b86e486bc049e3aef0594c95b
+  - filename: skills/README.md
+    checksum: 6a74a10445c50ddebe3fae7737c04f2bc49c776ffdc8973711463c4d878e6041
+  - filename: skills/code-review/SKILL.md
+    checksum: 3cff88deeefd1fadf5714adf5657effdf5ce839a368dc71e4cb7f88db2cd7ddc
+  - filename: skills/typescript-cli-tsgen/SKILL.md
+    checksum: abbe95d052464f5d3434dd36caa7aab62cf6931f223aed70b698dc8f1aff5c28
+  - filename: skills/testing/SKILL.md
+    checksum: 6dbbb85e8eb83ebf0dda715fcd8f9c2704495ed6598a67b7222010d4c91366a5
 version: "1.0"
@@ -1,51 +1,54 @@
-# `contentstack-cli-tsgen`
+# contentstack-cli-tsgen – Agent guide
 
-**Purpose:** Contentstack CLI (**OCLIF**) plugin that adds **`csdx tsgen`** to generate TypeScript typings from a stack. Generation is delegated to the **`@contentstack/types-generator`** npm package (`generateTS` / `graphqlTS`); this repo owns the command surface (flags, auth alias, file output, CLI error formatting).
+**Universal entry point** for contributors and AI agents. Detailed conventions live in **`skills/*/SKILL.md`**.
 
-- **Repository:** [github.com/Contentstack-Solutions/contentstack-cli-tsgen](https://github.com/Contentstack-Solutions/contentstack-cli-tsgen)
-- **Homepage:** [https://github.com/Contentstack-Solutions/contentstack-cli-tsgen](https://github.com/Contentstack-Solutions/contentstack-cli-tsgen)
+## What this repo is
 
-**Library dependency (separate repo):** [`@contentstack/types-generator`](https://www.npmjs.com/package/@contentstack/types-generator) (see version in [package.json](package.json)). Source for the generator itself: [github.com/contentstack/types-generator](https://github.com/contentstack/types-generator). Do not assume a local sibling folder; treat it as an npm dependency only.
+| Field | Detail |
+| --- | --- |
+| **Name:** | [Contentstack-Solutions/contentstack-cli-tsgen](https://github.com/Contentstack-Solutions/contentstack-cli-tsgen) |
+| **Purpose:** | OCLIF plugin that adds **`csdx tsgen`** to generate TypeScript typings from a stack. Generation is delegated to **`@contentstack/types-generator`** (`generateTS` / `graphqlTS`); this repo owns flags, auth alias, file output, and CLI error formatting. |
+| **Out of scope (if any):** | Core type-generation logic belongs in **`@contentstack/types-generator`** ([npm](https://www.npmjs.com/package/@contentstack/types-generator)), not reimplemented here. |
 
-## Tech stack
+## Tech stack (at a glance)
 
 | Area | Details |
 | --- | --- |
-| Language | TypeScript **5.9** (`strict` in [tsconfig.json](tsconfig.json)) |
-| Runtime | Node (CI **18.x** / **20.x**; release **22.x**) |
-| Build | **`tsc -b`** → **`lib/`**; **`npm run prepack`** runs `tsc -b`, **`oclif manifest`**, **`oclif readme`** |
-| CLI | **OCLIF** — commands compiled to **`lib/commands`** (see `oclif.commands` in [package.json](package.json)) |
-| Tests | **Jest** + **ts-jest** ([jest.config.js](jest.config.js)) |
-| Lint | **ESLint** runs in **`posttest`** after tests ([package.json](package.json) scripts) |
+| **Language** | TypeScript **5.9** (`strict` in [tsconfig.json](tsconfig.json)) |
+| **Build** | **`tsc -b`** → **`lib/`**; **`npm run prepack`** runs compile, **`oclif manifest`**, **`oclif readme`** |
+| **Tests** | **Jest** + **ts-jest** ([jest.config.js](jest.config.js)); integration tests under `tests/integration/` |
+| **Lint / coverage** | ESLint in **`posttest`** after **`npm test`** ([package.json](package.json)) |
+| **Other** | OCLIF, Node (CI **18.x** / **20.x**; release **22.x**) |
 
 **Main dependencies:** `@contentstack/cli-command`, `@contentstack/cli-utilities`, `@contentstack/types-generator`, `dotenv`.
 
-## Source layout
-
-- **Commands:** [src/commands/](src/commands/) (e.g. `tsgen.ts`)
-- **Helpers / errors:** [src/lib/](src/lib/)
-- **Types:** [src/types/](src/types/)
-- **Build output:** **`lib/`** (not committed as source of truth; produced by `prepack`)
-
-## Common commands
+## Commands (quick reference)
 
-| Command | Purpose |
+| Command type | Command |
 | --- | --- |
-| `npm run prepack` | Clean `lib/`, compile TypeScript, generate OCLIF manifest and README |
-| `npm test` | Jest (`--testPathPattern=tests`); then **`posttest`** runs ESLint with fix |
-| `npm run test:integration` | Jest for `tests/integration` only |
+| **Build** | `npm run prepack` (canonical compile; no separate `build` script) |
+| **Test** | `npm test` (then **`posttest`** → ESLint) |
+| **Lint** | via **`posttest`** after tests |
 
-There is no dedicated `build` script; **`prepack`** is the canonical compile path. CI may run `npm run build --if-present` (no-op here if no `build` script).
+**Integration tests:** `npm run test:integration` — Jest for `tests/integration` only.
+
+CI: [.github/workflows/node.js.yml](.github/workflows/node.js.yml); release: [.github/workflows/release.yml](.github/workflows/release.yml); SCA: [.github/workflows/sca-scan.yml](.github/workflows/sca-scan.yml).
 
 ## Credentials and integration tests
 
-Integration tests spawn **`csdx tsgen`** and require a configured **delivery token alias**. Set **`TOKEN_ALIAS`** (e.g. in **`.env`** at the package root; see [tests/integration/tsgen.integration.test.ts](tests/integration/tsgen.integration.test.ts)).
+Integration tests spawn **`csdx tsgen`** and require a **delivery token alias**. Set **`TOKEN_ALIAS`** (e.g. **`.env`** at package root; see [tests/integration/tsgen.integration.test.ts](tests/integration/tsgen.integration.test.ts)). CI uses secrets such as **`REGION`**, **`TOKEN_ALIAS`**, **`APIKEY`**, **`DELIVERYKEY`**, **`ENVIRONMENT`**.
+
+## Where the documentation lives: skills
 
-CI uses GitHub secrets such as **`REGION`**, **`TOKEN_ALIAS`**, **`APIKEY`**, **`DELIVERYKEY`**, **`ENVIRONMENT`** (see [.github/workflows/node.js.yml](.github/workflows/node.js.yml)).
+| Skill | Path | What it covers |
+| --- | --- | --- |
+| Development workflow | [skills/dev-workflow/SKILL.md](skills/dev-workflow/SKILL.md) | Branches, CI, prepack, PRs, releases |
+| TypeScript CLI tsgen | [skills/typescript-cli-tsgen/SKILL.md](skills/typescript-cli-tsgen/SKILL.md) | OCLIF command, flags, delegation to the library |
+| Testing | [skills/testing/SKILL.md](skills/testing/SKILL.md) | Jest, ESLint posttest, integration env |
+| Code review | [skills/code-review/SKILL.md](skills/code-review/SKILL.md) | PR checklist, terminology, semver |
 
----
+An index with “when to use” hints is in [skills/README.md](skills/README.md).
 
-## AI guidance index
+## Using Cursor (optional)
 
-- [Cursor rules (overview)](.cursor/rules/README.md)
-- [Skills index](skills/README.md)
+If you use **Cursor**, [.cursor/rules/README.md](.cursor/rules/README.md) only points to **`AGENTS.md`**—same docs as everyone else.
@@ -1,11 +1,16 @@
-# Skills for `contentstack-cli-tsgen`
+# Skills – contentstack-cli-tsgen
 
-Use with [AGENTS.md](../AGENTS.md) and [`.cursor/rules/`](../.cursor/rules/README.md).
+Source of truth for detailed guidance. Read [AGENTS.md](../AGENTS.md) first, then open the skill that matches your task.
 
-| Skill | When to use |
+## When to use which skill
+
+| Skill folder | Use when |
 | --- | --- |
-| [code-review](code-review/SKILL.md) | PR checklist: CLI UX, errors, Delivery vs CMA wording, dependency on `@contentstack/types-generator` |
-| [testing](testing/SKILL.md) | Jest, `posttest` ESLint, integration tests, `TOKEN_ALIAS`, CI secrets |
-| [typescript-cli-tsgen](typescript-cli-tsgen/SKILL.md) | OCLIF command flow, helpers, where to change flags vs library behavior |
+| [dev-workflow](dev-workflow/SKILL.md) | Branches, CI, prepack, PR and release process |
+| [typescript-cli-tsgen](typescript-cli-tsgen/SKILL.md) | OCLIF `tsgen` command, flags, helpers vs library behavior |
+| [testing](testing/SKILL.md) | Jest, posttest ESLint, integration tests, `TOKEN_ALIAS`, CI secrets |
+| [code-review](code-review/SKILL.md) | PR checklist: CLI UX, errors, Delivery vs CMA wording, types-generator dependency |
+
+HTTP and generation internals live in **`@contentstack/types-generator`** ([npm](https://www.npmjs.com/package/@contentstack/types-generator)); do not assume a sibling checkout.
 
-There is no separate **framework** skill: HTTP and generation details belong in **`@contentstack/types-generator`** (see npm / [github.com/contentstack/types-generator](https://github.com/contentstack/types-generator)), not relative paths to another checkout.
+Each folder contains `SKILL.md` with YAML frontmatter (`name`, `description`).
@@ -5,8 +5,6 @@ description: PR review checklist for contentstack-cli-tsgen (CLI, errors, Delive
 
 # Code review skill (`contentstack-cli-tsgen`)
 
-Aligned with [`.cursor/rules/code-review.mdc`](../../.cursor/rules/code-review.mdc).
-
 ## CLI and docs
 
 - Help text, **`static examples`**, and README/oclif-generated docs stay in sync when flags or behavior change.
@@ -27,6 +25,8 @@ Aligned with [`.cursor/rules/code-review.mdc`](../../.cursor/rules/code-review.m
 ## Tests and CI
 
 - Integration tests depend on **`csdx`** and **`TOKEN_ALIAS`**; document env needs when adding cases.
+- **Backward compatibility:** Avoid breaking changes to flags, exit behavior, or output file contract without semver intent.
+- **Supply chain:** `.github/workflows/sca-scan.yml` runs Snyk on pull requests.
 
 ## Optional severity
 

@@ -0,0 +1,36 @@
+---
+name: dev-workflow
+description: Branches, prepack, CI, PR and release workflow for contentstack-cli-tsgen.
+---
+
+# Development workflow – contentstack-cli-tsgen
+
+## When to use
+
+- Running the canonical build before pack or publish
+- Understanding which branches run CI and how releases work
+
+## Branches and CI
+
+- **Node.js workflow** (`.github/workflows/node.js.yml`) runs on **push** and **pull_request** for **`master`**, **`development`**, and **`staging`**.
+- **Release** (`.github/workflows/release.yml`) runs on **push** to **`master`** (Node **22.x**), publishes npm artifact from **`lib`**, creates GitHub release.
+
+Other Contentstack repos may use **`main`** instead of **`master`**; align with team branch protection when contributing.
+
+## Build
+
+- **`npm run prepack`**: removes **`lib/`**, runs **`tsc -b`**, **`oclif manifest`**, **`oclif readme`**. This is the canonical compile before pack/publish.
+- CI runs **`prepack`** after global **`csdx`** setup and **`plugins:link`** where applicable.
+
+## Tests and lint
+
+- **`npm test`**: Jest with `--testPathPattern=tests`.
+- **`posttest`** (after `npm test`): ESLint with `.eslintrc.js` and `--fix`.
+
+## Pull requests
+
+- Run **`npm run prepack`** and **`npm test`** (which runs **`posttest`**) when changing source or tests.
+
+## Releases
+
+- Version in **`package.json`** drives publishing; release workflow builds with **`prepack`** from **`master`**.