xdrs-core 0.23.0 → 0.24.1

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

@@ -14,6 +14,7 @@ Foundational standards, principles, and guidelines.
 - [_core-adr-006](principles/006-research-standards.md) - **Research standards** — How to structure research documents backing XDR decisions
 - [_core-adr-007](principles/007-plan-standards.md) - **Plan standards** — How to structure ephemeral execution plans that implement decisions
 - [_core-adr-008](principles/008-xdr-standards-structured.md) - **XDR standards - structured** — How to expose individually referenceable numbered rules inside an XDR when external citation by identifier is required
+- [_core-adr-009](principles/009-presentation-standards.md) - **Presentation standards** — How to structure Marp slide presentations that support XDR documents
 
 ## Skills
 
@@ -25,6 +26,7 @@ Step-by-step procedural guides for humans and AI agents.
 - [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 XDR documents
 
 ## Articles
 

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

@@ -0,0 +1,52 @@
+---
+name: _core-adr-009-presentation-standards
+description: Defines how Marp slide presentations are structured, named, placed, and linked within XDR projects. Use when creating, reviewing, or linting slide decks that support XDR documents.
+---
+
+# _core-adr-009: Presentation standards
+
+## Context and Problem Statement
+
+Teams often need slide presentations to communicate decisions, research findings, plans, or article content to different audiences. Without a standard, slides drift from the authoritative documents, use inconsistent formats, and become disconnected from the decision records they support.
+
+How should slide presentations be structured, placed, and maintained within the XDR framework so they remain consistent, discoverable, and always traceable to the documents they support?
+
+## Decision Outcome
+
+**Marp Markdown slides co-located in `.assets/` next to the parent document**
+
+Presentations are Markdown files in Marp format, stored in the `.assets/` folder of the document they support, with bidirectional links and strict naming conventions.
+
+### Details
+
+- Slides are supporting media for XDR documents. They must never exist as standalone artifacts without a parent decision, research, article, or plan.
+- Slides must use the [Marp](https://marp.app/) Markdown format with a minimal YAML frontmatter block at the beginning of the file:
+  ```
+  ---
+  marp: true
+  ---
+  ```
+  Additional Marp configuration keys (e.g. `theme`, `paginate`, `header`, `footer`) may be added when needed, but `marp: true` is always required as the first frontmatter key.
+- Slide files must be placed in the `.assets/` folder next to the element they relate to, following the `.assets/` placement rules defined in `_core-adr-001`.
+- The parent document must always contain a link to the slide file. The slide file must always contain a link back to the parent document at the end of the presentation. This bidirectional linking is mandatory.
+- Slide files must use the same base name as the parent file, suffixed with `-slides`. When multiple slide sets exist for the same parent, append a context indicator after `-slides` (e.g. `-slides-overview`, `-slides-executive`).
+  - Example: parent `003-naming-conventions.md` produces `003-naming-conventions-slides.md` or `003-naming-conventions-slides-overview.md`.
+- Slide file names must not exceed 64 characters (including the `.md` extension).
+- Slide file names must be lowercase.
+- When slides refer to content from multiple decisions, plans, or research documents, an article explaining the combined view must be written first. The slides then support that article, not the individual documents directly.
+- Slides should contain minimal text. Prefer Mermaid diagrams, short bullet points, ASCII art, key short statements, and tables. Use longer text only when the exact wording must be evaluated by the audience (policies, texts under discussion, controls).
+- Slides should follow a clean, linear storytelling structure (context, problem, solution, actions). Follow the structure of the underlying document, extracting the most important points and stressing central questions, answers, doubts, decisions, and risks.
+- Define the central message or objective of the presentation before creating the slides. If the objective is unclear or there are multiple possible paths, ask the user before proceeding.
+- Always identify the target audience (executives, engineers, specialists, control). If the audience is not clear from the underlying document, ask before creating the slides. Include audience info in the file name when multiple audiences exist (e.g. `005-rail-standards-slides-executive.md`).
+- Keep presentations under 30 slides. Create separate slide sets for different views or audiences when needed.
+- Slides never replace decision records or related document contents. When the underlying document changes, the associated slides must be reviewed and updated to stay consistent.
+- Never use emojis in slide content.
+- Always use lowercase file names.
+
+## References
+
+- [_core-adr-001 - XDRs core](001-xdrs-core.md) - Framework structure and `.assets/` placement rules
+- [_core-adr-002 - XDR standards](002-xdr-standards.md) - XDR document writing rules
+- [_core-adr-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
+- [Marp](https://marp.app/) - Markdown Presentation Ecosystem

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

@@ -0,0 +1,169 @@
+---
+name: 007-write-presentation
+description: >
+  Creates a Marp slide presentation for an existing XDR document (decision, research, article, or plan).
+  Activate this skill when the user asks to create slides, a presentation, or a slide deck for an XDR document.
+metadata:
+  author: flaviostutz
+  version: "1.0"
+---
+
+## Overview
+
+Guides the creation of a Marp Markdown slide presentation that supports an existing XDR document. The skill ensures the slides follow presentation standards (`_core-adr-009`), are correctly placed in the `.assets/` folder, and maintain bidirectional links with the parent document.
+
+## Instructions
+
+### Phase 1: Identify the Parent Document
+
+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-core.md` for `.assets/` placement rules and general framework structure.
+3. Identify the parent document (decision, research, article, or plan) 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.
+
+### Phase 2: Define the Presentation Scope
+
+1. Read the parent document in full.
+2. Define the central message or objective of the presentation. If the objective is ambiguous or there are multiple possible paths, ask the user before proceeding. Ask one question at a time.
+3. Identify the target audience. Check the parent document for audience indicators. If unclear, ask the user. Common audiences:
+   - **Executives**: high-level, strategic, outcome-focused
+   - **Engineers**: technical depth, implementation details, trade-offs
+   - **Specialists**: domain-specific depth, compliance, controls
+   - **Control**: risk, compliance, audit, governance focus
+4. Determine if multiple slide sets are needed for different audiences. If so, create separate files for each.
+
+### Phase 3: Plan the Slide Structure
+
+1. Extract the most important points from the parent document.
+2. Organize slides following a linear storytelling structure:
+   - **Context**: what is the situation, background, who is impacted
+   - **Problem**: what needs to be decided, addressed, or understood
+   - **Solution/Decision**: what was decided and why
+   - **Actions/Next Steps**: what happens now, who is responsible
+3. For each slide, identify the best format:
+   - Mermaid diagrams for flows, relationships, architecture
+   - Short bullet points for key decisions and trade-offs
+   - Tables for comparisons, options, criteria
+   - ASCII art for simple layouts or structures
+   - Key short statements for emphasis
+   - Longer text only when exact wording must be evaluated (policies, controls)
+4. Keep the total under 30 slides. If more content is needed, plan separate slide sets.
+
+### Phase 4: Determine the File Name
+
+1. Take the parent document file name (without `.md` extension).
+2. Append `-slides` for the primary set.
+3. If multiple sets exist, append a context indicator: `-slides-overview`, `-slides-executive`, `-slides-technical`, etc.
+4. Verify the final file name (including `.md`) is 64 characters or fewer. If it exceeds 64 characters, shorten the base name while keeping it recognizable.
+5. Ensure the file name is entirely lowercase.
+
+Examples:
+- Parent: `003-naming-conventions.md` -> `003-naming-conventions-slides.md`
+- Parent: `005-rail-standards.md` (executive audience) -> `005-rail-standards-slides-executive.md`
+- Parent: `001-xdrs-overview.md` (article) -> `001-xdrs-overview-slides.md`
+
+### Phase 5: Write the Slides
+
+Create the Marp Markdown file with this structure:
+
+```markdown
+---
+marp: true
+---
+
+# [Presentation Title]
+
+[Subtitle or context line]
+[Audience and date if relevant]
+
+---
+
+[Slide 2: Context/Background]
+
+---
+
+[Slide 3: Problem Statement]
+
+---
+
+[... additional slides ...]
+
+---
+
+# References
+
+- [Parent document title](relative/path/to/parent.md)
+- [Other related documents if applicable]
+```
+
+Rules:
+- The first line of YAML frontmatter must be `marp: true`. Additional Marp keys (`theme`, `paginate`, `header`, `footer`) may be added after.
+- Use `---` as the slide separator (standard Marp syntax).
+- The last slide must contain links back to the parent document and any other related documents.
+- Minimize text per slide. Prefer visual elements and short statements.
+- Stress central questions, answers, doubts, decisions, and risks from the parent document.
+- No emojis.
+- Use relative paths for all links.
+- Follow the audience-appropriate level of detail.
+
+### Phase 6: Update the Parent Document
+
+1. Add a link to the slide file in the parent document. Place it in the `## References` section or, for XDRs, in the most appropriate section.
+2. Use a descriptive link text such as "Presentation slides" pointing to the slide file in `.assets/`.
+
+### Phase 7: Write Files
+
+1. Create the slide file at the correct `.assets/` location:
+   - XDRs: `[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`
+   - Plans: `[xdrs-root]/[scope]/[type]/[subject]/plans/.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.
+
+### Phase 8: Verify with Lint
+
+1. Run the CLI lint utility from the repository root:
+   ```
+   npx -y xdrs-core lint .
+   ```
+2. Fix all reported errors before considering the task complete.
+
+### Constraints
+
+- MUST follow presentation standards from `_core-adr-009` exactly.
+- MUST NOT create slides without an existing parent document.
+- MUST NOT create standalone slides that reference multiple documents without an article as the parent.
+- MUST maintain bidirectional links between slides and parent document.
+- MUST keep slide file names under 64 characters.
+- MUST include `marp: true` in the slide frontmatter.
+- MUST keep presentations under 30 slides.
+- MUST ask the user about audience and objective when not clear from context.
+
+## Examples
+
+**Input**: "Create slides for our naming conventions decision"
+- Locate the parent XDR (e.g. `003-naming-conventions.md`)
+- Ask: "Who is the target audience for these slides?"
+- Create: `.assets/003-naming-conventions-slides.md`
+- Update: Add link in `003-naming-conventions.md`
+
+**Input**: "Create an executive presentation covering our security and data decisions"
+- Check if an article synthesizing security + data decisions exists
+- If not, suggest creating the article first
+- Create slides for the article, not the individual XDRs
+
+## Edge Cases
+
+- If the parent document does not exist, do not create slides. Inform the user and suggest creating the parent first.
+- If the slide file name would exceed 64 characters, shorten the base name while keeping it recognizable.
+- If the content requires more than 30 slides, split into multiple slide sets with distinct audience or topic focus.
+- If the parent document changes after slides are created, the slides must be reviewed and updated.
+
+## References
+
+- [_core-adr-009 - Presentation standards](../../009-presentation-standards.md)
+- [_core-adr-001 - XDRs core](../../001-xdrs-core.md)
+- [_core-adr-004 - Article standards](../../004-article-standards.md)
+- [_core-adr-003 - Skill standards](../../003-skill-standards.md)

package/.xdrs/_core/index.md

@@ -35,9 +35,13 @@ Each artifact type has its own writing standard:
 
 The business decision [_core-bdr-001](bdrs/principles/001-xdr-decisions-and-skills-usage.md) establishes how agents and humans must use XDR decisions and skills, separating policy authority (which lives in XDRs) from execution guidance (which lives in skills).
 
+### Presentation standards
+
+Slide presentations that support XDR documents follow [_core-adr-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.
+
 ### Available skills
 
-The `_core` scope ships with six skills that automate the most common framework operations:
+The `_core` scope ships with seven skills that automate the most common framework operations:
 
 - **001-lint** reviews code and files against applicable XDRs
 - **002-write-xdr** guides creation of a new decision record
@@ -45,6 +49,7 @@ The `_core` scope ships with six skills that automate the most common framework
 - **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
 
 ### Getting started
 

package/lib/lint.js

@@ -28,6 +28,8 @@ const SKILL_PACKAGE_OPTIONAL_DIRS = new Set(['scripts', 'references', RESOURCE_D
 const XDR_ALLOWED_FRONTMATTER_KEYS = new Set(['name', 'description', 'apply-to', 'valid-from', 'license', 'metadata']);
 const SKILL_ALLOWED_FRONTMATTER_KEYS = new Set(['name', 'description', 'license', 'metadata', 'compatibility', 'allowed-tools']);
 const IMAGE_EXTENSIONS = new Set(['.png', '.jpg', '.jpeg', '.gif', '.svg', '.webp', '.bmp']);
+const SLIDE_FILE_RE = /^.+-slides(?:-[a-z0-9-]+)?\.md$/;
+const SLIDE_MAX_NAME_LENGTH = 64;
 const EMOJI_RE = /\p{Extended_Pictographic}/u;
 const XDR_MAX_WORDS = 2600;
 const ARTICLE_MAX_WORDS = 5000;
@@ -808,6 +810,51 @@ function lintOrphanAssets(assetsDir, documentPaths, xdrsRoot, errors) {
       errors.push(`Orphan asset file not referenced by any document: ${toDisplayPath(assetPath)}`);
     }
   }
+
+  // Lint slide/presentation files inside .assets
+  for (const assetPath of assetTree.files) {
+    const fileName = path.basename(assetPath);
+    if (SLIDE_FILE_RE.test(fileName)) {
+      lintSlideFile(assetPath, documentPaths, xdrsRoot, errors);
+    }
+  }
+}
+
+function lintSlideFile(filePath, documentPaths, xdrsRoot, errors) {
+  const fileName = path.basename(filePath);
+
+  if (fileName !== fileName.toLowerCase()) {
+    errors.push(`Slide file name must be lowercase: ${toDisplayPath(filePath)}`);
+  }
+
+  if (fileName.length > SLIDE_MAX_NAME_LENGTH) {
+    errors.push(`Slide file name must be ${SLIDE_MAX_NAME_LENGTH} characters or fewer: ${toDisplayPath(filePath)}`);
+  }
+
+  const content = fs.readFileSync(filePath, 'utf8');
+
+  const fm = extractFrontmatter(content);
+  if (!fm.present) {
+    errors.push(`Slide file must start with a YAML frontmatter block containing marp: true: ${toDisplayPath(filePath)}`);
+  } else {
+    const hasMarp = /^marp:\s*true$/m.test(content.match(/^---\r?\n([\s\S]*?)\r?\n---/)[1]);
+    if (!hasMarp) {
+      errors.push(`Slide frontmatter must include marp: true: ${toDisplayPath(filePath)}`);
+    }
+  }
+
+  lintNoEmojis(content, filePath, 'Slide', errors);
+
+  // Check that the slide links back to at least one parent document
+  const repoRoot = path.dirname(xdrsRoot);
+  const slideDir = path.dirname(filePath);
+  const slideLinks = parseLocalLinks(content, slideDir, repoRoot);
+  const slideLinkSet = new Set(slideLinks.map(normalizePath));
+
+  const linksToParent = documentPaths.some((docPath) => slideLinkSet.has(normalizePath(docPath)));
+  if (!linksToParent) {
+    errors.push(`Slide file must contain a link back to its parent document: ${toDisplayPath(filePath)}`);
+  }
 }
 
 function collectAssetTree(dirPath, errors) {

package/lib/lint.test.js

@@ -1238,8 +1238,158 @@ test('passes when research ## Introduction contains Question: line', () => {
   expect(result.errors.join('\n')).not.toContain('Research ## Introduction must contain');
 });
 
+// ─── Slide / Presentation checks ─────────────────────────────────────────────
+
+test('passes for valid slide file in .assets with marp frontmatter and backlink', () => {
+  const workspaceRoot = createWorkspace('marp-valid', {
+    '.xdrs/index.md': rootIndex(),
+    '.xdrs/_local/index.md': '# _local Scope Overview\n\n## Content\n\nLocal scope.\n\n- [ADRs](adrs/index.md)\n',
+    '.xdrs/_local/adrs/index.md': localAdrIndex([
+      '- [001-main](principles/001-main.md) - Main decision'
+    ]),
+    '.xdrs/_local/adrs/principles/001-main.md': xdrDocument('Body.\n\n[Slides](.assets/001-main-slides.md)'),
+    '.xdrs/_local/adrs/principles/.assets/001-main-slides.md': slideDocument('[Parent](../001-main.md)'),
+  });
+
+  const result = lintWorkspace(workspaceRoot);
+
+  const slideErrors = result.errors.filter((e) => /\bSlide\b/.test(e) || /\bSlide\b/i.test(e) && e.includes('slides'));
+  expect(slideErrors).toHaveLength(0);
+});
+
+test('reports slide file missing marp: true in frontmatter', () => {
+  const workspaceRoot = createWorkspace('slide-no-marp', {
+    '.xdrs/index.md': rootIndex(),
+    '.xdrs/_local/adrs/index.md': localAdrIndex([
+      '- [001-main](principles/001-main.md) - Main decision'
+    ]),
+    '.xdrs/_local/adrs/principles/001-main.md': xdrDocument('Body.\n\n[Slides](.assets/001-main-slides.md)'),
+    '.xdrs/_local/adrs/principles/.assets/001-main-slides.md': [
+      '---',
+      'theme: default',
+      '---',
+      '',
+      '# Slides',
+      '',
+      '[Parent](../001-main.md)',
+      ''
+    ].join('\n'),
+  });
+
+  const result = lintWorkspace(workspaceRoot);
+
+  expect(result.errors.join('\n')).toContain('Slide frontmatter must include marp: true');
+});
+
+test('reports slide file without any frontmatter', () => {
+  const workspaceRoot = createWorkspace('slide-no-frontmatter', {
+    '.xdrs/index.md': rootIndex(),
+    '.xdrs/_local/adrs/index.md': localAdrIndex([
+      '- [001-main](principles/001-main.md) - Main decision'
+    ]),
+    '.xdrs/_local/adrs/principles/001-main.md': xdrDocument('Body.\n\n[Slides](.assets/001-main-slides.md)'),
+    '.xdrs/_local/adrs/principles/.assets/001-main-slides.md': '# Slides\n\n[Parent](../001-main.md)\n',
+  });
+
+  const result = lintWorkspace(workspaceRoot);
+
+  expect(result.errors.join('\n')).toContain('Slide file must start with a YAML frontmatter block containing marp: true');
+});
+
+test('reports slide file missing backlink to parent document', () => {
+  const workspaceRoot = createWorkspace('slide-no-backlink', {
+    '.xdrs/index.md': rootIndex(),
+    '.xdrs/_local/adrs/index.md': localAdrIndex([
+      '- [001-main](principles/001-main.md) - Main decision'
+    ]),
+    '.xdrs/_local/adrs/principles/001-main.md': xdrDocument('Body.\n\n[Slides](.assets/001-main-slides.md)'),
+    '.xdrs/_local/adrs/principles/.assets/001-main-slides.md': slideDocument('No link back here.'),
+  });
+
+  const result = lintWorkspace(workspaceRoot);
+
+  expect(result.errors.join('\n')).toContain('Slide file must contain a link back to its parent document');
+});
+
+test('reports slide file name exceeding 64 characters', () => {
+  const longName = '001-main-slides-' + 'a'.repeat(46) + '.md'; // > 64 chars
+  const workspaceRoot = createWorkspace('slide-name-too-long', {
+    '.xdrs/index.md': rootIndex(),
+    '.xdrs/_local/adrs/index.md': localAdrIndex([
+      '- [001-main](principles/001-main.md) - Main decision'
+    ]),
+    '.xdrs/_local/adrs/principles/001-main.md': xdrDocument(`Body.\n\n[Slides](.assets/${longName})`),
+    [`.xdrs/_local/adrs/principles/.assets/${longName}`]: slideDocument('[Parent](../001-main.md)'),
+  });
+
+  const result = lintWorkspace(workspaceRoot);
+
+  expect(result.errors.join('\n')).toContain('Slide file name must be 64 characters or fewer');
+});
+
+test('reports emojis in slide files', () => {
+  const workspaceRoot = createWorkspace('slide-emoji', {
+    '.xdrs/index.md': rootIndex(),
+    '.xdrs/_local/adrs/index.md': localAdrIndex([
+      '- [001-main](principles/001-main.md) - Main decision'
+    ]),
+    '.xdrs/_local/adrs/principles/001-main.md': xdrDocument('Body.\n\n[Slides](.assets/001-main-slides.md)'),
+    '.xdrs/_local/adrs/principles/.assets/001-main-slides.md': slideDocument('Great stuff! \u{1F680}\n\n[Parent](../001-main.md)'),
+  });
+
+  const result = lintWorkspace(workspaceRoot);
+
+  expect(result.errors.join('\n')).toContain('Slide must not contain emojis');
+});
+
+test('does not lint non-slide files in .assets as slides', () => {
+  const workspaceRoot = createWorkspace('non-slide-asset', {
+    '.xdrs/index.md': rootIndex(),
+    '.xdrs/_local/adrs/index.md': localAdrIndex([
+      '- [001-main](principles/001-main.md) - Main decision'
+    ]),
+    '.xdrs/_local/adrs/principles/001-main.md': xdrDocument('Body.\n\n[Schema](.assets/schema.json)'),
+    '.xdrs/_local/adrs/principles/.assets/schema.json': '{"type":"object"}',
+  });
+
+  const result = lintWorkspace(workspaceRoot);
+
+  expect(result.errors.join('\n')).not.toContain('Slide');
+  expect(result.errors.join('\n')).not.toContain('marp');
+});
+
+test('passes for slide file in article .assets with backlink', () => {
+  const workspaceRoot = createWorkspace('marp-article-valid', {
+    '.xdrs/index.md': rootIndex(),
+    '.xdrs/_local/index.md': '# _local Scope Overview\n\n## Content\n\nLocal scope.\n\n- [ADRs](adrs/index.md)\n',
+    '.xdrs/_local/adrs/index.md': localAdrIndex([
+      '- [001-guide](principles/articles/001-guide.md) - Guide'
+    ]),
+    '.xdrs/_local/adrs/principles/articles/001-guide.md': articleDocument('Body.\n\n[Slides](.assets/001-guide-slides.md)'),
+    '.xdrs/_local/adrs/principles/articles/.assets/001-guide-slides.md': slideDocument('[Parent](../001-guide.md)'),
+  });
+
+  const result = lintWorkspace(workspaceRoot);
+
+  expect(result.errors.join('\n')).not.toContain('Slide');
+  expect(result.errors.join('\n')).not.toContain('marp');
+});
+
 // ─── New helpers ──────────────────────────────────────────────────────────────
 
+function slideDocument(body) {
+  return [
+    '---',
+    'marp: true',
+    '---',
+    '',
+    '# Presentation',
+    '',
+    body,
+    ''
+  ].join('\n');
+}
+
 function articleDocument(body) {
   return [
     '# _local-article-001: Guide',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "xdrs-core",
-  "version": "0.23.0",
+  "version": "0.24.1",
   "description": "A standard way to organize Decision Records (XDRs) across scopes, subjects, and teams so that AI agents can reliably query and follow them.",
   "repository": {
     "type": "git",