commercetools-spec-driven-development

commercetools Spec-Driven Development Overlay

Makes a spec-driven development framework commercetools-aware, so every spec, plan, and task that touches commercetools loads the matching commercetools-* skill first. The framework keeps owning the workflow — this only adds commercetools rules through the surface each framework already offers for that.

Detected directory	Framework	How the overlay applies
.specify/	GitHub Spec Kit	Marker-fenced blocks in files it already has; creates no files
openspec/	OpenSpec	Marker-fenced blocks in files it already has; creates no files
_bmad/	BMad Method	Sparse override files in _bmad/custom/, the directory BMad contracts for this

Any combination present means each detected framework gets the overlay. BMad never has its installed files edited: it regenerates them on every install, so patching them would be destructive.

Workflow

1. Docs search (required, run first) — The first time you use this skill in a session you must run this before answering. It gathers the latest verified documentation as your primary grounding, filtered to the products this skill covers. Use this script for documentation search while working with this skill; the Knowledge MCP covers everything else. Always confirm details against retrieved documentation rather than the skill text alone:

node "<this skill's directory>/scripts/docs-search.mjs" \
  --query "<extract key terms from the user's question>" \
  --app-name "<host app: claude-code, claude-chat, cursor, codex, copilot — or the host's own name>" \
  --model "<current-model>" \
  --commercetools-project-key "<if known>" \
  --commercetools-region "<if known>" \
  --limit 10

Pass the commercetools project key and region (as in api.{region}.commercetools.com) only if already in your context; otherwise omit both. Never search files or ask the user for them.

Query the commercetools areas the project targets, not the framework's own terminology — those results are what let you fill in the plan's "Platform Skills Resolution" table later. This script queries the same index as the commercetools Knowledge MCP, with the product filters this skill needs — use it rather than the MCP tool while working in this skill.

1. Run the setup script (required, do the work with this) — never hand-edit the framework's files to apply the overlay; the script is idempotent and reversible, hand edits are neither:

   node scripts/setup.mjs
   

   Argument	Effect
   (none) or init	Apply the overlay to every detected framework
   status	Report what is applied; writes nothing
   remove	Strip applied blocks and delete files the overlay wrote
   --dry-run	Preview init/remove without writing
   --framework speckit|openspec|bmad	Act on one framework only
   --cwd <dir>	Target a project other than the current directory

2. Report what the script printed, and handle these outcomes:

   • No framework detected (exit 4) — tell the user to run specify init (Spec Kit), openspec init (OpenSpec), or npx bmad-method install (BMad) first, then re-run. Do not create those directories yourself.
   • A target file was skipped as missing — the framework is only partially initialized. Name the missing file; do not create it.
   • An anchor was not found — the upstream template changed, so the block was appended at end-of-file instead of at its intended heading. It still works; say the placement is not ideal.
   • Unsupported framework variant (exit 5) — the install predates the override surface the overlay needs. Relay the upgrade command the script named; do not work around the gate.
   • Rolled back (exit 6) — a written override failed the framework's own resolver and every write was reverted. Nothing is applied; report the named failure verbatim.
   • A target was skipped as not ours, validation could not run, or an override is inert because the skill is not installed — BMad-specific. None is silent, so none may go unmentioned.
   • Applied, or already up to date — state which files changed and stop.

What the overlay adds

Framework	File	Adds
Spec Kit	.specify/memory/constitution.md	Non-negotiable articles: resolve the platform skill, annotate tasks, never invent API surface
Spec Kit	.specify/templates/plan-template.md	A "Platform Skills Resolution" table mapping each architectural area to its skill
Spec Kit	.specify/templates/tasks-template.md	The [SKILL: <name>] task-grammar extension
OpenSpec	openspec/config.yaml	context: guidance plus rules: for the proposal and tasks artifacts
BMad	_bmad/custom/commercetools-spec-extension-rules.md	The three rules — resolve the skill, annotate the task, verify the API surface — loaded as a persistent fact by every override below
BMad	_bmad/custom/bmad-agent-{dev,pm,architect}.toml	Agent-scope facts and principles, inherited by every workflow that agent dispatches
BMad	_bmad/custom/bmad-{prd,architecture,spec,create-epics-and-stories}.toml	Planning-workflow facts; bmad-architecture also gets commercetools-knowledge MCP consultation and an API-surface review lens
BMad	_bmad/custom/bmad-build.toml	The [SKILL: <name>] task grammar — emitted at planning, carried to the implementation subagent via the spec's context: list

Patch-mode blocks are fenced by commercetools-spec-extension:begin / commercetools-spec-extension:end markers. Re-running init replaces a block in place rather than duplicating it, and remove restores the file to its original bytes. Write-mode files carry a commercetools-spec-extension:file marker on their first line; init replaces only files carrying it, and remove deletes only those — a same-named file the user wrote is never touched.

Checklist

• node scripts/docs-search.mjs ran first and its results were used as grounding
• The framework was initialized first (.specify/, openspec/ or _bmad/ exists)
• node scripts/setup.mjs ran and reported the blocks and files it applied
• No target was skipped as missing or as not ours, and no anchor warning went unmentioned
• For OpenSpec, config.yaml has no duplicate context: or rules: keys
• For BMad, every override validated and none was reported inert — or the user was told what to install or upgrade
• For BMad, the install is v6.4.0 or later; older ones exit 5 rather than being worked around