@commercetools/commercetools-ai-plugin-sdd

Keep vanilla Spec Kit / OpenSpec — this overlay wires in commercetools skills deterministically.

It patches a spec-driven development project (GitHub Spec Kit or OpenSpec) so that any spec, plan, or task touching commercetools reliably loads the right commercetools-* skill at the right phase — without forking either framework.

Quick start

# in a project already initialized with `specify init` or `openspec init`:
npx @commercetools/commercetools-ai-plugin-sdd init

That's it. The overlay detects which framework(s) are present and applies its marker blocks. Re-running is safe (idempotent), and remove restores the project exactly.

Commands

ct-sdd init    [--framework speckit|openspec] [--dry-run] [--pin <version>]
ct-sdd remove  [--framework speckit|openspec] [--dry-run]
ct-sdd status  [--framework speckit|openspec]

• --framework — act on only one framework (default: every one detected).
• --dry-run — print what would change, write nothing.
• --pin <version> — abort unless the bundled overlay matches <version>. The overlay content is pinned by the package version, so pin by installing a specific package version ([email protected]); this flag guards against using the wrong one.
• --cwd <dir> — operate in <dir> instead of the current directory.

Detection: .specify/ → Spec Kit, openspec/ → OpenSpec.

What it patches

Every change is wrapped in removable marker blocks — nothing outside the markers is ever rewritten.

Spec Kit (.specify/) | File | Block | Effect | |---|---|---| | .specify/memory/constitution.md | platform-skills-constitution | Adds the three platform-skill articles (skill resolution, task annotation, no unverified API surface). | | .specify/templates/plan-template.md | platform-skills-resolution | Adds a required Platform Skills Resolution section the agent fills during /speckit.plan. | | .specify/templates/tasks-template.md | task-skill-annotation | Extends the task grammar so each task carries a [SKILL: <name>] token, read at implement time. |

OpenSpec (openspec/) | File | Block | Effect | |---|---|---| | openspec/config.yaml | platform-skills-conventions | Adds a context: block + per-artifact rules: (proposal, tasks) that select the matching commercetools-* skill and annotate commercetools tasks. |

The load-bearing mechanism is the template patch: because tasks.md is re-read task-by-task during implementation, the [SKILL: …] token is physically in context at the moment code is written — no reliance on skill-triggering luck.

Marker convention

<!-- ct-sdd:begin v=1 id=<slug> -->
…injected content…
<!-- ct-sdd:end id=<slug> -->

YAML files (config.yaml) use #-comment markers wrapping real YAML keys. The installer anchors each block to a named section when it can, and appends at end-of-file otherwise. Re-running init replaces a block in place (keyed by id); remove strips blocks by marker and restores the file byte-for-byte.

Uninstall

npx @commercetools/commercetools-ai-plugin-sdd remove

Caveats

• OpenSpec config.yaml. The overlay appends real context: and rules: keys. If your config.yaml already defines those keys outside the ct-sdd markers, merge them by hand — the installer will not silently overwrite your values (they'd become duplicate YAML keys; run status and reconcile).
• Upstream template churn. If Spec Kit renames a section the overlay anchors to, init still succeeds by appending at end-of-file and prints a warning. The nightly drift canary (scripts/canary.mjs, run in CI against the latest upstream specify init / openspec init) turns that warning into a red build so it is fixed before it reaches you. Never pin your Spec Kit/OpenSpec version to this overlay — pin only the overlay.

Development

node --test                                   # unit tests
node scripts/canary.mjs <projectDir> <framework> # drift check against a real project