xdrs-core 0.48.1 → 0.49.0

package/.filedist-package.yml

@@ -10,9 +10,9 @@ sets:
     output:
       path: .
       symlinks:
-        - source: .xdrs/**/skills/001-review
+        - source: .xdrs/**/skills/review
           target: .agents/skills
-        - source: .xdrs/**/skills/008-write-xdrs-doc
+        - source: .xdrs/**/skills/write-xdrs-doc
           target: .agents/skills
       gitignore: false
 

package/.xdrs/_core/adrs/index.md

@@ -31,15 +31,15 @@ Foundational standards, principles, and guidelines.
 
 Step-by-step procedural guides for humans and AI agents.
 
-- [001-review](principles/skills/001-review/SKILL.md) - **Review** — review code and files against Policies
-- [002-write-policy](principles/skills/002-write-policy/SKILL.md) - **Write Policy** — create a new Policy document
-- [003-write-skill](principles/skills/003-write-skill/SKILL.md) - **Write Skill** — create a new skill package
-- [004-write-article](principles/skills/004-write-article/SKILL.md) - **Write Article** — create a new article document
-- [005-write-research](principles/skills/005-write-research/SKILL.md) - **Write Research** — create a new research document
-- [006-write-initiative](principles/skills/006-write-initiative/SKILL.md) - **Write Initiative** — create a new initiative document
-- [007-write-presentation](principles/skills/007-write-presentation/SKILL.md) - **Write Presentation** — create Marp slide presentations for XDRS documents
-- [008-write-xdrs-doc](principles/skills/008-write-xdrs-doc/SKILL.md) - **Write XDRS Doc** — router skill; infers document type and delegates to the appropriate authoring skill
-- [009-compile-scope](principles/skills/009-compile-scope/SKILL.md) - **Compile Scope** — compiles or updates a `compiled`-type scope from its configured external sources
+- [review](principles/skills/review/SKILL.md) - **Review** — review code and files against Policies
+- [write-policy](principles/skills/write-policy/SKILL.md) - **Write Policy** — create a new Policy document
+- [write-skill](principles/skills/write-skill/SKILL.md) - **Write Skill** — create a new skill package
+- [write-article](principles/skills/write-article/SKILL.md) - **Write Article** — create a new article document
+- [write-research](principles/skills/write-research/SKILL.md) - **Write Research** — create a new research document
+- [write-initiative](principles/skills/write-initiative/SKILL.md) - **Write Initiative** — create a new initiative document
+- [write-presentation](principles/skills/write-presentation/SKILL.md) - **Write Presentation** — create Marp slide presentations for XDRS documents
+- [write-xdrs-doc](principles/skills/write-xdrs-doc/SKILL.md) - **Write XDRS Doc** — router skill; infers document type and delegates to the appropriate authoring skill
+- [compile-scope](principles/skills/compile-scope/SKILL.md) - **Compile Scope** — compiles or updates a `compiled`-type scope from its configured external sources
 
 ## Articles
 

package/.xdrs/_core/adrs/principles/001-xdrs-standards.md

@@ -53,7 +53,7 @@ ADR and EDR share the same six technical subject names (see [`_core-adr-policy-0
 - **Files listed in `.filedist.lock` are external XDRs.** A file whose path appears in the workspace root `.filedist.lock` file was distributed from an external source repository. It MUST NOT be modified locally. To change it, submit the change to the source repository and re-extract the updated package. The `.filedist.lock` format is one entry per line: `<relative-path>|<package>|<version>`. A scope is considered external when any of its files appear in `.filedist.lock`, and tools (such as `xdrs-core lint`) will skip external scopes by default. The `.filedist.lock` file can also be used to detect which files changed when bumping an external scope to a newer version: compare the version field in `.filedist.lock` entries before and after the upgrade and diff the affected paths to understand what decisions were added, updated, or removed.
 - Optional supporting artifacts under the same subject:
   - `[xdrs-root]/[scope]/[type]/[subject]/researches/[number]-[short-title].md`
-  - `[xdrs-root]/[scope]/[type]/[subject]/skills/[number]-[skill-name]/SKILL.md`
+  - `[xdrs-root]/[scope]/[type]/[subject]/skills/[skill-name]/SKILL.md`
   - `[xdrs-root]/[scope]/[type]/[subject]/articles/[number]-[short-title].md`
   - `[xdrs-root]/[scope]/[type]/[subject]/initiatives/[number]-[short-title].md`
 - Research, skills, and articles are part of the framework, but each has its own concept-specific standards in dedicated Policies. This Policy defines the shared framework baseline; `_core-adr-policy-002` defines the Policy document writing standard.
@@ -67,7 +67,7 @@ ADR and EDR share the same six technical subject names (see [`_core-adr-policy-0
   - Articles use `[xdrs-root]/[scope]/[type]/[subject]/articles/.assets/`
   - Research uses `[xdrs-root]/[scope]/[type]/[subject]/researches/.assets/`
   - Initiatives use `[xdrs-root]/[scope]/[type]/[subject]/initiatives/.assets/`
-  - Skills use `[xdrs-root]/[scope]/[type]/[subject]/skills/[number]-[skill-name]/.assets/`
+  - Skills use `[xdrs-root]/[scope]/[type]/[subject]/skills/[skill-name]/.assets/`
 - **Scopes:** 
   - Short name that defines a group or a package of XDRS
   - examples: `business-x`, `business-y`, `team-43`, `_core`
@@ -147,8 +147,8 @@ subject/
 - [_core-adr-policy-010 - Scope governance](010-scope-governance.md) - Scope-type definition convention, scope-local standards, and governance application model
 - [_core-adr-policy-011 - core scope type](011-core-scope-type.md) - Defines the `core` scope type and meta-governance scope conventions
 - [_core-adr-policy-016 - Policy Subjects](016-policy-subjects.md) - Allowed subjects per type, descriptions, examples, and disambiguation tiebreakers
-- [001-review skill](skills/001-review/SKILL.md) - Skill for reviewing code changes against Policies
-- [002-write-policy skill](skills/002-write-policy/SKILL.md) - Skill for creating a new Policy following this standard
+- [review skill](skills/review/SKILL.md) - Skill for reviewing code changes against Policies
+- [write-policy skill](skills/write-policy/SKILL.md) - Skill for creating a new Policy following this standard
 - [_core-adr-policy-003 - Skill standards](003-skill-standards.md)
 - [_core-adr-policy-004 - Article standards](004-article-standards.md)
 - [_core-adr-policy-006 - Research standards](006-research-standards.md)

package/.xdrs/_core/adrs/principles/002-policy-standards.md

@@ -173,8 +173,8 @@ Question: In the end, state explicitly the question that needs to be answered. E
 ## References
 
 - [_core-adr-policy-001 - XDRS standards](001-xdrs-standards.md) - Framework elements: types, scopes, subjects, folder structure
-- [001-review skill](skills/001-review/SKILL.md) - Skill for reviewing code changes against Policies
-- [002-write-policy skill](skills/002-write-policy/SKILL.md) - Skill for creating a new Policy following this standard
+- [review skill](skills/review/SKILL.md) - Skill for reviewing code changes against Policies
+- [write-policy skill](skills/write-policy/SKILL.md) - Skill for creating a new Policy following this standard
 - [_core-adr-policy-003 - Skill standards](003-skill-standards.md)
 - [_core-adr-policy-004 - Article standards](004-article-standards.md)
 - [_core-adr-policy-006 - Research standards](006-research-standards.md)

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

@@ -19,7 +19,7 @@ How should skills be authored, structured, and organized within a project so tha
 
 **agentskills-compatible skill packages, co-located with XDRS**
 
-Skills follow the [agentskills](https://agentskills.io/specification) open format and live inside the XDRS subject folder under a `skills/` sub-directory. Each skill occupies its own numbered package folder, mirroring the XDRS numbering convention.
+Skills follow the [agentskills](https://agentskills.io/specification) open format and live inside the XDRS subject folder under a `skills/` sub-directory. Each skill occupies its own package folder named after the skill itself, without the numeric prefix used by other XDRS document types.
 
 A skill MAY target a human operator, an AI agent, or both. Instructions MUST be written imperatively and at a level of detail that either a person or an agent can follow without additional context. This design allows a skill to start as a human-only procedure and evolve — incrementally — toward partial or full AI automation without restructuring the document.
 
@@ -61,7 +61,7 @@ Quick test:
     [type]/
       [subject]/
         skills/
-          [number]-[skill-name]/
+          [skill-name]/
             SKILL.md              # required
             scripts/              # optional: executable scripts the agent may run
             references/           # optional: detailed reference material
@@ -69,21 +69,19 @@ Quick test:
 ```
 
 Examples:
-- `.xdrs/_core/adrs/principles/skills/001-code-review/SKILL.md`
-- `.xdrs/business-x/edrs/devops/skills/001-ci-pipeline-debug/SKILL.md`
-- `.xdrs/_local/adrs/principles/skills/001-my-nice-skill/SKILL.md`
+- `.xdrs/_core/adrs/principles/skills/code-review/SKILL.md`
+- `.xdrs/business-x/edrs/devops/skills/ci-pipeline-debug/SKILL.md`
+- `.xdrs/_local/adrs/principles/skills/my-nice-skill/SKILL.md`
 
-**Skill numbering**
+**Skill naming**
 
-- Each skill has a number unique within its `scope/type/subject/skills/` namespace.
-- Determine the next number by checking the highest number already present in that namespace. MUST NOT reuse numbers of deleted skills.
-- Gaps in the sequence are expected and allowed.
+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.
 
 **SKILL.md format** (agentskills spec)
 
 ```
 ---
-name: [number]-[skill-name]              # required: matches the folder name exactly; max 64 chars
+name: [skill-name]              # required: matches the folder name exactly; max 64 chars
 description: >            # required: what the skill does AND when to activate it; max 1024 chars
   Concise explanation of the skill and the situations in which an agent should load it.
 license: <license>        # optional
@@ -112,8 +110,8 @@ Known gotchas and how to handle them.
 ```
 
 Rules:
-- The `name` field MUST match the folder name exactly (e.g., `001-code-review`). This keeps skill identifiers simple and aligned with the filesystem hierarchy.
-- The directory name MUST follow the format `[number]-[skill-name]` (e.g., `001-code-review`), matching the `name:` field.
+- 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.
 - `## 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).
@@ -127,7 +125,7 @@ Rules:
 Use the [skills-ref](https://github.com/agentskills/agentskills/tree/main/skills-ref) CLI to validate before committing:
 
 ```
-skills-ref validate .xdrs/[scope]/[type]/[subject]/skills/[number]-[skill-name]
+skills-ref validate .xdrs/[scope]/[type]/[subject]/skills/[skill-name]
 ```
 
 ## Considered Options

package/.xdrs/_core/adrs/principles/004-article-standards.md

@@ -101,4 +101,4 @@ when referencing an information from those documents.]
 - [_core-adr-policy-001 - XDRS standards](001-xdrs-standards.md)
 - [_core-adr-policy-003 - Skill standards](003-skill-standards.md)
 - [_core-adr-policy-006 - Research standards](006-research-standards.md)
-- [004-write-article skill](skills/004-write-article/SKILL.md) - Step-by-step instructions for creating a new article
+- [write-article skill](skills/write-article/SKILL.md) - Step-by-step instructions for creating a new article

package/.xdrs/_core/adrs/principles/006-research-standards.md

@@ -136,4 +136,4 @@ Prefer tables and bullet lists for simple comparisons; for diagrams see _core-ad
 - [_core-adr-policy-003 - Skill standards](003-skill-standards.md)
 - [_core-adr-policy-004 - Article standards](004-article-standards.md)
 - [_core-adr-policy-020 - Media and asset standards](020-media-and-asset-standards.md) - Diagram format preferences and non-Markdown asset rules
-- [005-write-research skill](skills/005-write-research/SKILL.md) - Step-by-step instructions for creating a research document
+- [write-research skill](skills/write-research/SKILL.md) - Step-by-step instructions for creating a research document

package/.xdrs/_core/adrs/principles/007-initiative-standards.md

@@ -137,4 +137,4 @@ Due date: YYYY-MM-DD
 - [_core-adr-policy-001 - XDRS standards](001-xdrs-standards.md) - Framework elements: types, scopes, subjects, folder structure
 - [_core-adr-policy-004 - Article standards](004-article-standards.md) - Companion artifact type for synthetic views
 - [_core-adr-policy-006 - Research standards](006-research-standards.md) - Companion artifact type for exploratory evidence
-- [006-write-initiative skill](skills/006-write-initiative/SKILL.md) - Step-by-step instructions for creating a new initiative
+- [write-initiative skill](skills/write-initiative/SKILL.md) - Step-by-step instructions for creating a new initiative

package/.xdrs/_core/adrs/principles/009-presentation-standards.md

@@ -50,6 +50,6 @@ Presentations are Markdown files in Marp format, stored in the `.assets/` folder
 - [_core-adr-policy-001 - XDRS standards](001-xdrs-standards.md) - Framework structure and `.assets/` placement rules
 - [_core-adr-policy-002 - Policy standards](002-policy-standards.md) - Policy document writing rules
 - [_core-adr-policy-004 - Article standards](004-article-standards.md) - Article standards for multi-document views
-- [007-write-presentation skill](skills/007-write-presentation/SKILL.md) - Skill for creating slide presentations
+- [write-presentation skill](skills/write-presentation/SKILL.md) - Skill for creating slide presentations
 - [_core-adr-policy-020 - Media and asset standards](020-media-and-asset-standards.md) - Diagram format preferences and non-Markdown asset rules
 - [Marp](https://marp.app/) - Markdown Presentation Ecosystem

package/.xdrs/_core/adrs/principles/018-external-path-symlinks.md

@@ -21,7 +21,7 @@ How should XDRS files be made accessible from paths outside the `.xdrs/` root wi
 
 When a file or directory inside `.xdrs/` needs to be reachable from an external path, a symlink MUST be created at the external path pointing to the canonical `.xdrs/` location. The canonical file MUST remain inside `.xdrs/`. Files MUST NOT be copied to external paths.
 
-**Example:** `.agents/skills/001-review` (symlink) → `.xdrs/_core/adrs/principles/skills/001-review/`
+**Example:** `.agents/skills/review` (symlink) → `.xdrs/_core/adrs/principles/skills/review/`
 
 ### Details
 

package/.xdrs/_core/adrs/principles/articles/001-xdrs-overview.md

@@ -114,7 +114,7 @@ Every decision record and its supporting artifacts live at a fixed path:
         researches/
           [number]-[short-title].md
         skills/
-          [number]-[skill-name]/
+          [skill-name]/
             SKILL.md
         articles/
           [number]-[short-title].md
@@ -170,7 +170,7 @@ Follow [_core-adr-policy-001](../001-xdrs-standards.md) and [_core-adr-policy-00
   allowed subject or use `principles` if none fits (propose a new subject via a `_core` ADR).
 - **New research** — add a `researches/[number]-[short-title].md` inside the relevant subject
   folder, following [_core-adr-policy-006](../006-research-standards.md).
-- **New skill** — add a `skills/[number]-[skill-name]/SKILL.md` inside the relevant subject
+- **New skill** — add a `skills/[skill-name]/SKILL.md` inside the relevant subject
   folder, following [_core-adr-policy-003](../003-skill-standards.md).
 - **New article** — add an `articles/[number]-[short-title].md` inside the relevant subject
   folder, following [_core-adr-policy-004](../004-article-standards.md).
@@ -200,9 +200,9 @@ Follow [_core-adr-policy-001](../001-xdrs-standards.md) and [_core-adr-policy-00
 - [_core-adr-policy-004](../004-article-standards.md) - Article standards
 - [_core-adr-policy-006](../006-research-standards.md) - Research standards
 - [_core-adr-policy-007](../007-initiative-standards.md) - Initiative standards
-- [001-review skill](../skills/001-review/SKILL.md) - Reviewing code against Policies
-- [002-write-policy skill](../skills/002-write-policy/SKILL.md) - Writing a new Policy
-- [003-write-skill skill](../skills/003-write-skill/SKILL.md) - Writing a new skill
-- [004-write-article skill](../skills/004-write-article/SKILL.md) - Writing a new article
-- [005-write-research skill](../skills/005-write-research/SKILL.md) - Writing a new research document
+- [review skill](../skills/review/SKILL.md) - Reviewing code against Policies
+- [write-policy skill](../skills/write-policy/SKILL.md) - Writing a new Policy
+- [write-skill skill](../skills/write-skill/SKILL.md) - Writing a new skill
+- [write-article skill](../skills/write-article/SKILL.md) - Writing a new article
+- [write-research skill](../skills/write-research/SKILL.md) - Writing a new research document
 - [_core-adr-policy-005](../005-semantic-versioning-for-xdrs-packages.md) - Semantic versioning rules for XDRS packages

package/.xdrs/_core/adrs/principles/skills/.assets/conflict-detection.md

@@ -2,7 +2,7 @@
 
 ## Purpose
 
-This module provides LLM-agent instructions for detecting semantic and structural conflicts between `#### NN-rulename` rule blocks across all governance policies loaded for a scope. It is invoked from within skills (001-review, 002-write-policy, etc.) after all governance layers have been loaded and before any authoring or review work begins.
+This module provides LLM-agent instructions for detecting semantic and structural conflicts between `#### NN-rulename` rule blocks across all governance policies loaded for a scope. It is invoked from within skills (review, write-policy, etc.) after all governance layers have been loaded and before any authoring or review work begins.
 
 Lint tools enforce *structural* conflicts only (duplicate rule numbers with different content). This module handles *semantic* conflicts: two rules with different numbers that are logically incompatible.
 

package/.xdrs/_core/adrs/principles/skills/{009-compile-scope → compile-scope}/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: 009-compile-scope
+name: compile-scope
 description: >
   Compiles or updates any scope declaring `scope-type: compiled` from its configured external sources. Reads compilation meta-policies to discover sources, fetches content (git clone, local copy, or web scrape), plans policy changes, migrates policies one at a time with structured format, `## Source` sections, and `**compilation-note:**` markers, then runs lint and review. Documents source inconsistencies without inventing fixes. Activate when the user asks to compile, update, sync, refresh, or recompile a compiled scope.
 metadata:
@@ -95,7 +95,7 @@ After writing each policy:
 
 ### Phase 6: Review
 
-1. Read and follow `.xdrs/_core/adrs/principles/skills/001-review/SKILL.md` fully, scoped to the compiled scope.
+1. Read and follow `.xdrs/_core/adrs/principles/skills/review/SKILL.md` fully, scoped to the compiled scope.
 2. Apply any review notes from the meta-policy's `## Review Notes` section as additional mandatory conventions during this review.
 3. Fix only mechanical and structural findings from the review. Do NOT invent content to resolve content-level findings.
 4. Any review findings that require inventing or guessing content MUST be recorded as inconsistencies in Phase 7.

package/.xdrs/_core/adrs/principles/skills/{001-review → review}/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: 001-review
+name: review
 description: >
    Reviews code changes, xdrs docs or any other files against applicable Policies and reports violations as structured findings.
    Activate this skill when the user asks to review, lint, audit, check, verify, validate, or assess any files or Policies, or when checking whether a document or implementation is consistent with, compliant with, or conforms to a standard or Policy.

package/.xdrs/_core/adrs/principles/skills/{001-review/001-review.test.int.js → review/review.test.int.js}

@@ -15,7 +15,7 @@ test('smoke test', async () => {
 			...copilotCmd(REPO_ROOT),
 		},
 		'Reply ONLY with "READY" after checking if SKILL 001 has any contents',
-		'Verify that the final output is ONLY "READY" and that it read file 001-review/SKILL.md',
+		'Verify that the final output is ONLY "READY" and that it read file review/SKILL.md',
 		null,
 		true
 	);
@@ -23,7 +23,7 @@ test('smoke test', async () => {
 	expect(err).toBe('');
 });
 
-test('001-review outputs the required review template', async () => {
+test('review outputs the required review template', async () => {
 	const err = await testPrompt(
 		{
 			workspaceRoot: REPO_ROOT,
@@ -31,7 +31,7 @@ test('001-review outputs the required review template', async () => {
 			...copilotCmd(REPO_ROOT),
 		},
 		'Review XDRS Policy 001-xdrs-standards',
-		'Verify that the skill 001-review was used, contains "## Findings", and "## Summary", includes an "Outcome: PASS", and that it read file 001-review/SKILL.md and 001-xdrs-standards.md.',
+		'Verify that the skill review was used, contains "## Findings", and "## Summary", includes an "Outcome: PASS", and that it read file review/SKILL.md and 001-xdrs-standards.md.',
 		null,
 		true
 	);

package/.xdrs/_core/adrs/principles/skills/{004-write-article → write-article}/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: 004-write-article
+name: write-article
 description: >
    Creates a new article document following XDRS article standards: selects scope, type, subject, and number; then writes a focused synthetic text that combines and links multiple Policies, Research documents, and Skills around a topic. Activate this skill when the user asks to create, add, or write a new article, guide, or overview document within an XDRS project.
 metadata:
@@ -47,7 +47,7 @@ Consult `001-xdrs-standards` while making each choice in this phase. The summari
 **Scope** — confirmed in Phase 0. Follow the external-scope validation in `.xdrs/_core/adrs/principles/skills/.assets/scope-selection.md`.
 
 **Type** — match the type of the XDRS elements the article primarily synthesizes (`adrs`, `bdrs`, or `edrs`).
-If the topic spans multiple types, use `adrs`. Use the same rules as `002-write-policy` Phase 2:
+If the topic spans multiple types, use `adrs`. Use the same rules as `write-policy` Phase 2:
 - **BDR**: business process, product policy, strategic rule, operational procedure
 - **ADR**: system context, integration pattern, overarching architectural choice
 - **EDR**: specific tool/library, coding practice, testing strategy, project structure, pipelines
@@ -136,7 +136,7 @@ Follow the lint verification steps in `.xdrs/_core/adrs/principles/skills/.asset
 ## Edge Cases
 
 - **Article vs. Policy confusion** — if the user asks for a document that makes a decision, write a Policy
-  (use the `002-write-policy` skill), not an article.
+  (use the `write-policy` skill), not an article.
 - **Cross-subject topic** — place the article in `principles`, not in any single subject folder.
 - **No existing articles folder** — create it; it is optional in the folder layout.
 - **Conflicting information found** — note the conflict in the article and always defer to the Policy.

package/.xdrs/_core/adrs/principles/skills/{004-write-article/004-write-article.test.int.js → write-article/write-article.test.int.js}

@@ -7,7 +7,7 @@ const REPO_ROOT = path.resolve(__dirname, '..', '..', '..', '..', '..', '..');
 
 jest.setTimeout(300000);
 
-test('004-write-article creates a local principles article', async () => {
+test('write-article creates a local principles article', async () => {
 	const err = await testPrompt(
 		{
 			workspaceRoot: REPO_ROOT,

package/.xdrs/_core/adrs/principles/skills/{006-write-initiative → write-initiative}/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: 006-write-initiative
+name: write-initiative
 description: >
   Creates a new initiative document following XDRS initiative standards: selects scope, type, subject, and number;
   then writes a focused execution initiative with problem context, proposed solution, approach, milestones, and deliverables.

package/.xdrs/_core/adrs/principles/skills/{002-write-policy → write-policy}/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: 002-write-policy
+name: write-policy
 description: >
   Creates a new Policy interactively: selects type, scope, subject, and writes a focused, conflict-checked policy document.
   Activate this skill when the user asks to create, add, or write a new Policy (ADR, BDR, or EDR).

package/.xdrs/_core/adrs/principles/skills/{002-write-policy/002-write-policy.test.int.js → write-policy/write-policy.test.int.js}

@@ -7,7 +7,7 @@ const REPO_ROOT = path.resolve(__dirname, '..', '..', '..', '..', '..', '..');
 
 jest.setTimeout(300000);
 
-test('002-write-policy creates a local EDR policy', async () => {
+test('write-policy creates a local EDR policy', async () => {
 	const err = await testPrompt(
 		{
 			workspaceRoot: REPO_ROOT,
@@ -15,7 +15,7 @@ test('002-write-policy creates a local EDR policy', async () => {
 			...copilotCmd(REPO_ROOT),
 		},
 		'Create a very small XDRS Policy deciding to use pnpm for Node.js monorepos',
-		'Verify that an XDRS Policy markdown file was created under .xdrs/_local/edrs/devops/, that it contains "## Context and Problem Statement" and "## Decision Outcome", that it read file 002-write-policy/SKILL.md and has the decision of using pnpm for Node.js monorepos.',
+		'Verify that an XDRS Policy markdown file was created under .xdrs/_local/edrs/devops/, that it contains "## Context and Problem Statement" and "## Decision Outcome", that it read file write-policy/SKILL.md and has the decision of using pnpm for Node.js monorepos.',
 		null,
 		true
 	);

package/.xdrs/_core/adrs/principles/skills/{007-write-presentation → write-presentation}/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: 007-write-presentation
+name: write-presentation
 description: >
   Creates a Marp slide presentation for an existing XDRS document (policy, research, article, or initiative).
   Activate this skill when the user asks to create slides, a presentation, or a slide deck for an XDRS document.
@@ -23,7 +23,7 @@ Identify the target scope from the parent document's path or the user's request;
 1. Read `.xdrs/_core/adrs/principles/009-presentation-standards.md` in full to internalize all presentation rules.
 2. Read `.xdrs/_core/adrs/principles/001-xdrs-standards.md` for `.assets/` placement rules and general framework structure.
 3. Identify the parent document (policy, research, article, or initiative) that the slides will support. The parent document must already exist. If no parent document exists, inform the user that slides cannot be standalone and suggest creating the parent document first.
-4. If the user wants slides covering content from multiple documents, check whether an article already exists that synthesizes those documents. If not, suggest creating an article first (using the 004-write-article skill) and then creating slides for that article.
+4. If the user wants slides covering content from multiple documents, check whether an article already exists that synthesizes those documents. If not, suggest creating an article first (using the `write-article` skill) and then creating slides for that article.
 
 ### Phase 2: Define the Presentation Scope
 
@@ -119,7 +119,7 @@ Rules:
    - Policies: `[xdrs-root]/[scope]/[type]/[subject]/.assets/[slide-file].md`
    - Articles: `[xdrs-root]/[scope]/[type]/[subject]/articles/.assets/[slide-file].md`
    - Research: `[xdrs-root]/[scope]/[type]/[subject]/researches/.assets/[slide-file].md`
-   - Skills: `[xdrs-root]/[scope]/[type]/[subject]/skills/[number]-[skill-name]/.assets/[slide-file].md`
+   - Skills: `[xdrs-root]/[scope]/[type]/[subject]/skills/[skill-name]/.assets/[slide-file].md`
    - Initiatives: `[xdrs-root]/[scope]/[type]/[subject]/initiatives/.assets/[slide-file].md`
 2. Update the parent document with the link to the slide file.
 3. Verify that the slide file name is <= 64 characters and lowercase.

package/.xdrs/_core/adrs/principles/skills/{005-write-research → write-research}/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: 005-write-research
+name: write-research
 description: >
   Creates a new research document following XDRS research standards: selects scope, type, subject, and number;
   then writes an IMRAD-based study with enough evidence and method detail to stand on its own as a technical paper.
@@ -42,7 +42,7 @@ Consult `001-xdrs-standards` while making each choice in this phase. The summari
 
 **Scope** — confirmed in Phase 0. Follow the external-scope validation in `.xdrs/_core/adrs/principles/skills/.assets/scope-selection.md`.
 
-**Type** — match the type of decision this research supports (`adrs`, `bdrs`, or `edrs`). Use the same rules as `002-write-policy` Phase 2:
+**Type** — match the type of decision this research supports (`adrs`, `bdrs`, or `edrs`). Use the same rules as `write-policy` Phase 2:
 - **BDR**: business process, product policy, strategic rule, operational procedure
 - **ADR**: system context, integration pattern, overarching architectural choice
 - **EDR**: specific tool/library, coding practice, testing strategy, project structure, pipelines
@@ -280,7 +280,7 @@ Follow the lint verification steps in `.xdrs/_core/adrs/principles/skills/.asset
 
 - [_core-adr-policy-006 - Research standards](../../006-research-standards.md)
 - [_core-adr-policy-001 - XDRS standards](../../001-xdrs-standards.md)
-- [002-write-policy skill](../002-write-policy/SKILL.md)
+- [write-policy skill](../write-policy/SKILL.md)
 
 ## Constraints
 

package/.xdrs/_core/adrs/principles/skills/{005-write-research/005-write-research.test.int.js → write-research/write-research.test.int.js}

@@ -7,7 +7,7 @@ const REPO_ROOT = path.resolve(__dirname, '..', '..', '..', '..', '..', '..');
 
 jest.setTimeout(600000);
 
-test('005-write-research creates an IMRAD research document in copy mode', async () => {
+test('write-research creates an IMRAD research document in copy mode', async () => {
 	const err = await testPrompt(
 		{
 			workspaceRoot: REPO_ROOT,

package/.xdrs/_core/adrs/principles/skills/{003-write-skill → write-skill}/SKILL.md

@@ -1,7 +1,7 @@
 ---
-name: 003-write-skill
+name: write-skill
 description: >
-  Creates a new skill package following XDRS skill standards: determines type, scope, subject, and number;
+  Creates a new skill package following XDRS skill standards: determines type, scope, and subject;
   then writes a focused SKILL.md with correct frontmatter, phased instructions, examples, and edge cases.
   Activate this skill when the user asks to create, add, or write a new skill, agent skill, or SKILL.md file.
 metadata:
@@ -22,11 +22,11 @@ Guides the creation of a well-structured skill package by following `_core-adr-p
 
 ### Phase 1: Understand the Skill Goal
 
-1. Read `.xdrs/_core/adrs/principles/003-skill-standards.md` in full to internalize the SKILL.md format, folder layout, and numbering rules.
-2. Read `.xdrs/_core/adrs/principles/001-xdrs-standards.md` in full before defining any core element for the skill package. Treat it as the canonical source for type, scope, subject, numbering expectations, naming constraints, and folder placement rules.
+1. Read `.xdrs/_core/adrs/principles/003-skill-standards.md` in full to internalize the SKILL.md format and folder layout.
+2. Read `.xdrs/_core/adrs/principles/001-xdrs-standards.md` in full before defining any core element for the skill package. Treat it as the canonical source for type, scope, subject, naming constraints, and folder placement rules.
 3. Identify what the skill must do, the concrete outcome it should produce, and the exact conditions under which an agent should activate it. Do NOT proceed without a clear goal, outcome, and activation trigger.
 
-### Phase 2: Select Type, Scope, Subject, and Number
+### Phase 2: Select Type, Scope, and Subject
 
 Consult `001-xdrs-standards` while making each choice in this phase. The summaries below are orientation only; when there is any ambiguity or edge case, the standard decides.
 
@@ -44,9 +44,7 @@ Quick test:
 
 **Subject** — follow the subject selection guidance in `.xdrs/_core/adrs/principles/skills/.assets/scope-selection.md`.
 
-**Skill number** — scan `.xdrs/[scope]/[type]/[subject]/skills/` for the highest existing number and increment by 1. Never reuse numbers from deleted skills.
-
-**Skill name** — `[number]-[short-kebab-case-description]`, max 64 characters total. The directory name matches the `name` field exactly.
+**Skill name** — a short, descriptive, lowercase kebab-case name (e.g. `code-review`), max 64 characters total. The directory name matches the `name` field exactly. Check `.xdrs/[scope]/[type]/[subject]/skills/` first to avoid colliding with an existing skill name.
 
 ### Phase 3: Research Existing Skills and Related Policies
 
@@ -61,7 +59,7 @@ Use the mandatory agentskills format:
 
 ```
 ---
-name: [number]-[skill-name]
+name: [skill-name]
 description: >
   [What the skill does AND exactly when an agent should activate it. Max 1024 chars.]
 metadata:
@@ -100,7 +98,7 @@ Rules:
 - Do not present the skill itself as policy; mandatory behavior must come from referenced Policies or other policy artifacts.
 - When the skill depends on Policies, make the activation logic and instructions consistent with the Policy metadata so the skill does not operationalize inactive or out-of-scope decisions.
 - For diagrams and non-Markdown assets, follow `_core-adr-policy-020`: prefer plain Markdown tables/lists first, then ASCII art for very simple cases, then Mermaid.js (sequence, state, activity, entity diagrams) for complex ones, then draw.io when Mermaid is insufficient — save as Editable Vector (File → Save As → Editable Vector) and store as `.svg` in the sibling `.assets/` folder.
-- If `SKILL.md` genuinely needs local images or supporting files, store them in `.xdrs/[scope]/[type]/[subject]/skills/[number]-[skill-name]/.assets/` and link them using a same-folder relative path (e.g., `.assets/image.png`).
+- If `SKILL.md` genuinely needs local images or supporting files, store them in `.xdrs/[scope]/[type]/[subject]/skills/[skill-name]/.assets/` and link them using a same-folder relative path (e.g., `.assets/image.png`).
 - Use relative paths for all links; never use absolute paths starting with `/`.
 - No emojis. Lowercase filenames. Target under 6500 words.
 
@@ -119,11 +117,11 @@ If any check fails, revise before continuing.
 
 ### Phase 6: Write Files
 
-1. Create the skill file at `.xdrs/[scope]/[type]/[subject]/skills/[number]-[skill-name]/SKILL.md`.
-2. Create a symlink at `.agents/skills/[number]-[skill-name]` so VS Code picks it up immediately:
+1. Create the skill file at `.xdrs/[scope]/[type]/[subject]/skills/[skill-name]/SKILL.md`.
+2. Create a symlink at `.agents/skills/[skill-name]` so VS Code picks it up immediately:
    ```
    mkdir -p .agents/skills
-   ln -s ../../.xdrs/[scope]/[type]/[subject]/skills/[number]-[skill-name] .agents/skills/[number]-[skill-name]
+   ln -s ../../.xdrs/[scope]/[type]/[subject]/skills/[skill-name] .agents/skills/[skill-name]
    ```
 3. Evaluate whether the scope index at `.xdrs/[scope]/index.md` should be updated to reflect the new skill. If the scope index does not exist, create it following article standards and the scope index rules in `_core-adr-policy-001`.
 
@@ -134,7 +132,7 @@ Follow the lint verification steps in `.xdrs/_core/adrs/principles/skills/.asset
 ### Constraints
 
 - MUST follow the agentskills SKILL.md format from `003-skill-standards` exactly.
-- MUST consult `001-xdrs-standards` as the canonical source for every core element definition, especially type, scope, subject, numbering, naming, and placement.
+- MUST consult `001-xdrs-standards` as the canonical source for every core element definition, especially type, scope, subject, naming, and placement.
 - MUST NOT create a skill that duplicates an existing one — extend or reference it instead.
 - MUST keep scope `_local` unless the user explicitly states otherwise.
 - MUST NOT create documents in external scopes (scopes whose files appear in the workspace root `.filedist.lock`).
@@ -144,15 +142,13 @@ Follow the lint verification steps in `.xdrs/_core/adrs/principles/skills/.asset
 - Type: EDR (engineering workflow)
 - Scope: `_local`
 - Subject: `platform`
-- Number: scan `.xdrs/_local/edrs/platform/skills/` → next available
-- Output: `.xdrs/_local/edrs/platform/skills/001-debug-ci-pipeline/SKILL.md`
+- Output: `.xdrs/_local/edrs/platform/skills/debug-ci-pipeline/SKILL.md`
 
 **Input**: "Create a skill to review API designs"
 - Type: ADR (architectural evaluation)
 - Scope: `_local`
 - Subject: `application`
-- Number: scan `.xdrs/_local/adrs/application/skills/` → next available
-- Output: `.xdrs/_local/adrs/application/skills/001-review-api-design/SKILL.md`
+- Output: `.xdrs/_local/adrs/application/skills/review-api-design/SKILL.md`
 
 ## Edge Cases
 
@@ -164,4 +160,4 @@ Follow the lint verification steps in `.xdrs/_core/adrs/principles/skills/.asset
 
 - [_core-adr-policy-003 - Skill standards](../../003-skill-standards.md)
 - [_core-adr-policy-001 - XDRS standards](../../001-xdrs-standards.md)
-- [002-write-policy skill](../002-write-policy/SKILL.md)
+- [write-policy skill](../write-policy/SKILL.md)

package/.xdrs/_core/adrs/principles/skills/{003-write-skill/003-write-skill.test.int.js → write-skill/write-skill.test.int.js}

@@ -7,7 +7,7 @@ const REPO_ROOT = path.resolve(__dirname, '..', '..', '..', '..', '..', '..');
 
 jest.setTimeout(300000);
 
-test('003-write-skill creates a devops skill package', async () => {
+test('write-skill creates a devops skill package', async () => {
 	const err = await testPrompt(
 		{
 			workspaceRoot: REPO_ROOT,

package/.xdrs/_core/adrs/principles/skills/{008-write-xdrs-doc → write-xdrs-doc}/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: 008-write-xdrs-doc
+name: write-xdrs-doc
 description: >
   Use when writing documents such as decisions, policies, skills, procedures, research, initiatives, articles, or presentations.
   Activate this skill when the user asks to create or write any XDRS element.
@@ -36,12 +36,12 @@ Read the full content of the skill file for the inferred type, then follow all i
 
 | Document type | Skill file to read and follow |
 |---|---|
-| Policy (ADR / BDR / EDR) | `.xdrs/_core/adrs/principles/skills/002-write-policy/SKILL.md` |
-| Skill | `.xdrs/_core/adrs/principles/skills/003-write-skill/SKILL.md` |
-| Article | `.xdrs/_core/adrs/principles/skills/004-write-article/SKILL.md` |
-| Research | `.xdrs/_core/adrs/principles/skills/005-write-research/SKILL.md` |
-| Initiative | `.xdrs/_core/adrs/principles/skills/006-write-initiative/SKILL.md` |
-| Presentation | `.xdrs/_core/adrs/principles/skills/007-write-presentation/SKILL.md` |
+| Policy (ADR / BDR / EDR) | `.xdrs/_core/adrs/principles/skills/write-policy/SKILL.md` |
+| Skill | `.xdrs/_core/adrs/principles/skills/write-skill/SKILL.md` |
+| Article | `.xdrs/_core/adrs/principles/skills/write-article/SKILL.md` |
+| Research | `.xdrs/_core/adrs/principles/skills/write-research/SKILL.md` |
+| Initiative | `.xdrs/_core/adrs/principles/skills/write-initiative/SKILL.md` |
+| Presentation | `.xdrs/_core/adrs/principles/skills/write-presentation/SKILL.md` |
 
 ### Phase 3: Validate Mermaid Diagrams
 

package/.xdrs/_core/index.md

@@ -61,15 +61,17 @@ Every XDRS scope declares a `scope-type` in its `index.md` YAML frontmatter. A `
 
 ### Available skills
 
-The `_core` scope ships with seven skills that automate the most common framework operations:
-
-- **001-review** reviews code and files against applicable Policies
-- **002-write-policy** guides creation of a new Policy document
-- **003-write-skill** guides creation of a new skill package
-- **004-write-article** guides creation of a new article
-- **005-write-research** guides creation of a new research document
-- **006-write-initiative** guides creation of a new execution initiative
-- **007-write-presentation** guides creation of Marp slide presentations
+The `_core` scope ships with nine skills that automate the most common framework operations:
+
+- **review** reviews code and files against applicable Policies
+- **write-policy** guides creation of a new Policy document
+- **write-skill** guides creation of a new skill package
+- **write-article** guides creation of a new article
+- **write-research** guides creation of a new research document
+- **write-initiative** guides creation of a new execution initiative
+- **write-presentation** guides creation of Marp slide presentations
+- **write-xdrs-doc** routes a request to the right authoring skill above based on document type
+- **compile-scope** compiles or updates a `compiled`-type scope from its configured external sources
 
 ### Getting started
 

package/README.md

@@ -85,7 +85,7 @@ Every scope declares a `scope-type` in its `index.md` frontmatter. The six built
 
 **`platform` scopes** document what already exists and is ready to use. A scope is of type `platform` when its content describes a live operational capability — what is available, how to access it, and what constraints apply.
 
-**`compiled` scopes** hold policies compiled directly from external authoritative sources. All content must trace back to the source; no invented content is allowed. A `compiled` scope requires a local meta-policy with source URLs and compilation configuration, and uses the `009-compile-scope` skill to fetch, compile, and keep content up to date. The `compiled` type may be combined with another type (e.g. `scope-type: compiled, reference`) when the combined type's governance also applies.
+**`compiled` scopes** hold policies compiled directly from external authoritative sources. All content must trace back to the source; no invented content is allowed. A `compiled` scope requires a local meta-policy with source URLs and compilation configuration, and uses the `compile-scope` skill to fetch, compile, and keep content up to date. The `compiled` type may be combined with another type (e.g. `scope-type: compiled, reference`) when the combined type's governance also applies.
 
 ```yaml
 # .xdrs/owasp-top10/adrs/principles/001-core.md  (compilation meta-policy)
@@ -163,7 +163,7 @@ This is especially important for BDRs: because business rules govern decisions t
           [number]-[short-title].md
           .assets/
         skills/                     # optional skill packages for humans and AI agents
-          [number]-[skill-name]/
+          [skill-name]/
             SKILL.md
             .assets/
         articles/                   # optional synthetic views over Policies, Research, and Skills
@@ -231,7 +231,6 @@ The `lint` command reads `./.xdrs/**` from the given workspace path and checks c
 
 - allowed scope, type, and subject folder structure
 - Policy numbering uniqueness per `scope/type`
-- skill numbering uniqueness per `scope/type/subject/skills`
 - article numbering uniqueness per `scope/type/subject/articles`
 - research numbering uniqueness per `scope/type/subject/researches`
 - initiative numbering uniqueness per `scope/type/subject/initiatives`

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$/;
-const NUMBERED_DIR_RE = /^(\d{3,})-([a-z0-9-]+)$/;
+// Skill package folders are not numbered (see _core-adr-policy-003): plain lowercase kebab-case.
+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']);
 const RESOURCE_DIR_NAME = '.assets';
@@ -1010,7 +1011,6 @@ function lintXdrsElementFrontmatter(content, expectedName, filePath, errors, war
 
 function lintSkillsDirectory(xdrsRoot, scopeName, typeName, subjectName, skillsPath, errors, externalScopes = new Set()) {
   const artifacts = [];
-  const skillNumbers = new Map();
   const entries = safeReadDir(skillsPath, errors, `read skills directory ${scopeName}/${typeName}/${subjectName}/skills`);
 
   for (const entry of entries) {
@@ -1025,20 +1025,11 @@ function lintSkillsDirectory(xdrsRoot, scopeName, typeName, subjectName, skillsP
       continue;
     }
 
-    const match = entry.name.match(NUMBERED_DIR_RE);
-    if (!match) {
+    if (!SKILL_DIR_RE.test(entry.name)) {
       errors.push(`Invalid skill package name: ${toDisplayPath(entryPath)} [_core-adr-policy-003]`);
       continue;
     }
 
-    const number = match[1];
-    const previous = skillNumbers.get(number);
-    if (previous) {
-      errors.push(`Duplicate skill number ${number} in ${scopeName}/${typeName}/${subjectName}/skills: ${toDisplayPath(previous)} and ${toDisplayPath(entryPath)} [_core-adr-policy-003]`);
-    } else {
-      skillNumbers.set(number, entryPath);
-    }
-
     if (entry.name !== entry.name.toLowerCase()) {
       errors.push(`Skill package name must be lowercase: ${toDisplayPath(entryPath)} [_core-adr-policy-003]`);
     }
@@ -1076,9 +1067,8 @@ function lintSkillsDirectory(xdrsRoot, scopeName, typeName, subjectName, skillsP
       if (!skillFm.name) {
         errors.push(`SKILL.md frontmatter must include a non-empty name field: ${toDisplayPath(skillFilePath)} [_core-adr-policy-003]`);
       } else {
-        const expectedSkillName = `${number}-${match[2]}`;
-        if (skillFm.name !== expectedSkillName) {
-          errors.push(`Skill frontmatter name must be "${expectedSkillName}": ${toDisplayPath(skillFilePath)} [_core-adr-policy-003]`);
+        if (skillFm.name !== entry.name) {
+          errors.push(`Skill frontmatter name must be "${entry.name}": ${toDisplayPath(skillFilePath)} [_core-adr-policy-003]`);
         }
         if (skillFm.name.length > 64) {
           errors.push(`SKILL.md frontmatter name must be 64 characters or fewer: ${toDisplayPath(skillFilePath)} [_core-adr-policy-003]`);

package/lib/lint.test.js

@@ -487,11 +487,11 @@ test('allows child directory relative non-asset links in XDRS element documents'
     '.xdrs/_local/adrs/index.md': localAdrIndex([
       '- [001-main](principles/001-main.md) - Main decision'
     ]),
-    '.xdrs/_local/adrs/principles/001-main.md': xdrDocument('See [skill](skills/001-review/SKILL.md).'),
+    '.xdrs/_local/adrs/principles/001-main.md': xdrDocument('See [skill](skills/sample-skill/SKILL.md).'),
   });
-  const skillDir = path.join(workspaceRoot, '.xdrs/_local/adrs/principles/skills/001-review');
+  const skillDir = path.join(workspaceRoot, '.xdrs/_local/adrs/principles/skills/sample-skill');
   fs.mkdirSync(skillDir, { recursive: true });
-  fs.writeFileSync(path.join(skillDir, 'SKILL.md'), '---\nname: 001-review\ndescription: test skill\n---\n# Skill');
+  fs.writeFileSync(path.join(skillDir, 'SKILL.md'), '---\nname: sample-skill\ndescription: test skill\n---\n# Skill');
 
   const result = lintWorkspace(workspaceRoot);
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "xdrs-core",
-  "version": "0.48.1",
+  "version": "0.49.0",
   "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",