universal-dev-standards 6.15.0 → 6.16.0-beta.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (41) hide show
  1. package/bin/uds.js +2 -0
  2. package/bundled/locales/zh-CN/CHANGELOG.md +34 -4
  3. package/bundled/locales/zh-CN/CLAUDE.md +2 -2
  4. package/bundled/locales/zh-CN/README.md +17 -14
  5. package/bundled/locales/zh-CN/SECURITY.md +1 -0
  6. package/bundled/locales/zh-CN/docs/CHEATSHEET.md +1 -1
  7. package/bundled/locales/zh-CN/docs/CLI-INIT-OPTIONS.md +24 -2
  8. package/bundled/locales/zh-CN/docs/FEATURE-REFERENCE.md +3 -1
  9. package/bundled/locales/zh-TW/CHANGELOG.md +34 -4
  10. package/bundled/locales/zh-TW/CLAUDE.md +2 -2
  11. package/bundled/locales/zh-TW/README.md +17 -14
  12. package/bundled/locales/zh-TW/SECURITY.md +1 -0
  13. package/bundled/locales/zh-TW/docs/CHEATSHEET.md +1 -1
  14. package/bundled/locales/zh-TW/docs/CLI-INIT-OPTIONS.md +24 -2
  15. package/bundled/locales/zh-TW/docs/FEATURE-REFERENCE.md +3 -1
  16. package/package.json +3 -3
  17. package/src/commands/skills.js +9 -0
  18. package/src/commands/update.js +223 -2
  19. package/src/reconciler/desired-state-calculator.js +11 -2
  20. package/src/utils/optional-skills-report.js +86 -0
  21. package/src/utils/optional-skills.js +20 -0
  22. package/src/utils/skill-selection.js +137 -0
  23. package/src/utils/skills-installer.js +11 -4
  24. package/standards-registry.json +7 -7
  25. package/src/core/agent-communication-protocol.js +0 -257
  26. package/src/flow/condition-evaluator.js +0 -86
  27. package/src/flow/flow-bundler.js +0 -80
  28. package/src/flow/flow-commands.js +0 -107
  29. package/src/flow/flow-engine.js +0 -154
  30. package/src/flow/flow-inheritance.js +0 -100
  31. package/src/flow/flow-parser.js +0 -104
  32. package/src/flow/flow-validator.js +0 -37
  33. package/src/flow/gate-checker.js +0 -82
  34. package/src/flow/gate-loader.js +0 -52
  35. package/src/missions/MissionManager.js +0 -533
  36. package/src/utils/e2e-analyzer.js +0 -471
  37. package/src/utils/e2e-detector.js +0 -132
  38. package/src/utils/hook-stats.js +0 -151
  39. package/src/utils/workflow-executor.js +0 -870
  40. package/src/utils/workflows-installer.js +0 -545
  41. package/src/vibe/auto-sweep.js +0 -349
@@ -3,7 +3,7 @@ import { createSpinner } from '../utils/spinner.js';
3
3
  import { flushAndExit } from '../utils/flush-and-exit.js';
4
4
  import { select, confirm as inquirerConfirm, checkbox, Separator } from '@inquirer/prompts';
5
5
  import { execSync } from 'child_process';
6
- import { existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync } from 'fs';
6
+ import { existsSync, mkdirSync, readFileSync, rmSync, unlinkSync, writeFileSync } from 'fs';
7
7
  import { join, basename, dirname, relative } from 'path';
8
8
  import { readManifest, writeManifest, copyStandard, copyExtension, isInitialized, getRepoRoot } from '../utils/copier.js';
9
9
  import { getRepositoryInfo, getAllStandards, getShippableFilenames, getStandardSource } from '../utils/registry.js';
@@ -39,6 +39,7 @@ import { commandsUpdatedMessage } from '../utils/update-summary.js';
39
39
  import { t, setLanguage, isLanguageExplicitlySet } from '../i18n/messages.js';
40
40
  import { config } from '../utils/config-manager.js';
41
41
  import {
42
+ getAvailableSkillNames,
42
43
  installSkillsToMultipleAgents,
43
44
  installCommandsToMultipleAgents,
44
45
  deduplicateInstallations,
@@ -58,6 +59,8 @@ import {
58
59
  } from '../config/ai-agent-paths.js';
59
60
  import { getMarketplaceSkillsInfo } from '../utils/github.js';
60
61
  import { printSkillNameCollisionWarning } from '../utils/skill-name-collision.js';
62
+ import { OPTIONAL_SKILLS, readSkillChoices, resolveSkillName, skillDisplayName } from '../utils/skill-selection.js';
63
+ import { printOptionalSkillsSection, fileBasedSkillInstallations } from '../utils/optional-skills-report.js';
61
64
  import { detectAITools } from '../utils/detector.js';
62
65
  import { HOOK_CAPABLE_TOOLS, resolveHookTools, installMissingHooks, diffHookScripts, replaceStaleHookScripts } from '../installers/hooks-installer.js';
63
66
  import { persistRecorder, mergeRecorderInto, newRecorder } from '../core/install-records.js';
@@ -88,7 +91,8 @@ import {
88
91
  forgetFileProvenance,
89
92
  establishProvenance,
90
93
  isProvenanceEstablished,
91
- bumpManifestVersion
94
+ bumpManifestVersion,
95
+ MARKETPLACE_NAMES_SENTINEL
92
96
  } from '../core/manifest.js';
93
97
 
94
98
  /**
@@ -474,6 +478,16 @@ export async function updateCommand(options) {
474
478
  addStandards = request.ids;
475
479
  }
476
480
 
481
+ // Issue #298: `--add-skill <name>` / `--remove-skill <name>` (repeatable) add or remove ONE skill, in every
482
+ // tool folder the project has, and record the choice so no later update undoes it. Judged here, before any mode
483
+ // runs, so an unknown name stops everything instead of being skipped.
484
+ const addSkillNames = [].concat(options.addSkill || []);
485
+ const removeSkillNames = [].concat(options.removeSkill || []);
486
+ if (addSkillNames.length > 0 || removeSkillNames.length > 0) {
487
+ const outcome = await applySkillChoices(projectPath, manifest, options, addSkillNames, removeSkillNames);
488
+ if (!outcome.carryOn) return;
489
+ }
490
+
477
491
  // Handle --claude-target option (XSPEC-418 R4): switch an EXISTING
478
492
  // installation's claude-code integration target between CLAUDE.md and
479
493
  // CLAUDE.local.md, without a full reinstall. Standalone, like --sync-refs
@@ -2783,6 +2797,204 @@ function reportStaleSkillsCommandsHint(projectPath, manifest) {
2783
2797
  console.log();
2784
2798
  }
2785
2799
 
2800
+ /**
2801
+ * `--add-skill <name>` / `--remove-skill <name>` (issue #298): put ONE skill into, or take it out of, every
2802
+ * tool folder this project has, and record the choice in the manifest so no later `uds update` (plain, `--apply`,
2803
+ * `--skills`) undoes it.
2804
+ *
2805
+ * manifest.skills.extra optional skills the project asked for
2806
+ * manifest.skills.excluded skills the project does not want (any skill, not only the optional ones)
2807
+ *
2808
+ * Alone it is a whole command: it does that and stops. Combined with `--apply` / `--force` / `--skills` /
2809
+ * `--commands` / `--standards-only` it does that first and then lets the rest run (on the same manifest object,
2810
+ * so the later steps carry the choice instead of overwriting it). `--plan` writes nothing and says what would happen.
2811
+ *
2812
+ * A user-level folder (`~/.claude/skills`) is shared by every project on the machine, so a removal leaves it
2813
+ * alone and says where it is; the choice still stops this project's updates from writing there.
2814
+ *
2815
+ * @returns {Promise<{carryOn: boolean}>} carryOn: the caller may go on to the other modes/scopes
2816
+ */
2817
+ async function applySkillChoices(projectPath, manifest, options, addNames, removeNames) {
2818
+ const stop = (message) => {
2819
+ console.log(chalk.red(message));
2820
+ console.log();
2821
+ process.exitCode = 1;
2822
+ return { carryOn: false };
2823
+ };
2824
+
2825
+ for (const [key, flag] of [['rollback', '--rollback'], ['claudeTarget', '--claude-target'], ['withHooks', '--with-hooks'],
2826
+ ['syncRefs', '--sync-refs'], ['integrationsOnly', '--integrations-only']]) {
2827
+ if (options[key]) return stop(`--add-skill / --remove-skill cannot be combined with ${flag}: run them as separate commands.`);
2828
+ }
2829
+
2830
+ // Judge every name first; one bad name stops the run before anything is written.
2831
+ const shipped = getAvailableSkillNames();
2832
+ const toAdd = [];
2833
+ const toRemove = [];
2834
+ const unknown = [];
2835
+ let available = [];
2836
+ for (const [list, names] of [[toAdd, addNames], [toRemove, removeNames]]) {
2837
+ for (const raw of names) {
2838
+ const found = resolveSkillName(raw, shipped);
2839
+ if (found.folder) {
2840
+ if (!list.includes(found.folder)) list.push(found.folder);
2841
+ } else {
2842
+ unknown.push({ raw, reason: found.error });
2843
+ available = found.available;
2844
+ }
2845
+ }
2846
+ }
2847
+ if (unknown.length > 0) {
2848
+ for (const u of unknown) {
2849
+ console.log(chalk.red(u.reason === 'ambiguous'
2850
+ ? `'${u.raw}' names more than one skill; use the folder name.`
2851
+ : `Unknown skill '${u.raw}'. UDS does not ship a skill with that name.`));
2852
+ }
2853
+ console.log(chalk.gray(' Skills you can name (skill name, with the folder name in brackets when it differs):'));
2854
+ console.log(chalk.gray(` ${available.join(', ')}`));
2855
+ console.log();
2856
+ process.exitCode = 1;
2857
+ return { carryOn: false };
2858
+ }
2859
+ const both = toAdd.filter((f) => toRemove.includes(f));
2860
+ if (both.length > 0) return stop(`'${skillDisplayName(both[0])}' is named by both --add-skill and --remove-skill; pick one.`);
2861
+
2862
+ const skills = manifest.skills || {};
2863
+ const installations = fileBasedSkillInstallations(manifest);
2864
+ if (installations.length === 0 && ((skills.installations || []).some((i) => i.level === 'marketplace') || (skills.names || []).includes(MARKETPLACE_NAMES_SENTINEL))) {
2865
+ return stop('This project\'s skills come from the Claude Code plugin marketplace, which installs them as one set; --add-skill / --remove-skill choose per skill for skills UDS writes into folders.');
2866
+ }
2867
+
2868
+ const label = (folder) => {
2869
+ const name = skillDisplayName(folder);
2870
+ return name === folder ? folder : `${name} (${folder})`;
2871
+ };
2872
+ const dirOf = ({ agent, level }) => getSkillsDirForAgent(agent, level || 'project', projectPath);
2873
+ const isInsideProject = (dir) => {
2874
+ const rel = relative(projectPath, dir).replace(/\\/g, '/');
2875
+ return rel !== '' && !rel.startsWith('..') && !/^[a-zA-Z]:/.test(rel) && !rel.startsWith('/');
2876
+ };
2877
+ const toolName = (inst) => getAgentDisplayName(inst.agent) || inst.agent;
2878
+
2879
+ console.log(chalk.bold(options.plan ? 'Skill choices - plan (nothing is written)' : 'Skill choices'));
2880
+ if (installations.length === 0) {
2881
+ console.log(chalk.gray(' No skill folders are recorded for this project; the choice is recorded for when skills are installed.'));
2882
+ }
2883
+
2884
+ // ── plan: say what would happen, write nothing ─────────────────────
2885
+ if (options.plan) {
2886
+ for (const folder of toAdd) {
2887
+ const where = installations.map((i) => `${toolName(i)} (${dirOf(i) ?? 'no folder'})`).join(', ');
2888
+ console.log(chalk.cyan(` + would add ${label(folder)}${where ? ` to ${where}` : ''}`));
2889
+ }
2890
+ for (const folder of toRemove) {
2891
+ const present = installations.filter((i) => { const d = dirOf(i); return d && existsSync(join(d, folder)); });
2892
+ console.log(chalk.yellow(` - would remove ${label(folder)}${present.length ? ` from ${present.map((i) => `${toolName(i)} (${dirOf(i)})`).join(', ')}` : ' (not on disk in any tool folder)'}, and record it so no update installs it`));
2893
+ }
2894
+ console.log();
2895
+ console.log(chalk.gray(` Apply with: uds update${toAdd.map((f) => ` --add-skill ${skillDisplayName(f)}`).join('')}${toRemove.map((f) => ` --remove-skill ${skillDisplayName(f)}`).join('')}`));
2896
+ console.log();
2897
+ return { carryOn: false };
2898
+ }
2899
+
2900
+ // ── apply ──────────────────────────────────────────────────────────
2901
+ const backup = installations.length > 0 ? takeStepBackup(projectPath, 'skills', installations, 'skills') : { ok: true, none: true };
2902
+ if (!backup.ok) {
2903
+ process.exitCode = 1;
2904
+ return { carryOn: false };
2905
+ }
2906
+
2907
+ const { extra, excluded } = readSkillChoices(manifest);
2908
+ manifest.skills = manifest.skills || {};
2909
+ let failed = false;
2910
+
2911
+ for (const folder of toRemove) {
2912
+ excluded.add(folder);
2913
+ extra.delete(folder);
2914
+ const removedFrom = [];
2915
+ const keptShared = [];
2916
+ for (const inst of installations) {
2917
+ const dir = dirOf(inst);
2918
+ if (!dir || !existsSync(join(dir, folder))) continue;
2919
+ if (!isInsideProject(dir)) {
2920
+ keptShared.push(join(dir, folder));
2921
+ continue;
2922
+ }
2923
+ try {
2924
+ rmSync(join(dir, folder), { recursive: true, force: true });
2925
+ removedFrom.push(`${toolName(inst)} (${dir})`);
2926
+ for (const key of Object.keys(manifest.skillHashes || {})) {
2927
+ if (key.startsWith(`${inst.agent}/${inst.level || 'project'}/${folder}/`)) delete manifest.skillHashes[key];
2928
+ }
2929
+ } catch (err) {
2930
+ failed = true;
2931
+ console.log(chalk.red(` x could not remove ${join(dir, folder)}: ${err.message}`));
2932
+ }
2933
+ }
2934
+ if (Array.isArray(manifest.skills.names)) manifest.skills.names = manifest.skills.names.filter((n) => n !== folder);
2935
+ console.log(chalk.green(` - removed ${label(folder)}${removedFrom.length ? ` from ${removedFrom.join(', ')}` : ' (it was not on disk in any tool folder)'}`));
2936
+ for (const shared of keptShared) {
2937
+ console.log(chalk.yellow(` kept ${shared}: a user-level folder is shared by every project on this machine. Delete it yourself if you want it gone everywhere.`));
2938
+ }
2939
+ console.log(chalk.gray(` recorded in the manifest (skills.excluded); no later update installs it. Undo: uds update --add-skill ${skillDisplayName(folder)}`));
2940
+ }
2941
+
2942
+ if (toAdd.length > 0) {
2943
+ for (const folder of toAdd) {
2944
+ excluded.delete(folder);
2945
+ if (OPTIONAL_SKILLS[folder]) extra.add(folder);
2946
+ }
2947
+ if (installations.length > 0) {
2948
+ // The tool folder's `.manifest.json` says which UDS version the folder was written by. Writing one skill
2949
+ // must not make the others look current, so what it said before is put back afterwards.
2950
+ const bookkeeping = installations.filter((inst) => dirOf(inst)).map((inst) => join(dirOf(inst), '.manifest.json'));
2951
+ const before = bookkeeping.map((f) => (f && existsSync(f) ? readFileSync(f, 'utf-8') : null));
2952
+ const locale = resolveLocale(manifest, projectPath, options);
2953
+ const result = await installSkillsToMultipleAgents(installations, toAdd, projectPath, locale); // wire:add-skill-installs
2954
+ bookkeeping.forEach((f, i) => { if (before[i] !== null) writeFileSync(f, before[i]); });
2955
+ replaceSkillHashesForInstalled(manifest, result);
2956
+ manifest.skills.names = mergeInstalledNames(manifest.skills.names, result);
2957
+ if (!result.success) failed = true;
2958
+ for (const folder of toAdd) {
2959
+ const tools = result.installations.filter((r) => (r.installed || []).includes(folder)).map((r) => `${getAgentDisplayName(r.agent) || r.agent} (${r.targetDir})`);
2960
+ console.log(tools.length > 0
2961
+ ? chalk.green(` + added ${label(folder)} to ${tools.join(', ')}`)
2962
+ : chalk.red(` x could not add ${label(folder)}`));
2963
+ }
2964
+ for (const inst of result.installations) {
2965
+ for (const err of inst.errors || []) console.log(chalk.red(` ${inst.agent}: ${err.skill}: ${err.error}`));
2966
+ }
2967
+ } else {
2968
+ for (const folder of toAdd) console.log(chalk.green(` + ${label(folder)} will be installed when skills are installed for this project`));
2969
+ }
2970
+ for (const folder of toAdd) {
2971
+ console.log(chalk.gray(` ${OPTIONAL_SKILLS[folder] ? 'recorded in the manifest (skills.extra)' : 'no longer excluded'}; updates keep it. Undo: uds update --remove-skill ${skillDisplayName(folder)}`));
2972
+ }
2973
+ }
2974
+
2975
+ // Write the lists. An empty list is dropped, so a project that never chose anything keeps the manifest it had.
2976
+ for (const [key, set] of [['extra', extra], ['excluded', excluded]]) {
2977
+ if (set.size > 0) manifest.skills[key] = [...set].sort();
2978
+ else delete manifest.skills[key];
2979
+ }
2980
+
2981
+ // Re-read before writing, as `updateSkillsOnly` does, and carry over only the fields this step owns.
2982
+ const fresh = readManifest(projectPath) || manifest;
2983
+ fresh.skills = manifest.skills;
2984
+ fresh.skillHashes = manifest.skillHashes;
2985
+ writeManifest(fresh, projectPath);
2986
+ if (!backup.none) finishStepBackup(projectPath, backup);
2987
+ console.log();
2988
+ printOptionalSkillsSection(manifest, projectPath);
2989
+
2990
+ if (failed) {
2991
+ process.exitCode = 1;
2992
+ return { carryOn: false };
2993
+ }
2994
+ const carryOn = Boolean(options.apply || options.force || options.skills || options.commands || options.standardsOnly);
2995
+ return { carryOn };
2996
+ }
2997
+
2786
2998
  async function planSkills(projectPath, manifest, options) {
2787
2999
  const repoInfo = getRepositoryInfo();
2788
3000
  const latestVersion = repoInfo.skills.version;
@@ -2828,6 +3040,7 @@ async function planSkills(projectPath, manifest, options) {
2828
3040
  console.log(chalk.gray(` Locale that would be used: ${resolveLocale(manifest, projectPath, options)}`));
2829
3041
  console.log(chalk.gray(' Run `uds update --apply --yes --skills` to apply.'));
2830
3042
  console.log();
3043
+ printOptionalSkillsSection(manifest, projectPath);
2831
3044
  }
2832
3045
 
2833
3046
  /**
@@ -3117,6 +3330,7 @@ async function updateSkillsOnly(projectPath, manifest, options, { chained = fals
3117
3330
  // XSPEC-465 R1: a personal skill with the same name as one of the UDS skills just written wins silently.
3118
3331
  // Information only: it does not change what was installed or the exit code.
3119
3332
  printSkillNameCollisionWarning(projectPath);
3333
+ printOptionalSkillsSection(manifest, projectPath);
3120
3334
  return endScope(0, chained);
3121
3335
  }
3122
3336
 
@@ -4005,6 +4219,8 @@ async function handlePlan(projectPath, options, manifest, addStandards = []) {
4005
4219
  // the plan is final and nothing above reads it.
4006
4220
  printAvailableStandardsSection(result.manifest || manifest, { phase: 'plan' });
4007
4221
  console.log();
4222
+ // Issue #298: which skills the plan leaves out on purpose (optional, or removed by the project), and how to change that.
4223
+ printOptionalSkillsSection(result.manifest || manifest, projectPath);
4008
4224
  }
4009
4225
 
4010
4226
  /**
@@ -4062,6 +4278,7 @@ async function handleReconcile(projectPath, options, { force, addStandards = []
4062
4278
  // XSPEC-458 R2: "up to date" is about the files UDS manages; say what UDS ships that is not managed here.
4063
4279
  printAvailableStandardsSection(planResult.manifest, { phase: 'apply' });
4064
4280
  console.log();
4281
+ printOptionalSkillsSection(planResult.manifest, projectPath);
4065
4282
  return;
4066
4283
  }
4067
4284
 
@@ -4126,6 +4343,10 @@ async function handleReconcile(projectPath, options, { force, addStandards = []
4126
4343
  runHookScriptStep(projectPath);
4127
4344
  }
4128
4345
 
4346
+ // Issue #298: this path (a plan with changes) ends here too, so it says what the plan leaves out on purpose, as the other ends do.
4347
+ console.log();
4348
+ printOptionalSkillsSection(readManifest(projectPath) || planResult.manifest, projectPath);
4349
+
4129
4350
  if (!result.success) {
4130
4351
  // XSPEC-482 R10: say what a partly failed run left behind and the way to finish it.
4131
4352
  console.log();
@@ -43,6 +43,7 @@ import {
43
43
  computeCommandContentHash
44
44
  } from '../utils/skills-installer.js';
45
45
  import { MARKETPLACE_NAMES_SENTINEL } from '../core/manifest.js';
46
+ import { selectSkillNames } from '../utils/skill-selection.js';
46
47
 
47
48
  /**
48
49
  * @typedef {Object} FileEntry
@@ -480,6 +481,10 @@ function calculateIntegrations(state, manifest) {
480
481
  * proposed for deletion. `uds update` always installs the full set (every call site
481
482
  * passes `skillNames = null`), so the shipped list *is* the desired list.
482
483
  * (XSPEC-343 R1/R2 — 40 of machine-setup's 86 proposed deletions.)
484
+ *
485
+ * "What this UDS ships" is narrowed per tool folder by `selectSkillNames` (#298): optional skills the project
486
+ * has not asked for are not desired, skills the project removed are not desired, and an optional skill that is
487
+ * already in the folder stays desired. The installer asks the same function.
483
488
  */
484
489
  function calculateSkills(state, projectPath, manifest) {
485
490
  const skills = manifest.skills;
@@ -490,8 +495,8 @@ function calculateSkills(state, projectPath, manifest) {
490
495
  // on-disk skill for deletion.
491
496
  if (skills.location === 'marketplace' || (skills.names || []).includes(MARKETPLACE_NAMES_SENTINEL)) return;
492
497
 
493
- const skillNames = getAvailableSkillNames();
494
- if (skillNames.length === 0) {
498
+ const shippedSkillNames = getAvailableSkillNames();
499
+ if (shippedSkillNames.length === 0) {
495
500
  // An empty shipped list means the source tree is unreadable, not that the
496
501
  // project should hold no skills. Returning here would leave `desired` empty
497
502
  // and every installed skill would diff as a deletion — the failure mode this
@@ -512,6 +517,10 @@ function calculateSkills(state, projectPath, manifest) {
512
517
  const skillsDir = getSkillsDirForAgent(agent, level, projectPath);
513
518
  if (!skillsDir) continue;
514
519
 
520
+ // The skills THIS tool's folder should hold: the one function the installer also asks (#298), so the
521
+ // plan and the write cannot disagree about whether `open-work` or a removed skill belongs here.
522
+ const skillNames = selectSkillNames({ shipped: shippedSkillNames, manifest, projectPath, agent, level }); // wire:plan-uses-skill-selection
523
+
515
524
  for (const skillName of skillNames) {
516
525
  // Each skill is a directory containing files; we track the directory marker
517
526
  const relativeBase = level === 'project'
@@ -0,0 +1,86 @@
1
+ /**
2
+ * What `uds update` says about optional skills and about the skills a project removed (issue #298).
3
+ *
4
+ * Information only: it is printed after a plan or an update is final, and nothing reads it. The plan
5
+ * itself already leaves optional and removed skills out (`selectSkillNames`); this says WHY a skill a
6
+ * person may have heard of is not in it, and the one command that changes that.
7
+ *
8
+ * @module utils/optional-skills-report
9
+ */
10
+
11
+ import chalk from 'chalk';
12
+ import { existsSync } from 'fs';
13
+ import { join } from 'path';
14
+ import { getAgentDisplayName, getSkillsDirForAgent } from '../config/ai-agent-paths.js';
15
+ import { getAvailableSkillNames } from './skills-installer.js';
16
+ import { OPTIONAL_SKILLS, readSkillChoices, skillDisplayName } from './skill-selection.js';
17
+
18
+ /** Project-recorded installations that live in a folder on disk (not the Claude Code marketplace). */
19
+ export function fileBasedSkillInstallations(manifest) {
20
+ return (manifest?.skills?.installations || [])
21
+ .filter((inst) => inst && inst.level !== 'marketplace' && inst.agent);
22
+ }
23
+
24
+ /**
25
+ * Where a skill folder exists, among the project's skill installations.
26
+ * @returns {string[]} display names of the tools, e.g. ['Claude Code', 'OpenCode']
27
+ */
28
+ function toolsHolding(folder, manifest, projectPath) {
29
+ const tools = [];
30
+ for (const { agent, level } of fileBasedSkillInstallations(manifest)) {
31
+ const dir = getSkillsDirForAgent(agent, level || 'project', projectPath);
32
+ if (dir && existsSync(join(dir, folder, 'SKILL.md'))) tools.push(getAgentDisplayName(agent) || agent);
33
+ }
34
+ return [...new Set(tools)];
35
+ }
36
+
37
+ /**
38
+ * The facts the section prints, separately from the printing so a test can read them.
39
+ * @returns {{optional: Array<{folder: string, name: string, why: string, installedIn: string[], asked: boolean, removed: boolean}>, removed: Array<{folder: string, name: string}>}}
40
+ */
41
+ export function describeSkillChoices(manifest, projectPath) {
42
+ const shipped = new Set(getAvailableSkillNames());
43
+ const { extra, excluded } = readSkillChoices(manifest);
44
+ const optional = Object.entries(OPTIONAL_SKILLS)
45
+ .filter(([folder]) => shipped.has(folder))
46
+ .map(([folder, why]) => ({
47
+ folder,
48
+ name: skillDisplayName(folder),
49
+ why,
50
+ installedIn: toolsHolding(folder, manifest, projectPath),
51
+ asked: extra.has(folder),
52
+ removed: excluded.has(folder)
53
+ }));
54
+ const removed = [...excluded]
55
+ .filter((folder) => shipped.has(folder) && !OPTIONAL_SKILLS[folder])
56
+ .sort()
57
+ .map((folder) => ({ folder, name: skillDisplayName(folder) }));
58
+ return { optional, removed };
59
+ }
60
+
61
+ /**
62
+ * Print the optional-skills section. Silent when the project has no skill folders (nothing to say about).
63
+ * @param {Object} manifest
64
+ * @param {string} projectPath
65
+ */
66
+ export function printOptionalSkillsSection(manifest, projectPath) {
67
+ if (fileBasedSkillInstallations(manifest).length === 0) return;
68
+ const { optional, removed } = describeSkillChoices(manifest, projectPath);
69
+ if (optional.length === 0 && removed.length === 0) return;
70
+
71
+ console.log(chalk.bold('Optional skills'));
72
+ console.log(chalk.gray(' UDS ships these but installs them only in a project that asks for them.'));
73
+ for (const s of optional) {
74
+ if (s.removed) {
75
+ console.log(chalk.gray(` - ${s.name} (${s.folder}): removed by this project, not installed. Add it back: uds update --add-skill ${s.name}`));
76
+ } else if (s.installedIn.length > 0) {
77
+ console.log(chalk.gray(` - ${s.name} (${s.folder}): installed in ${s.installedIn.join(', ')}${s.asked ? '' : ' (already there; kept and updated)'}. Remove it: uds update --remove-skill ${s.name}`));
78
+ } else {
79
+ console.log(chalk.gray(` - ${s.name} (${s.folder}): not installed. Add it: uds update --add-skill ${s.name}`));
80
+ }
81
+ }
82
+ for (const s of removed) {
83
+ console.log(chalk.gray(` - ${s.name} (${s.folder}): removed by this project (skills.excluded in the manifest), so no update installs it. Add it back: uds update --add-skill ${s.name}`));
84
+ }
85
+ console.log();
86
+ }
@@ -0,0 +1,20 @@
1
+ /**
2
+ * Which shipped skills are optional (issue #298). No imports: scripts at the repository root
3
+ * (`scripts/generate-adoption-skills.mjs`) read this list without installing the CLI's packages, and a second
4
+ * copy of the list there would be a second definition of "optional".
5
+ *
6
+ * Skills UDS ships but installs only in a project that asks for them. Folder name -> why it is optional.
7
+ * A skill belongs here when UDS itself says "nothing in UDS requires it" and a project that never wanted it,
8
+ * or already has its own, is worse off with it installed. Adding a name changes what every adopter's next
9
+ * `uds update` plans: the skill stops being installed in projects that do not hold it. Projects that already
10
+ * hold it keep it (see skill-selection.js).
11
+ */
12
+ export const OPTIONAL_SKILLS = Object.freeze({
13
+ 'open-work-assistant':
14
+ 'Help for work that stays open across sessions. Its own text says nothing in UDS requires it, and a person who already keeps such a skill would get two that read alike.'
15
+ });
16
+
17
+ /** @param {string} folder @returns {boolean} */
18
+ export function isOptionalSkill(folder) {
19
+ return Object.prototype.hasOwnProperty.call(OPTIONAL_SKILLS, folder);
20
+ }
@@ -0,0 +1,137 @@
1
+ /**
2
+ * Which skills a project gets: the one place that decides (issue #298).
3
+ *
4
+ * UDS ships every skill under `skills/`. Until 6.15.0-beta.1 every project got every skill. A skill that
5
+ * calls itself optional (`open-work`) was installed everywhere anyway, next to the adopter's own skill of
6
+ * the same kind, and the model then saw two skills that said nearly the same thing.
7
+ *
8
+ * The set a project gets is:
9
+ *
10
+ * shipped - optional skills - skills the project removed
11
+ * + optional skills the project added
12
+ * + optional skills that are already in this tool's folder
13
+ *
14
+ * ... and then minus the skills the project removed, whichever line they came in on.
15
+ *
16
+ * "Already in this tool's folder" keeps what 6.15.0-beta.1 installed: a project that already holds
17
+ * `open-work` is not told to delete it on the next `uds update`; it is updated like any other skill, until
18
+ * the project removes it (`uds update --remove-skill open-work`).
19
+ *
20
+ * ONE FUNCTION, TWO CALLERS. The reconciler's plan (`calculateSkills`) and the installer
21
+ * (`installSkillsForAgent`, every call that passes `skillNames = null`) both ask {@link selectSkillNames}.
22
+ * They used to each derive "the set" on their own, and two derivations of one set are how a plan promises
23
+ * one thing and an apply does another (XSPEC-382 R1).
24
+ *
25
+ * Names are the skill's FOLDER name everywhere inside the manifest and this module.
26
+ * {@link resolveSkillName} turns what a person types (`open-work` or `open-work-assistant`) into it.
27
+ */
28
+
29
+ import { existsSync, readFileSync } from 'fs';
30
+ import { join } from 'path';
31
+ import { getSkillsSourceDir } from './skills-source.js';
32
+ import { parseFrontmatter } from './skill-frontmatter.js';
33
+ import { getSkillsDirForAgent } from '../config/ai-agent-paths.js';
34
+ import { readManifest } from '../core/manifest.js';
35
+ import { OPTIONAL_SKILLS, isOptionalSkill } from './optional-skills.js';
36
+
37
+ export { OPTIONAL_SKILLS, isOptionalSkill };
38
+
39
+ const asNameSet = (value) => new Set(Array.isArray(value) ? value.filter((v) => typeof v === 'string') : []);
40
+
41
+ /**
42
+ * What the project chose, read from `manifest.skills`. A manifest written before #298 has neither key,
43
+ * which reads as "the project chose nothing".
44
+ *
45
+ * `skills.extra` optional skills the project asked for (`--add-skill`)
46
+ * `skills.excluded` skills the project does not want (`--remove-skill`); any skill, not only optional ones
47
+ *
48
+ * (`skills.names` is no substitute: it is the union of what UDS has installed, written by the installer,
49
+ * not a choice anyone made.)
50
+ *
51
+ * @param {Object|null|undefined} manifest
52
+ * @returns {{extra: Set<string>, excluded: Set<string>}}
53
+ */
54
+ export function readSkillChoices(manifest) {
55
+ return { extra: asNameSet(manifest?.skills?.extra), excluded: asNameSet(manifest?.skills?.excluded) };
56
+ }
57
+
58
+ /** Is this skill's folder present in the tool's skills folder? (SKILL.md is what makes a folder a skill.) */
59
+ function isOnDisk(folder, projectPath, agent, level) {
60
+ if (!agent) return false;
61
+ const dir = getSkillsDirForAgent(agent, level || 'project', projectPath || null);
62
+ return Boolean(dir) && existsSync(join(dir, folder, 'SKILL.md'));
63
+ }
64
+
65
+ /**
66
+ * The skills one tool folder should hold.
67
+ *
68
+ * @param {Object} args
69
+ * @param {string[]} args.shipped - what this UDS ships (`getAvailableSkillNames()`)
70
+ * @param {Object|null} [args.manifest] - the project's manifest; null = the project chose nothing
71
+ * @param {string|null} [args.projectPath]
72
+ * @param {string} [args.agent] - the tool whose folder this is (needed to see what is already there)
73
+ * @param {string} [args.level] - 'project' | 'user'
74
+ * @returns {string[]} folder names, in the order of `shipped`
75
+ */
76
+ export function selectSkillNames({ shipped, manifest = null, projectPath = null, agent = null, level = 'project' }) {
77
+ const { extra, excluded } = readSkillChoices(manifest);
78
+ return shipped.filter((folder) => {
79
+ if (excluded.has(folder)) return false;
80
+ if (!isOptionalSkill(folder)) return true;
81
+ return extra.has(folder) || isOnDisk(folder, projectPath, agent, level); // wire:optional-skill-kept-on-disk
82
+ });
83
+ }
84
+
85
+ /**
86
+ * The same question for the installer, which has a project path and not a manifest in hand: it reads the
87
+ * choices the project has recorded. No project path (a user-level install) or no manifest (a first
88
+ * `uds init`) means no choices - the default set.
89
+ */
90
+ export function selectSkillNamesForInstall({ shipped, projectPath = null, agent = null, level = 'project' }) {
91
+ let manifest = null;
92
+ if (projectPath) {
93
+ try {
94
+ manifest = readManifest(projectPath);
95
+ } catch {
96
+ manifest = null;
97
+ }
98
+ }
99
+ return selectSkillNames({ shipped, manifest, projectPath, agent, level });
100
+ }
101
+
102
+ /**
103
+ * The name a person sees for a skill: its `name:` line (`open-work`), which differs from the folder
104
+ * (`open-work-assistant`) for many skills. Read from the English source.
105
+ * @param {string} folder
106
+ * @returns {string} the folder name when the frontmatter has no `name`
107
+ */
108
+ export function skillDisplayName(folder) {
109
+ try {
110
+ const parsed = parseFrontmatter(readFileSync(join(getSkillsSourceDir(), folder, 'SKILL.md'), 'utf-8'));
111
+ const name = parsed?.frontmatter?.name;
112
+ return typeof name === 'string' && name ? name : folder;
113
+ } catch {
114
+ return folder;
115
+ }
116
+ }
117
+
118
+ /**
119
+ * Turn what a person typed into a shipped skill's folder name. Accepts the folder name or the skill's
120
+ * `name:` (`open-work-assistant` and `open-work` both mean the same skill).
121
+ *
122
+ * @param {string} input
123
+ * @param {string[]} shipped
124
+ * @returns {{folder: string}|{error: 'unknown'|'ambiguous', available: string[]}}
125
+ * `available` lists every name that would have been accepted, as `name (folder)`-style labels for the message.
126
+ */
127
+ export function resolveSkillName(input, shipped) {
128
+ const wanted = String(input ?? '').trim();
129
+ const labels = shipped.map((folder) => {
130
+ const display = skillDisplayName(folder);
131
+ return display === folder ? folder : `${display} (${folder})`;
132
+ });
133
+ if (shipped.includes(wanted)) return { folder: wanted };
134
+ const byDisplay = shipped.filter((folder) => skillDisplayName(folder) === wanted);
135
+ if (byDisplay.length === 1) return { folder: byDisplay[0] };
136
+ return { error: byDisplay.length > 1 ? 'ambiguous' : 'unknown', available: labels };
137
+ }
@@ -26,6 +26,7 @@ import { isLocalizedLocale } from './locale.js';
26
26
  import { getSkillsSourceDir } from './skills-source.js';
27
27
  import { rewriteOutsideLinks, createRepoPathProbe } from './skill-link-rewriter.js';
28
28
  import { t } from '../i18n/messages.js';
29
+ import { selectSkillNamesForInstall } from './skill-selection.js';
29
30
 
30
31
  // Get the CLI package root directory
31
32
  const __filename = fileURLToPath(import.meta.url);
@@ -193,7 +194,7 @@ export function getAvailableCommandNames() {
193
194
  * Install skills for a specific AI agent
194
195
  * @param {string} agent - Agent identifier (e.g., 'opencode', 'cursor')
195
196
  * @param {string} level - 'user' or 'project'
196
- * @param {string[]} skillNames - Array of skill names to install (null = all)
197
+ * @param {string[]} skillNames - Array of skill names to install (null = the project's default set, see skill-selection.js)
197
198
  * @param {string} projectPath - Project root path (required for project level)
198
199
  * @param {string} locale - Locale for skill content (default: 'en')
199
200
  * @returns {Object} Installation result
@@ -229,9 +230,15 @@ export async function installSkillsForAgent(agent, level, skillNames = null, pro
229
230
  mkdirSync(targetDir, { recursive: true });
230
231
  }
231
232
 
232
- // Get skills to install
233
+ // Get skills to install.
234
+ //
235
+ // An explicit list is installed as given: the reconciler passes the set its plan already chose, and
236
+ // `--add-skill` names the one skill it adds. `null` means "the project's default set" - shipped, minus the
237
+ // optional skills the project has not asked for, minus the ones it removed (issue #298) - and it is
238
+ // decided by the same function the reconciler's plan asks, so a plan cannot promise a different set than
239
+ // this writes. Every `installSkills*(..., null, ...)` call in init, update and config lands here.
233
240
  const availableSkills = getAvailableSkillNames();
234
- const toInstall = skillNames || availableSkills;
241
+ const toInstall = skillNames || selectSkillNamesForInstall({ shipped: availableSkills, projectPath, agent, level }); // wire:install-uses-skill-selection
235
242
 
236
243
  const results = {
237
244
  success: true,
@@ -1183,7 +1190,7 @@ function printLocalePackMissing(locale) {
1183
1190
  /**
1184
1191
  * Install skills to multiple agents at once
1185
1192
  * @param {Array<{agent: string, level: string}>} installations - Array of installation targets
1186
- * @param {string[]} skillNames - Skills to install (null = all)
1193
+ * @param {string[]} skillNames - Skills to install (null = the project's default set, see skill-selection.js)
1187
1194
  * @param {string} projectPath - Project root path
1188
1195
  * @param {string} locale - Locale for skill content (default: 'en')
1189
1196
  * @returns {Object} Combined results