gdd-new-addendum

name	gdd-new-addendum
description	Scaffolds a new Phase-54 composable reference addendum for a design-system, framework, or motion library: validates the kind and the slug, defaults composes_into by kind, and writes a 4-section skeleton at reference/{systems|frameworks|motion}/<name>.md from the pure generator. Use when adding stack-specific guidance that an explore mapper should compose at spawn time and you want the frontmatter, the composes_into wiring, and the mandatory sections correct from the first commit. Activates for requests involving authoring a reference addendum, adding stack-specific mapper guidance, scaffolding a systems or frameworks or motion doc, or registering a new design-system.
argument-hint	<kind> <name>
tools	Read, Write, Bash, AskUserQuestion
user-invocable	true

{{command_prefix}}new-addendum

Role: Scaffold a contract-compliant stack addendum. Validate the kind and the name, then write reference/{systems|frameworks|motion}/<name>.md from the pure generator at scripts/lib/new-addendum.cjs. This skill writes ONE reference file. It does NOT touch reference/registry.json and does NOT run any build; it prints the exact follow-up steps instead.

An addendum is a registry entry, not a skill. Read reference/registry.json for the type:"stack-addendum" entry shape and scripts/lib/mapper-spawn.cjs for how composes_into selects an addendum at spawn time. Read one shipped example first, for instance reference/systems/tailwind.md, to match the house style.

Step 1 - Gather the fields

1. kind: the first token of $ARGUMENTS if present, else ask. Must be one of system, framework, or motion. This picks the target subdir and the default composes_into.
2. name: the second token of $ARGUMENTS if present, else ask. Must match ^[a-z0-9][a-z0-9-._]*$. The basename is also the matcher key in mapper-spawn.cjs, so it must equal the value detectStack reports for this stack (for example tailwind, nextjs, framer-motion). Reject a reference/{dir}/<name>.md collision.
3. composes_into (optional): accept the kind default, or override with a comma list of mapper names. Defaults: system to token-mapper, component-taxonomy-mapper; framework to component-taxonomy-mapper, visual-hierarchy-mapper; motion to motion-mapper.

Resolve the target path and check for a collision:

node -e "
const a = require('./scripts/lib/new-addendum.cjs');
console.log(a.targetPathFor(process.argv[1], process.argv[2]));
" "<kind>" "<name>"

If that path already exists, stop and tell the user to edit the existing file instead.

Step 2 - Write the file

Build the record and render the skeleton with the pure generator, then write it with the Write tool (not shell redirection):

node -e "
const a = require('./scripts/lib/new-addendum.cjs');
const rec = a.buildAddendumRecord({
  kind: process.env.AD_KIND,
  name: process.env.AD_NAME,
  composesInto: process.env.AD_COMPOSES || undefined,
});
process.stdout.write(a.renderAddendumMd(rec));
"

buildAddendumRecord throws on an invalid kind, an invalid name, or a malformed composes_into list. Surface the thrown message to the user and re-prompt the offending field. Capture stdout and write it verbatim to the path from Step 1 via the Write tool.

Step 3 - Fill the four sections

The skeleton ships four mandatory sections with TODO placeholders: Conventions, File patterns, Gotchas, Example output. Replace every TODO with terse vendor-checked bullets (keep the file at or under about 50 lines). Rules:

• Lead with the real vendor docs URL in the attribution comment.
• The Example output block uses ONLY the Phase 52 DesignContext schema (node types token / component / variant / state / motion-fragment / screen / layer; edge types uses-token / composes / extends / transitions-to / mirrors).
• Tags must come from reference/design-context-tag-vocab.md; drop any tag not in that vocabulary.
• For a motion addendum, reuse the reference/motion-transition-taxonomy.md duration classes (instant / quick / standard / slow / narrative) and call out the seconds-vs-ms-vs-no-duration unit trap.
• No em dashes anywhere (the lint:prose gate scans reference/).

Step 4 - Tell the user the follow-up

The skill stops here by contract. Print the next steps for the maintainer to run:

1. Add a registry entry for "<name>" to reference/registry.json
   (name addendum-<kind>-<name>, path, type "stack-addendum", phase 54, kind, composes_into, description).
2. node -e "require('./scripts/lib/reference-registry.cjs').validateRegistry({cwd:process.cwd()})"
   must report ok:true (the round-trip scan picks up the new subdir file).
3. npm test (the reference-registry + phase-54 suites must stay green).

The registry round-trip test stays red until the registry entry exists; that is expected and is the maintainer's step.

Do Not

• Do not edit reference/registry.json, package.json, or scripts/lib/manifest/skills.json.
• Do not run a build or the registry generator for the user; print the steps.
• Do not write the file with shell redirection; use the Write tool so the content is exact.
• Do not invent vendor facts; the addendum content must be vendor-checked.

NEW-ADDENDUM COMPLETE