From 8a2332f700dac765a33e4b4414c22f909ba47d53 Mon Sep 17 00:00:00 2001 From: OMpawar-21 Date: Mon, 17 Aug 2026 16:31:22 +0530 Subject: [PATCH] feat: add sdk-feature, sdk-parity, sdk-review skills MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Adds three management SDK automation skills to support feature parity across the Contentstack management SDK portfolio (JS, Python, Java, .NET). sdk-feature: Full 11-step implementation pipeline — CMA spec as source of truth, TDD-first approach, 12-check architecture scan, security gates (Talisman/Snyk/TruffleHog), human review gate, model separation enforced (higher model for thinking, lower model for code writing). sdk-parity: Parity audit across all management SDKs — fetches CMA OpenAPI spec dynamically, endpoint-based matching (catches aliases like query↔find), dynamic resource discovery via grep, generates HTML parity report. sdk-review: Independent 3-pass code review (Source, Tests, Regression) — 10 checks in Pass 1 (spec compliance, plan compliance, return types, param naming, docstrings, deprecated endpoints, cross-SDK method count), test quality review in Pass 2, full regression in Pass 3. Co-Authored-By: Claude Sonnet 4.6 --- skills/sdk-feature/SKILL.md | 139 ++++++++++++++++++++++++++++ skills/sdk-parity/SKILL.md | 101 ++++++++++++++++++++ skills/sdk-review/SKILL.md | 178 ++++++++++++++++++++++++++++++++++++ 3 files changed, 418 insertions(+) create mode 100644 skills/sdk-feature/SKILL.md create mode 100644 skills/sdk-parity/SKILL.md create mode 100644 skills/sdk-review/SKILL.md diff --git a/skills/sdk-feature/SKILL.md b/skills/sdk-feature/SKILL.md new file mode 100644 index 0000000..5898e53 --- /dev/null +++ b/skills/sdk-feature/SKILL.md @@ -0,0 +1,139 @@ +--- +name: sdk-feature +description: "Implement a feature across any Contentstack management SDK (JS, Python, Java, .NET). TDD approach — tests first, then implementation. CMA OpenAPI spec is the primary source of truth. Fully generic — works for any SDK language and any AI agent. Model separation enforced: higher model for thinking/design/review, lower model for code writing. Use when asked to implement SDK parity, add a new CMA feature to management SDKs, or replicate an existing feature across multiple SDK languages." +allowed-tools: Read Edit Write WebFetch Bash Glob Grep +--- + +# sdk-feature + +## What This Skill Does + +Implements a feature across any Contentstack management SDK using a structured, TDD-first pipeline. Reads local repos directly — no cached index needed. + +## Usage + +``` +/sdk-feature "feature description" + --docs + --ref + --sdks + --tickets +``` + +## The One Rule + +``` +THINKING → Higher-capability model (analysis, design, review) +WRITING → Lower-capability model (code translation, after thinking is done) +``` + +## Pipeline (11 steps) + +**Step 0 — Task Checklist** +Create tasks using TaskCreate before starting. Shared tasks first (Phase 1), per-SDK tasks after search confirms gaps (Phase 2). + +``` +TaskCreate({ subject: "Fetch API spec + search all repos", activeForm: "Fetching spec and searching repos", description: "..." }) +TaskCreate({ subject: "[] Architecture scan", activeForm: "Scanning architecture", description: "..." }) +``` + +**Step 1 — Parse Arguments** +Extract feature description, --docs URLs, --ref SDK, --sdks targets, --tickets mode. + +**Step 2 — API Spec + Search 🔵 HIGHER MODEL** +1. Fetch CMA OpenAPI spec: `https://assets.contentstack.io/v3/assets/blt02f7b45378b008ee/blt85399a97399b4ecf/cma-openapi-3.json?v=3.0.1` +2. Scan ALL repos in `repos/contentstack-management-*/` on `origin/development` +3. Build gap table — which SDKs have the feature, which are missing +4. Create per-SDK tasks in Phase 2 based on actual gaps found + +**Tier-1 gate:** if JS is also missing, implement JS first then lock others behind human gate. + +**Step 3 — Build TRD 🔵 HIGHER MODEL** +- Confluence/product-wiki in --docs → use directly, skip spec file +- Only API docs → write `docs/specs/.md` + +**Step 4 — Tickets 🔵 HIGHER MODEL** +- `none` — skip. Read ticket URL from --docs as context. +- `tasks` — one Task per target SDK via Atlassian MCP (or markdown fallback) +- `full` — Epic → Spike → Task per SDK + +**Step 5 — Architecture Scan 🔵 HIGHER MODEL** (mandatory per SDK, 12 sub-checks) +- 5a: Read resource file + base class + 2-3 recent methods +- 5b: Method signature consistency check +- 5c: Error handling pattern extraction +- 5d: HTTP client instantiation pattern +- 5e: Deprecated pattern detection (git log) +- 5f: Header injection pattern +- 5g: Test file pattern pre-read +- 5h: Recent PR scan for similar patterns +- 5i: Reuse check — existing base class, service, helper +- 5j: Rollback plan if new class unavoidable (ask for approval) +- 5k: Cross-SDK pattern comparison +- 5l: Confirm plan — write to `docs/plans//-plan.md` + +**Rule:** Only create new class if nothing existing can handle it. + +**Step 6 — TDD: Write Test Cases First 🔵 HIGHER MODEL** +Write ALL unit + integration tests BEFORE implementation. Tests must FAIL before Step 7. +- Unit: positive + negative paths (URL, verb, headers, body assertions) +- Integration: write but don't run (need live credentials) +- Cross-SDK parity: same test coverage across all target SDKs + +**Step 7 — Implement 🟢 LOWER MODEL** +Context handoff via `docs/plans//-plan.md` (file persists across model switches). +- `git checkout development && git checkout -b feat/` +- Read locked plan — implement EXACTLY what it says +- Make failing tests pass + +**Step 8 — Code Review 🔵 HIGHER MODEL** +Run `/sdk-review` — 3 passes. Must be APPROVED before proceeding. + +**Step 9 — Security Checks** +Sequential within each SDK (avoids rate limits): +1. `talisman --staged` — no secrets in staged files +2. `snyk test` — no new high/critical vulnerabilities +3. `trufflehog git file://. --since-commit HEAD --only-verified` — no secrets in history + +**Step 9b — Manual Review Gate 🟢 LOWER MODEL** +Present diff summary + checklist to developer. Wait for explicit per-SDK approval. Record `Reviewed-by:` in commit. + +**Step 10 — Commit + PR** +- Commit: `feat: add to management SDK` +- PR against `development` — never `main`/`master` +- Comment PR link on Jira ticket + +**Step 11 — Final Summary** + +## Consistency Rules + +| Language | Convention | Example | +|----------|-----------|---------| +| JavaScript | camelCase | `publish()` | +| Python | snake_case | `publish()` | +| Java | camelCase | `publish()` | +| .NET | PascalCase + Async | `Publish()` + `PublishAsync()` | +| Any new SDK | Read from its existing methods | Follow its pattern | + +- Same methods in every target SDK — no partial implementations +- Return type must match existing methods in same SDK +- Parameter naming must match existing methods in same SDK +- Docstrings: if existing methods have them → new method must have one +- Deprecated spec endpoints: add `@deprecated` notice in docstring + +## Multi-SDK Agent Strategy + +When running via `sdk-feature.js` workflow, each SDK gets an independent agent: +- Isolated context — no shared state with other SDKs +- State persisted to `docs/plans//-state.json` +- Independent error recovery — one SDK fails, others continue +- Sequential gates: Jira creation, human review (prevents race conditions) +- Agent identity in commits: `[agent:impl--]` + +## Model Switch Instructions + +| Platform | Higher model | Lower model | +|----------|-------------|-------------| +| Claude Code | `/config → Model → claude-opus-4-8` | `/config → Model → claude-sonnet-4-6` | +| Cursor | Model picker → highest available | Model picker → standard | +| CLI | `--model ` | `--model ` | +| Other | Use most capable model | Use default model | diff --git a/skills/sdk-parity/SKILL.md b/skills/sdk-parity/SKILL.md new file mode 100644 index 0000000..0cc75c1 --- /dev/null +++ b/skills/sdk-parity/SKILL.md @@ -0,0 +1,101 @@ +--- +name: sdk-parity +description: "Run a full parity audit across all Contentstack management SDKs. Uses the CMA OpenAPI spec as the source of truth — not hardcoded resource lists. Endpoint-based matching catches method aliases (query↔find, import↔imports). Generates an HTML parity report. Use when checking what's missing across JS, Python, Java, .NET management SDKs, or when deep-scanning a specific resource." +allowed-tools: Read Write WebFetch Bash Glob Grep +--- + +# sdk-parity + +## What This Skill Does + +Audits all management SDKs against the CMA OpenAPI spec. Reports gaps per SDK per resource. Generates a rich HTML report. + +## Usage + +``` +/sdk-parity ← full audit: all resources from spec +/sdk-parity taxonomy ← deep scan: one resource, endpoint-level detail +``` + +## Model + +**Higher-capability model for entire skill** — pure analysis, no code writing. + +## Source of Truth + +CMA OpenAPI spec (always fetched first): +``` +https://assets.contentstack.io/v3/assets/blt02f7b45378b008ee/blt85399a97399b4ecf/cma-openapi-3.json?v=3.0.1 +``` + +The spec defines the resource list — no hardcoded "20 resources". If spec fetch fails → fallback to JS repo as baseline. + +## Full Audit Flow + +1. **Fetch spec** → extract all resource tags → canonical endpoint list + spec version +2. **Fetch all repos:** `git -C repos/contentstack-management- fetch origin` +3. **Discover files dynamically** (no hardcoded paths): + ```bash + git -C repos/ grep -rl "" origin/development + ``` +4. **Endpoint-based matching** (not name matching): + - Same HTTP verb + path → ✅ (show actual name with `*` if alias) + - Known aliases auto-resolved: `query↔find`, `fetchAll↔findAll`, `import↔imports` + - Spec endpoint absent in SDK → ❌ MISSING + - JS also missing a spec endpoint → JS flagged ❌ too + - Method in SDK not in spec → flagged as extra/diverged +5. **Output gap report** — resource × SDK table with endpoint per row +6. **Generate HTML report** from `sdk-automation/templates/sdk-parity-report.template.html` + +## Deep Scan Flow + +For `/sdk-parity `: +1. Fetch spec → filter by resource keyword +2. Find source files via grep +3. Match every spec endpoint against each SDK +4. Show: JS method + HTTP endpoint + actual method per SDK + +## HTML Report + +Generated at `docs/sdk-parity-report.html`. Template at `sdk-automation/templates/sdk-parity-report.template.html`. + +Fill these placeholders: +- `SPEC_VERSION_PLACEHOLDER` — from spec `info.version` +- `RUN_DATE_PLACEHOLDER` — today's date +- `PREV_RUN_DATE_PLACEHOLDER` — previous run date (for delta) +- `SDK_NAMES_PLACEHOLDER` — array of SDK display names +- `SDK_KEYS_PLACEHOLDER` — array of data keys e.g. `["js","py","jv","nt"]` +- `SDK_VERSIONS_PLACEHOLDER` — object with version per SDK key +- `SDK_COLORS_PLACEHOLDER` — array of hex colors (one per SDK, cycle palette if >6) +- `DELTA_CLOSED_PLACEHOLDER` — gaps closed since last run +- `DELTA_FOUND_PLACEHOLDER` — new gaps found since last run +- `SPEC_NEW_PLACEHOLDER` — new spec endpoints count +- `SPEC_CHANGELOG_PLACEHOLDER` — array of new endpoint strings +- `DATA_PLACEHOLDER` — full resource data object + +## Data Object Schema + +```javascript +{ + resourceName: { + lastModified: { js: "2 days ago", py: "3 months ago", ... }, + subResources: ["terms"], + actionCmd: "/sdk-feature \"resource export\" --sdks python --ref js", + extras: { js: [], py: ["validate_uid()"], jv: [], nt: [] }, + methods: [ + { + js: "export()", + ep: "GET /resource/:uid/export", + py: "❌ MISSING", + jv: "❌ MISSING", + nt: "✅ Export", + tests: { py: "❌", jv: "❌", nt: "✅" }, + effort: { py: "Easy", jv: "Easy" } + } + ] + } +} +``` + +Status strings: `"✅ name"` · `"✅ name *"` (alias) · `"❌ MISSING"` · `"— "` (not in spec) +Effort: `"Easy"` / `"Medium"` / `"Hard"` — for missing SDKs only diff --git a/skills/sdk-review/SKILL.md b/skills/sdk-review/SKILL.md new file mode 100644 index 0000000..da64eb4 --- /dev/null +++ b/skills/sdk-review/SKILL.md @@ -0,0 +1,178 @@ +--- +name: sdk-review +description: "Independent 3-pass code review for Contentstack management SDK implementations. Higher-capability model only — the model that wrote the code must NOT review its own work. Checks spec compliance, plan compliance, SDK conventions, return types, parameter naming, docstrings, deprecated endpoints, cross-SDK method parity, test quality, and regression. Use after implementing a feature in any management SDK, before committing." +allowed-tools: Read Bash Glob Grep +--- + +# sdk-review + +## What This Skill Does + +Three-pass independent code review for management SDK implementations. Produces structured findings with severity ratings. Only APPROVED implementations proceed to commit. + +## Usage + +``` +/sdk-review + +Example: +/sdk-review repos/contentstack-management-python docs/plans/taxonomy-export/python-plan.md +``` + +## Model + +**Higher-capability model (Pass 1 + Pass 2) · Any model (Pass 3)** + +The model that wrote the code (lower model, Step 7) must NOT review its own work. + +## Pass 1 — Source Code Review + +Reads `git diff HEAD` — source files only (excludes test files). + +### 1a — Spec compliance +- Correct HTTP verb + path per CMA spec +- Required params enforced, optional params truly optional + +### 1b — Plan compliance +- Check `docs/plans//-plan.md` exists → verify plan was followed +- If plan missing → emit INFO: "Locked plan not found — skipping 1b" +- Unexpected new files → BLOCKER +- New class created that plan said wouldn't be → BLOCKER + +### 1c — SDK convention compliance +- Naming follows this SDK's existing methods (read from unchanged methods) +- Method signature matches pattern from Step 5b +- Error handling matches pattern from Step 5c +- HTTP client usage matches pattern from Step 5d +- Header injection matches pattern from Step 5f + +### 1d — No reference SDK copy +- Flag any idiom belonging to a different language +- e.g. `.then()` in Python, `async/await` in Java without proper syntax + +### 1e — Redundancy check +- New class created that existing one could handle → MAJOR +- Duplicate methods doing the same thing → MAJOR + +### 1f — Return type consistency +- New method must return same type as existing methods in same file +- Python → `requests.Response` · Java → `Call` · .NET → `ContentstackResponse` + `Task` +- Flag MAJOR if returning raw dict/JSON where existing methods return typed response +- Flag MAJOR if .NET async pair missing when existing methods have async pairs + +### 1g — Parameter naming consistency +- Read 3 existing method signatures → extract naming convention +- New method params must match (e.g. all use `data`, not `body`) +- Check parameter ORDER matches existing conventions +- Flag MINOR + +### 1h — Docstring consistency +- Read 5 existing methods → check for docstrings +- If existing have docstrings → new method MUST have one in same format +- If existing have none → new method must NOT add one +- Special case: first method in file → add docstring (sets the standard) +- Format: Python triple-quote · Java Javadoc `/** */` · .NET XML `/// ` · JS JSDoc `/** @param */` +- Flag MAJOR if missing when required, MINOR if wrong format + +### 1i — Deprecated endpoint handling +- Check each implemented endpoint against spec `deprecated: true` flag +- If deprecated → BLOCKER if no `@deprecated` in docstring +- If deprecated → MAJOR if SDK has logging but no runtime warning + +### 1j — Cross-SDK method count verification +- Read other target SDKs' `feat/` branch diffs: + ```bash + git -C repos/ log --oneline -1 feat/ + git -C repos/ diff HEAD~1 HEAD --name-only + ``` +- Compare method counts — flag MAJOR if counts differ +- If other SDKs not yet implemented → skip, emit INFO + +## Pass 2 — Test Quality Review + +Reads `git diff HEAD` — test files only. + +### 2a — Positive test cases +- Actually asserts URL, verb, headers, body — not just `assert response is not None` +- Covers happy path completely +- Tests optional params separately + +### 2b — Negative test cases +- Missing UID test actually triggers the guard +- Invalid body test verifies correct error type +- Not just happy path with a misleading name + +### 2c — Cross-SDK test parity +- Compare test count vs other SDKs that already have this feature +- Same negative paths must be covered in all SDKs — flag MAJOR if discrepancy + +### 2d — Integration test completeness +- Positive (2xx) + Negative (401, 404, 422) paths written +- Follows ordering convention of existing integration test file + +## Pass 3 — Regression Check + +Run full existing test suite: +```bash +# Python +python3 -m pytest tests/unit/ -v --tb=short + +# .NET +dotnet test --filter "Category!=Integration" + +# Java +mvn test -q -Dgpg.skip=true + +# JS +npm test +``` + +All existing tests must still pass. Any regression → BLOCKER with test name. + +## Finding Format + +Every finding must use this exact structure: + +``` +FINDING #N +Severity: BLOCKER | MAJOR | MINOR | INFO +Pass: Source | Tests | Regression +File: +Line: +Issue: +Expected: +Found: +Fix: +``` + +## Severity Definitions + +| Severity | Action | +|----------|--------| +| BLOCKER | Must fix before commit | +| MAJOR | Must fix before commit | +| MINOR | Fix recommended, does not block | +| INFO | Observation only | + +## Re-Review After Fix + +If BLOCKER or MAJOR found: +1. Developer fixes all BLOCKER + MAJOR +2. Re-run `/sdk-review` — Pass 1 + Pass 2 only (regression already confirmed) +3. Must be clean before commit + +## Review Summary Output + +``` +REVIEW SUMMARY — — +════════════════════════════════════ +Pass 1 (Source): PASSED / N findings +Pass 2 (Tests): PASSED / N findings +Pass 3 (Regression): PASSED / N failures + +Blockers: N +Majors: N +Minors: N + +Status: APPROVED ✅ / CHANGES REQUIRED ❌ +```