xdrs-core 0.25.0 → 0.26.0

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

@@ -20,16 +20,16 @@ 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-plan](principles/skills/006-write-plan/SKILL.md) - **Write Plan** — create a new plan document
-- [007-write-presentation](principles/skills/007-write-presentation/SKILL.md) - **Write Presentation** — create Marp slide presentations for XDRS documents
+- [_core-adr-skill-001-review](principles/skills/001-review/SKILL.md) - **Review** — review code and files against Policies
+- [_core-adr-skill-002-write-policy](principles/skills/002-write-policy/SKILL.md) - **Write Policy** — create a new Policy document
+- [_core-adr-skill-003-write-skill](principles/skills/003-write-skill/SKILL.md) - **Write Skill** — create a new skill package
+- [_core-adr-skill-004-write-article](principles/skills/004-write-article/SKILL.md) - **Write Article** — create a new article document
+- [_core-adr-skill-005-write-research](principles/skills/005-write-research/SKILL.md) - **Write Research** — create a new research document
+- [_core-adr-skill-006-write-plan](principles/skills/006-write-plan/SKILL.md) - **Write Plan** — create a new plan document
+- [_core-adr-skill-007-write-presentation](principles/skills/007-write-presentation/SKILL.md) - **Write Presentation** — create Marp slide presentations for XDRS documents
 
 ## Articles
 
 Synthetic views combining Policies, Research, and Skills around a specific topic.
 
-- [_core-article-001](principles/articles/001-xdrs-overview.md) - **XDRS Overview** (objective, structure, getting started, guidelines, extension, usage)
+- [_core-adr-article-001](principles/articles/001-xdrs-overview.md) - **XDRS Overview** (objective, structure, getting started, guidelines, extension, usage)

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

@@ -81,7 +81,7 @@ Examples:
 
 ```
 ---
-name: 001-skill-name      # required: must match the parent directory name exactly; max 64 chars
+name: [scope]-[type]-skill-[number]-[skill-name]      # required: full identifier including scope and type; 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
@@ -110,7 +110,8 @@ Known gotchas and how to handle them.
 ```
 
 Rules:
-- The `name` field must match the parent directory name exactly (e.g., directory `001-code-review` uses `name: 001-code-review`). This preserves agentskills spec compliance while encoding the ordering number.
+- The `name` field MUST use the format `[scope]-[type]-skill-[number]-[skill-name]` (e.g., `_core-adr-skill-001-code-review`). This aligns skill identifiers with the Policy document identifier format, making every XDRS element consistently identifiable by scope and type.
+- The directory name MUST follow the format `[number]-[skill-name]` (e.g., `001-code-review`), which keeps the filesystem hierarchy simple while the `name:` field carries the full identifier.
 - `## 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 simple structure, flow, layout, or relationship indications, `SKILL.md` SHOULD prefer plain Markdown, tables, or ASCII art instead of external assets.

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

@@ -62,7 +62,7 @@ Examples:
 All articles MUST follow this template:
 
 ```markdown
-# [scope]-article-[number]: [Short Title]
+# [scope]-[type]-article-[number]: [Short Title]
 
 ## Overview
 

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

@@ -81,7 +81,7 @@ Examples:
 All research documents MUST follow this template:
 
 ```markdown
-# [scope]-research-[number]: [Short Title]
+# [scope]-[type]-research-[number]: [Short Title]
 
 ## Abstract
 

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

@@ -61,7 +61,7 @@ Examples:
 All plans MUST follow this template:
 
 ```markdown
-# [scope]-plan-[number]: [Short Title]
+# [scope]-[type]-plan-[number]: [Short Title]
 
 ## Executive Summary
 

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

@@ -1,4 +1,4 @@
-# _core-article-001: XDRS Overview
+# _core-adr-article-001: XDRS Overview
 
 ## Overview
 

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

@@ -1,5 +1,5 @@
 ---
-name: 001-review
+name: _core-adr-skill-001-review
 description: >
   Reviews code changes or files against applicable Policies and reports violations as structured findings. 
   Activate this skill when the user asks to review, lint, or audit code or Policies, or when you identify a need to check compliance with Policies during implementation.

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

@@ -1,5 +1,5 @@
 ---
-name: 002-write-policy
+name: _core-adr-skill-002-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/003-write-skill/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: 003-write-skill
+name: _core-adr-skill-003-write-skill
 description: >
   Creates a new skill package following XDRS skill standards: determines type, scope, subject, and number;
   then writes a focused SKILL.md with correct frontmatter, phased instructions, examples, and edge cases.
@@ -45,7 +45,7 @@ Quick test:
 
 **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.
+**Skill name** — `[scope]-[type]-skill-[number]-[short-kebab-case-description]`, max 64 characters total. The directory name is `[number]-[short-kebab-case-description]`.
 
 ### Phase 3: Research Existing Skills and Related Policies
 
@@ -60,7 +60,7 @@ Use the mandatory agentskills format:
 
 ```
 ---
-name: [number]-[skill-name]
+name: [scope]-[type]-skill-[number]-[skill-name]
 description: >
   [What the skill does AND exactly when an agent should activate it. Max 1024 chars.]
 metadata:

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

@@ -1,5 +1,5 @@
 ---
-name: 004-write-article
+name: _core-adr-skill-004-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:
@@ -72,7 +72,7 @@ If the article spans more than one subject, place it in `principles`.
 Use the mandatory template from `004-article-standards`:
 
 ```
-# [scope]-article-[number]: [Short Title]
+# [scope]-[type]-article-[number]: [Short Title]
 
 ## Overview
 

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

@@ -1,5 +1,5 @@
 ---
-name: 005-write-research
+name: _core-adr-skill-005-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.
@@ -88,7 +88,7 @@ If the results contain competing interpretations or the intended audience for th
 Use the mandatory template from `006-research-standards`:
 
 ```markdown
-# [scope]-research-[number]: [Short Title]
+# [scope]-[type]-research-[number]: [Short Title]
 
 ## Abstract
 

package/.xdrs/_core/adrs/principles/skills/006-write-plan/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: 006-write-plan
+name: _core-adr-skill-006-write-plan
 description: >
   Creates a new plan document following XDRS plan standards: selects scope, type, subject, and number;
   then writes a focused execution plan with problem context, proposed solution, approach, milestones, and deliverables.
@@ -62,7 +62,7 @@ Consult `001-xdrs-core` while making each choice in this phase. The summaries be
 Use the mandatory template from `007-plan-standards`:
 
 ```markdown
-# [scope]-plan-[number]: [Short Title]
+# [scope]-[type]-plan-[number]: [Short Title]
 
 ## Executive Summary
 

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

@@ -1,5 +1,5 @@
 ---
-name: 007-write-presentation
+name: _core-adr-skill-007-write-presentation
 description: >
   Creates a Marp slide presentation for an existing XDRS document (policy, research, article, or plan).
   Activate this skill when the user asks to create slides, a presentation, or a slide deck for an XDRS document.

package/.xdrs/_core/index.md

@@ -31,10 +31,6 @@ Each artifact type has its own writing standard:
 
 [_core-adr-policy-005](adrs/principles/005-semantic-versioning-for-xdrs-packages.md) defines how XDRS packages use semantic versioning to communicate upgrade impact when decisions are shared across repositories or teams.
 
-### Usage policy
-
-The business decision [_core-bdr-policy-001](bdrs/principles/001-xdr-decisions-and-skills-usage.md) establishes how agents and humans must use XDRS policies and skills, separating policy authority (which lives in Policies) from execution guidance (which lives in skills).
-
 ### Presentation standards
 
 Slide presentations that support XDRS documents follow [_core-adr-policy-009](adrs/principles/009-presentation-standards.md). Slides use the Marp Markdown format, live in `.assets/` next to the document they support, and must maintain bidirectional links with the parent document.
@@ -43,20 +39,18 @@ Slide presentations that support XDRS documents follow [_core-adr-policy-009](ad
 
 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-plan** guides creation of a new execution plan
-- **007-write-presentation** guides creation of Marp slide presentations
+- **_core-adr-skill-001-review** reviews code and files against applicable Policies
+- **_core-adr-skill-002-write-policy** guides creation of a new Policy document
+- **_core-adr-skill-003-write-skill** guides creation of a new skill package
+- **_core-adr-skill-004-write-article** guides creation of a new article
+- **_core-adr-skill-005-write-research** guides creation of a new research document
+- **_core-adr-skill-006-write-plan** guides creation of a new execution plan
+- **_core-adr-skill-007-write-presentation** guides creation of Marp slide presentations
 
 ### Getting started
 
-For a narrative introduction to the framework, including how elements differ, how to decide whether a Policy applies, and how to extend the framework with your own scopes, see the overview article [_core-article-001](adrs/principles/articles/001-xdrs-overview.md).
+For a narrative introduction to the framework, including how elements differ, how to decide whether a Policy applies, and how to extend the framework with your own scopes, see the overview article [_core-adr-article-001](adrs/principles/articles/001-xdrs-overview.md).
 
 ## Type Indexes
 
 - [ADRs Index](adrs/index.md) - Architectural decisions about the XDRS framework structure and standards
-- [BDRs Index](bdrs/index.md) - Business decisions about XDRS framework governance and usage
-- [BDRs Index](bdrs/index.md) - Business decisions about how agents and humans must use XDRS policies and skills

package/lib/lint.js

@@ -472,8 +472,10 @@ function lintSkillsDirectory(xdrsRoot, scopeName, typeName, subjectName, skillsP
       if (!skillFm.name) {
         errors.push(`SKILL.md frontmatter must include a non-empty name field: ${toDisplayPath(skillFilePath)}`);
       } else {
-        if (skillFm.name !== entry.name) {
-          errors.push(`Skill frontmatter name must match package directory "${entry.name}": ${toDisplayPath(skillFilePath)}`);
+        const typeId = TYPE_TO_ID[typeName].split('-')[0]; // 'adr', 'bdr', or 'edr'
+        const expectedSkillName = `${scopeName}-${typeId}-skill-${number}-${match[2]}`;
+        if (skillFm.name !== expectedSkillName) {
+          errors.push(`Skill frontmatter name must be "${expectedSkillName}": ${toDisplayPath(skillFilePath)}`);
         }
         if (skillFm.name.length > 64) {
           errors.push(`SKILL.md frontmatter name must be 64 characters or fewer: ${toDisplayPath(skillFilePath)}`);
@@ -537,7 +539,8 @@ function lintArticlesDirectory(xdrsRoot, scopeName, typeName, subjectName, artic
     }
 
     const content = fs.readFileSync(entryPath, 'utf8');
-    const expectedHeader = `# ${scopeName}-article-${number}:`;
+    const typeId = TYPE_TO_ID[typeName].split('-')[0]; // 'adr', 'bdr', or 'edr'
+    const expectedHeader = `# ${scopeName}-${typeId}-article-${number}:`;
     const firstLine = firstNonEmptyLine(content);
     if (!firstLine.startsWith(expectedHeader)) {
       errors.push(`Article title must start with "${expectedHeader}": ${toDisplayPath(entryPath)}`);
@@ -591,7 +594,8 @@ function lintResearchDirectory(xdrsRoot, scopeName, typeName, subjectName, resea
     }
 
     const content = fs.readFileSync(entryPath, 'utf8');
-    const expectedHeader = `# ${scopeName}-research-${number}:`;
+    const typeId = TYPE_TO_ID[typeName].split('-')[0]; // 'adr', 'bdr', or 'edr'
+    const expectedHeader = `# ${scopeName}-${typeId}-research-${number}:`;
     const firstLine = firstNonEmptyLine(content);
     if (!firstLine.startsWith(expectedHeader)) {
       errors.push(`Research title must start with "${expectedHeader}": ${toDisplayPath(entryPath)}`);
@@ -646,7 +650,8 @@ function lintPlansDirectory(xdrsRoot, scopeName, typeName, subjectName, plansPat
     }
 
     const content = fs.readFileSync(entryPath, 'utf8');
-    const expectedHeader = `# ${scopeName}-plan-${number}:`;
+    const typeId = TYPE_TO_ID[typeName].split('-')[0]; // 'adr', 'bdr', or 'edr'
+    const expectedHeader = `# ${scopeName}-${typeId}-plan-${number}:`;
     const firstLine = firstNonEmptyLine(content);
     if (!firstLine.startsWith(expectedHeader)) {
       errors.push(`Plan title must start with "${expectedHeader}": ${toDisplayPath(entryPath)}`);

package/lib/lint.test.js

@@ -242,7 +242,7 @@ test('reports unknown frontmatter fields in SKILL.md files', () => {
     ]),
     '.xdrs/_local/adrs/principles/skills/001-check-links/SKILL.md': [
       '---',
-      'name: 001-check-links',
+      'name: _local-adr-skill-001-check-links',
       'description: Test skill document',
       'unknown-field: some value',
       '---',
@@ -271,7 +271,7 @@ test('accepts all known frontmatter fields in SKILL.md files', () => {
     ]),
     '.xdrs/_local/adrs/principles/skills/001-check-links/SKILL.md': [
       '---',
-      'name: 001-check-links',
+      'name: _local-adr-skill-001-check-links',
       'description: Test skill document',
       'license: MIT',
       'metadata:',
@@ -429,7 +429,7 @@ test('allows child directory relative non-asset links in XDRS element documents'
   });
   const skillDir = path.join(workspaceRoot, '.xdrs/_local/adrs/principles/skills/001-review');
   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: _local-adr-skill-001-review\ndescription: test skill\n---\n# Skill');
 
   const result = lintWorkspace(workspaceRoot);
 
@@ -626,7 +626,7 @@ test('reports orphan asset in articles .assets directory', () => {
       '- [001-guide](principles/articles/001-guide.md) - Guide article'
     ]),
     '.xdrs/_local/adrs/principles/articles/001-guide.md': [
-      '# _local-article-001: Guide',
+      '# _local-adr-article-001: Guide',
       '',
       'See ![used](.assets/used.png).',
       ''
@@ -838,7 +838,7 @@ function xdrDocument(body) {
 function skillDocument(body) {
   return [
     '---',
-    'name: 001-check-links',
+    'name: _local-adr-skill-001-check-links',
     'description: Test skill document',
     '---',
     '',
@@ -1392,7 +1392,7 @@ function slideDocument(body) {
 
 function articleDocument(body) {
   return [
-    '# _local-article-001: Guide',
+    '# _local-adr-article-001: Guide',
     '',
     '## Overview',
     '',
@@ -1414,7 +1414,7 @@ function researchDocument(introBody, questionLine) {
     ? `${introBody}\n\n${questionLine}`
     : introBody;
   return [
-    '# _local-research-001: Study',
+    '# _local-adr-research-001: Study',
     '',
     '## Abstract',
     '',
@@ -1449,7 +1449,7 @@ function researchDocument(introBody, questionLine) {
 
 function planDocument(body) {
   return [
-    '# _local-plan-001: My plan',
+    '# _local-adr-plan-001: My plan',
     '',
     '## Executive Summary',
     '',

package/package.json

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

package/.xdrs/_core/bdrs/index.md

@@ -1,9 +0,0 @@
-# _core BDRs Index
-
-Business decisions about how the XDRS framework itself is governed and used. Owned by the platform team. Propose changes via pull request.
-
-## Principles
-
-Foundational standards, principles, and guidelines.
-
-- [_core-bdr-policy-001](principles/001-xdr-decisions-and-skills-usage.md) - **Policy decisions and skills usage** — How agents and humans must use XDRS policies and skills, separating policy authority from execution guidance

package/.xdrs/_core/bdrs/principles/001-xdr-decisions-and-skills-usage.md

@@ -1,52 +0,0 @@
----
-name: _core-bdr-policy-001-policy-decisions-and-skills-usage
-description: Defines how agents and humans must use Policy decisions and skills, separating policy authority from execution guidance across single-agent and multi-agent workflows.
----
-
-# _core-bdr-policy-001: Policy decisions and skills usage
-
-## Context and Problem Statement
-
-Repositories using the XDRS framework contain both policies (BDRs, ADRs, EDRs) and skills. In multi-agent or multi-role workflows, each actor needs to know which artifact carries policy authority and which carries execution guidance.
-
-Question: How must agents and humans use Policy decisions and skills so policy, execution guidance, and role boundaries stay clear?
-
-## Decision Outcome
-
-**BDRs define compliance policy; skills operationalize it**
-
-Policy decisions are the authoritative source of mandatory decisions. Skills are execution artifacts that operationalize those decisions and must never substitute them as policy authority.
-
-### Details
-
-- Before treating any Policy as a current requirement, evaluate applicability in order: `valid-from`, `apply-to`, then the decision text.
-- The set of policies that an agent or human must comply with for a given operational context must be declared in BDRs.
-- If a policy set becomes too large or too mixed in purpose to review clearly in one record, it must be split into multiple focused BDRs.
-- Specific work instructions that operationalize BDR policies must be structured as skills when the procedure is detailed enough to benefit from a dedicated operational document.
-- Every skill that operationalizes or verifies BDR policies must link to the BDRs it implements or checks.
-- If a skill conflicts with an applicable Policy, the Policy prevails. The human or agent must stop relying on the conflicting skill behavior and report the inconsistency.
-- If an applicable BDR exists but no supporting skill exists yet, the human or agent may proceed by following the BDR directly when the decision is actionable, and must report the missing skill as an operational gap.
-- In multi-agent graphs or staged workflows, every participating agent must remain bounded by the same applicable BDR policies even when agents have different local objectives, prompts, or skills.
-- Each agent or human role involved in a workflow must make explicit which applicable BDRs govern its work and which skills it is following.
-- Different documents may be consumed by different actors. For example: one agent uses skills for data acquisition, another for plan execution, and a reviewer reads BDRs directly to validate outcomes.
-
-Allowed:
-- using multiple skills to operationalize one BDR in different phases of a workflow;
-- using one skill to operationalize multiple related BDRs when the skill links them clearly;
-- having human-only, agent-only, or mixed human-agent execution for the same skill.
-
-Disallowed:
-- treating a skill as policy authority by itself;
-- inventing mandatory policy rules only inside prompts, plans, or skills;
-- allowing one agent in a workflow to bypass an applicable BDR because another agent checked a different subset of rules.
-
-## Considered Options
-
-- (REJECTED) **Keep policy and execution guidance mixed inside operational BDRs** — Makes decisions harder to reuse, review, and assign across humans and multiple agent roles.
-- (CHOSEN) **Separate mandatory policy in BDRs from executable guidance in skills** — Preserves a clear source of truth while allowing different humans and agents to execute specialized procedures.
-
-## References
-
-- [_core-adr-001](../../adrs/principles/001-xdrs-core.md)
-- [_core-adr-002](../../adrs/principles/002-policy-standards.md)
-- [_core-adr-003](../../adrs/principles/003-skill-standards.md)