showdar-skills 0.12.1 → 0.13.0

package/CHANGELOG.md

@@ -6,6 +6,21 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+## [0.13.0]
+
+### Added
+
+- `showdar add profile <profile>`: additive union of built-in profile primitives without replacing an existing base profile or other installed skills.
+- `showdar add workflow <name>`: install built-in workflow skills and any missing stage primitives; `showdar add feature` / `showdar add showdar-feature` remain equivalent aliases.
+- `showdar add workflow ./local.json`: convenient spelling for existing project-scoped custom workflow installation.
+
+### Changed
+
+- Additive installation preserves existing extension metadata and supports projects initialized with `--ai all`.
+- `showdar init --profile ...` retains its explicit replace semantics; existing standalone `showdar add-workflow` remains supported.
+- Added installer regression coverage for existing-skill preservation, aliases, workflow stage closure, custom workflows, foreign-path safety and re-init replacement.
+
+
 ## [0.12.1]
 
 ### Fixed

package/README.md

@@ -40,6 +40,32 @@ Claude Code as supported installation targets. Choose `backend`, `qa`, or
 `product` when that gives discovery a more precise context; use `full` when
 you want all capabilities available.
 
+## Additive installation
+
+`showdar init --profile <name>` **replaces** the Showdar-owned skill selection.
+`showdar add` always **preserves** existing skills and the selected base profile:
+
+```bash
+showdar init --profile developer --ai opencode
+showdar add git                         # same as showdar add showdar-git
+showdar add profile insurance           # union, no deletions
+showdar add workflow feature            # workflow + missing primitive stages
+showdar add workflow ./acme-release.json # standalone custom workflow, project scope
+```
+
+Both `showdar add feature` and `showdar add showdar-feature` are aliases for
+`showdar add workflow feature`, including automatic installation of missing
+primitive stage skills. All built-in profiles are additive via `add profile`;
+`init` remains the explicit replace operation. Existing workflow packs and
+custom workflow definitions are preserved when adding skills. The runtime
+router is included in the Showdar CLI and is automatically referenced by
+updated native guidance; it does not require an additional skill.
+
+Built-in workflow dependency installation does **not** execute the workflow,
+authorize source mutation, commit, merge or push. A custom workflow JSON file
+uses the existing `add-workflow` validation/manifest semantics; remote files
+and arbitrary executable plugins are unsupported.
+
 ## Runtime routing and task branches
 
 ```bash
@@ -845,6 +871,8 @@ Product behavior notes:
 ```bash
 showdar init [--scope <project|global>] --ai <target> --profile <profile>
 showdar add <skill> [--ai <target>] [--scope <project|global>]
+showdar add profile <profile> [--ai <target>] [--scope <project|global>]
+showdar add workflow <builtin-name|local-json-path> [--ai <target>] [--scope <project|global>]
 showdar add-pack <local-path>
 showdar remove-pack <name>
 showdar add-workflow <local-path>

package/bin/showdar.js

@@ -7,8 +7,8 @@ import { routeRequest, formatRoute } from '../src/runtime-route.js';
 import { homedir } from 'node:os';
 import { readFile } from 'node:fs/promises';
 import { fileURLToPath } from 'node:url';
-import { AI_TARGETS, PRIMITIVE_COUNT, PROFILE_ALIASES, PROFILES, SKILLS, TOTAL_COUNT, WORKFLOW_COUNT, canonicalProfile, isDeprecatedProfile, resolveProfile } from '../src/catalog.js';
-import { addPack, addSkill, addWorkflow, globalManifestPath, initGlobal, initProject, inspectGlobal, inspectProject, listExtensions, listExtensionsDetailed, removeGlobal, removePack, removeProject, validatePackSource, createPack, inspectPack, doctor, updatePack, readProjectOverrides } from '../src/project.js';
+import { AI_TARGETS, PRIMITIVE_COUNT, PROFILE_ALIASES, PROFILES, SKILLS, TOTAL_COUNT, WORKFLOW_COUNT, canonicalProfile, isDeprecatedProfile, resolveProfile, getWorkflow, normalizeSkillName } from '../src/catalog.js';
+import { addPack, addSkill, addSkills, addWorkflow, globalManifestPath, initGlobal, initProject, inspectGlobal, inspectProject, listExtensions, listExtensionsDetailed, removeGlobal, removePack, removeProject, validatePackSource, createPack, inspectPack, doctor, updatePack, readProjectOverrides } from '../src/project.js';
 import { formatPlanPreviewHuman, projectPackUpdatePreview } from '../src/pack-plan.js';
 import { assessCheckpointAgainstCandidate } from '../src/pack-inspect.js';
 import { validateRepository } from '../src/validate.js';
@@ -58,10 +58,10 @@ function printHelp(version, command = null) {
     return;
   }
   if (command === 'add') {
-    console.log(`Showdar Skills ${version}\n\nUsage:\n  showdar add <skill> [--ai <universal|codex|opencode|cursor|claude>] [--scope <project|global>]\n\nExamples:\n  showdar add debug\n  showdar add showdar-security\n  showdar add test --ai cursor\n  showdar add review --scope global --ai claude\n\nDefault scope: project. Default AI target: universal, or the configured .showdar.json value when present.`);
+    console.log(`Showdar Skills ${version}\n\nUsage:\n  showdar add <skill> [--ai <target>] [--scope <project|global>]\n  showdar add profile <profile> [--ai <target>] [--scope <project|global>]\n  showdar add workflow <builtin-name|local-json-path> [--ai <target>] [--scope <project|global>]\n\nExamples:\n  showdar add git\n  showdar add showdar-git\n  showdar add profile insurance\n  showdar add workflow feature\n  showdar add workflow ./workflows/acme-release.json\n\nAdd preserves installed skills; init replaces the managed set. Built-in workflows add required stages.`);
     return;
   }
-  console.log(`Showdar Skills ${version}\n\nUsage:\n  showdar init ${scopeUsage} [--profile <name>] [--ai <universal|codex|opencode|cursor|claude|all>] [--pack <local-path>]\n  showdar add <skill> [--ai <universal|codex|opencode|cursor|claude>] [--scope <project|global>]\n  showdar route (--stdin | --prompt <text>) [--json]\n  showdar git-start --type <type> --name <task> [--base <branch>] [--dry-run] [--json]\n  showdar guard --mutation <read-only|local-write> [--json]\n  showdar add-pack <local-path>\n  showdar remove-pack <name>\n  showdar add-workflow <local-path>\n  showdar status ${scopeUsage}\n  showdar doctor ${scopeUsage}\n  showdar validate\n  showdar list [--extensions]\n  showdar remove ${scopeUsage}\n  showdar create-pack <path> [--vendor <vendor>] [--description <text>] [--with-workflow <id>] [--with-profile <name>]\n  showdar validate-pack <local-path> [--json]\n  showdar inspect-pack <local-path> [--json] [--checkpoint <file>]\n  showdar doctor ${scopeUsage} [--extensions] [--json]\n  showdar update-pack <local-path> [--dry-run] [--json]\n  showdar validate\n  showdar list [--extensions] [--json]\n  showdar remove ${scopeUsage}\n\nExtension packs accept local directories/workspace paths only; tarball, URL, Git, and registry sources are rejected.\n\nDefaults: scope project, profile full, AI target universal.\nProfiles: ${Object.keys(PROFILES).join(', ')}\nDeprecated aliases: ${Object.entries(PROFILE_ALIASES).map(([alias, target]) => `${alias} -> ${target}`).join(', ')}\nAI targets: ${AI_TARGETS.join(', ')}`);
+  console.log(`Showdar Skills ${version}\n\nUsage:\n  showdar init ${scopeUsage} [--profile <name>] [--ai <universal|codex|opencode|cursor|claude|all>] [--pack <local-path>]\n  showdar add <skill> [--ai <target>] [--scope <project|global>]\n  showdar add profile <profile> [--ai <target>] [--scope <project|global>]\n  showdar add workflow <builtin-name|local-json-path> [--ai <target>] [--scope <project|global>]\n  showdar route (--stdin | --prompt <text>) [--json]\n  showdar git-start --type <type> --name <task> [--base <branch>] [--dry-run] [--json]\n  showdar guard --mutation <read-only|local-write> [--json]\n  showdar add-pack <local-path>\n  showdar remove-pack <name>\n  showdar add-workflow <local-path>\n  showdar status ${scopeUsage}\n  showdar doctor ${scopeUsage}\n  showdar validate\n  showdar list [--extensions]\n  showdar remove ${scopeUsage}\n  showdar create-pack <path> [--vendor <vendor>] [--description <text>] [--with-workflow <id>] [--with-profile <name>]\n  showdar validate-pack <local-path> [--json]\n  showdar inspect-pack <local-path> [--json] [--checkpoint <file>]\n  showdar doctor ${scopeUsage} [--extensions] [--json]\n  showdar update-pack <local-path> [--dry-run] [--json]\n  showdar validate\n  showdar list [--extensions] [--json]\n  showdar remove ${scopeUsage}\n\nExtension packs accept local directories/workspace paths only; tarball, URL, Git, and registry sources are rejected.\n\nDefaults: scope project, profile full, AI target universal.\nProfiles: ${Object.keys(PROFILES).join(', ')}\nDeprecated aliases: ${Object.entries(PROFILE_ALIASES).map(([alias, target]) => `${alias} -> ${target}`).join(', ')}\nAI targets: ${AI_TARGETS.join(', ')}`);
 }
 
 async function main() {
@@ -242,20 +242,49 @@ async function main() {
   }
 
   if (command === 'add') {
-    const positional = args.filter((a, i) => i > 0 && !a.startsWith('--') && args[i - 1] !== '--ai' && args[i - 1] !== '--scope');
-    const skillArg = positional[0];
-    if (!skillArg) throw new Error('Skill name is required. Usage: showdar add <skill> [--ai <target>] [--scope <project|global>]');
+    const positional = args.filter((arg, index) => index > 0 && !arg.startsWith('--') && args[index - 1] !== '--ai' && args[index - 1] !== '--scope');
+    const kind = positional[0];
+    if (!kind) throw new Error('Usage: showdar add <skill> | profile <profile> | workflow <builtin-name|local-json-path>');
     const hasAiFlag = args.includes('--ai');
     const hasScopeFlag = args.includes('--scope');
-    const result = await addSkill({
+    const options = {
       cwd: projectRoot,
-      skill: skillArg,
       ai: hasAiFlag ? valueAfter(args, '--ai', 'universal') : null,
       scope: hasScopeFlag ? scope : null,
       home: homedir(),
       packageRoot,
       packageVersion: version,
-    });
+    };
+    if (kind === 'profile') {
+      if (positional.length !== 2) throw new Error('Usage: showdar add profile <profile> [--ai <target>] [--scope <project|global>]');
+      const profileName = positional[1];
+      const selected = resolveProfile(profileName);
+      const result = await addSkills({ ...options, skills: selected });
+      if (isDeprecatedProfile(profileName)) console.warn(`Warning: profile "${profileName}" is deprecated; use "${canonicalProfile(profileName)}".`);
+      console.log(`Showdar profile added.\nAdded profile: ${canonicalProfile(profileName)}\nNew skills: ${result.added}\nAlready installed: ${result.alreadyInstalled}\nTotal requested: ${result.skills.length}\nExisting profile preserved: ${result.profile ?? '(none)'}\nScope: ${result.scope}\nAI: ${result.ai}`);
+      return;
+    }
+    const installBuiltinWorkflow = async workflow => {
+      const result = await addSkills({ ...options, skills: [workflow.id, ...workflow.stages] });
+      console.log(`Showdar workflow added.\nWorkflow: ${workflow.id}\nNew skills: ${result.added}\nAlready installed: ${result.alreadyInstalled}\nRequired stage skills: ${workflow.stages.join(', ')}\nScope: ${result.scope}\nAI: ${result.ai}`);
+    };
+    if (kind === 'workflow') {
+      if (positional.length !== 2) throw new Error('Usage: showdar add workflow <builtin-name|local-json-path>');
+      const name = positional[1];
+      const builtin = getWorkflow(name.startsWith('showdar-') ? name : `showdar-${name}`);
+      if (builtin) return installBuiltinWorkflow(builtin);
+      if (!name.endsWith('.json')) throw new Error(`Unknown built-in workflow "${name}". For custom workflows provide a local JSON file.`);
+      if (hasAiFlag || (hasScopeFlag && scope !== 'project')) {
+        throw new Error('Custom workflow files support project scope only and do not accept --ai.');
+      }
+      const result = await addWorkflow({ cwd: projectRoot, source: name });
+      console.log(`Showdar custom workflow added.\nWorkflow: ${result.workflow}\nPath: ${result.path}`);
+      return;
+    }
+    if (positional.length !== 1) throw new Error('Usage: showdar add <skill> [--ai <target>] [--scope <project|global>]');
+    const workflow = getWorkflow(normalizeSkillName(kind));
+    if (workflow) return installBuiltinWorkflow(workflow);
+    const result = await addSkill({ ...options, skill: kind });
     console.log(`Showdar skill ${result.added ? 'added' : 'already installed'}.\nSkill: ${result.skill}\nScope: ${result.scope}\nAI: ${result.ai}\nPath: ${result.destination}`);
     return;
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "showdar-skills",
-  "version": "0.12.1",
+  "version": "0.13.0",
   "description": "Production-grade software engineering lifecycle skills for coding agents.",
   "type": "module",
   "bin": {

package/src/project.js

@@ -584,7 +584,7 @@ export async function addSkill({ cwd, skill, ai = null, scope = null, home = hom
 
   const effectiveAi = ai ?? existingManifest?.ai ?? 'universal';
   const effectiveScope = scope ?? existingManifest?.scope ?? 'project';
-  if (!NATIVE_TARGETS.includes(effectiveAi)) throw new Error(`Unknown AI target "${effectiveAi}".`);
+  if (effectiveAi !== 'all' && !NATIVE_TARGETS.includes(effectiveAi)) throw new Error(`Unknown AI target "${effectiveAi}".`);
   if (effectiveScope !== 'project' && effectiveScope !== 'global') throw new Error(`Unknown scope "${effectiveScope}".`);
 
   if (existingManifest?.skills?.includes(skillId)) {
@@ -633,10 +633,7 @@ export async function addSkill({ cwd, skill, ai = null, scope = null, home = hom
     return { skill: skillId, root: '', destination: '', added: false, scope: effectiveScope, ai: effectiveAi, profile: existingManifest.profile };
   }
 
-  const root = effectiveScope === 'global'
-    ? globalSkillRootFor(effectiveAi, { homeRoot: home })
-    : skillRootFor(effectiveAi, cwd);
-  const destination = path.join(root, skillId);
+  const targets = resolveTargets(effectiveAi);
   const managedRoots = effectiveScope === 'global'
     ? [...new Set([
         ...NATIVE_TARGETS.map((t) => globalSkillRootFor(t, { homeRoot: home })),
@@ -644,30 +641,38 @@ export async function addSkill({ cwd, skill, ai = null, scope = null, home = hom
       ])]
     : [];
   const manifestPath = effectiveScope === 'global' ? globalManifestPath(home) : path.join(cwd, PROJECT_MANIFEST);
-
   const source = path.join(packageRoot, 'skills', skillId);
   if (!(await exists(path.join(source, 'SKILL.md')))) throw new Error(`Packaged skill source missing: ${skillId}`);
 
   await mkdir(baseRoot, { recursive: true });
   const priorOwned = ownedPathSet(existingManifest);
-  const relative = manifestPathFor(baseRoot, destination);
-  const existed = await exists(destination);
-  const alreadyTracked = priorOwned.has(relative);
-
   const files = [];
-  await copyOwned({ baseRoot, source, destination, priorOwned, newFiles: files, managedRoots });
+  const destinations = [...new Set(targets.map(target => effectiveScope === 'global'
+    ? globalSkillRootFor(target, { homeRoot: home })
+    : skillRootFor(target, cwd)))].map(root => path.join(root, skillId));
+  const alreadyInstalled = destinations.every(destination =>
+    priorOwned.has(manifestPathFor(baseRoot, destination)));
+
+  // Inspect every target before copying anything. Never overwrite foreign skills.
+  for (const destination of destinations) {
+    await assertSafeManagedPath(baseRoot, destination, managedRoots);
+    const relative = manifestPathFor(baseRoot, destination);
+    if ((await exists(destination)) && !priorOwned.has(relative)) {
+      throw new Error(`Refusing to overwrite existing non-Showdar-managed skill or command: ${destination}`);
+    }
+  }
+  for (const destination of destinations) {
+    await copyOwned({ baseRoot, source, destination, priorOwned, newFiles: files, managedRoots });
+  }
 
-  const targets = [effectiveAi];
   const commandHarnesses = [];
   for (const target of targets) {
     const adapter = ADAPTERS[target];
     if (adapter?.commands?.destination) {
-      if (effectiveScope === 'project') {
-        commandHarnesses.push({ target, root: commandRootFor(target, cwd) });
-      } else {
-        const globalRoot = globalCommandRootForTarget(target, { homeRoot: home });
-        if (globalRoot) commandHarnesses.push({ target, root: globalRoot });
-      }
+      const root = effectiveScope === 'project'
+        ? commandRootFor(target, cwd)
+        : globalCommandRootForTarget(target, { homeRoot: home });
+      if (root) commandHarnesses.push({ target, root });
     }
   }
 
@@ -684,10 +689,11 @@ export async function addSkill({ cwd, skill, ai = null, scope = null, home = hom
   const merged = new Map((existingManifest?.files ?? []).map((e) => [e.path, e]));
   for (const f of files) merged.set(f.path, f);
 
-  const instructionFile = existingManifest?.instructions ?? (effectiveScope === 'project' ? instructionSurfaceFor(effectiveAi, cwd) : null);
+  const instructionFile = existingManifest?.instructions ?? (effectiveScope === 'project' ? instructionSurfaceFor(effectiveAi === 'all' ? 'universal' : effectiveAi, cwd) : null);
   const commandHarness = [...new Set([...(existingManifest?.commandHarness ?? []), ...commandHarnesses.map((c) => c.target)])];
 
   const manifest = {
+    ...(existingManifest ?? {}),
     version: existingManifest?.version ?? 2,
     scope: effectiveScope,
     packageVersion,
@@ -713,7 +719,55 @@ export async function addSkill({ cwd, skill, ai = null, scope = null, home = hom
     }
   }
 
-  return { skill: skillId, root, destination, added: !alreadyTracked || !existed, scope: effectiveScope, ai: effectiveAi, profile: manifest.profile };
+  return { skill: skillId, root: path.dirname(destinations[0]), destination: destinations[0], added: !alreadyInstalled, scope: effectiveScope, ai: effectiveAi, profile: manifest.profile };
+}
+
+
+/**
+ * Additive profile/workflow member install. Existing project profile and any
+ * extra extension metadata are preserved. Requested members are deduplicated.
+ * Each member uses the standard single-skill installer and remains rerunnable.
+ */
+export async function addSkills({ cwd, skills, ai = null, scope = null, home = homedir(), packageRoot, packageVersion = '0.2.0' }) {
+  if (!Array.isArray(skills) || !skills.length) throw new Error('At least one skill is required.');
+  const skillIds = [...new Set(skills.map(normalizeSkillName))];
+  const baseRoot = scope === 'global' ? home : cwd;
+  const manifestPath = scope === 'global' ? globalManifestPath(home) : path.join(cwd, PROJECT_MANIFEST);
+  const existing = await readManifest(manifestPath, baseRoot);
+  const effectiveAi = ai ?? existing?.ai ?? 'universal';
+  const targets = resolveTargets(effectiveAi);
+  const owned = ownedPathSet(existing);
+  const managedRoots = scope === 'global'
+    ? [...new Set(NATIVE_TARGETS.map(target => globalSkillRootFor(target, { homeRoot: home })))]
+    : [];
+  // Preflight packaged inputs and all requested target paths before writing.
+  for (const skillId of skillIds) {
+    const source = path.join(packageRoot, 'skills', skillId, 'SKILL.md');
+    if (!(await exists(source))) throw new Error(`Packaged skill source missing: ${skillId}`);
+    for (const target of targets) {
+      const skillRoot = scope === 'global'
+        ? globalSkillRootFor(target, { homeRoot: home })
+        : skillRootFor(target, cwd);
+      const destination = path.join(skillRoot, skillId);
+      await assertSafeManagedPath(baseRoot, destination, managedRoots);
+      const relative = manifestPathFor(baseRoot, destination);
+      if ((await exists(destination)) && !owned.has(relative)) {
+        throw new Error(`Refusing to overwrite existing non-Showdar-managed skill or command: ${destination}`);
+      }
+    }
+  }
+  const installed = [];
+  for (const skill of skillIds) {
+    installed.push(await addSkill({ cwd, skill, ai, scope, home, packageRoot, packageVersion }));
+  }
+  return {
+    skills: skillIds,
+    added: installed.filter(entry => entry.added).length,
+    alreadyInstalled: installed.filter(entry => !entry.added).length,
+    profile: installed.at(-1)?.profile ?? existing?.profile ?? null,
+    ai: installed.at(-1)?.ai ?? effectiveAi,
+    scope: installed.at(-1)?.scope ?? scope ?? existing?.scope ?? 'project',
+  };
 }
 
 export async function removeProject(projectRoot) {