contentstack · sunil-lakshman · Apr 7, 2026
@@ -0,0 +1,5 @@
+# Cursor (optional)
+
+**Cursor** users: start at the repo root **[`AGENTS.md`](../../AGENTS.md)**. All conventions live in **`skills/*/SKILL.md`** (universal for any editor or tool).
+
+This folder only points contributors here so nothing editor-specific duplicates the canonical docs.
@@ -0,0 +1,49 @@
+# Contentstack PHP SDK – Agent guide
+
+**Universal entry point** for anyone automating or assisting work in this repo—AI agents (Cursor, Copilot, CLI tools), reviewers, and contributors. Conventions and detailed guidance live in **`skills/*/SKILL.md`**, not in editor-specific config, so the same instructions apply whether or not you use Cursor.
+
+## What this repo is
+
+- **Name:** [contentstack-php](https://github.com/contentstack/contentstack-php)
+- **Purpose:** PHP library for the Contentstack **Delivery API**—stack initialization, content types, entries, assets, queries, sync, live preview config, and RTE rendering via the optional **`contentstack/utils`** package.
+- **Out of scope:** This package is not the Management API client; it focuses on read/delivery patterns documented in the SDK README.
+
+## Tech stack (at a glance)
+
+| Area | Details |
+|------|---------|
+| Language | PHP (see `composer.json` `require.php`; supports legacy 5.5+ per package) |
+| Layout | PSR-4 `Contentstack\` → `src/`; helper `src/Support/helper.php` |
+| Tests | PHPUnit 10 → `test/` (`phpunit.xml`) |
+| Docs | Doctum → `composer run generate:docs` (`config.php`) |
+| Dependency | `contentstack/utils` for `Utils`, `Option`, RTE rendering helpers |
+
+## Commands (quick reference)
+
+```bash
+composer install
+composer test
+# or: vendor/bin/phpunit
+composer run generate:docs
+```
+
+Coverage and reports (when configured in `phpunit.xml`) write under `./tmp/`.
+
+## Where the real documentation lives: skills
+
+Read these **`SKILL.md` files** for full conventions—**this is the source of truth** for implementation and review:
+
+| Skill | Path | What it covers |
+|-------|------|----------------|
+| **Development workflow** | [`skills/dev-workflow/SKILL.md`](skills/dev-workflow/SKILL.md) | Branches, CI expectations, Composer test/docs, PR notes |
+| **Contentstack PHP SDK / Utils** | [`skills/contentstack-utils/SKILL.md`](skills/contentstack-utils/SKILL.md) | `Contentstack::Stack`, `Stack`, queries, entries, assets, regions, `contentstack/utils`, semver |
+| **PHP style & repo layout** | [`skills/php-style/SKILL.md`](skills/php-style/SKILL.md) | PSR-4, namespaces, docblocks, `src/` layout, PHP version constraints |
+| **Testing** | [`skills/testing/SKILL.md`](skills/testing/SKILL.md) | PHPUnit, `test/` layout, constants/helpers, credentials hygiene |
+| **Code review** | [`skills/code-review/SKILL.md`](skills/code-review/SKILL.md) | PR checklist (API, errors, deps/SCA, tests), Blocker/Major/Minor |
+| **Framework / build** | [`skills/framework/SKILL.md`](skills/framework/SKILL.md) | `composer.json`, autoload, Doctum, optional CI workflows |
+
+An index with short “when to use” hints is in [`skills/README.md`](skills/README.md).
+
+## Using Cursor
+
+If you use **Cursor**, [`.cursor/rules/README.md`](.cursor/rules/README.md) only points to **`AGENTS.md`**—same source of truth as everyone else; no separate `.mdc` rule files.
@@ -0,0 +1,19 @@
+# Skills – Contentstack PHP SDK
+
+**This directory is the source of truth** for conventions (workflow, SDK API, style, tests, review, build). Read **`AGENTS.md`** at the repo root for the index and quick commands; each skill is a folder with **`SKILL.md`** (YAML frontmatter: `name`, `description`).
+
+## When to use which skill
+
+| Skill folder | Use when |
+|--------------|----------|
+| **dev-workflow** | Branches, `composer test` / docs, GitHub workflows, PR expectations |
+| **contentstack-utils** | `Contentstack`, `Stack`, queries, entries, assets, sync, Composer `contentstack/utils` |
+| **php-style** | PSR-4, namespaces, docblocks, `src/` structure, PHP compatibility |
+| **testing** | PHPUnit, `test/` helpers, offline vs live tests, secrets |
+| **code-review** | PR checklist, Blocker/Major/Minor, API and dependency gates |
+| **framework** | `composer.json`, autoload, Doctum, dev dependencies |
+
+## How to use these docs
+
+- **Humans / any AI tool:** Start at **`AGENTS.md`**, then open the relevant **`skills/<name>/SKILL.md`**.
+- **Cursor users:** **`.cursor/rules/README.md`** only points to **`AGENTS.md`** so guidance stays universal—no duplicate `.mdc` rule sets.
@@ -0,0 +1,56 @@
+---
+name: code-review
+description: PR checklist—API stability, docs, errors, compatibility, dependencies/SCA, tests; Blocker/Major/Minor.
+---
+
+# Code review – Contentstack PHP SDK
+
+## When to use
+
+- Reviewing a PR, self-review before submit, or automated review prompts.
+
+## Instructions
+
+Work through the checklist below. Optionally tag findings: **Blocker**, **Major**, **Minor**.
+
+### API design and stability
+
+- [ ] **Public API:** New or changed public methods/classes under `src/` are necessary, semver-conscious, and documented (`README.md` / `CHANGELOG.md` when user-visible).
+- [ ] **Backward compatibility:** No breaking changes unless explicitly justified (e.g. major version). Prefer additive options and default config shapes.
+- [ ] **Naming:** Matches existing SDK terminology (`Stack`, `ContentType`, `Query`, `Entry`, regions, etc.).
+
+### Error handling and robustness
+
+- [ ] **Errors:** New failure paths use or extend `CSException` / domain messages where appropriate; callers get actionable context.
+- [ ] **Input:** Validate or document preconditions for public parameters; avoid silent failures on malformed API responses where the SDK should surface errors.
+- [ ] **HTTP / JSON:** Parsing stays tolerant of documented Delivery API shapes; regressions for edge payloads are called out.
+
+### Dependencies and security
+
+- [ ] **Dependencies:** `composer.json` changes are justified; versions do not introduce known vulnerabilities.
+- [ ] **SCA:** Address security findings (e.g. Snyk, org scanners) in the PR or via an agreed follow-up.
+
+### Testing
+
+- [ ] **Coverage:** New or modified behavior in `src/` has tests under `test/` when feasible.
+- [ ] **Quality:** Tests are readable, deterministic, and follow existing helper/constants patterns.
+
+### Severity (optional)
+
+| Level | Examples |
+|-------|----------|
+| **Blocker** | Breaking public API without approval; security issue; no tests for new code where tests are practical |
+| **Major** | Inconsistent errors; README examples that do not match real APIs |
+| **Minor** | Style; minor docs |
+
+### Detailed review themes
+
+- **API:** Breaking public signatures without semver / CHANGELOG alignment.
+- **Errors:** Exception changes that confuse callers without a version strategy.
+- **README:** Examples must match real `Contentstack::Stack` and query APIs.
+- **Dependencies:** New packages need justification and license awareness.
+
+## References
+
+- `skills/testing/SKILL.md`
+- `skills/contentstack-utils/SKILL.md`
@@ -0,0 +1,47 @@
+---
+name: contentstack-utils
+description: PHP Delivery SDK API—Contentstack::Stack, queries, entries, assets, regions, sync; RTE via Composer package contentstack/utils.
+---
+
+# Contentstack PHP SDK (and Utils integration)
+
+## When to use
+
+- Implementing or changing Delivery API behavior, query builders, entries, assets, or sync.
+- Updating `README.md` / `CHANGELOG.md` for user-visible behavior.
+- Assessing semver impact of public API changes or **`contentstack/utils`** usage.
+
+## Main entry (consumer API)
+
+- Consumers use **`Contentstack\Contentstack::Stack(...)`** to obtain a **`Contentstack\Stack\Stack`** instance (API key, delivery token, environment, optional region / branch / live preview config).
+- Query and fetch patterns flow through **content types**, **queries**, **entries**, and **assets** under `src/Stack/`.
+- **RTE / JSON rendering:** `Contentstack::renderContent` and related helpers delegate to the **`contentstack/utils`** Composer package (`Contentstack\Utils\*`, `Option`). Do not reimplement utils behavior inside this SDK without strong reason.
+
+## Customization and options
+
+- Stack **config** array supports region, branch, live preview host/enable flags—preserve backward compatibility when extending keys.
+- **ContentstackRegion** (or string region values per existing API) must stay consistent with documented Contentstack regions.
+
+## Data and HTTP
+
+- The SDK builds requests to Contentstack Delivery endpoints; keep URL construction, headers, and query parameters aligned with product documentation.
+- **Result** parsing should match documented JSON shapes; guard against missing keys where the API allows omission.
+
+## Errors
+
+- Use **`Contentstack\Error\CSException`** and **`ErrorMessages`** patterns for domain failures.
+- Avoid suppressing errors on public code paths without documentation.
+
+## Related package
+
+- **`contentstack/utils`** is a required dependency for RTE features shipped through this repo’s public surface; version ranges in `composer.json` should stay coherent with utils releases.
+
+## Docs and versioning
+
+- Follow **semver** for public API changes; update **CHANGELOG** and tag/release process per team norms.
+
+## References
+
+- [Contentstack](https://www.contentstack.com/)
+- [PHP Delivery SDK docs](https://www.contentstack.com/docs/developers/sdks/content-delivery-sdk/php)
+- `skills/php-style/SKILL.md`, `skills/framework/SKILL.md`
@@ -0,0 +1,39 @@
+---
+name: dev-workflow
+description: Branches, CI expectations, Composer test/docs, PR hygiene for Contentstack PHP SDK.
+---
+
+# Development workflow – Contentstack PHP SDK
+
+## When to use
+
+- Setting up locally, opening a PR, or aligning with repository automation.
+- Answering “how do we run tests?” or “why did the branch check fail?”
+
+## Branches
+
+- Use feature branches (e.g. `feat/...`, `fix/...`, ticket branches).
+- **`.github/workflows/check-branch.yml`** blocks pull requests into **`master`** unless the head branch is **`staging`** (SRE policy). Prefer PRs to **`staging`** when targeting a master release train.
+- **Policy / SCA** workflows may run on PRs (see `.github/workflows/policy-scan.yml`, `sca-scan.yml`).
+
+## Running tests and build
+
+- **Install:** `composer install`
+- **Tests:** `composer test` or `vendor/bin/phpunit` (config: `phpunit.xml`, suite under `test/`).
+- Tests may require Contentstack credentials or mocks as documented in `test/README.md`—do not commit secrets.
+
+## Documentation generation
+
+- **Doctum:** `composer run generate:docs` (see `config.php`, output per Doctum defaults).
+
+## Pull requests
+
+- Build/tests pass locally where applicable (`composer test`).
+- Follow the **code-review** skill (`skills/code-review/SKILL.md`) before merge.
+- Prefer backward-compatible public API; call out breaking changes and semver.
+- Update **`CHANGELOG.md`** when behavior visible to integrators changes.
+
+## References
+
+- `skills/testing/SKILL.md`
+- `skills/code-review/SKILL.md`
@@ -0,0 +1,35 @@
+---
+name: framework
+description: Composer package, PSR-4 autoload, Doctum docs, PHP version constraints, dev dependencies.
+---
+
+# Framework / build – Contentstack PHP SDK
+
+## When to use
+
+- Editing `composer.json`, autoload blocks, or scripts.
+- Changing minimum PHP version or required packages (e.g. `contentstack/utils`, PHPUnit).
+- Updating documentation generation (`config.php`, Doctum).
+
+## Composer
+
+- **Package name:** `contentstack/contentstack` (see `composer.json`).
+- **Autoload:** PSR-4 `Contentstack\` → `src/` plus `files` entry for `src/Support/helper.php`—keep in sync when moving classes.
+- **Scripts:** `test` → PHPUnit; `generate:docs` → Doctum.
+
+## PHP version
+
+- `require.php` sets minimum language level; raising it is a **compatibility decision**—document in CHANGELOG and coordinate releases.
+
+## Documentation
+
+- **Doctum** scans `./src` per `config.php`; adjust only when layout changes.
+
+## CI / automation
+
+- This repo may not define a dedicated PHPUnit workflow file; still run **`composer test`** before merge. Branch and policy workflows live under `.github/workflows/`.
+
+## References
+
+- `skills/php-style/SKILL.md`
+- `skills/dev-workflow/SKILL.md`
@@ -0,0 +1,42 @@
+---
+name: php-style
+description: PSR-4 layout, namespaces, docblocks, PHP compatibility, src/ structure for this SDK.
+---
+
+# PHP style and repo layout – Contentstack PHP SDK
+
+## When to use
+
+- Editing any PHP under `src/` or `test/`.
+- Adding classes or changing namespace boundaries.
+
+## Layout
+
+- **Library code:** `src/` with namespace **`Contentstack\...`** matching PSR-4 paths.
+- **Stack / Delivery:** `src/Stack/` (e.g. `Stack.php`, `ContentType/`, `Assets.php`, `BaseQuery.php`).
+- **Config / errors / support:** `src/Config/`, `src/Error/`, `src/Support/`.
+- **Entry point:** `src/Contentstack.php` exposes static factory and utils-facing helpers.
+
+## PHP language
+
+- Honor **minimum PHP** from `composer.json`; avoid syntax and standard-library features unavailable on that floor unless the constraint is explicitly raised.
+- **`#[\AllowDynamicProperties]`** and legacy patterns may exist for backward compatibility—do not remove without a semver plan.
+
+## Documentation blocks
+
+- Existing files use **PHPDoc** (`@param`, `@return`, `@package`, etc.); new public APIs should include equivalent documentation for IDEs and Doctum.
+
+## Naming
+
+- **Classes:** `PascalCase` matching file names under PSR-4.
+- **Methods:** `camelCase` consistent with surrounding code.
+- Preserve established **public** names even when imperfect unless doing a **semver-major** cleanup with maintainer agreement.
+
+## Imports and visibility
+
+- Prefer `use` statements for classes in other namespaces; keep **public** surface explicit (public methods on classes intended for consumers).
+
+## References
+
+- `skills/framework/SKILL.md` (Composer, autoload)
+- `skills/testing/SKILL.md`
@@ -0,0 +1,38 @@
+---
+name: testing
+description: PHPUnit—test/ layout, helpers, constants, coverage output, secrets hygiene.
+---
+
+# Testing – Contentstack PHP SDK
+
+## When to use
+
+- Adding or changing tests under `test/`.
+- Debugging failing tests or coverage gaps.
+
+## Runner and config
+
+- **PHPUnit 10** via `vendor/bin/phpunit` or `composer test`.
+- Configuration: **`phpunit.xml`**—suite directory `test/`, source coverage for `src/`, reports under `./tmp/` when generated.
+
+## Layout and naming
+
+- Tests live as `*Test.php` (e.g. `EntriesTest.php`, `AssetsTest.php`, `SyncTest.php`) alongside helpers such as `constants.php`, `utility.php`, `REST.php`.
+- Reuse existing helpers before introducing parallel fixtures.
+
+## Integration vs unit
+
+- Some tests may exercise HTTP against Contentstack (see `test/README.md` **Prerequisite**); treat credentials as **local-only** or CI secrets—never commit API keys or tokens.
+
+## Coverage
+
+- Clover/HTML/text reports are configured in `phpunit.xml`; ensure `tmp/` (or chosen output dirs) stays out of version control if generated locally (see `.gitignore`).
+
+## Secrets
+
+- Tests must not embed real **delivery tokens** or **API keys** in the repository.
+
+## References
+
+- `skills/dev-workflow/SKILL.md`
+- `skills/code-review/SKILL.md`