contentstack · reeshika-h · Apr 8, 2026 · Apr 8, 2026
@@ -0,0 +1,7 @@
+# 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.
+
+Path to AGENTS.md: from `.cursor/rules/README.md` use `../../AGENTS.md`.
@@ -0,0 +1,50 @@
+# Contentstack Dart SDK – 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/contentstack-dart](https://github.com/contentstack/contentstack-dart) |
+| *Purpose:* | Official Dart package for Contentstack’s **Content Delivery API (CDA)**—fetch and query published content (entries, assets, content types), live preview, sync, and image transforms. |
+| *Out of scope (if any):* | Not the Management API, not a Flutter UI kit, and not a standalone HTTP server—this is a client library built on the `http` package. |
+
+## Tech stack (at a glance)
+
+| Area | Details |
+| --- | --- |
+| Language | Dart SDK `>=2.12.0 <4.0.0` (`environment` in `pubspec.yaml`) |
+| Build | `dart pub get`; JSON models use `json_serializable`—regenerate with `dart run build_runner build --delete-conflicting-outputs` when `*.dart` parts change (`pubspec.yaml`, `analysis_options.yaml` excludes `*.g.dart`) |
+| Tests | `package:test`; tests under `test/*.dart` (see `test/run_test.sh` for optional coverage steps) |
+| Lint / coverage | Analyzer + linter rules in `analysis_options.yaml` (`flutter_lints`-aligned custom rule set); coverage via `dart test --coverage=./coverage` and tooling described in `test/run_test.sh` |
+| Other | Runtime deps: `http`, `json_annotation`, `logger`, `path`, `dotenv`, `file`; API docs generated with `dartdoc` (dev dependency) |
+
+## Commands (quick reference)
+
+| Command Type | Command |
+| --- | --- |
+| Build | `dart pub get` |
+| Codegen (when models / `part` files change) | `dart run build_runner build --delete-conflicting-outputs` |
+| Test | `dart test` |
+| Lint | `dart analyze` |
+| Format (optional) | `dart format .` |
+
+**CI / automation:** workflows under [.github/workflows/](.github/workflows/) (e.g. branch checks, publish to pub.dev on version tags, policy scan, Jira integration).
+
+## Where the documentation lives: skills
+
+| Skill | Path | What it covers |
+| --- | --- | --- |
+| Dev workflow | [skills/dev-workflow/SKILL.md](skills/dev-workflow/SKILL.md) | Branches, PR expectations, local commands, optional codegen |
+| Contentstack Dart SDK (API) | [skills/contentstack-dart-sdk/SKILL.md](skills/contentstack-dart-sdk/SKILL.md) | Public surface, `Stack`/queries, errors, integration boundaries |
+| Dart style & layout | [skills/dart-style/SKILL.md](skills/dart-style/SKILL.md) | Package layout, imports, analyzer conventions |
+| Testing | [skills/testing/SKILL.md](skills/testing/SKILL.md) | Test layout, env/credentials, coverage notes |
+| Code review | [skills/code-review/SKILL.md](skills/code-review/SKILL.md) | PR checklist and severity hints |
+| Runtime & HTTP | [skills/runtime-and-http/SKILL.md](skills/runtime-and-http/SKILL.md) | HTTP client usage, env config, logging, packaging |
+
+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.
@@ -0,0 +1,16 @@
+# Skills – Contentstack Dart SDK
+
+Source of truth for detailed guidance. Read [AGENTS.md](../AGENTS.md) first, then open the skill that matches your task.
+
+## When to use which skill
+
+| Skill folder | Use when |
+| --- | --- |
+| [dev-workflow](dev-workflow/) | Branching, CI expectations, day-to-day build/test/lint/codegen |
+| [contentstack-dart-sdk](contentstack-dart-sdk/) | Changing public API, `Stack`, queries, errors, or CDA behavior |
+| [dart-style](dart-style/) | Imports, library structure, analyzer/linter alignment |
+| [testing](testing/) | Writing or running tests, fixtures, coverage, credentials |
+| [code-review](code-review/) | Preparing or reviewing a PR |
+| [runtime-and-http](runtime-and-http/) | HTTP usage, retries/env, dependencies, or packaging concerns |
+
+Each folder contains `SKILL.md` with YAML frontmatter (`name`, `description`).
@@ -0,0 +1,36 @@
+---
+name: code-review
+description: Use when preparing a pull request or reviewing changes for this SDK repository.
+---
+# Code review – Contentstack Dart SDK
+
+## When to use
+
+- Before requesting review or approving a PR
+- When triaging risk (API breaks, security, test gaps)
+
+## Instructions
+
+### Checklist
+
+- **Behavior:** Change matches CDA semantics; no accidental Management API assumptions
+- **API:** Public exports updated deliberately in `lib/contentstack.dart`; breaking changes documented and versioned
+- **Quality:** `dart analyze` clean; `dart test` passes; codegen committed if `*.g.dart` changed
+- **Security:** No API keys, tokens, or `.env` with secrets in the diff
+- **Style:** Matches `analysis_options.yaml` and project patterns ([../dart-style/SKILL.md](../dart-style/SKILL.md))
+
+### Severity (optional)
+
+- **Blocker:** Breaks consumers, leaks credentials, or ships broken analyze/tests
+- **Major:** Incorrect API usage, missing tests for risky logic, undocumented breaking change
+- **Minor:** Naming, small refactors, doc nits
+
+### Process
+
+- Respect branch rules in [.github/workflows/check-branch.yml](../../.github/workflows/check-branch.yml) for target branches
+
+## References
+
+- [../dev-workflow/SKILL.md](../dev-workflow/SKILL.md)
+- [../testing/SKILL.md](../testing/SKILL.md)
+- [AGENTS.md](../../AGENTS.md)
@@ -0,0 +1,38 @@
+---
+name: contentstack-dart-sdk
+description: Use when changing the public API, Stack, queries, CDA calls, errors, or SDK boundaries.
+---
+# Contentstack Dart SDK (API) – Contentstack Dart SDK
+
+## When to use
+
+- Adding or changing exported types in `lib/contentstack.dart`
+- Working on `Stack`, content types, entries, queries, assets, image transforms, sync, or live preview
+- Defining or handling SDK errors and response models
+
+## Instructions
+
+### Entry points
+
+- Main library: [`lib/contentstack.dart`](../../lib/contentstack.dart) re-exports `src/` modules—prefer exporting new public types from there
+- Core client: [`lib/src/stack.dart`](../../lib/src/stack.dart) and related `entry.dart`, `query.dart`, `contenttype.dart`, `asset.dart`, `image_transform.dart`
+
+### API boundaries
+
+- This package targets **Content Delivery API** usage (read/query published content), not Management API operations
+- HTTP is performed via the `http` package; see [../runtime-and-http/SKILL.md](../runtime-and-http/SKILL.md)
+
+### Models and errors
+
+- JSON models use `json_annotation` + generated `*.g.dart` parts—regenerate after schema changes (see [../dev-workflow/SKILL.md](../dev-workflow/SKILL.md))
+- Errors live under [`lib/src/error/`](../../lib/src/error/); keep messages and types consistent with CDA behavior
+
+### Versioning
+
+- Package version and changelog: follow semver in `pubspec.yaml` and `CHANGELOG.md` when releasing
+
+## References
+
+- [Content Delivery API](https://www.contentstack.com/docs/developers/apis/content-delivery-api/)
+- [../dart-style/SKILL.md](../dart-style/SKILL.md) — imports and docs
+- [../testing/SKILL.md](../testing/SKILL.md) — integration-style tests
@@ -0,0 +1,35 @@
+---
+name: dart-style
+description: Use for package layout, imports, naming, and analyzer/linter alignment in this Dart repo.
+---
+# Dart style & layout – Contentstack Dart SDK
+
+## When to use
+
+- Adding new files under `lib/` or `test/`
+- Fixing analyzer or lint findings
+- Choosing import style (`package:` vs relative) consistent with this repo
+
+## Instructions
+
+### Layout
+
+- Public API: `lib/contentstack.dart` and `lib/src/`
+- Tests: `test/*.dart` alongside optional scripts like `test/run_test.sh`
+- Analyzer config: root [`analysis_options.yaml`](../../analysis_options.yaml)
+
+### Conventions reflected in `analysis_options.yaml`
+
+- Prefer `package:` imports for public code; `avoid_relative_lib_imports` is enabled
+- `directives_ordering`, `package_api_docs` (document public APIs), `always_declare_return_types`, strong null-safety practices
+- Generated `*.g.dart` files are excluded from analysis—do not hand-edit them
+
+### Naming
+
+- Follow `file_names`, `camel_case_types`, `non_constant_identifier_names` as enforced by the configured lints
+
+## References
+
+- [../dev-workflow/SKILL.md](../dev-workflow/SKILL.md) — `dart analyze` / format
+- [Effective Dart](https://dart.dev/effective-dart)
+- [Analyzer options](https://dart.dev/tools/analysis)
@@ -0,0 +1,42 @@
+---
+name: dev-workflow
+description: Use for branches, CI, local build/test/lint, codegen, and PR workflow for this repo.
+---
+# Dev workflow – Contentstack Dart SDK
+
+## When to use
+
+- Starting work in this repository or onboarding
+- Before opening a PR (verify analyze, tests, format)
+- After editing JSON-serializable models or `part` files
+
+## Instructions
+
+### Dependencies and codegen
+
+- Install deps: `dart pub get`
+- If you change files that use `json_serializable` / `part '*.g.dart'`, run:  
+  `dart run build_runner build --delete-conflicting-outputs`  
+  Generated files are excluded from manual lint in `analysis_options.yaml`
+
+### Quality gates
+
+- Static analysis: `dart analyze` (rules in `analysis_options.yaml`)
+- Tests: `dart test`
+- Optional format check: `dart format .`
+
+### Branches and automation
+
+- Pull requests run [.github/workflows/check-branch.yml](../../.github/workflows/check-branch.yml) (e.g. restrictions when targeting `master`)
+- Publishing: [.github/workflows/publish.yml](../../.github/workflows/publish.yml) on semver tags; dry-run uses `dart pub publish --dry-run`
+
+### Package docs
+
+- HTML API docs: `dartdoc` is listed in `pubspec.yaml`; generate when documenting public API changes
+
+## References
+
+- [../contentstack-dart-sdk/SKILL.md](../contentstack-dart-sdk/SKILL.md) — API surface
+- [../testing/SKILL.md](../testing/SKILL.md) — tests and coverage
+- [../dart-style/SKILL.md](../dart-style/SKILL.md) — layout and analyzer
+- [Dart SDK environment](https://dart.dev/tools/pub/pubspec#sdk)
@@ -0,0 +1,42 @@
+---
+name: runtime-and-http
+description: Use for HTTP client usage, env configuration, logging, retries, and dependency packaging for this SDK.
+---
+# Runtime & HTTP – Contentstack Dart SDK
+
+## When to use
+
+- Changing how requests are built or executed
+- Working with `http`, headers, hosts/regions, or error mapping from responses
+- Adjusting runtime dependencies (`pubspec.yaml`) or environment loading (`dotenv`)
+
+## Instructions
+
+### HTTP stack
+
+- HTTP calls use the [`http`](https://pub.dev/packages/http) package—keep usage consistent with Dart async/await patterns elsewhere in `lib/src/`
+- Do not introduce an alternate HTTP client for the same code paths without team agreement
+
+### Configuration
+
+- `dotenv` is used in tests and may be used for local/dev configuration—never commit real credentials ([../testing/SKILL.md](../testing/SKILL.md))
+- `path` and `file` support path handling where needed; keep imports minimal
+
+### Logging
+
+- `logger` is a dependency; avoid logging sensitive tokens or full auth headers
+
+### Packaging
+
+- Keep `pubspec.yaml` constraints coherent with Dart SDK bounds (`>=2.12.0 <4.0.0`)
+- Publishing flow: see [.github/workflows/publish.yml](../../.github/workflows/publish.yml)
+
+### Retries and resilience
+
+- If adding retries, backoff, or timeouts, document behavior in public API or internal modules and add tests where feasible
+
+## References
+
+- [../contentstack-dart-sdk/SKILL.md](../contentstack-dart-sdk/SKILL.md)
+- [http package](https://pub.dev/packages/http)
+- [../dev-workflow/SKILL.md](../dev-workflow/SKILL.md)
@@ -0,0 +1,35 @@
+---
+name: testing
+description: Use for test layout, running tests, coverage, fixtures, and credential handling in this repo.
+---
+# Testing – Contentstack Dart SDK
+
+## When to use
+
+- Adding or changing tests under `test/`
+- Running the suite locally or generating coverage
+- Dealing with API keys and environment variables for integration-style tests
+
+## Instructions
+
+### Layout and runner
+
+- Tests live in `test/` (e.g. `stack_test.dart`, `query_test.dart`, `entry_test.dart`)
+- Run all: `dart test`
+- Optional coverage workflow and LCOV steps are documented in [`test/run_test.sh`](../../test/run_test.sh) (`dart test --coverage=./coverage`, `coverage:format_coverage`, etc.)
+
+### Credentials policy
+
+- Tests such as [`test/stack_test.dart`](../../test/stack_test.dart) load credentials via `dotenv` (`apiKey`, `deliveryToken`, `environment`, optional `host`)
+- **Do not commit secrets**—use local `.env` or CI secrets only as your team documents; never paste real tokens into the repo or PR descriptions
+
+### Scope
+
+- Prefer unit tests for pure logic; use guarded integration tests only when stack credentials are available
+- After codegen changes, ensure tests still pass and coverage excludes generated files if you use the scripts in `test/run_test.sh`
+
+## References
+
+- [../dev-workflow/SKILL.md](../dev-workflow/SKILL.md) — `dart test` in CI workflow
+- [../contentstack-dart-sdk/SKILL.md](../contentstack-dart-sdk/SKILL.md) — behavior under test
+- [package:test](https://pub.dev/packages/test)