xdrs-core 0.27.1 → 0.28.1

package/.filedist-package.yml

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

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

@@ -27,6 +27,7 @@ Step-by-step procedural guides for humans and AI agents.
 - [_core-adr-skill-005-write-research](principles/skills/005-write-research/SKILL.md) - **Write Research** — create a new research document
 - [_core-adr-skill-006-write-plan](principles/skills/006-write-plan/SKILL.md) - **Write Plan** — create a new plan document
 - [_core-adr-skill-007-write-presentation](principles/skills/007-write-presentation/SKILL.md) - **Write Presentation** — create Marp slide presentations for XDRS documents
+- [_core-adr-skill-008-write-xdrs-doc](principles/skills/008-write-xdrs-doc/SKILL.md) - **Write XDRS Doc** — router skill; infers document type and delegates to the appropriate authoring skill
 
 ## Articles
 

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

@@ -40,7 +40,7 @@ Policies can be of different kinds, depending on the nature of the decision:
   `[xdrs-root]/[scope]/[type]/[subject]/[number]-[short-title].md`
   where `[xdrs-root]` is the XDRS 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.
+- **Files listed in `.filedist.lock` are external XDRs.** A file whose path appears in the workspace root `.filedist.lock` file was distributed from an external source repository. It must NEVER be modified locally. To change it, submit the change to the source repository and re-extract the updated package. The `.filedist.lock` format is one entry per line: `<relative-path>|<package>|<version>`. A scope is considered external when any of its files appear in `.filedist.lock`, and tools (such as `xdrs-core lint`) will skip external scopes by default. The `.filedist.lock` file can also be used to detect which files changed when bumping an external scope to a newer version: compare the version field in `.filedist.lock` entries before and after the upgrade and diff the affected paths to understand what decisions were added, updated, or removed.
 - Optional supporting artifacts under the same subject:
   - `[xdrs-root]/[scope]/[type]/[subject]/researches/[number]-[short-title].md`
   - `[xdrs-root]/[scope]/[type]/[subject]/skills/[number]-[skill-name]/SKILL.md`

package/.xdrs/_core/adrs/principles/008-xdr-standards-structured.md

@@ -17,7 +17,7 @@ Question: How should a Policy document expose strong or individually referenceab
 
 **Numbered rule blocks inside Details with a canonical citation syntax**
 
-When a Policy 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.
+When a Policy document defines strong rules or policies that must 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.
 
 ### Details
 
@@ -28,11 +28,11 @@ Use this format when the decision defines strong rules or policies that must be
 Each numbered rule must be written as:
 
 ```markdown
-#### [NN]-[short descriptive title with mandatory or advisory language about the enforced policy item]
+#### [NN]-[short-rule-title-in-mandatory-advisory-language-in-kebab-case-<12-words]
 [Body using mandatory or advisory language as defined in _core-adr-policy-001. State the requirement and the situations in which it must or should be followed. Under 500 words.]
 ```
 
-Where `NN` is a two-digit zero-padded sequence number (e.g. `01`, `02`, `12`). Numbers must be unique within the document and must never be reused after a rule is removed.
+Where `NN` is a two-digit zero-padded sequence number (e.g. `01`, `02`, `12`). Numbers must be unique within the document and must never be reused after a rule is removed. The short descriptive title must be in kebab-case (lowercase words separated by hyphens, no spaces or uppercase letters) and express the rule summary contents (e.g.: "43-code-must-be-linted", "12-use-standard-file-structure", "02-log-all-errors-to-mlflow")
 
 Rule bodies must use the mandatory or advisory language terms defined in `_core-adr-policy-001`:
 
@@ -44,31 +44,31 @@ Rule bodies must use the mandatory or advisory language terms defined in `_core-
 When another document or skill cites a specific rule, it must use the following dot-notation:
 
 ```
-policy-name.[NN-Short descriptive title as written in the heading]
+policy-name.NN-short-rule-title-in-kebab-case
 ```
 
 Examples:
 
-- `_core-adr-policy-008-policy-standards-structured.[01-Always use numbered rules for strong or referenceable policies]`
-- `_local-bdr-policy-003-data-retention-policy.[02-Purge schedule for PII]`
+- `_core-adr-policy-008-policy-standards-structured.01-always-use-numbered-rules-for-strong-or-referenceable-policies`
+- `_local-bdr-policy-003-data-retention-policy.02-purge-schedule-for-pii`
 
-The `policy-name` must match the `name` field in the frontmatter of the source document exactly. The rule identifier inside the brackets must match the heading text exactly, including the two-digit prefix.
+The `policy-name` must match the `name` field in the frontmatter of the source document exactly. The rule identifier after the dot must match the heading text exactly, including the two-digit prefix.
 
-#### 01-Always use numbered rules for strong or referenceable policies
+#### 01-always-use-numbered-rules-for-strong-or-referenceable-policies
 
 Numbered rule blocks must be added to a Policy when the decision defines strong rules or policies that must be stated explicitly as stable items, or when there is a clear need for other documents, skills, or agents to cite individual rules by identifier. Adding numbered rules only for cosmetic organization is not recommended. Standard Policy documents that do not define strong rule sets and are not expected to be cited at the rule level should follow `_core-adr-policy-002-policy-standards` without this structured format.
 
-#### 02-Rule numbering must be stable
+#### 02-rule-numbering-must-be-stable
 
 Rule numbers must never be reused within the same document. When a rule is removed, its number becomes permanently retired for that document. Gaps in the sequence are expected and must not be filled by renumbering remaining rules, as existing citations depend on number stability.
 
-#### 03-Rule body must use normative language
+#### 03-rule-body-must-use-normative-language
 
 Every rule body must contain at least one mandatory or advisory language term as defined in `_core-adr-policy-001`. Rule bodies without normative language must not be published, as they fail to communicate whether compliance is required or recommended.
 
-#### 04-Citations must use exact identifiers
+#### 04-citations-must-use-exact-identifiers
 
-Documents and skills that cite a rule must use the exact dot-notation form: `policy-name.[NN-Heading text as written]`. Prose paraphrases such as "see rule 3" or "the third rule in that Policy" must not be used as citations, because they are ambiguous and break when rules are reordered or reworded.
+Documents and skills that cite a rule must use the exact dot-notation form: `policy-name.NN-short-rule-title-in-kebab-case`. Prose paraphrases such as "see rule 3" or "the third rule in that Policy" must not be used as citations, because they are ambiguous and break when rules are reordered or reworded.
 
 ## Considered Options
 

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

@@ -0,0 +1,234 @@
+---
+marp: true
+paginate: true
+---
+
+# XDRS Framework
+
+A structured system for capturing, organizing, and distributing architectural, business, and engineering decisions
+
+---
+
+## Context
+
+Teams accumulate decisions across architecture, engineering, and business domains.
+
+Without structure, decisions are:
+- Buried in wikis, tickets, or chat threads
+- Mixed with rationale, plans, and how-to guides
+- Invisible to AI agents and future contributors
+
+---
+
+## Problem
+
+A standard Decision Record combines too many concerns in one file:
+
+| Concern | Job |
+|---------|-----|
+| Why we decided | Rationale / Research |
+| What we decided | Policy (the rule) |
+| How to implement it | Plan |
+| How to apply it daily | Skill |
+| Overview for readers | Article |
+
+Mixing these makes decisions hard to search, update, and apply.
+
+---
+
+## Solution: Separate Artifact Types
+
+XDRS splits the concerns into focused, linkable documents:
+
+- **Policy** — the authoritative decision (ADR / BDR / EDR)
+- **Research** — exploration, options, evidence
+- **Skill** — step-by-step execution procedure
+- **Article** — synthetic overview linking multiple artifacts
+- **Plan** — ephemeral execution plan, deleted after implementation
+
+---
+
+## Policies — the Source of Truth
+
+The central artifact. Answers a concrete question and records the adopted direction.
+
+Three types:
+- **ADR** — architectural and technical decisions
+- **BDR** — business and operational decisions
+- **EDR** — engineering implementation decisions
+
+If Research and a Policy disagree, **the Policy wins**.
+
+---
+
+## Research
+
+Captures exploration **before or around** a decision.
+
+- Constraints, findings, options, pros, cons
+- Supports elaboration and discussion — not a rule
+- One Research document may inform multiple downstream Policies
+- Lives beside the Policy in `researches/`
+
+---
+
+## Skills
+
+Describe **how to execute** work under the constraints of a decision.
+
+- Add procedural detail that Policies intentionally avoid
+- Used by humans, AI agents, or both
+- Task-based, end in a verifiable outcome
+- Only mandatory when a Policy makes them mandatory
+
+---
+
+## Articles
+
+Synthetic views that **explain a topic** across multiple Policies, Research, and Skills.
+
+- Help readers understand the system without making new decisions
+- Do not replace the source of truth
+- Useful for onboarding and cross-cutting topics
+
+---
+
+## Plans
+
+Describe a problem, proposed solution, and implementation approach.
+
+- Clear start and end, well-defined scope
+- **Ephemeral**: deleted after full implementation
+- Lasting outputs are captured as Policies, Skills, or Articles
+
+---
+
+## How They Differ at a Glance
+
+| Artifact | Central question |
+|----------|-----------------|
+| Policy | What did we decide? |
+| Research | What did we learn while evaluating options? |
+| Skill | How do we carry out work under this decision? |
+| Article | How do these artifacts fit together for a reader? |
+| Plan | What are we going to do, why, and how? |
+
+---
+
+## Lifecycle
+
+```
+Explore  →  Decide  →  Execute  →  Explain  →  Distribute
+Research    Policy      Skill       Article     Scopes / Indexes
+```
+
+Research usually appears **before** a decision.
+The Policy marks the **adopted outcome**.
+Skills appear when the decision must be **executed repeatedly**.
+Articles appear when the **ecosystem around the decision** needs explanation.
+
+---
+
+## Folder Structure
+
+```
+.xdrs/
+  [scope]/
+    [type]/          # adrs | bdrs | edrs
+      [subject]/
+        [N]-[title].md        ← Policy
+        researches/
+        skills/[N]-[name]/SKILL.md
+        articles/
+        plans/
+        .assets/              ← slides, diagrams
+```
+
+- **Scope** — ownership domain (e.g. `_core`, `team-43`)
+- **Type** — ADR / BDR / EDR
+- **Subject** — topic category (e.g. `principles`, `application`)
+
+---
+
+## Scope Precedence
+
+The root `.xdrs/index.md` lists all scope indexes.
+
+Scopes listed **later override** those listed earlier.
+
+```
+_core         ← base rules (broadest)
+my-platform   ← platform-specific overrides
+_local        ← project-specific overrides (narrowest)
+```
+
+---
+
+## Applying a Policy
+
+Before treating a Policy as a rule, check in order:
+
+1. **Valid** — is the policy active?
+2. **Applied to** — does the current context match the scope?
+3. **Decision text** — do the context and exceptions allow this case?
+
+Only decisions that pass all three checks should be enforced.
+
+---
+
+## Getting Started
+
+```bash
+# 1. Install
+npm install xdrs-core   # or pnpm add xdrs-core
+
+# 2. Bootstrap
+npx xdrs-core
+
+# 3. Start writing with your AI agent
+# "Create an ADR about our decision to use Python for AI projects."
+```
+
+This creates `AGENTS.md` and `.xdrs/index.md` with the `_core` scope pre-loaded.
+
+---
+
+## Extending XDRS
+
+| Goal | Action |
+|------|--------|
+| New scope | Create `.xdrs/[scope]/[type]/index.md`, add to root index |
+| New subject | Add subject folder under scope+type path |
+| New research | Add `researches/[N]-[title].md` |
+| New skill | Add `skills/[N]-[name]/SKILL.md` |
+| Distribute a scope | Pack `.xdrs/[scope]/` and publish to an npm registry |
+
+---
+
+## Distributing Across Teams
+
+- Pack `.xdrs/[scope]/` with `pnpm pack`
+- Publish to public or internal npm registry
+- Consumers install the package and run `npx xdrs-core extract`
+- `filedist` tracks managed files; `_local` overrides are preserved
+- Run `npx xdrs-core check` to verify files are in sync
+
+---
+
+# Summary
+
+- XDRS separates concerns: Policy, Research, Skill, Article, Plan
+- Policies are the source of truth; all other artifacts support them
+- Scopes and indexes make decisions discoverable and overridable
+- AI agents consult XDRS before every request via `AGENTS.md`
+
+---
+
+# References
+
+- [XDRS Overview article](../001-xdrs-overview.md)
+- [_core-adr-policy-001 - XDRS core](../../001-xdrs-core.md)
+- [_core-adr-policy-002 - Policy standards](../../002-policy-standards.md)
+- [_core-adr-policy-003 - Skill standards](../../003-skill-standards.md)
+- [_core-adr-policy-004 - Article standards](../../004-article-standards.md)
+- [_core-adr-policy-009 - Presentation standards](../../009-presentation-standards.md)

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

@@ -181,7 +181,7 @@ Follow [_core-adr-policy-001](../001-xdrs-core.md) and [_core-adr-policy-002](..
 1. **Install** — add the scope package as a dependency and run `npx xdrs-core extract` (or
    `pnpm exec xdrs-core extract`) to unpack XDRS files into `.xdrs/` in your workspace.
 2. **Pins and upgrades** — update the npm dependency version to pull in the latest decisions
-   for a scope. The `filedist` mechanism tracks managed files in `.filedist` and keeps
+   for a scope. The `filedist` mechanism tracks managed files in `.filedist.lock` and keeps
   `.xdrs/index.md` in `keepExisting` mode so local edits are preserved.
 3. **Multi-scope** — list multiple scope packages as dependencies. Edit `.xdrs/index.md` to
    add each scope's canonical index link; place more specific scopes below broader ones.
@@ -192,6 +192,7 @@ Follow [_core-adr-policy-001](../001-xdrs-core.md) and [_core-adr-policy-002](..
 
 ## References
 
+- [Presentation slides](.assets/001-xdrs-overview-slides.md) - Marp slide deck overview of this article
 - [_core-adr-policy-001](../001-xdrs-core.md) - XDRS elements: types, scopes, subjects, folder structure
 - [_core-adr-policy-002](../002-policy-standards.md) - Policy document standards and mandatory template
 - [_core-adr-policy-003](../003-skill-standards.md) - Skill standards and co-location rules

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

@@ -35,7 +35,7 @@ Consult `001-xdrs-core` while making each choice in this phase. The summaries be
 - **EDR**: specific tool/library, coding practice, testing strategy, project structure
 
 **Scope** — use `_local` unless the user explicitly names another scope.
-- If the user names a scope other than `_local`, check the workspace root `.filedist` file. If any file under `.xdrs/[scope]/` appears in `.filedist`, the scope is external and new documents MUST NOT be created there. Inform the user and ask them to choose a non-external scope.
+- If the user names a scope other than `_local`, check the workspace root `.filedist.lock` file. If any file under `.xdrs/[scope]/` appears in `.filedist.lock`, the scope is external and new documents MUST NOT be created there. Inform the user and ask them to choose a non-external scope.
 
 **Subject** — pick one from the allowed list for the chosen type (from `001-xdrs-core`):
 - ADR: `principles`, `application`, `data`, `integration`, `platform`, `controls`, `operations`
@@ -187,7 +187,7 @@ If any check fails, revise and re-run this phase before proceeding.
 - MUST NOT create a Policy that duplicates a decision already captured in another Policy — extend or reference instead.
 - MUST prefer links and short references over repeating the same decision content across related documents.
 - MUST keep scope `_local` unless the user explicitly states otherwise.
-- MUST NOT create documents in external scopes (scopes whose files appear in the workspace root `.filedist`).
+- MUST NOT create documents in external scopes (scopes whose files appear in the workspace root `.filedist.lock`).
 
 ## References
 

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

@@ -36,7 +36,7 @@ Quick test:
 - "How to execute a business process or policy?" → BDR
 
 **Scope** — use `_local` unless the user explicitly names another scope.
-- If the user names a scope other than `_local`, check the workspace root `.filedist` file. If any file under `.xdrs/[scope]/` appears in `.filedist`, the scope is external and new documents MUST NOT be created there. Inform the user and ask them to choose a non-external scope.
+- If the user names a scope other than `_local`, check the workspace root `.filedist.lock` file. If any file under `.xdrs/[scope]/` appears in `.filedist.lock`, the scope is external and new documents MUST NOT be created there. Inform the user and ask them to choose a non-external scope.
 
 **Subject** — pick the most specific match for the chosen type (required list per type is in `_core-adr-policy-001`):
 - ADR subjects: `principles`, `application`, `data`, `integration`, `platform`, `controls`, `operations`
@@ -131,11 +131,9 @@ If any check fails, revise before continuing.
 - MUST consult `001-xdrs-core` as the canonical source for every core element definition, especially type, scope, subject, numbering, naming, and placement.
 - MUST NOT create a skill that duplicates an existing one — extend or reference it instead.
 - MUST keep scope `_local` unless the user explicitly states otherwise.
-- MUST NOT create documents in external scopes (scopes whose files appear in the workspace root `.filedist`).
+- MUST NOT create documents in external scopes (scopes whose files appear in the workspace root `.filedist.lock`).
 - MUST include a References section linking to `003-skill-standards`.
 
-## Examples
-
 **Input**: "Create a skill to help debug CI pipelines"
 - Type: EDR (engineering workflow)
 - Scope: `_local`

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

@@ -41,7 +41,7 @@ Do NOT proceed to Phase 1 until you have at minimum a clear **topic** and **audi
 Consult `001-xdrs-core` while making each choice in this phase. The summaries below are orientation only; when any detail is unclear, the standard decides.
 
 **Scope** — use `_local` unless the user explicitly names another scope.
-- If the user names a scope other than `_local`, check the workspace root `.filedist` file. If any file under `.xdrs/[scope]/` appears in `.filedist`, the scope is external and new documents MUST NOT be created there. Inform the user and ask them to choose a non-external scope.
+- If the user names a scope other than `_local`, check the workspace root `.filedist.lock` file. If any file under `.xdrs/[scope]/` appears in `.filedist.lock`, the scope is external and new documents MUST NOT be created there. Inform the user and ask them to choose a non-external scope.
 
 **Type** — match the type of the XDRS elements the article primarily synthesizes (`adrs`, `bdrs`, or `edrs`).
 If the topic spans multiple types, use `adrs`. Use the same rules as `002-write-policy` Phase 2:
@@ -140,11 +140,9 @@ Rules to apply while drafting:
 - MUST consult `001-xdrs-core` as the canonical source for every core element definition, especially type, scope, subject, numbering, naming, and placement.
 - MUST follow the article template and placement rules from `004-article-standards`.
 - MUST keep scope `_local` unless the user explicitly states otherwise.
-- MUST NOT create documents in external scopes (scopes whose files appear in the workspace root `.filedist`).
+- MUST NOT create documents in external scopes (scopes whose files appear in the workspace root `.filedist.lock`).
 - MUST defer to active and applicable Policies when article synthesis conflicts with them.
 
-## References
-
 - [_core-adr-policy-004 - Article standards](../../004-article-standards.md)
 - [_core-adr-policy-006 - Research standards](../../006-research-standards.md)
 - [_core-adr-policy-001 - XDRS core](../../001-xdrs-core.md)

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

@@ -36,7 +36,7 @@ If the answers from Phase 1 leave scope, type, or subject ambiguous, use `vscode
 Consult `001-xdrs-core` while making each choice in this phase. The summaries below are orientation only; when any detail matters, the standard decides.
 
 **Scope** — use `_local` unless the user explicitly names another scope.
-- If the user names a scope other than `_local`, check the workspace root `.filedist` file. If any file under `.xdrs/[scope]/` appears in `.filedist`, the scope is external and new documents MUST NOT be created there. Inform the user and ask them to choose a non-external scope.
+- If the user names a scope other than `_local`, check the workspace root `.filedist.lock` file. If any file under `.xdrs/[scope]/` appears in `.filedist.lock`, the scope is external and new documents MUST NOT be created there. Inform the user and ask them to choose a non-external scope.
 
 **Type** — match the type of decision this research supports (`adrs`, `bdrs`, or `edrs`). Use the same rules as `002-write-policy` Phase 2:
 - **BDR**: business process, product policy, strategic rule, operational procedure
@@ -278,6 +278,5 @@ If any check fails, revise before continuing.
 - MUST consult `001-xdrs-core` as the canonical source for every core element definition, especially type, scope, subject, numbering, naming, and placement.
 - MUST follow the research template and section-goal rules from `006-research-standards`.
 - MUST keep scope `_local` unless the user explicitly states otherwise.
-- MUST NOT create documents in external scopes (scopes whose files appear in the workspace root `.filedist`).
+- MUST NOT create documents in external scopes (scopes whose files appear in the workspace root `.filedist.lock`).
 - MUST keep the document as research rather than turning it into a final decision.
-ing it into a final decision.

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

@@ -33,7 +33,7 @@ Guides the creation of a well-structured plan document by following `_core-adr-p
 Consult `001-xdrs-core` while making each choice in this phase. The summaries below are orientation only; when any detail is unclear, the standard decides.
 
 **Scope** — use `_local` unless the user explicitly names another scope.
-- If the user names a scope other than `_local`, check the workspace root `.filedist` file. If any file under `.xdrs/[scope]/` appears in `.filedist`, the scope is external and new documents MUST NOT be created there. Inform the user and ask them to choose a non-external scope.
+- If the user names a scope other than `_local`, check the workspace root `.filedist.lock` file. If any file under `.xdrs/[scope]/` appears in `.filedist.lock`, the scope is external and new documents MUST NOT be created there. Inform the user and ask them to choose a non-external scope.
 
 **Type** — match the type of the Policies the plan primarily implements or relates to (`adrs`, `bdrs`, or `edrs`).
 - **BDR**: business process, product policy, strategic rule, operational procedure
@@ -164,4 +164,4 @@ Rules to apply while drafting:
 - MUST follow the plan template and section-goal rules from `007-plan-standards`.
 - MUST consult `001-xdrs-core` as the canonical source for every core element definition, especially type, scope, subject, numbering, naming, and placement.
 - MUST keep scope `_local` unless the user explicitly states otherwise.
-- MUST NOT create documents in external scopes (scopes whose files appear in the workspace root `.filedist`).
+- MUST NOT create documents in external scopes (scopes whose files appear in the workspace root `.filedist.lock`).

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

@@ -0,0 +1,46 @@
+---
+name: _core-adr-skill-008-write-xdrs-doc
+description: >
+  Use when writing documents such as decisions, policies, skills, procedures, research, plans, articles, or presentations.
+  Activate this skill when the user asks to create or write any XDRS element.
+metadata:
+  author: flaviostutz
+  version: "1.0"
+---
+
+## Overview
+
+Routes the request to the appropriate XDRS authoring skill based on the type of document the user wants to create. Reads the target skill at runtime and follows its instructions in full.
+
+## Instructions
+
+### Phase 1: Infer Document Type
+
+1. Infer the target document type from the user's request and context using the mapping below. Do not ask the user unless the type is genuinely ambiguous after reading the request.
+   - **Policy** (ADR/BDR/EDR) — user wants to record a decision, rule, standard, guideline, or architectural/business/engineering policy
+   - **Skill** — user wants to create an agent skill, SKILL.md, or reusable workflow instruction
+   - **Research** — user wants to produce a study, investigation, evidence-based analysis, or IMRAD-style document
+   - **Plan** — user wants to create an execution plan, project plan, roadmap, or milestone document
+   - **Article** — user wants to create a guide, overview, or synthetic document that combines multiple XDRS elements
+   - **Presentation** — user wants to create slides or a Marp deck for an existing XDRS document
+
+2. If the type cannot be confidently inferred, ask the user one focused question: *"What type of XDRS document do you want to create — Policy, Skill, Research, Plan, Article, or Presentation?"* Wait for the answer before proceeding.
+
+### Phase 2: Load and Follow Target Skill
+
+Read the full content of the skill file for the inferred type, then follow all its phases and instructions exactly as if that skill had been activated directly.
+
+| Document type | Skill file to read and follow |
+|---|---|
+| Policy (ADR / BDR / EDR) | `.xdrs/_core/adrs/principles/skills/002-write-policy/SKILL.md` |
+| Skill | `.xdrs/_core/adrs/principles/skills/003-write-skill/SKILL.md` |
+| Article | `.xdrs/_core/adrs/principles/skills/004-write-article/SKILL.md` |
+| Research | `.xdrs/_core/adrs/principles/skills/005-write-research/SKILL.md` |
+| Plan | `.xdrs/_core/adrs/principles/skills/006-write-plan/SKILL.md` |
+| Presentation | `.xdrs/_core/adrs/principles/skills/007-write-presentation/SKILL.md` |
+
+### Constraints
+
+- MUST read the full target SKILL.md before proceeding — do not rely on summaries or prior knowledge of the target skill.
+- MUST follow all phases of the target skill from Phase 1 onward; do not skip any phase.
+- MUST NOT create documents of a type not listed in the routing table above.

package/README.md

@@ -166,7 +166,7 @@ Multiple scope packages can be combined in the same workspace by listing them as
 The published package exposes the `xdrs-core` CLI.
 
 - Bootstrap or extract managed XDRS files with the existing `filedist`-backed commands such as `npx -y xdrs-core extract` and `npx -y xdrs-core check`.
-- Lint a Policy tree with `npx -y xdrs-core lint .`. By default, scopes whose files are listed in the workspace root `.filedist` file are treated as external and skipped; use `--all` to include them.
+- Lint a Policy tree with `npx -y xdrs-core lint .`. By default, scopes whose files are listed in the workspace root `.filedist.lock` file are treated as external and skipped; use `--all` to include them.
 
 The `lint` command reads `./.xdrs/**` from the given workspace path and checks common consistency rules, including:
 

package/lib/lint.js

@@ -64,7 +64,7 @@ function printHelp() {
   console.log('Usage: xdrs-core lint [options] [path]\n');
   console.log('Lint the XDRS tree rooted at [path] when [path] contains an index.md, or at [path]/.xdrs by default.');
   console.log('\nOptions:');
-  console.log('  --all    Check all files, including files from external scopes distributed via .filedist (default: skip external scopes)');
+  console.log('  --all    Check all files, including files from external scopes distributed via .filedist.lock (default: skip external scopes)');
   console.log('\nAll other commands continue to be delegated to the bundled filedist CLI.');
 }
 
@@ -991,7 +991,7 @@ function isExternalScopeLink(resolvedPath, xdrsRoot, externalScopes) {
   if (parts.length === 0 || !parts[0]) return false;
   const scopeName = parts[0];
 
-  // Treat as external if explicitly listed via .filedist OR if the scope directory
+  // Treat as external if explicitly listed via .filedist.lock OR if the scope directory
   // doesn't exist locally (e.g. hasn't been extracted from an external package yet)
   return externalScopes.has(scopeName) || !existsDirectory(path.join(xdrsRoot, scopeName));
 }
@@ -1192,7 +1192,7 @@ function existsFile(filePath) {
 }
 
 function loadFiledist(repoRoot) {
-  const filedistPath = path.join(repoRoot, '.filedist');
+  const filedistPath = path.join(repoRoot, '.filedist.lock');
   if (!existsFile(filedistPath)) {
     return new Set();
   }

package/lib/lint.test.js

@@ -91,7 +91,7 @@ test('skips external scopes by default and checks them when ignoreExternal is fa
       'See [Missing](002-missing.md).',
       ''
     ].join('\n'),
-    '.filedist': '.xdrs/extscope/adrs/principles/001-ext.md|some-package|1.0.0\n',
+    '.filedist.lock': '.xdrs/extscope/adrs/principles/001-ext.md|some-package|1.0.0\n',
   });
 
   const defaultResult = lintWorkspace(workspaceRoot);
@@ -160,7 +160,7 @@ test('skips entire external scope when only some of its files are in filedist',
       'See [Missing](003-missing.md).',
       ''
     ].join('\n'),
-    '.filedist': '.xdrs/extscope/adrs/principles/001-ext.md|some-package|1.0.0\n',
+    '.filedist.lock': '.xdrs/extscope/adrs/principles/001-ext.md|some-package|1.0.0\n',
   });
 
   const result = lintWorkspace(workspaceRoot);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "xdrs-core",
-  "version": "0.27.1",
+  "version": "0.28.1",
   "description": "A framework to structure, compile and distribute Architectural (ADR), Business (BDR), and Engineering (EDR) decision records contents so that AI agents and humans can reliably find and use them with hierarchical scopes and controlled rollout in the format of distributable versioned packages.",
   "repository": {
     "type": "git",