xdrs-core 0.20.1 → 0.21.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (22) hide show
  1. package/.xdrs/_core/adrs/principles/001-xdrs-core.md +20 -18
  2. package/.xdrs/_core/adrs/principles/002-xdr-standards.md +15 -15
  3. package/.xdrs/_core/adrs/principles/003-skill-standards.md +3 -3
  4. package/.xdrs/_core/adrs/principles/004-article-standards.md +3 -3
  5. package/.xdrs/_core/adrs/principles/005-semantic-versioning-for-xdr-packages.md +1 -1
  6. package/.xdrs/_core/adrs/principles/006-research-standards.md +2 -2
  7. package/.xdrs/_core/adrs/principles/007-plan-standards.md +2 -2
  8. package/.xdrs/_core/adrs/principles/008-xdr-standards-structured.md +5 -5
  9. package/.xdrs/_core/adrs/principles/articles/001-xdrs-overview.md +22 -22
  10. package/.xdrs/_core/adrs/principles/skills/001-lint/SKILL.md +6 -6
  11. package/.xdrs/_core/adrs/principles/skills/002-write-xdr/SKILL.md +23 -23
  12. package/.xdrs/_core/adrs/principles/skills/003-write-skill/SKILL.md +5 -5
  13. package/.xdrs/_core/adrs/principles/skills/004-write-article/SKILL.md +7 -7
  14. package/.xdrs/_core/adrs/principles/skills/005-write-research/SKILL.md +7 -6
  15. package/.xdrs/_core/adrs/principles/skills/006-write-plan/SKILL.md +6 -6
  16. package/.xdrs/_core/bdrs/principles/001-xdr-decisions-and-skills-usage.md +5 -5
  17. package/AGENTS.md +15 -3
  18. package/README.md +3 -3
  19. package/lib/lint.js +84 -42
  20. package/lib/lint.test.js +106 -8
  21. package/package.json +3 -3
  22. /package/bin/{filedist.js → core.js} +0 -0
package/.xdrs/_core/adrs/principles/001-xdrs-core.md CHANGED
@@ -17,7 +17,7 @@ How should XDRs be structured and organized across types, teams, and scopes?
17
17
 
18
18
  Provides clear ownership by scope, predictable navigation, and reusable decisions that work well with AI agents by keeping files small and focused.
19
19
 
20
- ### Implementation Details
20
+ ### Details
21
21
 
22
22
  Decision Records can be of different kinds, depending on the nature of the decision:
23
23
  - BDR (Business Decision Record): Captures business process, product features, procedures and strategic decisions. Examples: business rules, product policies, customer service, business workflow, control frameworks for regulators for finance, product procedures and manuals, KYC requirements, business requirements in general
@@ -33,15 +33,17 @@ Collectively, these are referred to as XDRs.
33
33
  - Make it clear if an instruction is mandatory or advisory.
34
34
  - Mandatory language: "must", "always", "never", "required", "mandatory"
35
35
  - Advisory language: "should", "recommended", "advised", "preferably", "possibly", "optionally"
36
+ - The XDR root folder is the folder that contains the root `index.md`. The default root folder name is `.xdrs/`. Any folder name is valid as long as it contains an `index.md`. When `.xdrs/` is used, tools and agents discover it automatically by looking for `.xdrs/index.md` relative to the workspace root. When a different folder name is used, it must be passed explicitly to tools (e.g., `xdrs-core lint my-decisions/`).
36
37
  - ALWAYS use the following folder structure for XDR documents:
37
- `.xdrs/[scope]/[type]/[subject]/[number]-[short-title].md`
38
+ `[xdrs-root]/[scope]/[type]/[subject]/[number]-[short-title].md`
39
+ where `[xdrs-root]` is the XDR root folder (default: `.xdrs/`).
38
40
  - ALWAYS ignore symlinks paths. NEVER create or update documents inside symlinked folders.
39
41
  - **Files listed in `.filedist` are external XDRs.** A file whose path appears in the workspace root `.filedist` file was distributed from an external source repository. It must NEVER be modified locally. To change it, submit the change to the source repository and re-extract the updated package. The `.filedist` format is one entry per line: `<relative-path>|<package>|<version>`. A scope is considered external when any of its files appear in `.filedist`, and tools (such as `xdrs-core lint`) will skip external scopes by default. The `.filedist` 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` entries before and after the upgrade and diff the affected paths to understand what decisions were added, updated, or removed.
40
42
  - Optional supporting artifacts under the same subject:
41
- - `.xdrs/[scope]/[type]/[subject]/researches/[number]-[short-title].md`
42
- - `.xdrs/[scope]/[type]/[subject]/skills/[number]-[skill-name]/SKILL.md`
43
- - `.xdrs/[scope]/[type]/[subject]/articles/[number]-[short-title].md`
44
- - `.xdrs/[scope]/[type]/[subject]/plans/[number]-[short-title].md`
43
+ - `[xdrs-root]/[scope]/[type]/[subject]/researches/[number]-[short-title].md`
44
+ - `[xdrs-root]/[scope]/[type]/[subject]/skills/[number]-[skill-name]/SKILL.md`
45
+ - `[xdrs-root]/[scope]/[type]/[subject]/articles/[number]-[short-title].md`
46
+ - `[xdrs-root]/[scope]/[type]/[subject]/plans/[number]-[short-title].md`
45
47
  - Research, skills, and articles are part of the framework, but each has its own concept-specific standards in dedicated XDRs. This XDR defines the shared framework baseline; `_core-adr-002` defines the XDR document writing standard.
46
48
  - `_core-adr-002` defines XDR standards (document writing)
47
49
  - `_core-adr-003` defines skill standards
@@ -50,14 +52,14 @@ Collectively, these are referred to as XDRs.
50
52
  - `_core-adr-007` defines plan standards
51
53
  - For simple structures, flows, layout, or relationship indications, documents SHOULD prefer plain Markdown, tables, Mermaid.js (sequence, state, activity, entity diagrams) or ASCII art instead of external assets.
52
54
  - Images and other supporting files SHOULD be used only when they are materially necessary to preserve clarity, fidelity, or evidence. When used, they MUST live in a sibling `.assets/` folder next to the document.
53
- - XDRs in the subject root use `.xdrs/[scope]/[type]/[subject]/.assets/`
54
- - Articles use `.xdrs/[scope]/[type]/[subject]/articles/.assets/`
55
- - Research uses `.xdrs/[scope]/[type]/[subject]/researches/.assets/`
56
- - Skills use `.xdrs/[scope]/[type]/[subject]/skills/[number]-[skill-name]/.assets/`
55
+ - XDRs in the subject root use `[xdrs-root]/[scope]/[type]/[subject]/.assets/`
56
+ - Articles use `[xdrs-root]/[scope]/[type]/[subject]/articles/.assets/`
57
+ - Research uses `[xdrs-root]/[scope]/[type]/[subject]/researches/.assets/`
58
+ - Skills use `[xdrs-root]/[scope]/[type]/[subject]/skills/[number]-[skill-name]/.assets/`
57
59
  - **Scopes:**
58
60
  - Short name that defines a group or a package of xdrs
59
61
  - examples: `business-x`, `business-y`, `team-43`, `_core`
60
- - `_local` is a reserved scope for XDRs created locally to a specific project or repository. XDRs in `_local` must not be shared with or propagated to other contexts. This scope must always be placed in the lowest position in `.xdrs/index.md` so that its decisions override or extend any decisions from all higher-positioned scopes. Shared `.xdrs/index.md` files MUST NOT link `_local` canonical type indexes because `_local` stays workspace-local and is not distributed with shared packages. Readers, tools, and agents SHOULD still try to discover existing workspace-local `_local` canonical indexes by default, even when the shared root index does not link them. Documents in non-`_local` scopes MUST NEVER link to any document inside the `_local` scope, because `_local` is workspace-only and such links would break in any consumer workspace. Documents inside `_local` MAY link to other documents inside `_local`.
62
+ - `_local` is a reserved scope for XDRs created locally to a specific project or repository. XDRs in `_local` must not be shared with or propagated to other contexts. This scope must always be placed in the lowest position in the root `index.md` so that its decisions override or extend any decisions from all higher-positioned scopes. Shared root `index.md` files MUST NOT link `_local` canonical type indexes because `_local` stays workspace-local and is not distributed with shared packages. Readers, tools, and agents SHOULD still try to discover existing workspace-local `_local` canonical indexes by default, even when the shared root index does not link them. Documents in non-`_local` scopes MUST NEVER link to any document inside the `_local` scope, because `_local` is workspace-only and such links would break in any consumer workspace. Documents inside `_local` MAY link to other documents inside `_local`.
61
63
  - **Types:** `adrs`, `bdrs`, `edrs`
62
64
  - there can exist sufixes to the standard scope names (e.g: `business-x-mobileapp`, `business-y-servicedesk`)
63
65
  - **Subjects:** MUST be one of the following depending on the type of the XDR. Use the subject to indicate the main concern of the decision.
@@ -107,26 +109,26 @@ Collectively, these are referred to as XDRs.
107
109
  - `governance`: Engineering governance, risk controls, and compliance mechanics.
108
110
  - Examples: dependency governance, approval policies, mandatory quality checks.
109
111
  - Never use emojis
110
- - **Links:** Links that reference a parent folder MUST use absolute paths from the repository root with a leading `/` (e.g., `/.xdrs/_core/adrs/principles/001-xdrs-core.md`). Sibling files and child folder references SHOULD use relative paths (e.g., `002-other-doc.md`, `.assets/image.png`, `subdir/file.md`). Never use relative paths that traverse up the directory tree (e.g., `../../.assets/test.png`, `../other.md`); they break when files are moved and are harder to read.
112
+ - **Links:** Use relative paths for all links; never use absolute paths starting with `/`.
111
113
  - **Indexes**
112
114
  - Every document in the collection (XDRs, skills, articles, research, and plans) must be reachable through the index chain: root index → scope index → type index → document. A document that exists on disk but is not linked from its canonical type index is considered an orphan and must be added to the index or removed.
113
- - Keep a canonical type index with all documents of a certain type+scope in `.xdrs/[scope]/[type]/index.md`. The type index must link to every XDR, skill, article, research, and plan under that type+scope.
115
+ - Keep a canonical type index with all documents of a certain type+scope in `[xdrs-root]/[scope]/[type]/index.md`. The type index must link to every XDR, skill, article, research, and plan under that type+scope.
114
116
  - Canonical index requirements:
115
117
  - Organize XDR documents by subject for easier navigation
116
118
  - Add a short description of what this scope is about (responsibilities, general worries, teams involved, link to discussion process, etc)
117
119
  - Add a list of other scope indexes that this scope might be related to (only add scopes that might be overridden). E.g: "business-x-mobileapp" scope could refer to "business-x" and "sensitive-data" scopes in its index list. XDRs in scopes listed last override XDRs in scopes listed first when addressing the same topic.
118
120
  - Each XDR element entry in the index MUST include a short description of its content, preferably with an imperative statement or the question it answers, when possible (<15 words). Example: "Use this while planning a new feature", "What communication tone we use with our customers?", "PNPM vs Yarn comparison study"
119
- - Outside the scopes, keep a root index in `.xdrs/index.md` that links to each scope index (`.xdrs/[scope]/index.md`). Add the text "XDRs in scopes listed last override the ones listed first". The root index must not link directly to type indexes; readers navigate from the scope index to the type indexes. Use the link text pattern `View scope [scope_name]` for each scope link (e.g. `[View scope myteam] linking to (myteam/index.md)`).
121
+ - Outside the scopes, keep a root index in `[xdrs-root]/index.md` that links to each scope index (`[xdrs-root]/[scope]/index.md`). Add the text "XDRs in scopes listed last override the ones listed first". The root index must not link directly to type indexes; readers navigate from the scope index to the type indexes. Use the link text pattern `View scope [scope_name]` for each scope link (e.g. `[View scope myteam] linking to (myteam/index.md)`).
120
122
  - Always verify if indexes are up to date after making changes
121
123
  - **Scope index**
122
- - Each scope folder must maintain an `index.md` file at `.xdrs/[scope]/index.md`.
124
+ - Each scope folder must maintain an `index.md` file at `[xdrs-root]/[scope]/index.md`.
123
125
  - The scope index is a short article (under 1000 words) that provides an overview of all XDR contents within that scope. Follow article standards (`_core-adr-004`) when writing this file.
124
126
  - The audience for the scope index are engineers, architects, or business analysts who want to check if the scope's contents are useful for them before diving into the specific documents. Write a guided summary that helps them decide whether to explore further.
125
127
  - Focus on the most relevant content of the scope: what decisions are covered, what problems they address, and how the scope relates to other scopes.
126
128
  - At the end of the scope index, always add links to the canonical type indexes (`adrs/index.md`, `bdrs/index.md`, `edrs/index.md`) that exist within the scope.
127
129
  - Whenever the contents of a scope change (new XDRs, skills, articles, research, or plans are added, updated, or removed), evaluate whether the scope index should be updated to reflect the newer contents.
128
130
 
129
- **Folder structure examples:**
131
+ **Folder structure examples** (using the default `.xdrs/` root):
130
132
  - `.xdrs/business-x/edrs/devops/003-required-development-workflow.md`
131
133
  - `.xdrs/business-x/adrs/controls/010-security-and-secrets-management.md`
132
134
  - `.xdrs/_core/edrs/devops/001-multi-repo.md`
@@ -153,8 +155,8 @@ subject/
153
155
  ## References
154
156
 
155
157
  - [_core-adr-002 - XDR standards](002-xdr-standards.md) - Standards for writing individual XDR decision documents
156
- - [001-lint skill](/.xdrs/_core/adrs/principles/skills/001-lint/SKILL.md) - Skill for reviewing code changes against XDRs
157
- - [002-write-xdr skill](/.xdrs/_core/adrs/principles/skills/002-write-xdr/SKILL.md) - Skill for creating a new XDR following this standard
158
+ - [001-lint skill](skills/001-lint/SKILL.md) - Skill for reviewing code changes against XDRs
159
+ - [002-write-xdr skill](skills/002-write-xdr/SKILL.md) - Skill for creating a new XDR following this standard
158
160
  - [_core-adr-003 - Skill standards](003-skill-standards.md)
159
161
  - [_core-adr-004 - Article standards](004-article-standards.md)
160
162
  - [_core-adr-006 - Research standards](006-research-standards.md)
package/.xdrs/_core/adrs/principles/002-xdr-standards.md CHANGED
@@ -15,7 +15,7 @@ XDR framework elements (types, scopes, subjects, folder structure) are defined i
15
15
 
16
16
  XDR documents are the authoritative policy for their scope, type, and subject. They must be concise, template-compliant, and clear about applicability so that humans and AI agents can reliably determine whether and how to apply any decision.
17
17
 
18
- ### Implementation Details
18
+ ### Details
19
19
 
20
20
  - XDRs MUST contain a clear decision about a certain problem or situation. Avoid being too verbose and focus on explaining clearly the context and the decision. Avoid adding contents that are not original. If you have other references that are important to understand the document, add links and references. Always cite sources.
21
21
  - XDRs are the central artifact of the framework and the authoritative policy for their scope, type, and subject. Supporting artifacts may explain, justify, or operationalize the decision (like articles, researches and skills), but they do not replace it.
@@ -25,8 +25,8 @@ XDR documents are the authoritative policy for their scope, type, and subject. T
25
25
  |---|---|---|
26
26
  | `name` | Yes | 1-64 characters. Lowercase letters, numbers, hyphens, and leading underscores only. Must not end with a hyphen. Must not contain consecutive hyphens. Must match the document identifier from the heading: `[scope]-[type]-[number]-[short-title]`. |
27
27
  | `description` | Yes | 1-1024 characters. Describes what this decision is about and when to use it. Should include keywords that help agents identify when to apply it. |
28
- | `applied-to` | No | Short description of contexts this decision is applicable to. Keep it under 40 words. If omitted, the decision applies to all logically applicable elements. ONLY use this section if the usage is very specific to a specific case. Examples: `Only frontend code`, `JavaScript projects`. |
29
- | `valid-from` | No | ISO date (`YYYY-MM-DD`) indicating from when this decision must be enforced. Before this date it should be used everywhere possible, but compliance is not enforced during reviews until after this date. |
28
+ | `applyTo` | No | Short description of contexts this decision is applicable to. Keep it under 40 words. If omitted, the decision applies to all logically applicable elements. ONLY use this section if the usage is very specific to a specific case. Examples: `Only frontend code`, `JavaScript projects`. |
29
+ | `validFrom` | No | ISO date (`YYYY-MM-DD`) indicating from when this decision must be enforced. Before this date it should be used everywhere possible, but compliance is not enforced during reviews until after this date. |
30
30
  | `license` | No | SPDX license expression (e.g. `MIT`, `Apache-2.0`, `CC-BY-4.0`). Indicates the license under which the document content is shared. If omitted, the license is governed by the repository or package defaults. |
31
31
  | `metadata` | No | Arbitrary key-value map for additional properties not defined by this spec. |
32
32
 
@@ -42,23 +42,23 @@ XDR documents are the authoritative policy for their scope, type, and subject. T
42
42
  ---
43
43
  name: _core-adr-002-xdr-standards
44
44
  description: Defines how XDR documents should be written. Use when writing or reviewing any XDR.
45
- applied-to: All XDR scopes
46
- valid-from: 2026-06-01
45
+ applyTo: All XDR scopes
46
+ validFrom: 2026-06-01
47
47
  metadata:
48
48
  author: example-org
49
49
  ---
50
50
  ```
51
51
  - All documents present in the collection are considered active. There is no status field. When a decision is no longer relevant, valid or active, it must be removed from the collection. Historical versions are available via versioned packages or git history.
52
52
  - Before using, enforcing, or citing an XDR as a current rule, humans and AI agents MUST decide whether the decision is applicable for the current case.
53
- - Check `valid-from:` first. If a date is present and has not yet been reached, the decision SHOULD be adopted for new implementations but is not enforced during reviews.
54
- - Check `applied-to:` next to determine whether the decision fits the current codebase, system, workflow, or audience.
53
+ - Check `validFrom:` first. If a date is present and has not yet been reached, the decision SHOULD be adopted for new implementations but is not enforced during reviews.
54
+ - Check `applyTo:` next to determine whether the decision fits the current codebase, system, workflow, or audience.
55
55
  - Check the decision context and implementation details last to determine any additional boundaries, exceptions, or qualifiers that metadata alone cannot express.
56
56
  - Research documents MAY be added under the same subject to capture the exploration, findings, and proposals that backed a decision. Research is useful during elaboration, discussion, and updates of XDRs, but the XDR document remains the source of truth.
57
57
  - **XDR Id:** [scope]-[type]-[xdr number] (numbers are scoped per type+scope combination and must not be reused within that combination; always use lowercase)
58
58
  - Types in IDs: `adr`, `bdr`, `edr`
59
59
  - Define the next number of an XDR by checking what is the highest number present in the type+scope. Don't fill numbering gaps, as they might be old deleted XDRs and we should never reuse numbers of different documents/decisions. Numbering gaps are expected.
60
60
  - Decisions MUST be concise and reference other XDRs to avoid duplication.
61
- - The `### Implementation Details` section SHOULD state relevant boundaries or exceptions and what a reader should do or avoid in common cases. Use the frontmatter fields `applied-to` and `valid-from` as the first-pass filter for applicability, then keep nuanced boundaries in the decision text.
61
+ - The `### Details` section SHOULD state relevant boundaries or exceptions and what a reader should do or avoid in common cases. Use the frontmatter fields `applyTo` and `validFrom` as the first-pass filter for applicability, then keep nuanced boundaries in the decision text.
62
62
  - Use concise rules, examples, `Allowed` / `Disallowed` lists or checklists with required items to help the reader apply the decision correctly. Keep them short and decision-specific.
63
63
  - When the decision defines strong policies or rules that should be stated explicitly as stable rule blocks, or when other documents, skills, or agents need to cite those rules individually by identifier, the XDR MUST follow the extension [_core-adr-008 - XDR standards - structured](008-xdr-standards-structured.md) instead of using plain bullet lists for those rules.
64
64
  - Conflict handling applies to XDR documents:
@@ -81,8 +81,8 @@ All XDRs MUST follow this template
81
81
  ---
82
82
  name: [scope]-[type]-[number]-[short-title]
83
83
  description: [What this decision is about and when to use it]
84
- applied-to: [Optional. Contexts this decision applies to, under 40 words]
85
- valid-from: [Optional. ISO date YYYY-MM-DD from when enforcement begins]
84
+ applyTo: [Optional. Contexts this decision applies to, under 40 words]
85
+ validFrom: [Optional. ISO date YYYY-MM-DD from when enforcement begins]
86
86
  license: [Optional. SPDX license expression]
87
87
  metadata:
88
88
  [optional-key]: [optional-value]
@@ -104,7 +104,7 @@ Question: In the end, state explicitly the question that needs to be answered. E
104
104
 
105
105
  [Short description of implementation details for the chosen path]
106
106
 
107
- ### Implementation Details
107
+ ### Details
108
108
 
109
109
  [Optional section with implementation specifics, applicability boundaries, rules, concise examples, or do/don't guidance. This is the answer to the question in the "Context and Problem Statement". (<1300 words)]
110
110
 
@@ -137,8 +137,8 @@ Question: In the end, state explicitly the question that needs to be answered. E
137
137
 
138
138
  **Examples:**
139
139
  - Frontmatter examples:
140
- - `valid-from: 2026-03-01`
141
- - `applied-to: JavaScript projects`
140
+ - `validFrom: 2026-03-01`
141
+ - `applyTo: JavaScript projects`
142
142
 
143
143
  **XDR ID Examples:**
144
144
  - `business-x-adr-001` (not `ADR-business-x-001` or `business-x-adr-1`)
@@ -148,8 +148,8 @@ Question: In the end, state explicitly the question that needs to be answered. E
148
148
  ## References
149
149
 
150
150
  - [_core-adr-001 - XDRs core](001-xdrs-core.md) - Framework elements: types, scopes, subjects, folder structure
151
- - [001-lint skill](/.xdrs/_core/adrs/principles/skills/001-lint/SKILL.md) - Skill for reviewing code changes against XDRs
152
- - [002-write-xdr skill](/.xdrs/_core/adrs/principles/skills/002-write-xdr/SKILL.md) - Skill for creating a new XDR following this standard
151
+ - [001-lint skill](skills/001-lint/SKILL.md) - Skill for reviewing code changes against XDRs
152
+ - [002-write-xdr skill](skills/002-write-xdr/SKILL.md) - Skill for creating a new XDR following this standard
153
153
  - [_core-adr-003 - Skill standards](003-skill-standards.md)
154
154
  - [_core-adr-004 - Article standards](004-article-standards.md)
155
155
  - [_core-adr-006 - Research standards](006-research-standards.md)
package/.xdrs/_core/adrs/principles/003-skill-standards.md CHANGED
@@ -21,7 +21,7 @@ Skills follow the [agentskills](https://agentskills.io/specification) open forma
21
21
 
22
22
  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.
23
23
 
24
- ### Implementation Details
24
+ ### Details
25
25
 
26
26
  **Automation gradient**
27
27
  Skills exist on a spectrum from fully manual (human-only) to fully automated (agent-only). A skill should be written so it can be executed at any point on that spectrum:
@@ -36,7 +36,7 @@ Skills are procedures, XDRs are guardrails and decisions, Research documents cap
36
36
  Always create links back and forth between skills <-> XDRs when the relationship is direct, and link to related Research or Articles when they provide important context.
37
37
  - Skills are task-based artifacts. They should have a clear starting trigger, an expected end result, and enough detail for a human or agent to verify that the task finished correctly.
38
38
  - A skill is not policy by itself. If following a skill is mandatory, that obligation must come from an XDR or another explicit policy that references the skill.
39
- - When a skill reads, operationalizes, or enforces XDRs, it MUST evaluate the XDR metadata first. `Valid:` determines the convergence date for adoption, `Applied to:` determines whether the decision fits the current task context, and the decision text itself determines any remaining boundaries. All documents present in the collection are considered active. Skills must not treat out-of-window or out-of-scope XDRs as current requirements.
39
+ - When a skill reads, operationalizes, or enforces XDRs, it MUST evaluate the XDR metadata first. `validFrom:` determines the convergence date for adoption, `applyTo:` determines whether the decision fits the current task context, and the decision text itself determines any remaining boundaries. All documents present in the collection are considered active. Skills must not treat out-of-window or out-of-scope XDRs as current requirements.
40
40
  - Skills and XDRs have a many-to-many relationship: one skill may operationalize multiple XDRs, and one XDR may be executed through multiple skills in different contexts.
41
41
 
42
42
  Place a skill under the XDR type that matches the nature of the activity the skill performs:
@@ -116,7 +116,7 @@ Rules:
116
116
  - For simple structure, flow, layout, or relationship indications, `SKILL.md` SHOULD prefer plain Markdown, tables, or ASCII art instead of external assets.
117
117
  - Images and other local resource files referenced from `SKILL.md` SHOULD be used only when they are materially necessary and MUST live in `.assets/` inside the same skill package.
118
118
  - Keep `SKILL.md` under 6500 words. Move lengthy reference material to `references/`.
119
- - Links that reference a parent folder MUST use absolute paths from the repository root with a leading `/`. Sibling files and child folder references SHOULD use relative paths (e.g., `.assets/image.png`, `subdir/file.md`). Never use relative paths that traverse up the directory tree (e.g., `../other.md`).
119
+ - Use relative paths for all links; never use absolute paths starting with `/`.
120
120
  - Always use lowercase file names.
121
121
  - Never use emojis in skill content.
122
122
 
package/.xdrs/_core/adrs/principles/004-article-standards.md CHANGED
@@ -17,14 +17,14 @@ How should articles be structured and organized to provide useful views over XDR
17
17
 
18
18
  Articles are Markdown documents placed inside a subject folder alongside decision records. Placing articles within a subject keeps them close to the decisions, research, and skills they reference.
19
19
 
20
- ### Implementation Details
20
+ ### Details
21
21
 
22
22
  - Articles are views, not decisions. They summarize and synthesize content from XDRs, Research, and Skills but are NOT the source of truth. When there is a conflict between an article and a Decision Record, the Decision Record takes precedence.
23
23
  - Articles are not limited to synthesizing XDRs. They may also document application features, APIs, general project information, reference tables, diagrams, FAQs and other elements useful to their intended audience.
24
24
  - Articles must reference the XDRs, Research documents, and Skills they synthesize. Never duplicate decision content; link back to the authoritative sources.
25
25
  - Articles may serve as indexes, combining related artifacts on a specific topic into a single navigable document.
26
26
  - In more complex cases, an article may be an index of links to other articles, grouping related documentation into a single entry point that guides readers across a set of related topics.
27
- - When an article tells readers which decisions to follow, it SHOULD check `Valid:` first to determine the convergence date, `Applied to:` second to determine context fit, and the decision text itself last. All documents present in the collection are considered active; articles must not present out-of-window or out-of-scope XDRs as current rules for the discussed context.
27
+ - When an article tells readers which decisions to follow, it SHOULD check `validFrom:` first to determine the convergence date, `applyTo:` second to determine context fit, and the decision text itself last. All documents present in the collection are considered active; articles must not present out-of-window or out-of-scope XDRs as current rules for the discussed context.
28
28
  - Articles must remain consistent with the XDRs, Research documents, and Skills they reference. When a referenced artifact changes, the article must be reviewed and updated.
29
29
  - Place an article in the subject folder that best matches its topic using the required list of subjects per type defined in `_core-adr-001`. If an article spans more than one subject, place it in `principles`.
30
30
  - For simple structure, flow, layout, or relationship indications, articles SHOULD prefer plain Markdown, tables, or ASCII art instead of external assets.
@@ -89,4 +89,4 @@ when referencing an information from those documents.]
89
89
  - [_core-adr-001 - XDRs core](001-xdrs-core.md)
90
90
  - [_core-adr-003 - Skill standards](003-skill-standards.md)
91
91
  - [_core-adr-006 - Research standards](006-research-standards.md)
92
- - [004-write-article skill](/.xdrs/_core/adrs/principles/skills/004-write-article/SKILL.md) - Step-by-step instructions for creating a new article
92
+ - [004-write-article skill](skills/004-write-article/SKILL.md) - Step-by-step instructions for creating a new article
package/.xdrs/_core/adrs/principles/005-semantic-versioning-for-xdr-packages.md CHANGED
@@ -17,7 +17,7 @@ Question: How should semantic versioning be used when publishing or versioning a
17
17
 
18
18
  XDR packages must use semantic versioning so the package version communicates the expected upgrade impact on consuming teams and projects.
19
19
 
20
- ### Implementation Details
20
+ ### Details
21
21
 
22
22
  - Package versions MUST follow `MAJOR.MINOR.PATCH`.
23
23
  - The published package version MUST represent the impact of the package as a whole, not only of a single changed file.
package/.xdrs/_core/adrs/principles/006-research-standards.md CHANGED
@@ -17,7 +17,7 @@ Question: How should research documents be structured and organized so they comm
17
17
 
18
18
  Research documents are Markdown files placed inside a subject folder alongside decision records. They use an IMRAD-inspired paper structure adapted to company needs so teams can communicate investigated problems, methods, findings, and conclusions clearly, combine experienced professional judgment with good-enough evidence, preserve reproducibility where it matters, and revisit the work when technology, constraints, or facts change.
19
19
 
20
- ### Implementation Details
20
+ ### Details
21
21
 
22
22
  - Research is evidence and exploration, not the adopted decision. When a research document and an XDR disagree, the XDR takes precedence.
23
23
  - `Research` is the artifact name. `researches/` is only the folder name used alongside `skills/` and `articles/`.
@@ -133,4 +133,4 @@ Prefer tables, bullets, or ASCII art for simple comparisons. Use external figure
133
133
  - [_core-adr-001 - XDRs core](001-xdrs-core.md)
134
134
  - [_core-adr-003 - Skill standards](003-skill-standards.md)
135
135
  - [_core-adr-004 - Article standards](004-article-standards.md)
136
- - [005-write-research skill](/.xdrs/_core/adrs/principles/skills/005-write-research/SKILL.md) - Step-by-step instructions for creating a research document
136
+ - [005-write-research skill](skills/005-write-research/SKILL.md) - Step-by-step instructions for creating a research document
package/.xdrs/_core/adrs/principles/007-plan-standards.md CHANGED
@@ -17,7 +17,7 @@ How should plans be structured and organized so they provide clear guidance for
17
17
 
18
18
  Plans are Markdown documents placed inside a subject folder alongside decision records. They describe a problem, a proposed solution, and the approach to solve it. Plans have a clear start and end and a well-defined scope.
19
19
 
20
- ### Implementation Details
20
+ ### Details
21
21
 
22
22
  - Plans describe a problem (why), what we will do to solve the problem, and the approach and activities needed to solve it (how).
23
23
  - Plans are NOT the source of truth. When a plan and an XDR disagree, the XDR takes precedence.
@@ -135,4 +135,4 @@ Due date: YYYY-MM-DD
135
135
  - [_core-adr-001 - XDRs core](001-xdrs-core.md) - Framework elements: types, scopes, subjects, folder structure
136
136
  - [_core-adr-004 - Article standards](004-article-standards.md) - Companion artifact type for synthetic views
137
137
  - [_core-adr-006 - Research standards](006-research-standards.md) - Companion artifact type for exploratory evidence
138
- - [006-write-plan skill](/.xdrs/_core/adrs/principles/skills/006-write-plan/SKILL.md) - Step-by-step instructions for creating a new plan
138
+ - [006-write-plan skill](skills/006-write-plan/SKILL.md) - Step-by-step instructions for creating a new plan
package/.xdrs/_core/adrs/principles/008-xdr-standards-structured.md CHANGED
@@ -7,17 +7,17 @@ description: Extends xdr-standards with a numbered rule format for XDR documents
7
7
 
8
8
  ## Context and Problem Statement
9
9
 
10
- Some XDR documents define multiple strong policies or rules that must be stated explicitly so they can be applied consistently. In other cases, documents, skills, or agents need to refer to one specific rule without copying its content. Without a standard format, prose references like "see the third bullet in Implementation Details" are fragile and ambiguous.
10
+ Some XDR documents define multiple strong policies or rules that must be stated explicitly so they can be applied consistently. In other cases, documents, skills, or agents need to refer to one specific rule without copying its content. Without a standard format, prose references like "see the third bullet in Details" are fragile and ambiguous.
11
11
 
12
12
  Question: How should an XDR document expose strong or individually referenceable rules or policies so they stay explicit, stable, and easy to cite?
13
13
 
14
14
  ## Decision Outcome
15
15
 
16
- **Numbered rule blocks inside Implementation Details with a canonical citation syntax**
16
+ **Numbered rule blocks inside Details with a canonical citation syntax**
17
17
 
18
- When an XDR document defines strong rules or policies that should be stated explicitly, or when documents and skills need to cite individual rules precisely, each rule must be placed inside `### Implementation Details` as a numbered heading block. Referencing documents and skills must cite rules using the canonical dot-notation identifier.
18
+ When an XDR document defines strong rules or policies that should be stated explicitly, or when documents and skills need to cite individual rules precisely, each rule must be placed inside `### Details` as a numbered heading block. Referencing documents and skills must cite rules using the canonical dot-notation identifier.
19
19
 
20
- ### Implementation Details
20
+ ### Details
21
21
 
22
22
  Use this format when the decision defines strong rules or policies that must be stated explicitly as stable rule blocks, or when there is a clear need for external documents, skills, or agents to reference specific items inside an XDR without duplicating the full policy text. Standard XDRs that do not define strong rule sets and do not need item-level citation should follow `_core-adr-002-xdr-standards` without adding numbered rule headings.
23
23
 
@@ -72,7 +72,7 @@ Documents and skills that cite a rule must use the exact dot-notation form: `[xd
72
72
 
73
73
  * (REJECTED) **Free-form prose rules with section anchors** — Use markdown heading anchors as citation targets.
74
74
  * Reason: Anchors are fragile across editors, rendering tools, and refactors. They do not enforce a stable numbering contract and break silently when headings are reworded.
75
- * (CHOSEN) **Numbered rule blocks inside Implementation Details** — Prefix each rule heading with a two-digit sequence number and use dot-notation for citations.
75
+ * (CHOSEN) **Numbered rule blocks inside Details** — Prefix each rule heading with a two-digit sequence number and use dot-notation for citations.
76
76
  * Reason: Minimal addition to the existing XDR template, stable identifiers independent of heading text, and fully compatible with `_core-adr-002-xdr-standards`.
77
77
 
78
78
  ## References
package/.xdrs/_core/adrs/principles/articles/001-xdrs-overview.md CHANGED
@@ -17,23 +17,23 @@ same decision system.
17
17
  record the adopted direction. They are the central policy artifact of the framework for the
18
18
  scope and topic they cover. Three decision record types exist: **ADR** for architectural and
19
19
  technical decisions, **BDR** for business and operational decisions, and **EDR** for engineering
20
- implementation decisions. See [_core-adr-001](/.xdrs/_core/adrs/principles/001-xdrs-core.md).
20
+ implementation decisions. See [_core-adr-001](../001-xdrs-core.md).
21
21
  - **Research** captures exploration before or around a decision: constraints, findings, options,
22
22
  pros, and cons. Research supports elaboration, discussion, and updates,
23
23
  but it is not the final rule. A single Research document may inform multiple downstream ADRs,
24
24
  BDRs, or EDRs. If Research and an XDR disagree, the XDR wins. See
25
- [_core-adr-006](/.xdrs/_core/adrs/principles/006-research-standards.md).
25
+ [_core-adr-006](../006-research-standards.md).
26
26
  - **Skills** describe how to execute work under the constraints of the decisions. They add the
27
27
  procedural detail that XDRs intentionally avoid. A Skill may be used by a human, an AI agent, or
28
28
  both. Skills are task-based, should end in a verifiable outcome, and are only mandatory when a
29
- policy such as an XDR makes them mandatory. See [_core-adr-003](/.xdrs/_core/adrs/principles/003-skill-standards.md).
29
+ policy such as an XDR makes them mandatory. See [_core-adr-003](../003-skill-standards.md).
30
30
  - **Articles** are synthetic views, like this one. They explain a topic across multiple XDRs,
31
31
  Research documents, and Skills, helping readers understand the system without making new
32
- decisions. See [_core-adr-004](/.xdrs/_core/adrs/principles/004-article-standards.md).
32
+ decisions. See [_core-adr-004](../004-article-standards.md).
33
33
  - **Plans** describe a problem, a proposed solution, and the approach and activities needed to
34
34
  solve it. They have a clear start and end and a well-defined scope. Plans are ephemeral: they
35
35
  must be deleted after full implementation, with lasting outputs captured as Decisions, Skills,
36
- Articles, or other artifacts. See [_core-adr-007](/.xdrs/_core/adrs/principles/007-plan-standards.md).
36
+ Articles, or other artifacts. See [_core-adr-007](../007-plan-standards.md).
37
37
  - **Indexes and folder structure** are the discovery layer. They do not make decisions by
38
38
  themselves, but they determine how people and agents find the right artifacts, how scopes
39
39
  override one another, and how a large set of decisions remains navigable.
@@ -139,7 +139,7 @@ guidance, and the explanatory overview close together without collapsing them in
139
139
 
140
140
  ### Guidelines
141
141
 
142
- Follow [_core-adr-001](/.xdrs/_core/adrs/principles/001-xdrs-core.md) and [_core-adr-002](/.xdrs/_core/adrs/principles/002-xdr-standards.md) strictly. Key rules:
142
+ Follow [_core-adr-001](../001-xdrs-core.md) and [_core-adr-002](../002-xdr-standards.md) strictly. Key rules:
143
143
 
144
144
  - Use **mandatory language** (`must`, `never`, `required`) for non-negotiable rules and
145
145
  **advisory language** (`should`, `recommended`) for guidance.
@@ -157,13 +157,13 @@ Follow [_core-adr-001](/.xdrs/_core/adrs/principles/001-xdrs-core.md) and [_core
157
157
  - **New subject** — create the subject folder under the existing scope+type path. Add an
158
158
  allowed subject or use `principles` if none fits (propose a new subject via a `_core` ADR).
159
159
  - **New research** — add a `researches/[number]-[short-title].md` inside the relevant subject
160
- folder, following [_core-adr-006](/.xdrs/_core/adrs/principles/006-research-standards.md).
160
+ folder, following [_core-adr-006](../006-research-standards.md).
161
161
  - **New skill** — add a `skills/[number]-[skill-name]/SKILL.md` inside the relevant subject
162
- folder, following [_core-adr-003](/.xdrs/_core/adrs/principles/003-skill-standards.md).
162
+ folder, following [_core-adr-003](../003-skill-standards.md).
163
163
  - **New article** — add an `articles/[number]-[short-title].md` inside the relevant subject
164
- folder, following [_core-adr-004](/.xdrs/_core/adrs/principles/004-article-standards.md).
164
+ folder, following [_core-adr-004](../004-article-standards.md).
165
165
  - **New plan** — add a `plans/[number]-[short-title].md` inside the relevant subject
166
- folder, following [_core-adr-007](/.xdrs/_core/adrs/principles/007-plan-standards.md).
166
+ folder, following [_core-adr-007](../007-plan-standards.md).
167
167
 
168
168
  ### Using XDRs in your own project
169
169
 
@@ -181,15 +181,15 @@ Follow [_core-adr-001](/.xdrs/_core/adrs/principles/001-xdrs-core.md) and [_core
181
181
 
182
182
  ## References
183
183
 
184
- - [_core-adr-001](/.xdrs/_core/adrs/principles/001-xdrs-core.md) - XDR elements: types, scopes, subjects, folder structure
185
- - [_core-adr-002](/.xdrs/_core/adrs/principles/002-xdr-standards.md) - XDR document standards and mandatory template
186
- - [_core-adr-003](/.xdrs/_core/adrs/principles/003-skill-standards.md) - Skill standards and co-location rules
187
- - [_core-adr-004](/.xdrs/_core/adrs/principles/004-article-standards.md) - Article standards
188
- - [_core-adr-006](/.xdrs/_core/adrs/principles/006-research-standards.md) - Research standards
189
- - [_core-adr-007](/.xdrs/_core/adrs/principles/007-plan-standards.md) - Plan standards
190
- - [001-lint skill](/.xdrs/_core/adrs/principles/skills/001-lint/SKILL.md) - Linting code against XDRs
191
- - [002-write-xdr skill](/.xdrs/_core/adrs/principles/skills/002-write-xdr/SKILL.md) - Writing a new XDR
192
- - [003-write-skill skill](/.xdrs/_core/adrs/principles/skills/003-write-skill/SKILL.md) - Writing a new skill
193
- - [004-write-article skill](/.xdrs/_core/adrs/principles/skills/004-write-article/SKILL.md) - Writing a new article
194
- - [005-write-research skill](/.xdrs/_core/adrs/principles/skills/005-write-research/SKILL.md) - Writing a new research document
195
- - [_core-adr-005](/.xdrs/_core/adrs/principles/005-semantic-versioning-for-xdr-packages.md) - Semantic versioning rules for XDR packages
184
+ - [_core-adr-001](../001-xdrs-core.md) - XDR elements: types, scopes, subjects, folder structure
185
+ - [_core-adr-002](../002-xdr-standards.md) - XDR document standards and mandatory template
186
+ - [_core-adr-003](../003-skill-standards.md) - Skill standards and co-location rules
187
+ - [_core-adr-004](../004-article-standards.md) - Article standards
188
+ - [_core-adr-006](../006-research-standards.md) - Research standards
189
+ - [_core-adr-007](../007-plan-standards.md) - Plan standards
190
+ - [001-lint skill](../skills/001-lint/SKILL.md) - Linting code against XDRs
191
+ - [002-write-xdr skill](../skills/002-write-xdr/SKILL.md) - Writing a new XDR
192
+ - [003-write-skill skill](../skills/003-write-skill/SKILL.md) - Writing a new skill
193
+ - [004-write-article skill](../skills/004-write-article/SKILL.md) - Writing a new article
194
+ - [005-write-research skill](../skills/005-write-research/SKILL.md) - Writing a new research document
195
+ - [_core-adr-005](../005-semantic-versioning-for-xdr-packages.md) - Semantic versioning rules for XDR packages
package/.xdrs/_core/adrs/principles/skills/001-lint/SKILL.md CHANGED
@@ -22,12 +22,12 @@ Performs a structured review of code changes or files against the XDRs in the re
22
22
 
23
23
  ### Phase 2: XDR Compilation
24
24
 
25
- 1. Gather all Decision Records from `.xdrs/index.md` starting from the working directory.
25
+ 1. Gather all Decision Records from the XDR root `index.md` (default: `.xdrs/index.md`) starting from the working directory.
26
26
  - XDR scopes are controlled by nested folders; some are broad, others domain-specific.
27
27
  - Extract frontmatter first to decide whether each XDR should be used for the current review context.
28
28
  - All documents present in the collection are considered active.
29
- - Check `valid-from:` first. If a date is present and has not yet been reached, the decision SHOULD be adopted for new implementations but is not enforced during reviews.
30
- - Check `applied-to:` second. Keep only XDRs whose stated scope fits the files, systems, or workflows under review.
29
+ - Check `validFrom:` first. If a date is present and has not yet been reached, the decision SHOULD be adopted for new implementations but is not enforced during reviews.
30
+ - Check `applyTo:` second. Keep only XDRs whose stated scope fits the files, systems, or workflows under review.
31
31
  - Check the decision text itself last for additional boundaries or exceptions that metadata does not encode.
32
32
  2. Filter relevance based on file types, domains, and architectural patterns in scope.
33
33
 
@@ -88,7 +88,7 @@ Scope: [scope identifier]
88
88
 
89
89
  ## References
90
90
 
91
- - [_core-adr-001 - XDRs core](/.xdrs/_core/adrs/principles/001-xdrs-core.md)
92
- - [_core-adr-002 - XDR standards](/.xdrs/_core/adrs/principles/002-xdr-standards.md)
93
- - [_core-adr-003 - Skill standards](/.xdrs/_core/adrs/principles/003-skill-standards.md)
91
+ - [_core-adr-001 - XDRs core](../../001-xdrs-core.md)
92
+ - [_core-adr-002 - XDR standards](../../002-xdr-standards.md)
93
+ - [_core-adr-003 - Skill standards](../../003-skill-standards.md)
94
94
 
package/.xdrs/_core/adrs/principles/skills/002-write-xdr/SKILL.md CHANGED
@@ -16,7 +16,7 @@ Guides the creation of a well-structured XDR by following the standards in `_cor
16
16
 
17
17
  ### Phase 1: Understand the Decision
18
18
 
19
- 1. Read `.xdrs/index.md` to discover all active scopes and their canonical indexes.
19
+ 1. Read the XDR root `index.md` (default: `.xdrs/index.md`) to discover all active scopes and their canonical indexes.
20
20
  2. Read `.xdrs/_core/adrs/principles/001-xdrs-core.md` in full to internalize structure rules, mandatory language, and the XDR framework elements.
21
21
  3. Read `.xdrs/_core/adrs/principles/002-xdr-standards.md` in full to internalize the XDR template and document writing rules.
22
22
  4. Treat `001-xdrs-core` as the canonical source for all core XDR element definitions (type, scope, subject, numbering, placement). Treat `002-xdr-standards` as the canonical source for how to write and structure the document itself.
@@ -57,8 +57,8 @@ Choose a title that clearly states the question this XDR answers, not the answer
57
57
 
58
58
  ### Phase 4: Research Related XDRs
59
59
 
60
- 1. Read all existing XDRs relevant to the topic across all scopes listed in `.xdrs/index.md`.
61
- 2. Evaluate XDR metadata before treating any decision as a current constraint. All documents present in the collection are considered active. `Valid:` determines the convergence date for adoption, `Applied to:` determines whether it fits the current topic, and the decision text defines any remaining boundaries. Treat out-of-window or out-of-scope XDRs as background only when assessing overlaps and conflicts.
60
+ 1. Read all existing XDRs relevant to the topic across all scopes listed in the XDR root `index.md`.
61
+ 2. Evaluate XDR metadata before treating any decision as a current constraint. All documents present in the collection are considered active. `validFrom:` determines the convergence date for adoption, `applyTo:` determines whether it fits the current topic, and the decision text defines any remaining boundaries. Treat out-of-window or out-of-scope XDRs as background only when assessing overlaps and conflicts.
62
62
  3. Identify decisions that already address the topic (full or partial overlap).
63
63
  4. Note decisions that might conflict with the intended outcome.
64
64
  5. Read related `researches/` documents when they exist, especially if they contain constraints, findings, or option tradeoffs that should influence the decision.
@@ -79,7 +79,7 @@ Use the mandatory template from `002-xdr-standards`:
79
79
 
80
80
  **Check if the decision requires a structured set of rules:**
81
81
  If the decision defines strong rules or policies that must be stated explicitly, or if other documents, skills, or agents have a clear need to reference individual rules, you MUST apply the structured rule format from `_core-adr-008-xdr-standards-structured`. This means:
82
- - Place each rule as a numbered heading block inside `### Implementation Details`.
82
+ - Place each rule as a numbered heading block inside `### Details`.
83
83
  - Use the format:
84
84
  #### [NN]-[short-descriptive-title-in-kebab-case]
85
85
  [Rule body with mandatory/advisory language.]
@@ -89,7 +89,7 @@ If the decision defines strong rules or policies that must be stated explicitly,
89
89
  **Example of a structured set of rules:**
90
90
 
91
91
  ```markdown
92
- ### Implementation Details
92
+ ### Details
93
93
 
94
94
  #### 01-data-must-be-encrypted-at-rest
95
95
  All user data must be encrypted at rest using AES-256 or stronger algorithms.
@@ -107,8 +107,8 @@ Refer to `_core-adr-008-xdr-standards-structured` for full requirements and cita
107
107
  ---
108
108
  name: [scope]-[type]-[number]-[short-title]
109
109
  description: [What this decision is about and when to use it]
110
- applied-to: [Optional. Contexts this decision applies to, under 40 words]
111
- valid-from: [Optional. ISO date YYYY-MM-DD from when enforcement begins]
110
+ applyTo: [Optional. Contexts this decision applies to, under 40 words]
111
+ validFrom: [Optional. ISO date YYYY-MM-DD from when enforcement begins]
112
112
  ---
113
113
 
114
114
  # [scope]-[type]-[number]: [Short Title]
@@ -121,7 +121,7 @@ valid-from: [Optional. ISO date YYYY-MM-DD from when enforcement begins]
121
121
  **[Chosen Option Title]**
122
122
  [One sentence: what is the decision - under 30 words]
123
123
 
124
- ### Implementation Details
124
+ ### Details
125
125
  [Rules, applicability boundaries, concise examples, and optional do/don't guidance — under 1300 words]
126
126
 
127
127
  ## Considered Options (only if the user explicitly indicated multiple options)
@@ -132,10 +132,10 @@ valid-from: [Optional. ISO date YYYY-MM-DD from when enforcement begins]
132
132
  ```
133
133
 
134
134
  Mandatory rules to apply while drafting:
135
- - Include frontmatter `applied-to:` only when it adds value by narrowing the decision scope; omit it when the decision applies broadly.
136
- - Include frontmatter `valid-from:` only when there is a specific future enforcement date; omit it when the decision is immediately effective.
137
- - Keep `applied-to:` under 40 words and use `valid-from:` only with `YYYY-MM-DD` ISO format.
138
- - When frontmatter metadata is present, write it so a reader can decide whether the XDR should be used for the current case without guessing. `valid-from:` sets a convergence date for adoption, `applied-to:` narrows the contexts where the decision applies, and the decision text defines any remaining boundaries.
135
+ - Include frontmatter `applyTo:` only when it adds value by narrowing the decision scope; omit it when the decision applies broadly.
136
+ - Include frontmatter `validFrom:` only when there is a specific future enforcement date; omit it when the decision is immediately effective.
137
+ - Keep `applyTo:` under 40 words and use `validFrom:` only with `YYYY-MM-DD` ISO format.
138
+ - When frontmatter metadata is present, write it so a reader can decide whether the XDR should be used for the current case without guessing. `validFrom:` sets a convergence date for adoption, `applyTo:` narrows the contexts where the decision applies, and the decision text defines any remaining boundaries.
139
139
  - Use mandatory language ("must", "always", "never") only for hard requirements; use advisory language ("should", "recommended") for guidance.
140
140
  - Do not duplicate content already in referenced XDRs — link instead.
141
141
  - Keep the decision itself authoritative in the XDR. Supporting artifacts may elaborate, but they should not restate the full decision when a short reference is enough.
@@ -143,7 +143,7 @@ Mandatory rules to apply while drafting:
143
143
  - Keep exploratory option analysis in a related Research document when it would distract from the final decision text.
144
144
  - Prefer plain Markdown, tables, Mermaid.js (sequence, state, activity, entity diagrams), or ASCII art for simple structure, flow, layout, or relationship indications.
145
145
  - If the XDR genuinely needs local images or supporting files, store them in `.xdrs/[scope]/[type]/[subject]/.assets/` and link them using a same-folder relative path (e.g., `.assets/image.png`).
146
- - Links that reference a parent folder MUST use absolute paths from the repository root with a leading `/` (e.g., `/.xdrs/_core/adrs/principles/001-xdrs-core.md`). Sibling files and child folder references SHOULD use relative paths (e.g., `002-other-doc.md`, `.assets/image.png`, `subdir/file.md`). Never use relative paths that traverse up the directory tree (e.g., `../../.assets/test.png`, `../other.md`).
146
+ - Use relative paths for all links; never use absolute paths starting with `/`.
147
147
  - No emojis. Lowercase filenames.
148
148
  - Target under 1300 words total; under 2600 words for complex decisions.
149
149
 
@@ -152,23 +152,23 @@ Mandatory rules to apply while drafting:
152
152
  Check every item before finalizing:
153
153
 
154
154
  1. **Length**: Is it under 1300 words? Trim verbose explanations. Move detailed skills to a separate file and link.
155
- 2. **Frontmatter**: Are `applied-to:` and `valid-from:` present only when they add value, omitted entirely when not needed, and specific enough for a reader to decide whether the XDR is currently valid and applicable?
155
+ 2. **Frontmatter**: Are `applyTo:` and `validFrom:` present only when they add value, omitted entirely when not needed, and specific enough for a reader to decide whether the XDR is currently valid and applicable?
156
156
  3. **Originality**: Does every sentence add value that cannot be found in a generic web search? Remove obvious advice. Keep only the project-specific decision.
157
157
  4. **Clarity**: Is the chosen option unambiguous? Is the "why" clear in one reading?
158
158
  5. **Redundancy**: Is the XDR the primary source for the decision itself, with related documents linked instead of duplicated wherever possible?
159
159
  6. **Conflicts section**: Is it present and filled if Phase 3 found any conflicts?
160
- 7. **Index entries**: Will the new XDR be added to `[scope]/[type]/index.md` and `.xdrs/index.md`?
160
+ 7. **Index entries**: Will the new XDR be added to `[scope]/[type]/index.md` and the XDR root `index.md`?
161
161
 
162
162
  If any check fails, revise and re-run this phase before proceeding.
163
163
 
164
164
  ### Phase 8: Write Files
165
165
 
166
- 1. Create the XDR file at `.xdrs/[scope]/[type]/[subject]/[number]-[short-title].md`.
167
- 2. Add an entry to `.xdrs/[scope]/[type]/index.md` (create the file if it does not exist).
168
- 3. Add or verify the scope entry in `.xdrs/index.md`.
166
+ 1. Create the XDR file at `[xdrs-root]/[scope]/[type]/[subject]/[number]-[short-title].md` (default root: `.xdrs/`).
167
+ 2. Add an entry to `[xdrs-root]/[scope]/[type]/index.md` (create the file if it does not exist).
168
+ 3. Add or verify the scope entry in the XDR root `index.md`.
169
169
  4. If significant research was produced or already exists, link it from the XDR `## Considered Options` section.
170
- 5. If concise rules, examples, or do/don't bullets help readers apply the decision correctly, add them inside `### Implementation Details` without turning the XDR into a long procedure.
171
- 6. Evaluate whether the scope index at `.xdrs/[scope]/index.md` should be updated to reflect the new content. If the scope index does not exist, create it following article standards and the scope index rules in `_core-adr-001`.
170
+ 5. If concise rules, examples, or do/don't bullets help readers apply the decision correctly, add them inside `### Details` without turning the XDR into a long procedure.
171
+ 6. Evaluate whether the scope index at `[xdrs-root]/[scope]/index.md` should be updated to reflect the new content. If the scope index does not exist, create it following article standards and the scope index rules in `_core-adr-001`.
172
172
 
173
173
  ### Phase 9: Verify Package structure with Lint
174
174
 
@@ -191,6 +191,6 @@ If any check fails, revise and re-run this phase before proceeding.
191
191
 
192
192
  ## References
193
193
 
194
- - [_core-adr-001 - XDRs core](/.xdrs/_core/adrs/principles/001-xdrs-core.md)
195
- - [_core-adr-002 - XDR standards](/.xdrs/_core/adrs/principles/002-xdr-standards.md)
196
- - [_core-adr-003 - Skill standards](/.xdrs/_core/adrs/principles/003-skill-standards.md)
194
+ - [_core-adr-001 - XDRs core](../../001-xdrs-core.md)
195
+ - [_core-adr-002 - XDR standards](../../002-xdr-standards.md)
196
+ - [_core-adr-003 - Skill standards](../../003-skill-standards.md)
package/.xdrs/_core/adrs/principles/skills/003-write-skill/SKILL.md CHANGED
@@ -51,7 +51,7 @@ Quick test:
51
51
 
52
52
  1. List `.xdrs/[scope]/[type]/[subject]/skills/` for existing skills. If one already covers the goal, extend or reference it instead of creating a duplicate.
53
53
  2. Read all XDRs relevant to the skill's domain to collect rules and cross-references.
54
- 3. Evaluate XDR metadata before operationalizing those rules. All documents present in the collection are considered active. `Valid:` determines the convergence date for adoption, `Applied to:` determines whether the decision fits the intended task context, and the decision text defines any remaining boundaries. Keep out-of-window or out-of-scope XDRs as background only.
54
+ 3. Evaluate XDR metadata before operationalizing those rules. All documents present in the collection are considered active. `validFrom:` determines the convergence date for adoption, `applyTo:` determines whether the decision fits the intended task context, and the decision text defines any remaining boundaries. Keep out-of-window or out-of-scope XDRs as background only.
55
55
  4. Decide whether the skill is merely guidance or is being referenced by an XDR as a mandatory procedure. Do not encode policy in the skill unless it comes from a referenced XDR.
56
56
 
57
57
  ### Phase 4: Write the SKILL.md
@@ -100,7 +100,7 @@ Rules:
100
100
  - When the skill depends on XDRs, make the activation logic and instructions consistent with the XDR metadata so the skill does not operationalize inactive or out-of-scope decisions.
101
101
  - Prefer plain Markdown, tables, Mermaid.js (sequence, state, activity, entity diagrams), or ASCII art for simple structure, flow, layout, or relationship indications.
102
102
  - 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`).
103
- - Links that reference a parent folder MUST use absolute paths from the repository root with a leading `/` (e.g., `/.xdrs/_core/adrs/principles/001-xdrs-core.md`). Sibling files and child folder references SHOULD use relative paths (e.g., `002-other-doc.md`, `.assets/image.png`, `subdir/file.md`). Never use relative paths that traverse up the directory tree (e.g., `../../.assets/test.png`, `../other.md`).
103
+ - Use relative paths for all links; never use absolute paths starting with `/`.
104
104
  - No emojis. Lowercase filenames. Target under 6500 words.
105
105
 
106
106
  ### Phase 5: Review the Draft
@@ -158,6 +158,6 @@ If any check fails, revise before continuing.
158
158
 
159
159
  ## References
160
160
 
161
- - [_core-adr-003 - Skill standards](/.xdrs/_core/adrs/principles/003-skill-standards.md)
162
- - [_core-adr-001 - XDRs core](/.xdrs/_core/adrs/principles/001-xdrs-core.md)
163
- - [002-write-xdr skill](/.github/skills/002-write-xdr/SKILL.md)
161
+ - [_core-adr-003 - Skill standards](../../003-skill-standards.md)
162
+ - [_core-adr-001 - XDRs core](../../001-xdrs-core.md)
163
+ - [002-write-xdr skill](../002-write-xdr/SKILL.md)