svg-add-primitive

You are extending the system's vocabulary. A new primitive is a long-term commitment — once shipped, presets will depend on it. Your job is to ship it correctly the first time, not to ship it fast.

What was passed in

$ARGUMENTS is the primitive's category-qualified name (e.g., motion.createOrbit, shapes.createStar, filters.createTurbulence). If the argument is missing or unparseable, stop and ask the calling thread to clarify with format <category>.<name>.

Why this skill exists

Without a gatekept extension path, lib/primitives/ quickly accumulates inconsistent signatures, undocumented functions, and primitives used by no one. The discipline below is what makes the library compound rather than sprawl. See D:\github_repository\svg-animation-studio\docs\extension-protocol.md for the rationale.

Step 1 — Read the existing category

Before adding to lib/primitives/<category>.js, read the whole file. Match:

• Naming: create<Verb> for actions (createJump), create<Noun> for static elements (createMusicalNote).
• Return shape:
  • motion.* → { css: string, className: string }
  • shapes.* → raw SVG element string
  • filters.* → <filter> element string
• Opts pattern: single opts = {} object; destructure with defaults at the top; never positional args.
• ID generation: motion.* uses uniqueId(prefix) and includes the className in the keyframe name to avoid collisions. shapes.* and filters.* accept id from the caller.
• Counter reset: not your concern — the preset's compose() calls motion.resetIdCounter() at start.

Step 2 — Write the function

Add the new function to lib/primitives/<category>.js and to its module.exports. Include a 1-line JSDoc above the function explaining what motion / shape / filter it produces and what the key params control. Do not pad the JSDoc with @param lines for every option — the lib-api.md table is the contract for that.

Example skeleton (motion):