xdrs-core 0.49.0 → 0.49.1

package/.xdrs/_core/adrs/principles/003-skill-standards.md

@@ -75,7 +75,7 @@ Examples:
 
 **Skill naming**
 
-Unlike Policies, Research, Articles, and Initiatives, skill packages MUST NOT use a numeric prefix. A skill is identified by a descriptive name alone, keeping it compatible with the wider agentskills ecosystem, where clients (including this framework's own agentskills-format consumers) expect a plain descriptive identifier rather than a sequence number. Each skill name MUST be unique within its `scope/type/subject/skills/` namespace; check for an existing skill with the same name before creating a new one.
+Unlike Policies, Research, Articles, and Initiatives, skill packages are not auto-numbered. A skill is identified by a descriptive name, keeping it compatible with the wider agentskills ecosystem, where clients (including this framework's own agentskills-format consumers) expect a plain descriptive identifier rather than an auto-generated sequence number. The name MAY still contain digits, including as a prefix, when that is simply part of the descriptive name (e.g., `2fa-setup`). Each skill name MUST be unique within its `scope/type/subject/skills/` namespace; check for an existing skill with the same name before creating a new one.
 
 **SKILL.md format** (agentskills spec)
 
@@ -111,7 +111,7 @@ Known gotchas and how to handle them.
 
 Rules:
 - The `name` field MUST match the folder name exactly (e.g., `code-review`). This keeps skill identifiers simple and aligned with the filesystem hierarchy.
-- The directory name and the `name:` field MUST contain only lowercase alphanumeric characters and hyphens (e.g., `code-review`), with no numeric prefix.
+- The directory name and the `name:` field MUST contain only lowercase alphanumeric characters and hyphens (e.g., `code-review`, `2fa-setup`).
 - `## Overview` SHOULD state the task objective, expected outcome, and relevant prerequisites or tools when they matter.
 - `## Instructions` SHOULD include verification steps or acceptance criteria at the end of the task, or at the end of major phases when partial validation matters.
 - For diagram format preferences and non-Markdown asset rules, see [`_core-adr-policy-020`](020-media-and-asset-standards.md).

package/lib/lint.js

@@ -19,7 +19,8 @@ const ALLOWED_SUBJECTS = {
 const TYPE_NAMES = new Set(Object.keys(TYPE_TO_ID));
 const RESERVED_SCOPES = new Set(['_core', '_local']);
 const NUMBERED_FILE_RE = /^(\d{3,})-([a-z0-9-]+)\.md$/;
-// Skill package folders are not numbered (see _core-adr-policy-003): plain lowercase kebab-case.
+// Skill package folders are not auto-numbered (see _core-adr-policy-003): plain lowercase
+// kebab-case; digits are allowed anywhere in the name, including as a prefix.
 const SKILL_DIR_RE = /^[a-z0-9-]+$/;
 const REQUIRED_ROOT_INDEX_TEXT = 'XDRS scopes listed last override the ones listed first';
 const SUBJECT_ARTIFACT_DIRS = new Set(['skills', 'articles', 'researches', 'initiatives']);

package/lib/lint.test.js

@@ -53,9 +53,9 @@ test('reports broken local document links in skill files', () => {
   const workspaceRoot = createWorkspace('broken-skill-link', {
     '.xdrs/index.md': rootIndex(),
     '.xdrs/_local/adrs/index.md': localAdrIndex([
-      '- [001-check-links](principles/skills/001-check-links/SKILL.md) - Check local links'
+      '- [check-links](principles/skills/check-links/SKILL.md) - Check local links'
     ]),
-    '.xdrs/_local/adrs/principles/skills/001-check-links/SKILL.md': skillDocument('See [Missing](missing.md).'),
+    '.xdrs/_local/adrs/principles/skills/check-links/SKILL.md': skillDocument('See [Missing](missing.md).'),
   });
 
   const result = lintWorkspace(workspaceRoot);
@@ -300,11 +300,11 @@ test('reports unknown frontmatter fields in SKILL.md files', () => {
   const workspaceRoot = createWorkspace('skill-unknown-frontmatter', {
     '.xdrs/index.md': rootIndex(),
     '.xdrs/_local/adrs/index.md': localAdrIndex([
-      '- [001-check-links](principles/skills/001-check-links/SKILL.md) - Check links'
+      '- [check-links](principles/skills/check-links/SKILL.md) - Check links'
     ]),
-    '.xdrs/_local/adrs/principles/skills/001-check-links/SKILL.md': [
+    '.xdrs/_local/adrs/principles/skills/check-links/SKILL.md': [
       '---',
-      'name: 001-check-links',
+      'name: check-links',
       'description: Test skill document',
       'unknown-field: some value',
       '---',
@@ -329,11 +329,11 @@ test('accepts all known frontmatter fields in SKILL.md files', () => {
   const workspaceRoot = createWorkspace('skill-known-frontmatter', {
     '.xdrs/index.md': rootIndex(),
     '.xdrs/_local/adrs/index.md': localAdrIndex([
-      '- [001-check-links](principles/skills/001-check-links/SKILL.md) - Check links'
+      '- [check-links](principles/skills/check-links/SKILL.md) - Check links'
     ]),
-    '.xdrs/_local/adrs/principles/skills/001-check-links/SKILL.md': [
+    '.xdrs/_local/adrs/principles/skills/check-links/SKILL.md': [
       '---',
-      'name: 001-check-links',
+      'name: check-links',
       'description: Test skill document',
       'license: MIT',
       'metadata:',
@@ -358,6 +358,34 @@ test('accepts all known frontmatter fields in SKILL.md files', () => {
   expect(result.errors.join('\n')).not.toContain('unknown field');
 });
 
+test('accepts skill package names containing digits, including as a prefix', () => {
+  const workspaceRoot = createWorkspace('skill-name-with-digits', {
+    '.xdrs/index.md': rootIndex(),
+    '.xdrs/_local/adrs/index.md': localAdrIndex([
+      '- [2fa-setup](principles/skills/2fa-setup/SKILL.md) - 2FA setup'
+    ]),
+    '.xdrs/_local/adrs/principles/skills/2fa-setup/SKILL.md': [
+      '---',
+      'name: 2fa-setup',
+      'description: Test skill document',
+      '---',
+      '',
+      '## Overview',
+      '',
+      'Test skill overview.',
+      '',
+      '## Instructions',
+      '',
+      'Test instructions.',
+      ''
+    ].join('\n'),
+  });
+
+  const result = lintWorkspace(workspaceRoot);
+
+  expect(result.errors.join('\n')).not.toContain('Invalid skill package name');
+});
+
 test('derives expected frontmatter name from the markdown heading title', () => {
   const workspaceRoot = createWorkspace('heading-name-match', {
     '.xdrs/index.md': rootIndex(),
@@ -2063,10 +2091,10 @@ test('reports unexpected directories inside a skill package', () => {
     '.xdrs/index.md': rootIndex(),
     '.xdrs/_local/index.md': localScopeIndex(),
     '.xdrs/_local/adrs/index.md': localAdrIndex([
-      '- [001-check-links](principles/skills/001-check-links/SKILL.md) - Check local links'
+      '- [check-links](principles/skills/check-links/SKILL.md) - Check local links'
     ]),
-    '.xdrs/_local/adrs/principles/skills/001-check-links/SKILL.md': skillDocument('Skill body.'),
-    '.xdrs/_local/adrs/principles/skills/001-check-links/extras/note.txt': 'unexpected',
+    '.xdrs/_local/adrs/principles/skills/check-links/SKILL.md': skillDocument('Skill body.'),
+    '.xdrs/_local/adrs/principles/skills/check-links/extras/note.txt': 'unexpected',
   });
 
   const result = lintWorkspace(workspaceRoot);
@@ -3181,7 +3209,7 @@ function xdrDocument(body) {
 function skillDocument(body) {
   return [
     '---',
-    'name: 001-check-links',
+    'name: check-links',
     'description: Test skill document',
     '---',
     '',
@@ -3302,9 +3330,9 @@ test('reports emoji in SKILL.md', () => {
   const workspaceRoot = createWorkspace('skill-emoji', {
     '.xdrs/index.md': rootIndex(),
     '.xdrs/_local/adrs/index.md': localAdrIndex([
-      '- [001-check-links](principles/skills/001-check-links/SKILL.md) - Check links'
+      '- [check-links](principles/skills/check-links/SKILL.md) - Check links'
     ]),
-    '.xdrs/_local/adrs/principles/skills/001-check-links/SKILL.md': skillDocument('Step 1: do something \u2705'),
+    '.xdrs/_local/adrs/principles/skills/check-links/SKILL.md': skillDocument('Step 1: do something \u2705'),
   });
 
   const result = lintWorkspace(workspaceRoot);
@@ -3585,13 +3613,13 @@ test('reports XDRS element frontmatter description exceeding 1024 characters', (
 });
 
 test('reports SKILL.md frontmatter name exceeding 64 characters', () => {
-  const longName = '001-check-links-' + 'a'.repeat(50);
+  const longName = 'check-links-' + 'a'.repeat(60);
   const workspaceRoot = createWorkspace('skill-name-too-long', {
     '.xdrs/index.md': rootIndex(),
     '.xdrs/_local/adrs/index.md': localAdrIndex([
-      '- [001-check-links](principles/skills/001-check-links/SKILL.md) - Check links'
+      '- [check-links](principles/skills/check-links/SKILL.md) - Check links'
     ]),
-    '.xdrs/_local/adrs/principles/skills/001-check-links/SKILL.md': [
+    '.xdrs/_local/adrs/principles/skills/check-links/SKILL.md': [
       '---',
       `name: ${longName}`,
       'description: Test skill document',
@@ -3617,11 +3645,11 @@ test('reports SKILL.md frontmatter description exceeding 1024 characters', () =>
   const workspaceRoot = createWorkspace('skill-description-too-long', {
     '.xdrs/index.md': rootIndex(),
     '.xdrs/_local/adrs/index.md': localAdrIndex([
-      '- [001-check-links](principles/skills/001-check-links/SKILL.md) - Check links'
+      '- [check-links](principles/skills/check-links/SKILL.md) - Check links'
     ]),
-    '.xdrs/_local/adrs/principles/skills/001-check-links/SKILL.md': [
+    '.xdrs/_local/adrs/principles/skills/check-links/SKILL.md': [
       '---',
-      'name: 001-check-links',
+      'name: check-links',
       `description: ${'x'.repeat(1025)}`,
       '---',
       '',
@@ -3693,9 +3721,9 @@ test('reports SKILL.md exceeding 6500 word limit', () => {
   const workspaceRoot = createWorkspace('skill-too-many-words', {
     '.xdrs/index.md': rootIndex(),
     '.xdrs/_local/adrs/index.md': localAdrIndex([
-      '- [001-check-links](principles/skills/001-check-links/SKILL.md) - Check links'
+      '- [check-links](principles/skills/check-links/SKILL.md) - Check links'
     ]),
-    '.xdrs/_local/adrs/principles/skills/001-check-links/SKILL.md': skillDocument(longBody),
+    '.xdrs/_local/adrs/principles/skills/check-links/SKILL.md': skillDocument(longBody),
   });
 
   const result = lintWorkspace(workspaceRoot);
@@ -3709,11 +3737,11 @@ test('passes when extra files exist at skill package root', () => {
   const workspaceRoot = createWorkspace('extra-skill-file', {
     '.xdrs/index.md': rootIndex(),
     '.xdrs/_local/adrs/index.md': localAdrIndex([
-      '- [001-check-links](principles/skills/001-check-links/SKILL.md) - Check links'
+      '- [check-links](principles/skills/check-links/SKILL.md) - Check links'
     ]),
-    '.xdrs/_local/adrs/principles/skills/001-check-links/SKILL.md': skillDocument('Body.'),
-    '.xdrs/_local/adrs/principles/skills/001-check-links/extra.md': 'Allowed extra file',
-    '.xdrs/_local/adrs/principles/skills/001-check-links/schema.json': '{"type":"object"}',
+    '.xdrs/_local/adrs/principles/skills/check-links/SKILL.md': skillDocument('Body.'),
+    '.xdrs/_local/adrs/principles/skills/check-links/extra.md': 'Allowed extra file',
+    '.xdrs/_local/adrs/principles/skills/check-links/schema.json': '{"type":"object"}',
   });
 
   const result = lintWorkspace(workspaceRoot);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "xdrs-core",
-  "version": "0.49.0",
+  "version": "0.49.1",
   "description": "XDRS (eXtensible Decision Record System): a framework to structure, compile and distribute Architectural (ADR), Business (BDR), and Engineering (EDR) decision records contents so that AI agents and humans can reliably find and use them with hierarchical scopes and controlled rollout in the format of distributable versioned packages.",
   "repository": {
     "type": "git",