xdrs-core 0.27.1 → 0.28.0

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/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

@@ -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/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/package.json

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