universal-dev-standards 6.14.0-beta.6 → 6.14.0-beta.7

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 (84) hide show
  1. package/README.md +13 -3
  2. package/bin/uds.js +30 -6
  3. package/bundled/ai/options/code-review/pr-review.ai.yaml +20 -1
  4. package/bundled/ai/standards/code-review.ai.yaml +15 -2
  5. package/bundled/ai/standards/developer-memory.ai.yaml +12 -2
  6. package/bundled/ai/standards/full-coverage-testing.ai.yaml +44 -6
  7. package/bundled/ai/standards/open-work-tracking.ai.yaml +191 -11
  8. package/bundled/ai/standards/pipeline-security-gates.ai.yaml +48 -3
  9. package/bundled/ai/standards/project-context-memory.ai.yaml +12 -2
  10. package/bundled/core/code-review-checklist.md +20 -2
  11. package/bundled/core/developer-memory.md +12 -2
  12. package/bundled/core/full-coverage-testing.md +44 -4
  13. package/bundled/core/open-work-tracking.md +156 -16
  14. package/bundled/core/pipeline-security-gates.md +63 -0
  15. package/bundled/core/project-context-memory.md +10 -2
  16. package/bundled/locales/zh-CN/CHANGELOG.md +51 -3
  17. package/bundled/locales/zh-CN/README.md +1 -1
  18. package/bundled/locales/zh-CN/SECURITY.md +1 -1
  19. package/bundled/locales/zh-CN/adoption/ADOPTION-GUIDE.md +13 -4
  20. package/bundled/locales/zh-CN/adoption/STATIC-DYNAMIC-GUIDE.md +7 -1
  21. package/bundled/locales/zh-CN/adoption/checklists/enterprise.md +7 -1
  22. package/bundled/locales/zh-CN/adoption/checklists/minimal.md +13 -3
  23. package/bundled/locales/zh-CN/adoption/checklists/recommended.md +7 -1
  24. package/bundled/locales/zh-CN/core/code-review-checklist.md +17 -0
  25. package/bundled/locales/zh-CN/core/developer-memory.md +9 -0
  26. package/bundled/locales/zh-CN/core/full-coverage-testing.md +48 -8
  27. package/bundled/locales/zh-CN/core/pipeline-security-gates.md +64 -4
  28. package/bundled/locales/zh-CN/core/project-context-memory.md +5 -0
  29. package/bundled/locales/zh-CN/docs/AVAILABLE-STANDARDS.md +70 -0
  30. package/bundled/locales/zh-CN/docs/CHEATSHEET.md +4 -3
  31. package/bundled/locales/zh-CN/docs/CLI-INIT-OPTIONS.md +25 -23
  32. package/bundled/locales/zh-CN/docs/FEATURE-REFERENCE.md +13 -11
  33. package/bundled/locales/zh-CN/docs/USAGE-MODES-COMPARISON.md +6 -6
  34. package/bundled/locales/zh-CN/docs/WINDOWS-GUIDE.md +7 -1
  35. package/bundled/locales/zh-CN/docs/user/GETTING-STARTED.md +44 -0
  36. package/bundled/locales/zh-CN/options/code-review/pr-review.md +13 -2
  37. package/bundled/locales/zh-TW/CHANGELOG.md +51 -3
  38. package/bundled/locales/zh-TW/README.md +1 -1
  39. package/bundled/locales/zh-TW/SECURITY.md +1 -1
  40. package/bundled/locales/zh-TW/adoption/ADOPTION-GUIDE.md +13 -4
  41. package/bundled/locales/zh-TW/adoption/STATIC-DYNAMIC-GUIDE.md +7 -1
  42. package/bundled/locales/zh-TW/adoption/checklists/enterprise.md +7 -1
  43. package/bundled/locales/zh-TW/adoption/checklists/minimal.md +13 -3
  44. package/bundled/locales/zh-TW/adoption/checklists/recommended.md +7 -1
  45. package/bundled/locales/zh-TW/core/code-review-checklist.md +17 -0
  46. package/bundled/locales/zh-TW/core/developer-memory.md +9 -0
  47. package/bundled/locales/zh-TW/core/full-coverage-testing.md +48 -8
  48. package/bundled/locales/zh-TW/core/open-work-tracking.md +90 -14
  49. package/bundled/locales/zh-TW/core/pipeline-security-gates.md +64 -4
  50. package/bundled/locales/zh-TW/core/project-context-memory.md +5 -0
  51. package/bundled/locales/zh-TW/docs/AVAILABLE-STANDARDS.md +70 -0
  52. package/bundled/locales/zh-TW/docs/CHEATSHEET.md +4 -3
  53. package/bundled/locales/zh-TW/docs/CLI-INIT-OPTIONS.md +25 -23
  54. package/bundled/locales/zh-TW/docs/FEATURE-REFERENCE.md +13 -11
  55. package/bundled/locales/zh-TW/docs/USAGE-MODES-COMPARISON.md +6 -6
  56. package/bundled/locales/zh-TW/docs/WINDOWS-GUIDE.md +7 -1
  57. package/bundled/locales/zh-TW/docs/user/GETTING-STARTED.md +44 -0
  58. package/bundled/locales/zh-TW/options/code-review/pr-review.md +13 -2
  59. package/bundled/skills/SKILL_NAMING.md +9 -0
  60. package/bundled/templates/gates/check-anti-fake-tests.mjs +305 -5
  61. package/package.json +3 -1
  62. package/src/commands/audit.js +9 -2
  63. package/src/commands/check.js +17 -0
  64. package/src/commands/init.js +41 -21
  65. package/src/commands/open-work.js +65 -6
  66. package/src/commands/skills.js +19 -33
  67. package/src/commands/update.js +61 -61
  68. package/src/core/open-work-config.js +103 -0
  69. package/src/flows/init-flow.js +10 -0
  70. package/src/i18n/messages.js +237 -60
  71. package/src/installers/skills-installer.js +3 -1
  72. package/src/prompts/init.js +148 -13
  73. package/src/reconciler/index.js +42 -5
  74. package/src/utils/available-standards-report.js +144 -0
  75. package/src/utils/available-standards.js +216 -0
  76. package/src/utils/copier.js +5 -4
  77. package/src/utils/friction-detector.js +27 -0
  78. package/src/utils/open-work-tracking.mjs +919 -48
  79. package/src/utils/skill-frontmatter.js +102 -0
  80. package/src/utils/skill-name-collision.js +169 -0
  81. package/src/utils/skills-install-paths.js +114 -0
  82. package/src/utils/skills-installer.js +63 -105
  83. package/src/utils/transient-fs.js +113 -0
  84. package/standards-registry.json +9 -9
@@ -0,0 +1,102 @@
1
+ /**
2
+ * Skill frontmatter: parse a SKILL.md's YAML header and rebuild a file with merged fields.
3
+ *
4
+ * Why this is its own file: `scripts/generate-adoption-skills.mjs` (run by the "Self-Adoption Skill Drift
5
+ * Gate" and by `scripts/bump-version.mjs`) needs exactly these two functions, and those CI jobs install no CLI
6
+ * packages. They used to be exported from skills-installer.js, so importing them also loaded `chalk` and the
7
+ * rest of the installer; when XSPEC-468 made the installer import `chalk`, both jobs failed with
8
+ * ERR_MODULE_NOT_FOUND. A module a root script reaches must import Node built-ins only — enforced by
9
+ * cli/tests/e2e/root-scripts-need-no-cli-packages.test.js.
10
+ */
11
+
12
+ /**
13
+ * Parse YAML frontmatter from a markdown file content.
14
+ * Handles multi-line values (e.g., `description: |`).
15
+ * @param {string} content - File content with YAML frontmatter
16
+ * @returns {{ frontmatter: Object, body: string } | null} Parsed result or null if no frontmatter
17
+ */
18
+ export function parseFrontmatter(content) {
19
+ const match = content.match(/^---\n([\s\S]*?)\n---\n?([\s\S]*)$/);
20
+ if (!match) return null;
21
+
22
+ const [, yamlText, body] = match;
23
+ const frontmatter = {};
24
+
25
+ const lines = yamlText.split('\n');
26
+ let currentKey = null;
27
+ let currentValue = '';
28
+ let isMultiline = false;
29
+
30
+ for (const line of lines) {
31
+ if (isMultiline) {
32
+ // Multi-line value: lines starting with spaces belong to current key
33
+ if (line.match(/^\s/) || line === '') {
34
+ currentValue += (currentValue ? '\n' : '') + line;
35
+ continue;
36
+ } else {
37
+ // End of multi-line value
38
+ frontmatter[currentKey] = currentValue.trimEnd();
39
+ isMultiline = false;
40
+ }
41
+ }
42
+
43
+ const keyMatch = line.match(/^([a-zA-Z_-]+):\s*(.*)$/);
44
+ if (keyMatch) {
45
+ currentKey = keyMatch[1];
46
+ const value = keyMatch[2].trim();
47
+
48
+ if (value === '|' || value === '>') {
49
+ // Start of multi-line value
50
+ isMultiline = true;
51
+ currentValue = '';
52
+ } else {
53
+ frontmatter[currentKey] = value;
54
+ }
55
+ }
56
+ }
57
+
58
+ // Flush last multi-line value
59
+ if (isMultiline && currentKey) {
60
+ frontmatter[currentKey] = currentValue.trimEnd();
61
+ }
62
+
63
+ return { frontmatter, body };
64
+ }
65
+
66
+ /**
67
+ * Rebuild file content with updated frontmatter fields.
68
+ * Preserves existing frontmatter fields and adds/overrides with provided fields.
69
+ * @param {string} content - Original file content
70
+ * @param {Object} fieldsToMerge - Fields to add or override in frontmatter
71
+ * @returns {string} Rebuilt content
72
+ */
73
+ export function rebuildWithFrontmatter(content, fieldsToMerge) {
74
+ const parsed = parseFrontmatter(content);
75
+ if (!parsed) {
76
+ // No existing frontmatter — create one
77
+ const lines = ['---'];
78
+ for (const [key, value] of Object.entries(fieldsToMerge)) {
79
+ lines.push(`${key}: ${value}`);
80
+ }
81
+ lines.push('---');
82
+ return lines.join('\n') + '\n' + content;
83
+ }
84
+
85
+ const merged = { ...parsed.frontmatter, ...fieldsToMerge };
86
+
87
+ const lines = ['---'];
88
+ for (const [key, value] of Object.entries(merged)) {
89
+ if (value && value.includes('\n')) {
90
+ // Multi-line value
91
+ lines.push(`${key}: |`);
92
+ for (const vline of value.split('\n')) {
93
+ lines.push(vline);
94
+ }
95
+ } else {
96
+ lines.push(`${key}: ${value}`);
97
+ }
98
+ }
99
+ lines.push('---');
100
+
101
+ return lines.join('\n') + '\n' + parsed.body;
102
+ }
@@ -0,0 +1,169 @@
1
+ /**
2
+ * A personal skill with the same name as a UDS skill installed in the project (dev-platform XSPEC-465 R1).
3
+ *
4
+ * Why it matters: Claude Code picks ONE skill per name, and it picks silently. Personal skills
5
+ * (`~/.claude/skills/<name>/`) rank above project skills (`.claude/skills/<name>/`), where `uds init` and
6
+ * `uds update --apply --skills` put the UDS skills. So an adopter who already has a personal `plan` or `push`
7
+ * skill runs their own when they type `/plan`, and the UDS one never runs. There is no error, no warning,
8
+ * nothing in the output of the install.
9
+ *
10
+ * What the rule is (Claude Code skills documentation, read 2026-10-07, https://code.claude.com/docs/en/skills):
11
+ * - a skill's command name is the `name` in its SKILL.md frontmatter, or the folder name when there is none;
12
+ * "the directory name also invokes the skill", so BOTH names are compared here (on both sides);
13
+ * - enterprise over personal, and personal over project;
14
+ * - a plugin skill is `/<plugin>:<skill>`, so it never collides, and a skill beats a `.claude/commands/`
15
+ * file of the same name, so neither is listed.
16
+ *
17
+ * What this can see, and what it cannot (said in the printed text too, because "no warning" must not be
18
+ * read as "no collision"):
19
+ * - sees: this machine's personal folder, read again on every call;
20
+ * - does not see: the enterprise level (the managed settings directory, location depends on the
21
+ * organization), and personal skills added after the call.
22
+ *
23
+ * It is information only: the callers' verdict and exit code do not read anything from here, and nothing here
24
+ * throws. A personal folder that is missing, is not a folder, or cannot be read prints nothing.
25
+ *
26
+ * @module utils/skill-name-collision
27
+ */
28
+
29
+ import chalk from 'chalk';
30
+ import { readdirSync, readFileSync, realpathSync, statSync } from 'fs';
31
+ import { homedir } from 'os';
32
+ import { join } from 'path';
33
+ import { load as parseYaml } from 'js-yaml';
34
+ import { t } from '../i18n/messages.js';
35
+ import { getAvailableSkillNames } from './skills-installer.js';
36
+
37
+ function fill(template, values) {
38
+ return Object.entries(values).reduce((text, [key, value]) => text.replaceAll(`{${key}}`, String(value)), template);
39
+ }
40
+
41
+ function isDirectory(path) {
42
+ try {
43
+ return statSync(path).isDirectory(); // follows symlinks: people link their skill folders in
44
+ } catch {
45
+ return false;
46
+ }
47
+ }
48
+
49
+ /**
50
+ * The names a skill folder answers to: its folder name, plus the frontmatter `name` when there is one.
51
+ *
52
+ * @param {string} skillDir - folder holding SKILL.md
53
+ * @returns {string[]|null} null = this folder is not a skill we can read (no SKILL.md, cannot be read, or the
54
+ * frontmatter is present but is not valid YAML, so nobody can say what Claude Code would do with it)
55
+ */
56
+ export function skillCommandNames(skillDir) {
57
+ const folderName = skillDir.split(/[\\/]/).filter(Boolean).pop();
58
+ let text;
59
+ try {
60
+ const file = join(skillDir, 'SKILL.md');
61
+ if (!statSync(file).isFile()) return null;
62
+ text = readFileSync(file, 'utf-8');
63
+ } catch {
64
+ return null;
65
+ }
66
+ const names = [folderName];
67
+ const match = text.match(/^\uFEFF?---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/);
68
+ if (!match) return names; // no frontmatter: the folder name is the name
69
+ let data;
70
+ try {
71
+ data = parseYaml(match[1]);
72
+ } catch {
73
+ return null;
74
+ }
75
+ if (data && typeof data === 'object' && typeof data.name === 'string' && data.name.trim()) {
76
+ const declared = data.name.trim();
77
+ if (declared !== folderName) names.push(declared);
78
+ }
79
+ return names;
80
+ }
81
+
82
+ /**
83
+ * Collisions between the UDS skills installed in the project and the personal skills of this machine.
84
+ *
85
+ * @param {string} projectPath
86
+ * @param {{ home?: string }} [opts] - `home` only for callers that already know it; defaults to os.homedir()
87
+ * @returns {{ names: string[], udsFolder: string, personalFolder: string }[]} one entry per (UDS skill,
88
+ * personal skill) pair that share a name; `names` are the shared names, empty list when nothing is found or
89
+ * anything could not be read
90
+ */
91
+ export function findSkillNameCollisions(projectPath, { home } = {}) {
92
+ try {
93
+ const personalDir = join(home ?? homedir(), '.claude', 'skills');
94
+ const projectDir = join(projectPath, '.claude', 'skills');
95
+ if (!isDirectory(personalDir) || !isDirectory(projectDir)) return [];
96
+ // A project that IS the home folder has the same folder on both sides: that is one skill, not two.
97
+ if (realpathSync(personalDir) === realpathSync(projectDir)) return [];
98
+
99
+ const shipped = new Set(getAvailableSkillNames());
100
+
101
+ // UDS installed at user level (`uds init --skills-location user`) leaves its own copies, and a manifest that
102
+ // says so, in the personal folder. Those are UDS's, not someone else's skill: leave them out.
103
+ let personalHoldsUds = false;
104
+ try {
105
+ const manifest = JSON.parse(readFileSync(join(personalDir, '.manifest.json'), 'utf-8'));
106
+ personalHoldsUds = manifest?.source === 'universal-dev-standards';
107
+ } catch {
108
+ personalHoldsUds = false;
109
+ }
110
+
111
+ const uds = [];
112
+ for (const entry of readdirSync(projectDir, { withFileTypes: true })) {
113
+ if (!shipped.has(entry.name)) continue; // only the skills UDS ships; the adopter's own are not ours to judge
114
+ const dir = join(projectDir, entry.name);
115
+ if (!isDirectory(dir)) continue;
116
+ const names = skillCommandNames(dir);
117
+ if (names) uds.push({ folder: entry.name, names });
118
+ }
119
+ if (uds.length === 0) return [];
120
+
121
+ const found = [];
122
+ for (const entry of readdirSync(personalDir, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
123
+ if (entry.name.startsWith('.')) continue;
124
+ if (personalHoldsUds && shipped.has(entry.name)) continue;
125
+ const dir = join(personalDir, entry.name);
126
+ if (!isDirectory(dir)) continue;
127
+ const personalNames = skillCommandNames(dir);
128
+ if (!personalNames) continue;
129
+ for (const skill of uds.slice().sort((a, b) => a.folder.localeCompare(b.folder))) {
130
+ const shared = skill.names.filter(n => personalNames.includes(n));
131
+ if (shared.length > 0) found.push({ names: shared, udsFolder: skill.folder, personalFolder: entry.name });
132
+ }
133
+ }
134
+ return found;
135
+ } catch {
136
+ return []; // unreadable, permission denied, anything else: no warning and no error
137
+ }
138
+ }
139
+
140
+ /**
141
+ * Print the warning. Information only; the caller's verdict and exit code do not read anything from here.
142
+ *
143
+ * @param {string} projectPath
144
+ * @param {{ home?: string }} [opts]
145
+ * @returns {boolean} whether the warning was printed
146
+ */
147
+ export function printSkillNameCollisionWarning(projectPath, opts = {}) {
148
+ const collisions = findSkillNameCollisions(projectPath, opts);
149
+ if (collisions.length === 0) return false;
150
+
151
+ const msg = t().commands.check;
152
+ console.log(chalk.yellow(fill(msg.skillNameCollisionTitle, { count: collisions.length })));
153
+ for (const c of collisions) {
154
+ console.log(chalk.gray(` ${fill(msg.skillNameCollisionItem, {
155
+ command: c.names.map(n => `/${n}`).join(', '),
156
+ personal: `~/.claude/skills/${c.personalFolder}/`,
157
+ uds: `.claude/skills/${c.udsFolder}/`
158
+ })}`));
159
+ }
160
+ console.log(chalk.gray(` ${msg.skillNameCollisionEffect}`));
161
+ console.log(chalk.gray(` ${msg.skillNameCollisionChoose}`));
162
+ console.log(chalk.gray(` ${msg.skillNameCollisionRename}`));
163
+ console.log(chalk.gray(` ${msg.skillNameCollisionDrop}`));
164
+ console.log(chalk.gray(` ${msg.skillNameCollisionLimits}`));
165
+ console.log();
166
+ return true;
167
+ }
168
+
169
+ export default { findSkillNameCollisions, printSkillNameCollisionWarning, skillCommandNames };
@@ -0,0 +1,114 @@
1
+ /**
2
+ * The two ways to install UDS skills, said side by side (dev-platform XSPEC-462 R1, R2).
3
+ *
4
+ * Until 6.14 `uds skills` called installing skills into the project "deprecated" and told people to use the
5
+ * Claude Code plugin marketplace, while `uds check` and `uds update` told them to run
6
+ * `uds update --apply --skills` (the project way). The word dated from 2026-01 and nobody updated it. The
7
+ * decision (XSPEC-462): the project way is the main path; the plugin marketplace is an alternative with
8
+ * limits that are written down, not hidden.
9
+ *
10
+ * The facts printed here are the ones XSPEC-462 recorded on 2026-10-07:
11
+ * - the project way works for many AI tools (`cli/src/config/ai-agent-paths.js`), has Traditional and
12
+ * Simplified Chinese skill texts, and follows the UDS version you installed, betas included;
13
+ * - the plugin works in Claude Code only, loads the English texts only (the plugin settings have no
14
+ * language choice), follows stable releases only, and puts no files in the project.
15
+ *
16
+ * Nothing here changes a plan, a verdict or an exit code: it only prints.
17
+ *
18
+ * @module utils/skills-install-paths
19
+ */
20
+
21
+ import chalk from 'chalk';
22
+ import { existsSync, readdirSync } from 'fs';
23
+ import { join } from 'path';
24
+ import { t } from '../i18n/messages.js';
25
+ import { getAvailableSkillNames } from './skills-installer.js';
26
+
27
+ function fill(template, values) {
28
+ return Object.entries(values).reduce((text, [key, value]) => text.replaceAll(`{${key}}`, String(value)), template);
29
+ }
30
+
31
+ /**
32
+ * `uds skills`: both ways, each with what it can and cannot do.
33
+ */
34
+ export function printInstallPathComparison() {
35
+ const msg = t().commands.skills.installPaths;
36
+
37
+ console.log(chalk.bold(msg.title));
38
+ console.log();
39
+
40
+ console.log(chalk.green(` ● ${msg.projectTitle}`));
41
+ for (const line of msg.projectCommands) {
42
+ console.log(chalk.cyan(` ${line}`));
43
+ }
44
+ for (const line of msg.projectPoints) {
45
+ console.log(chalk.gray(` - ${line}`));
46
+ }
47
+ console.log();
48
+
49
+ console.log(chalk.blue(` ● ${msg.pluginTitle}`));
50
+ console.log(chalk.cyan(' /plugin marketplace add AsiaOstrich/universal-dev-standards'));
51
+ console.log(chalk.cyan(' /plugin install universal-dev-standards@asia-ostrich'));
52
+ for (const line of msg.pluginPoints) {
53
+ console.log(chalk.gray(` - ${line}`));
54
+ }
55
+ console.log();
56
+
57
+ console.log(chalk.gray(` ${msg.bothNote}`));
58
+ console.log();
59
+ }
60
+
61
+ /**
62
+ * The UDS skills that sit in the project's Claude Code skills folder: folders named like a skill UDS ships
63
+ * and holding a SKILL.md. Other people's skills in the same folder are not counted.
64
+ *
65
+ * @param {string} projectPath
66
+ * @returns {string[]}
67
+ */
68
+ export function projectUdsSkillNames(projectPath) {
69
+ const dir = join(projectPath, '.claude', 'skills');
70
+ if (!existsSync(dir)) return [];
71
+ let shipped;
72
+ try {
73
+ shipped = new Set(getAvailableSkillNames());
74
+ } catch {
75
+ return [];
76
+ }
77
+ try {
78
+ return readdirSync(dir, { withFileTypes: true })
79
+ .filter(e => e.isDirectory() && shipped.has(e.name) && existsSync(join(dir, e.name, 'SKILL.md')))
80
+ .map(e => e.name)
81
+ .sort();
82
+ } catch {
83
+ return [];
84
+ }
85
+ }
86
+
87
+ /**
88
+ * `uds check`: the project has UDS skills AND the UDS plugin is installed, so Claude Code lists every skill
89
+ * twice. Information only: the caller's verdict and exit code do not read anything from here.
90
+ *
91
+ * Silent when either side is missing, and when the plugin record could not be read (`pluginInfo` is null:
92
+ * no file, a file that is not JSON, no UDS plugin in it, or a record whose cache folder is gone).
93
+ *
94
+ * @param {string} projectPath
95
+ * @param {{installed?: boolean, pluginKey?: string, version?: string}|null} pluginInfo - what
96
+ * `getMarketplaceSkillsInfo()` returned
97
+ * @returns {boolean} whether the warning was printed
98
+ */
99
+ export function printDoubleInstallWarning(projectPath, pluginInfo) {
100
+ if (!pluginInfo?.installed) return false;
101
+ const names = projectUdsSkillNames(projectPath);
102
+ if (names.length === 0) return false;
103
+
104
+ const msg = t().commands.check;
105
+ const pluginKey = pluginInfo.pluginKey || 'universal-dev-standards@asia-ostrich';
106
+ console.log(chalk.yellow(fill(msg.skillsTwiceTitle, { count: names.length, plugin: pluginKey })));
107
+ console.log(chalk.gray(` ${msg.skillsTwiceNames}`));
108
+ console.log(chalk.gray(` ${msg.skillsTwiceContext}`));
109
+ console.log(chalk.gray(` ${msg.skillsTwiceChoose}`));
110
+ console.log(chalk.gray(` ${fill(msg.skillsTwiceKeepProject, { plugin: pluginKey })}`));
111
+ console.log(chalk.gray(` ${msg.skillsTwiceKeepPlugin}`));
112
+ console.log();
113
+ return true;
114
+ }
@@ -10,7 +10,9 @@
10
10
  import { mkdirSync, writeFileSync, existsSync, readFileSync, readdirSync, copyFileSync, statSync, rmSync, unlinkSync } from 'fs';
11
11
  import { dirname, join, basename } from 'path';
12
12
  import { createHash } from 'crypto';
13
+ import chalk from 'chalk';
13
14
  import { fileURLToPath } from 'url';
15
+ import { parseFrontmatter, rebuildWithFrontmatter } from './skill-frontmatter.js';
14
16
  import {
15
17
  getAgentConfig,
16
18
  getSkillsDirForAgent,
@@ -22,6 +24,7 @@ import {
22
24
  import { computeDirectoryHashes, computeFileHash, normalizeLineEndings } from './hasher.js';
23
25
  import { isLocalizedLocale } from './locale.js';
24
26
  import { getSkillsSourceDir } from './skills-source.js';
27
+ import { t } from '../i18n/messages.js';
25
28
 
26
29
  // Get the CLI package root directory
27
30
  const __filename = fileURLToPath(import.meta.url);
@@ -33,16 +36,21 @@ const BUNDLED_DIR = join(CLI_ROOT, 'bundled');
33
36
  // Its previous private copy here was the half that worked; the copy in github.js was not.
34
37
 
35
38
  /**
36
- * Get the localized Skills source directory for a given locale.
37
- * Falls back to the English source directory if the localized path does not exist.
38
- * @param {string} locale - Locale identifier (e.g., 'zh-TW', 'zh-CN', 'en')
39
- * @returns {string} Path to skills source directory for the locale
39
+ * Where this copy of UDS keeps the skill texts of a locale, or `null` when it keeps none.
40
+ *
41
+ * `null` is the answer that matters (XSPEC-468 R3). This lookup used to fall back to the English directory
42
+ * on its own, so a copy of UDS without the locale pack installed English skills for `--locale zh-tw`, exit
43
+ * code 0, and not one word about it: the same shape as `zh-CN` becoming English in XSPEC-451. Whoever asks
44
+ * now learns the pack is absent and says so.
45
+ *
46
+ * The pack is part of the npm package (`cli/scripts/prepack.mjs` bundles `locales/` into
47
+ * `bundled/locales/`), so an absent pack means an incomplete or damaged copy, not a missing network.
48
+ *
49
+ * @param {string} locale - e.g. 'zh-TW', 'zh-CN'
50
+ * @returns {string|null}
40
51
  */
41
- function getLocalizedSkillsSourceDir(locale) {
42
- const enDir = getSkillsSourceDir();
43
- if (!isLocalizedLocale(locale)) {
44
- return enDir;
45
- }
52
+ export function findLocalePackSkillsDir(locale) {
53
+ if (!isLocalizedLocale(locale)) return null;
46
54
 
47
55
  // Try bundled path first (npm install)
48
56
  const bundledPath = join(BUNDLED_DIR, 'locales', locale, 'skills');
@@ -56,8 +64,16 @@ function getLocalizedSkillsSourceDir(locale) {
56
64
  return devPath;
57
65
  }
58
66
 
59
- // Locale directory not found, fall back to English
60
- return enDir;
67
+ return null;
68
+ }
69
+
70
+ /**
71
+ * Whether the skill texts of `locale` are in this copy of UDS. Always true for English.
72
+ * @param {string} locale
73
+ * @returns {boolean}
74
+ */
75
+ export function isLocalePackAvailable(locale) {
76
+ return !isLocalizedLocale(locale) || findLocalePackSkillsDir(locale) !== null;
61
77
  }
62
78
 
63
79
  /**
@@ -266,98 +282,9 @@ export async function installSkillsForAgent(agent, level, skillNames = null, pro
266
282
  return results;
267
283
  }
268
284
 
269
- /**
270
- * Parse YAML frontmatter from a markdown file content.
271
- * Handles multi-line values (e.g., `description: |`).
272
- * @param {string} content - File content with YAML frontmatter
273
- * @returns {{ frontmatter: Object, body: string } | null} Parsed result or null if no frontmatter
274
- */
275
- export function parseFrontmatter(content) {
276
- const match = content.match(/^---\n([\s\S]*?)\n---\n?([\s\S]*)$/);
277
- if (!match) return null;
278
-
279
- const [, yamlText, body] = match;
280
- const frontmatter = {};
281
-
282
- const lines = yamlText.split('\n');
283
- let currentKey = null;
284
- let currentValue = '';
285
- let isMultiline = false;
286
-
287
- for (const line of lines) {
288
- if (isMultiline) {
289
- // Multi-line value: lines starting with spaces belong to current key
290
- if (line.match(/^\s/) || line === '') {
291
- currentValue += (currentValue ? '\n' : '') + line;
292
- continue;
293
- } else {
294
- // End of multi-line value
295
- frontmatter[currentKey] = currentValue.trimEnd();
296
- isMultiline = false;
297
- }
298
- }
299
-
300
- const keyMatch = line.match(/^([a-zA-Z_-]+):\s*(.*)$/);
301
- if (keyMatch) {
302
- currentKey = keyMatch[1];
303
- const value = keyMatch[2].trim();
304
-
305
- if (value === '|' || value === '>') {
306
- // Start of multi-line value
307
- isMultiline = true;
308
- currentValue = '';
309
- } else {
310
- frontmatter[currentKey] = value;
311
- }
312
- }
313
- }
314
-
315
- // Flush last multi-line value
316
- if (isMultiline && currentKey) {
317
- frontmatter[currentKey] = currentValue.trimEnd();
318
- }
319
-
320
- return { frontmatter, body };
321
- }
322
-
323
- /**
324
- * Rebuild file content with updated frontmatter fields.
325
- * Preserves existing frontmatter fields and adds/overrides with provided fields.
326
- * @param {string} content - Original file content
327
- * @param {Object} fieldsToMerge - Fields to add or override in frontmatter
328
- * @returns {string} Rebuilt content
329
- */
330
- export function rebuildWithFrontmatter(content, fieldsToMerge) {
331
- const parsed = parseFrontmatter(content);
332
- if (!parsed) {
333
- // No existing frontmatter — create one
334
- const lines = ['---'];
335
- for (const [key, value] of Object.entries(fieldsToMerge)) {
336
- lines.push(`${key}: ${value}`);
337
- }
338
- lines.push('---');
339
- return lines.join('\n') + '\n' + content;
340
- }
341
-
342
- const merged = { ...parsed.frontmatter, ...fieldsToMerge };
343
-
344
- const lines = ['---'];
345
- for (const [key, value] of Object.entries(merged)) {
346
- if (value && value.includes('\n')) {
347
- // Multi-line value
348
- lines.push(`${key}: |`);
349
- for (const vline of value.split('\n')) {
350
- lines.push(vline);
351
- }
352
- } else {
353
- lines.push(`${key}: ${value}`);
354
- }
355
- }
356
- lines.push('---');
357
-
358
- return lines.join('\n') + '\n' + parsed.body;
359
- }
360
-
285
+ // parseFrontmatter / rebuildWithFrontmatter live in ./skill-frontmatter.js (no dependencies, so scripts at the
286
+ // repo root can import them without installing the CLI's packages); imported above and re-exported here, so every existing importer keeps working.
287
+ export { parseFrontmatter, rebuildWithFrontmatter };
361
288
  /**
362
289
  * Merge required Claude Code frontmatter fields from the English source
363
290
  * into an installed localized SKILL.md.
@@ -450,8 +377,9 @@ export function resolveSkillFiles(skillName, locale = 'en') {
450
377
  let fallbackToEn = false;
451
378
 
452
379
  if (isLocalizedLocale(locale)) {
453
- const localizedSkillDir = join(getLocalizedSkillsSourceDir(locale), skillName);
454
- if (existsSync(localizedSkillDir)) {
380
+ const packDir = findLocalePackSkillsDir(locale);
381
+ const localizedSkillDir = packDir ? join(packDir, skillName) : null;
382
+ if (localizedSkillDir && existsSync(localizedSkillDir)) {
455
383
  sourceDir = localizedSkillDir;
456
384
  needsFrontmatterMerge = true;
457
385
  } else {
@@ -1128,6 +1056,25 @@ export function deduplicateInstallations(installations) {
1128
1056
  return deduped;
1129
1057
  }
1130
1058
 
1059
+ /**
1060
+ * Tell the adopter the locale pack is not in this copy of UDS and that English was installed instead.
1061
+ * Not an error, not silence: the install goes on in English, the message says why and how to get the texts.
1062
+ * @param {string} locale
1063
+ */
1064
+ const localePackMissingTold = new Set();
1065
+ function printLocalePackMissing(locale) {
1066
+ // Skills and commands both go through here; once per run is enough.
1067
+ if (localePackMissingTold.has(locale)) return;
1068
+ localePackMissingTold.add(locale);
1069
+ const msg = t().commands.common;
1070
+ const fill = (text) => text.replaceAll('{locale}', locale).replaceAll('{localeLower}', String(locale).toLowerCase());
1071
+ console.log();
1072
+ console.log(chalk.yellow(`⚠ ${fill(msg.localePackMissingTitle)}`));
1073
+ for (const line of msg.localePackMissingLines) {
1074
+ console.log(chalk.gray(` ${fill(line)}`));
1075
+ }
1076
+ }
1077
+
1131
1078
  /**
1132
1079
  * Install skills to multiple agents at once
1133
1080
  * @param {Array<{agent: string, level: string}>} installations - Array of installation targets
@@ -1153,6 +1100,13 @@ export async function installSkillsToMultipleAgents(installations, skillNames =
1153
1100
 
1154
1101
  const fallbackSet = new Set();
1155
1102
 
1103
+ // XSPEC-468 R3: every skills install (init, update, the reconciler's plan) goes through here, so this is the
1104
+ // one place that can say "the texts you asked for are not in this copy of UDS" for all of them.
1105
+ if (uniqueInstallations.length > 0 && !isLocalePackAvailable(locale)) {
1106
+ results.localePackMissing = true;
1107
+ printLocalePackMissing(locale);
1108
+ }
1109
+
1156
1110
  for (const { agent, level } of uniqueInstallations) {
1157
1111
  const result = await installSkillsForAgent(agent, level, skillNames, projectPath, locale);
1158
1112
  results.installations.push(result);
@@ -1205,6 +1159,10 @@ export async function installCommandsToMultipleAgents(installations, commandName
1205
1159
  allFileHashes: {} // New: combined file hashes from all installations
1206
1160
  };
1207
1161
 
1162
+ if (uniqueInstallations.length > 0 && !isLocalePackAvailable(locale)) {
1163
+ printLocalePackMissing(locale);
1164
+ }
1165
+
1208
1166
  for (const item of uniqueInstallations) {
1209
1167
  const agent = item.agent;
1210
1168
  const level = item.level;