xdrs-core 0.20.1 → 0.21.1

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

@@ -17,7 +17,7 @@ How should XDRs be structured and organized across types, teams, and scopes?
 
 Provides clear ownership by scope, predictable navigation, and reusable decisions that work well with AI agents by keeping files small and focused.
 
-### Implementation Details
+### Details
 
 Decision Records can be of different kinds, depending on the nature of the decision:
 - 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.
 - Make it clear if an instruction is mandatory or advisory.
   - Mandatory language: "must", "always", "never", "required", "mandatory"
   - Advisory language: "should", "recommended", "advised", "preferably", "possibly", "optionally"
+- 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/`).
 - ALWAYS use the following folder structure for XDR documents:
-  `.xdrs/[scope]/[type]/[subject]/[number]-[short-title].md`
+  `[xdrs-root]/[scope]/[type]/[subject]/[number]-[short-title].md`
+  where `[xdrs-root]` is the XDR root folder (default: `.xdrs/`).
 - ALWAYS ignore symlinks paths. NEVER create or update documents inside symlinked folders.
 - **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.
 - Optional supporting artifacts under the same subject:
-  - `.xdrs/[scope]/[type]/[subject]/researches/[number]-[short-title].md`
-  - `.xdrs/[scope]/[type]/[subject]/skills/[number]-[skill-name]/SKILL.md`
-  - `.xdrs/[scope]/[type]/[subject]/articles/[number]-[short-title].md`
-  - `.xdrs/[scope]/[type]/[subject]/plans/[number]-[short-title].md`
+  - `[xdrs-root]/[scope]/[type]/[subject]/researches/[number]-[short-title].md`
+  - `[xdrs-root]/[scope]/[type]/[subject]/skills/[number]-[skill-name]/SKILL.md`
+  - `[xdrs-root]/[scope]/[type]/[subject]/articles/[number]-[short-title].md`
+  - `[xdrs-root]/[scope]/[type]/[subject]/plans/[number]-[short-title].md`
 - 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.
   - `_core-adr-002` defines XDR standards (document writing)
   - `_core-adr-003` defines skill standards
@@ -50,14 +52,14 @@ Collectively, these are referred to as XDRs.
   - `_core-adr-007` defines plan standards
 - 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.
 - 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.
-  - XDRs in the subject root use `.xdrs/[scope]/[type]/[subject]/.assets/`
-  - Articles use `.xdrs/[scope]/[type]/[subject]/articles/.assets/`
-  - Research uses `.xdrs/[scope]/[type]/[subject]/researches/.assets/`
-  - Skills use `.xdrs/[scope]/[type]/[subject]/skills/[number]-[skill-name]/.assets/`
+  - XDRs in the subject root use `[xdrs-root]/[scope]/[type]/[subject]/.assets/`
+  - Articles use `[xdrs-root]/[scope]/[type]/[subject]/articles/.assets/`
+  - Research uses `[xdrs-root]/[scope]/[type]/[subject]/researches/.assets/`
+  - Skills use `[xdrs-root]/[scope]/[type]/[subject]/skills/[number]-[skill-name]/.assets/`
 - **Scopes:** 
   - Short name that defines a group or a package of xdrs
   - examples: `business-x`, `business-y`, `team-43`, `_core`
-  - `_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`.
+  - `_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 higher-positioned scopes. Shared root `index.md` files MUST NOT include an explicit link to `_local`, because `_local` remains workspace-local and is not distributed with shared packages. Readers, tools, and agents SHOULD still try the default workspace-local path `_local/index.md` when it exists, even without a root-index link. Documents in non-`_local` scopes MUST NEVER link to any document inside `_local`; documents inside `_local` MAY link to other documents inside `_local`.
   - **Types:** `adrs`, `bdrs`, `edrs`
   - there can exist sufixes to the standard scope names (e.g: `business-x-mobileapp`, `business-y-servicedesk`)
 - **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.
     - `governance`: Engineering governance, risk controls, and compliance mechanics.
       - Examples: dependency governance, approval policies, mandatory quality checks.
 - Never use emojis
-- **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.
+- **Links:** Use relative paths for all links; never use absolute paths starting with `/`.
 - **Indexes**
   - 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.
-  - 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.
+  - 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.
   - Canonical index requirements:
     - Organize XDR documents by subject for easier navigation
     - Add a short description of what this scope is about (responsibilities, general worries, teams involved, link to discussion process, etc)
     - 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.
     - 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"
-  - 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)`).
+  - 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)`).
   - Always verify if indexes are up to date after making changes
 - **Scope index**
-  - Each scope folder must maintain an `index.md` file at `.xdrs/[scope]/index.md`.
+  - Each scope folder must maintain an `index.md` file at `[xdrs-root]/[scope]/index.md`.
   - 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.
   - 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.
   - 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.
   - 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.
   - 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.
 
-**Folder structure examples:**
+**Folder structure examples** (using the default `.xdrs/` root):
 - `.xdrs/business-x/edrs/devops/003-required-development-workflow.md`
 - `.xdrs/business-x/adrs/controls/010-security-and-secrets-management.md`
 - `.xdrs/_core/edrs/devops/001-multi-repo.md`
@@ -153,8 +155,8 @@ subject/
 ## References
 
 - [_core-adr-002 - XDR standards](002-xdr-standards.md) - Standards for writing individual XDR decision documents
-- [001-lint skill](/.xdrs/_core/adrs/principles/skills/001-lint/SKILL.md) - Skill for reviewing code changes against XDRs
-- [002-write-xdr skill](/.xdrs/_core/adrs/principles/skills/002-write-xdr/SKILL.md) - Skill for creating a new XDR following this standard
+- [001-lint skill](skills/001-lint/SKILL.md) - Skill for reviewing code changes against XDRs
+- [002-write-xdr skill](skills/002-write-xdr/SKILL.md) - Skill for creating a new XDR following this standard
 - [_core-adr-003 - Skill standards](003-skill-standards.md)
 - [_core-adr-004 - Article standards](004-article-standards.md)
 - [_core-adr-006 - Research standards](006-research-standards.md)

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

@@ -15,7 +15,7 @@ XDR framework elements (types, scopes, subjects, folder structure) are defined i
 
 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.
 
-### Implementation Details
+### Details
 
 - 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.
 - 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
 |---|---|---|
 | `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]`. |
 | `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. |
-| `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`. |
-| `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. |
+| `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`. |
+| `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. |
 | `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. |
 | `metadata` | No | Arbitrary key-value map for additional properties not defined by this spec. |
 
@@ -42,23 +42,23 @@ XDR documents are the authoritative policy for their scope, type, and subject. T
     ---
     name: _core-adr-002-xdr-standards
     description: Defines how XDR documents should be written. Use when writing or reviewing any XDR.
-    applied-to: All XDR scopes
-    valid-from: 2026-06-01
+    applyTo: All XDR scopes
+    validFrom: 2026-06-01
     metadata:
       author: example-org
     ---
     ```
 - 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.
 - 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.
-  - 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.
-  - Check `applied-to:` next to determine whether the decision fits the current codebase, system, workflow, or audience.
+  - 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.
+  - Check `applyTo:` next to determine whether the decision fits the current codebase, system, workflow, or audience.
   - Check the decision context and implementation details last to determine any additional boundaries, exceptions, or qualifiers that metadata alone cannot express.
 - 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.
 - **XDR Id:** [scope]-[type]-[xdr number] (numbers are scoped per type+scope combination and must not be reused within that combination; always use lowercase)
   - Types in IDs: `adr`, `bdr`, `edr`
   - 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.
 - Decisions MUST be concise and reference other XDRs to avoid duplication.
-- 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.
+- 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.
 - 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.
 - 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.
 - Conflict handling applies to XDR documents:
@@ -81,8 +81,8 @@ All XDRs MUST follow this template
 ---
 name: [scope]-[type]-[number]-[short-title]
 description: [What this decision is about and when to use it]
-applied-to: [Optional. Contexts this decision applies to, under 40 words]
-valid-from: [Optional. ISO date YYYY-MM-DD from when enforcement begins]
+applyTo: [Optional. Contexts this decision applies to, under 40 words]
+validFrom: [Optional. ISO date YYYY-MM-DD from when enforcement begins]
 license: [Optional. SPDX license expression]
 metadata:
   [optional-key]: [optional-value]
@@ -104,7 +104,7 @@ Question: In the end, state explicitly the question that needs to be answered. E
 
 [Short description of implementation details for the chosen path]
 
-### Implementation Details
+### Details
 
 [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)]
 
@@ -137,8 +137,8 @@ Question: In the end, state explicitly the question that needs to be answered. E
 
 **Examples:**
 - Frontmatter examples:
-  - `valid-from: 2026-03-01`
-  - `applied-to: JavaScript projects`
+  - `validFrom: 2026-03-01`
+  - `applyTo: JavaScript projects`
 
 **XDR ID Examples:**
 - `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
 ## References
 
 - [_core-adr-001 - XDRs core](001-xdrs-core.md) - Framework elements: types, scopes, subjects, folder structure
-- [001-lint skill](/.xdrs/_core/adrs/principles/skills/001-lint/SKILL.md) - Skill for reviewing code changes against XDRs
-- [002-write-xdr skill](/.xdrs/_core/adrs/principles/skills/002-write-xdr/SKILL.md) - Skill for creating a new XDR following this standard
+- [001-lint skill](skills/001-lint/SKILL.md) - Skill for reviewing code changes against XDRs
+- [002-write-xdr skill](skills/002-write-xdr/SKILL.md) - Skill for creating a new XDR following this standard
 - [_core-adr-003 - Skill standards](003-skill-standards.md)
 - [_core-adr-004 - Article standards](004-article-standards.md)
 - [_core-adr-006 - Research standards](006-research-standards.md)

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

@@ -21,7 +21,7 @@ Skills follow the [agentskills](https://agentskills.io/specification) open forma
 
 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.
 
-### Implementation Details
+### Details
 
 **Automation gradient**
 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
 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.
 - 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.
 - 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.
-- 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.
+- 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.
 - 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.
 
 Place a skill under the XDR type that matches the nature of the activity the skill performs:
@@ -116,7 +116,7 @@ Rules:
 - For simple structure, flow, layout, or relationship indications, `SKILL.md` SHOULD prefer plain Markdown, tables, or ASCII art instead of external assets.
 - 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.
 - Keep `SKILL.md` under 6500 words. Move lengthy reference material to `references/`.
-- 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`).
+- Use relative paths for all links; never use absolute paths starting with `/`.
 - Always use lowercase file names.
 - Never use emojis in skill content.
 

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

@@ -17,14 +17,14 @@ How should articles be structured and organized to provide useful views over XDR
 
 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.
 
-### Implementation Details
+### Details
 
 - 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.
 - 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.
 - Articles must reference the XDRs, Research documents, and Skills they synthesize. Never duplicate decision content; link back to the authoritative sources.
 - Articles may serve as indexes, combining related artifacts on a specific topic into a single navigable document.
 - 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.
-- 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.
+- 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.
 - 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.
 - 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`.
 - 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.]
 - [_core-adr-001 - XDRs core](001-xdrs-core.md)
 - [_core-adr-003 - Skill standards](003-skill-standards.md)
 - [_core-adr-006 - Research standards](006-research-standards.md)
-- [004-write-article skill](/.xdrs/_core/adrs/principles/skills/004-write-article/SKILL.md) - Step-by-step instructions for creating a new article
+- [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

@@ -17,7 +17,7 @@ Question: How should semantic versioning be used when publishing or versioning a
 
 XDR packages must use semantic versioning so the package version communicates the expected upgrade impact on consuming teams and projects.
 
-### Implementation Details
+### Details
 
 - Package versions MUST follow `MAJOR.MINOR.PATCH`.
 - 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

@@ -17,7 +17,7 @@ Question: How should research documents be structured and organized so they comm
 
 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.
 
-### Implementation Details
+### Details
 
 - Research is evidence and exploration, not the adopted decision. When a research document and an XDR disagree, the XDR takes precedence.
 - `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
 - [_core-adr-001 - XDRs core](001-xdrs-core.md)
 - [_core-adr-003 - Skill standards](003-skill-standards.md)
 - [_core-adr-004 - Article standards](004-article-standards.md)
-- [005-write-research skill](/.xdrs/_core/adrs/principles/skills/005-write-research/SKILL.md) - Step-by-step instructions for creating a research document
+- [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

@@ -17,7 +17,7 @@ How should plans be structured and organized so they provide clear guidance for
 
 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.
 
-### Implementation Details
+### Details
 
 - Plans describe a problem (why), what we will do to solve the problem, and the approach and activities needed to solve it (how).
 - 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
 - [_core-adr-001 - XDRs core](001-xdrs-core.md) - Framework elements: types, scopes, subjects, folder structure
 - [_core-adr-004 - Article standards](004-article-standards.md) - Companion artifact type for synthetic views
 - [_core-adr-006 - Research standards](006-research-standards.md) - Companion artifact type for exploratory evidence
-- [006-write-plan skill](/.xdrs/_core/adrs/principles/skills/006-write-plan/SKILL.md) - Step-by-step instructions for creating a new plan
+- [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

@@ -7,17 +7,17 @@ description: Extends xdr-standards with a numbered rule format for XDR documents
 
 ## Context and Problem Statement
 
-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.
+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.
 
 Question: How should an XDR document expose strong or individually referenceable rules or policies so they stay explicit, stable, and easy to cite?
 
 ## Decision Outcome
 
-**Numbered rule blocks inside Implementation Details with a canonical citation syntax**
+**Numbered rule blocks inside Details with a canonical citation syntax**
 
-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.
+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.
 
-### Implementation Details
+### Details
 
 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.
 
@@ -72,7 +72,7 @@ Documents and skills that cite a rule must use the exact dot-notation form: `[xd
 
 * (REJECTED) **Free-form prose rules with section anchors** — Use markdown heading anchors as citation targets.
   * 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.
-* (CHOSEN) **Numbered rule blocks inside Implementation Details** — Prefix each rule heading with a two-digit sequence number and use dot-notation for citations.
+* (CHOSEN) **Numbered rule blocks inside Details** — Prefix each rule heading with a two-digit sequence number and use dot-notation for citations.
   * Reason: Minimal addition to the existing XDR template, stable identifiers independent of heading text, and fully compatible with `_core-adr-002-xdr-standards`.
 
 ## References

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

@@ -17,23 +17,23 @@ same decision system.
   record the adopted direction. They are the central policy artifact of the framework for the
   scope and topic they cover. Three decision record types exist: **ADR** for architectural and
   technical decisions, **BDR** for business and operational decisions, and **EDR** for engineering
-  implementation decisions. See [_core-adr-001](/.xdrs/_core/adrs/principles/001-xdrs-core.md).
+  implementation decisions. See [_core-adr-001](../001-xdrs-core.md).
 - **Research** captures exploration before or around a decision: constraints, findings, options,
   pros, and cons. Research supports elaboration, discussion, and updates,
   but it is not the final rule. A single Research document may inform multiple downstream ADRs,
   BDRs, or EDRs. If Research and an XDR disagree, the XDR wins. See
-  [_core-adr-006](/.xdrs/_core/adrs/principles/006-research-standards.md).
+  [_core-adr-006](../006-research-standards.md).
 - **Skills** describe how to execute work under the constraints of the decisions. They add the
   procedural detail that XDRs intentionally avoid. A Skill may be used by a human, an AI agent, or
   both. Skills are task-based, should end in a verifiable outcome, and are only mandatory when a
-  policy such as an XDR makes them mandatory. See [_core-adr-003](/.xdrs/_core/adrs/principles/003-skill-standards.md).
+  policy such as an XDR makes them mandatory. See [_core-adr-003](../003-skill-standards.md).
 - **Articles** are synthetic views, like this one. They explain a topic across multiple XDRs,
   Research documents, and Skills, helping readers understand the system without making new
-  decisions. See [_core-adr-004](/.xdrs/_core/adrs/principles/004-article-standards.md).
+  decisions. See [_core-adr-004](../004-article-standards.md).
 - **Plans** describe a problem, a proposed solution, and the approach and activities needed to
   solve it. They have a clear start and end and a well-defined scope. Plans are ephemeral: they
   must be deleted after full implementation, with lasting outputs captured as Decisions, Skills,
-  Articles, or other artifacts. See [_core-adr-007](/.xdrs/_core/adrs/principles/007-plan-standards.md).
+  Articles, or other artifacts. See [_core-adr-007](../007-plan-standards.md).
 - **Indexes and folder structure** are the discovery layer. They do not make decisions by
   themselves, but they determine how people and agents find the right artifacts, how scopes
   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
 
 ### Guidelines
 
-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:
+Follow [_core-adr-001](../001-xdrs-core.md) and [_core-adr-002](../002-xdr-standards.md) strictly. Key rules:
 
 - Use **mandatory language** (`must`, `never`, `required`) for non-negotiable rules and
   **advisory language** (`should`, `recommended`) for guidance.
@@ -157,13 +157,13 @@ Follow [_core-adr-001](/.xdrs/_core/adrs/principles/001-xdrs-core.md) and [_core
 - **New subject** — create the subject folder under the existing scope+type path. Add an
   allowed subject or use `principles` if none fits (propose a new subject via a `_core` ADR).
 - **New research** — add a `researches/[number]-[short-title].md` inside the relevant subject
-  folder, following [_core-adr-006](/.xdrs/_core/adrs/principles/006-research-standards.md).
+  folder, following [_core-adr-006](../006-research-standards.md).
 - **New skill** — add a `skills/[number]-[skill-name]/SKILL.md` inside the relevant subject
-  folder, following [_core-adr-003](/.xdrs/_core/adrs/principles/003-skill-standards.md).
+  folder, following [_core-adr-003](../003-skill-standards.md).
 - **New article** — add an `articles/[number]-[short-title].md` inside the relevant subject
-  folder, following [_core-adr-004](/.xdrs/_core/adrs/principles/004-article-standards.md).
+  folder, following [_core-adr-004](../004-article-standards.md).
 - **New plan** — add a `plans/[number]-[short-title].md` inside the relevant subject
-  folder, following [_core-adr-007](/.xdrs/_core/adrs/principles/007-plan-standards.md).
+  folder, following [_core-adr-007](../007-plan-standards.md).
 
 ### Using XDRs in your own project
 
@@ -181,15 +181,15 @@ Follow [_core-adr-001](/.xdrs/_core/adrs/principles/001-xdrs-core.md) and [_core
 
 ## References
 
-- [_core-adr-001](/.xdrs/_core/adrs/principles/001-xdrs-core.md) - XDR elements: types, scopes, subjects, folder structure
-- [_core-adr-002](/.xdrs/_core/adrs/principles/002-xdr-standards.md) - XDR document standards and mandatory template
-- [_core-adr-003](/.xdrs/_core/adrs/principles/003-skill-standards.md) - Skill standards and co-location rules
-- [_core-adr-004](/.xdrs/_core/adrs/principles/004-article-standards.md) - Article standards
-- [_core-adr-006](/.xdrs/_core/adrs/principles/006-research-standards.md) - Research standards
-- [_core-adr-007](/.xdrs/_core/adrs/principles/007-plan-standards.md) - Plan standards
-- [001-lint skill](/.xdrs/_core/adrs/principles/skills/001-lint/SKILL.md) - Linting code against XDRs
-- [002-write-xdr skill](/.xdrs/_core/adrs/principles/skills/002-write-xdr/SKILL.md) - Writing a new XDR
-- [003-write-skill skill](/.xdrs/_core/adrs/principles/skills/003-write-skill/SKILL.md) - Writing a new skill
-- [004-write-article skill](/.xdrs/_core/adrs/principles/skills/004-write-article/SKILL.md) - Writing a new article
-- [005-write-research skill](/.xdrs/_core/adrs/principles/skills/005-write-research/SKILL.md) - Writing a new research document
-- [_core-adr-005](/.xdrs/_core/adrs/principles/005-semantic-versioning-for-xdr-packages.md) - Semantic versioning rules for XDR packages
+- [_core-adr-001](../001-xdrs-core.md) - XDR elements: types, scopes, subjects, folder structure
+- [_core-adr-002](../002-xdr-standards.md) - XDR document standards and mandatory template
+- [_core-adr-003](../003-skill-standards.md) - Skill standards and co-location rules
+- [_core-adr-004](../004-article-standards.md) - Article standards
+- [_core-adr-006](../006-research-standards.md) - Research standards
+- [_core-adr-007](../007-plan-standards.md) - Plan standards
+- [001-lint skill](../skills/001-lint/SKILL.md) - Linting code against XDRs
+- [002-write-xdr skill](../skills/002-write-xdr/SKILL.md) - Writing a new XDR
+- [003-write-skill skill](../skills/003-write-skill/SKILL.md) - Writing a new skill
+- [004-write-article skill](../skills/004-write-article/SKILL.md) - Writing a new article
+- [005-write-research skill](../skills/005-write-research/SKILL.md) - Writing a new research document
+- [_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

@@ -22,12 +22,12 @@ Performs a structured review of code changes or files against the XDRs in the re
 
 ### Phase 2: XDR Compilation
 
-1. Gather all Decision Records from `.xdrs/index.md` starting from the working directory.
+1. Gather all Decision Records from the XDR root `index.md` (default: `.xdrs/index.md`) starting from the working directory.
    - XDR scopes are controlled by nested folders; some are broad, others domain-specific.
    - Extract frontmatter first to decide whether each XDR should be used for the current review context.
    - All documents present in the collection are considered active.
-   - 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.
-   - Check `applied-to:` second. Keep only XDRs whose stated scope fits the files, systems, or workflows under review.
+   - 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.
+   - Check `applyTo:` second. Keep only XDRs whose stated scope fits the files, systems, or workflows under review.
    - Check the decision text itself last for additional boundaries or exceptions that metadata does not encode.
 2. Filter relevance based on file types, domains, and architectural patterns in scope.
 
@@ -88,7 +88,7 @@ Scope: [scope identifier]
 
 ## References
 
-- [_core-adr-001 - XDRs core](/.xdrs/_core/adrs/principles/001-xdrs-core.md)
-- [_core-adr-002 - XDR standards](/.xdrs/_core/adrs/principles/002-xdr-standards.md)
-- [_core-adr-003 - Skill standards](/.xdrs/_core/adrs/principles/003-skill-standards.md)
+- [_core-adr-001 - XDRs core](../../001-xdrs-core.md)
+- [_core-adr-002 - XDR standards](../../002-xdr-standards.md)
+- [_core-adr-003 - Skill standards](../../003-skill-standards.md)
 

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

@@ -16,7 +16,7 @@ Guides the creation of a well-structured XDR by following the standards in `_cor
 
 ### Phase 1: Understand the Decision
 
-1. Read `.xdrs/index.md` to discover all active scopes and their canonical indexes.
+1. Read the XDR root `index.md` (default: `.xdrs/index.md`) to discover all active scopes and their canonical indexes.
 2. Read `.xdrs/_core/adrs/principles/001-xdrs-core.md` in full to internalize structure rules, mandatory language, and the XDR framework elements.
 3. Read `.xdrs/_core/adrs/principles/002-xdr-standards.md` in full to internalize the XDR template and document writing rules.
 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
 
 ### Phase 4: Research Related XDRs
 
-1. Read all existing XDRs relevant to the topic across all scopes listed in `.xdrs/index.md`.
-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.
+1. Read all existing XDRs relevant to the topic across all scopes listed in the XDR root `index.md`.
+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.
 3. Identify decisions that already address the topic (full or partial overlap).
 4. Note decisions that might conflict with the intended outcome.
 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`:
 
 **Check if the decision requires a structured set of rules:**
 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:
-  - Place each rule as a numbered heading block inside `### Implementation Details`.
+  - Place each rule as a numbered heading block inside `### Details`.
   - Use the format:
     #### [NN]-[short-descriptive-title-in-kebab-case]
     [Rule body with mandatory/advisory language.]
@@ -89,7 +89,7 @@ If the decision defines strong rules or policies that must be stated explicitly,
 **Example of a structured set of rules:**
 
 ```markdown
-### Implementation Details
+### Details
 
 #### 01-data-must-be-encrypted-at-rest
 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
 ---
 name: [scope]-[type]-[number]-[short-title]
 description: [What this decision is about and when to use it]
-applied-to: [Optional. Contexts this decision applies to, under 40 words]
-valid-from: [Optional. ISO date YYYY-MM-DD from when enforcement begins]
+applyTo: [Optional. Contexts this decision applies to, under 40 words]
+validFrom: [Optional. ISO date YYYY-MM-DD from when enforcement begins]
 ---
 
 # [scope]-[type]-[number]: [Short Title]
@@ -121,7 +121,7 @@ valid-from: [Optional. ISO date YYYY-MM-DD from when enforcement begins]
 **[Chosen Option Title]**
 [One sentence: what is the decision - under 30 words]
 
-### Implementation Details
+### Details
 [Rules, applicability boundaries, concise examples, and optional do/don't guidance — under 1300 words]
 
 ## 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]
 ```
 
 Mandatory rules to apply while drafting:
-- Include frontmatter `applied-to:` only when it adds value by narrowing the decision scope; omit it when the decision applies broadly.
-- Include frontmatter `valid-from:` only when there is a specific future enforcement date; omit it when the decision is immediately effective.
-- Keep `applied-to:` under 40 words and use `valid-from:` only with `YYYY-MM-DD` ISO format.
-- 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.
+- Include frontmatter `applyTo:` only when it adds value by narrowing the decision scope; omit it when the decision applies broadly.
+- Include frontmatter `validFrom:` only when there is a specific future enforcement date; omit it when the decision is immediately effective.
+- Keep `applyTo:` under 40 words and use `validFrom:` only with `YYYY-MM-DD` ISO format.
+- 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.
 - Use mandatory language ("must", "always", "never") only for hard requirements; use advisory language ("should", "recommended") for guidance.
 - Do not duplicate content already in referenced XDRs — link instead.
 - 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:
 - Keep exploratory option analysis in a related Research document when it would distract from the final decision text.
 - Prefer plain Markdown, tables, Mermaid.js (sequence, state, activity, entity diagrams), or ASCII art for simple structure, flow, layout, or relationship indications.
 - 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`).
-- 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`).
+- Use relative paths for all links; never use absolute paths starting with `/`.
 - No emojis. Lowercase filenames.
 - Target under 1300 words total; under 2600 words for complex decisions.
 
@@ -152,23 +152,23 @@ Mandatory rules to apply while drafting:
 Check every item before finalizing:
 
 1. **Length**: Is it under 1300 words? Trim verbose explanations. Move detailed skills to a separate file and link.
-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?
+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?
 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.
 4. **Clarity**: Is the chosen option unambiguous? Is the "why" clear in one reading?
 5. **Redundancy**: Is the XDR the primary source for the decision itself, with related documents linked instead of duplicated wherever possible?
 6. **Conflicts section**: Is it present and filled if Phase 3 found any conflicts?
-7. **Index entries**: Will the new XDR be added to `[scope]/[type]/index.md` and `.xdrs/index.md`?
+7. **Index entries**: Will the new XDR be added to `[scope]/[type]/index.md` and the XDR root `index.md`?
 
 If any check fails, revise and re-run this phase before proceeding.
 
 ### Phase 8: Write Files
 
-1. Create the XDR file at `.xdrs/[scope]/[type]/[subject]/[number]-[short-title].md`.
-2. Add an entry to `.xdrs/[scope]/[type]/index.md` (create the file if it does not exist).
-3. Add or verify the scope entry in `.xdrs/index.md`.
+1. Create the XDR file at `[xdrs-root]/[scope]/[type]/[subject]/[number]-[short-title].md` (default root: `.xdrs/`).
+2. Add an entry to `[xdrs-root]/[scope]/[type]/index.md` (create the file if it does not exist).
+3. Add or verify the scope entry in the XDR root `index.md`.
 4. If significant research was produced or already exists, link it from the XDR `## Considered Options` section.
-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.
-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`.
+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.
+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`.
 
 ### Phase 9: Verify Package structure with Lint
 
@@ -191,6 +191,6 @@ If any check fails, revise and re-run this phase before proceeding.
 
 ## References
 
-- [_core-adr-001 - XDRs core](/.xdrs/_core/adrs/principles/001-xdrs-core.md)
-- [_core-adr-002 - XDR standards](/.xdrs/_core/adrs/principles/002-xdr-standards.md)
-- [_core-adr-003 - Skill standards](/.xdrs/_core/adrs/principles/003-skill-standards.md)
+- [_core-adr-001 - XDRs core](../../001-xdrs-core.md)
+- [_core-adr-002 - XDR standards](../../002-xdr-standards.md)
+- [_core-adr-003 - Skill standards](../../003-skill-standards.md)

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

@@ -51,7 +51,7 @@ Quick test:
 
 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.
 2. Read all XDRs relevant to the skill's domain to collect rules and cross-references.
-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.
+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.
 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.
 
 ### Phase 4: Write the SKILL.md
@@ -100,7 +100,7 @@ Rules:
 - 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.
 - Prefer plain Markdown, tables, Mermaid.js (sequence, state, activity, entity diagrams), or ASCII art for simple structure, flow, layout, or relationship indications.
 - 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`).
-- 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`).
+- Use relative paths for all links; never use absolute paths starting with `/`.
 - No emojis. Lowercase filenames. Target under 6500 words.
 
 ### Phase 5: Review the Draft
@@ -158,6 +158,6 @@ If any check fails, revise before continuing.
 
 ## References
 
-- [_core-adr-003 - Skill standards](/.xdrs/_core/adrs/principles/003-skill-standards.md)
-- [_core-adr-001 - XDRs core](/.xdrs/_core/adrs/principles/001-xdrs-core.md)
-- [002-write-xdr skill](/.github/skills/002-write-xdr/SKILL.md)
+- [_core-adr-003 - Skill standards](../../003-skill-standards.md)
+- [_core-adr-001 - XDRs core](../../001-xdrs-core.md)
+- [002-write-xdr skill](../002-write-xdr/SKILL.md)