xdrs-core 0.4.2 → 0.6.0

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

@@ -10,3 +10,19 @@ Foundational standards, principles, and guidelines.
 
 - [_core-adr-001](principles/001-xdr-standards.md) - **XDR standards** (includes XDR template)
 - [_core-adr-003](principles/003-skill-standards.md) - **Skill standards**
+- [_core-adr-004](principles/004-article-standards.md) - **Article standards**
+
+## Skills
+
+Step-by-step procedural guides for humans and AI agents.
+
+- [001-lint](principles/skills/001-lint/SKILL.md) - **Lint** — review code and files against XDRs
+- [002-write-xdr](principles/skills/002-write-xdr/SKILL.md) - **Write XDR** — create a new Decision Record
+- [003-write-skill](principles/skills/003-write-skill/SKILL.md) - **Write Skill** — create a new skill package
+- [004-write-article](principles/skills/004-write-article/SKILL.md) - **Write Article** — create a new article document
+
+## Articles
+
+Synthetic views combining XDRs and Skills around a specific topic.
+
+- [_core-article-001](principles/articles/001-xdrs-overview.md) - **XDRs Overview** (objective, structure, getting started, guidelines, extension, usage)

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

@@ -138,3 +138,5 @@ Question: In the end, state explicitly the question that needs to be answered. E
 ## References
 
 - [001-lint skill](skills/001-lint/SKILL.md) - Skill for reviewing code changes against XDRs
+- [_core-adr-003 - Skill standards](003-skill-standards.md)
+- [_core-adr-004 - Article standards](004-article-standards.md)

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

@@ -2,9 +2,11 @@
 
 ## Context and Problem Statement
 
-AI agents benefit from reusable, discoverable prompt packages that encode specific expertise or behaviors. Without a standard, these "skills" accumulate inconsistently across repositories, making them hard to find, validate, or share.
+Teams and AI agents benefit from reusable, discoverable procedural packages that encode specific expertise or behaviors. Without a standard, these "skills" accumulate inconsistently across repositories, making them hard to find, validate, or share.
 
-How should skills be authored, structured, and organized within a project so that they are consistent, LLM-friendly, and easy to discover?
+A skill may describe a procedure performed exclusively by a human today but that is expected to be partially or fully automated by an AI agent in the future. Defining skills in a single, shared format from the start allows them to evolve along that automation gradient without restructuring.
+
+How should skills be authored, structured, and organized within a project so that they are consistent, readable by humans and LLMs alike, and easy to discover?
 
 ## Decision Outcome
 
@@ -12,10 +14,20 @@ How should skills be authored, structured, and organized within a project so tha
 
 Skills follow the [agentskills](https://agentskills.io/specification) open format and live inside the XDR subject folder under a `skills/` sub-directory. Each skill occupies its own numbered package folder, mirroring the XDR numbering convention.
 
+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
 
-**Relation with XDRs**
-Skills are procedures, XDRs are guardrails and decisions.
+**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:
+- Human reads and follows each step manually.
+- Human delegates some steps to an AI assistant.
+- An AI agent executes the skill autonomously.
+
+Write instructions so that each step is unambiguous and self-contained. Avoid implicit knowledge that only a human or only an AI would have.
+
+**Relation with XDRs and Articles**
+Skills are procedures, XDRs are guardrails and decisions, and Articles are synthetic views that combine information from multiple XDRs and Skills.
 Always create links back and forth between skills <-> XDRs as a reference.
 
 Place a skill under the XDR type that matches the nature of the activity the skill performs:
@@ -109,3 +121,4 @@ skills-ref validate .xdrs/[scope]/[type]/[subject]/skills/[number]-[skill-name]
 - [agentskills/agentskills repository](https://github.com/agentskills/agentskills)
 - [skills-ref validation library](https://github.com/agentskills/agentskills/tree/main/skills-ref)
 - [_core-adr-001 - XDR standards](001-xdr-standards.md)
+- [_core-adr-004 - Article standards](004-article-standards.md)

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

@@ -0,0 +1,79 @@
+# _core-adr-004: Article standards
+
+## Context and Problem Statement
+
+As the number of XDRs and Skills grows, navigating and understanding related decisions across subjects and types becomes difficult. Without a structured format for synthetic documentation, teams create ad-hoc documents that drift from the actual decisions over time.
+
+How should articles be structured and organized to provide useful views over XDRs and Skills without replacing them as the source of truth?
+
+## Decision Outcome
+
+**Subject-level synthetic documents co-located with XDRs**
+
+Articles are Markdown documents placed inside a subject folder alongside decision records. Placing articles within a subject keeps them close to the decisions and skills they reference.
+
+### Implementation Details
+
+- Articles are views, not decisions. They summarize and synthesize content from XDRs 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 must reference the XDRs and Skills they synthesize. Never duplicate decision content; link back to the authoritative sources.
+- Articles may serve as indexes, combining related DRs and Skills on a specific topic into a single navigable document.
+- Articles must remain consistent with the XDRs and Skills they reference. When a referenced XDR or Skill changes, the article must be reviewed and updated.
+- Place an article in the subject folder that best matches its topic. If an article spans more than one subject, place it in `principles`.
+- Always use lowercase file names.
+- Never use emojis in article content.
+- Articles should be kept under 150 lines. Move detailed content to referenced XDRs or Skills.
+
+**Folder layout**
+
+```
+.xdrs/[scope]/[type]/[subject]/
+  articles/
+    [number]-[short-title].md
+```
+
+Examples:
+- `.xdrs/_local/adrs/principles/articles/001-onboarding-guide.md`
+- `.xdrs/business-x/bdrs/product/articles/002-checkout-flow-overview.md`
+- `.xdrs/business-x/bdrs/principles/articles/003-cross-domain-overview.md`  ← spans multiple subjects
+
+**Article numbering**
+
+- Each article has a number unique within its `scope/type/subject/articles/` namespace.
+- Determine the next number by checking the highest number already present in that namespace.
+- Never reuse numbers of deleted articles. Gaps in the sequence are expected and allowed.
+
+**Article template**
+
+All articles MUST follow this template:
+
+```markdown
+# [scope]-article-[number]: [Short Title]
+
+## Overview
+
+[Brief description of what this article covers and its intended audience. (<3 lines)]
+
+## Content
+
+[Synthetic text combining and explaining the topic. Use links to Decision Records and Skills
+when referencing an information from those documents.]
+
+## References
+
+- [XDR id or Skill name](relative/path/to/file.md) - Brief description of relevance
+```
+
+## Considered Options
+
+* (REJECTED) **Inline summaries inside XDR index files** - Keeps everything in one place but clutters the navigation indexes.
+  * Reason: Index files should remain lean navigation aids; mixing synthesis into them hurts readability and makes updates harder.
+* (REJECTED) **Separate documentation repository** - Removes drift risk but decouples docs from decisions.
+  * Reason: Increases maintenance burden and makes it easy for articles to go stale relative to the XDRs they reference.
+* (CHOSEN) **Subject-level articles folder co-located with XDRs** - Keeps articles alongside the decision records and skills they reference, with `principles` as the fallback for cross-subject articles.
+  * Reason: Easy to discover, consistent with where skills are placed, and clearly distinct from the decision records themselves.
+
+## References
+
+- [_core-adr-001 - XDR standards](001-xdr-standards.md)
+- [_core-adr-003 - Skill standards](003-skill-standards.md)
+- [004-write-article skill](skills/004-write-article/SKILL.md) - Step-by-step instructions for creating a new article

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

@@ -0,0 +1,138 @@
+# _core-article-001: XDRs Overview
+
+## Overview
+
+This article introduces XDRs (Decision Records), explains their purpose and design, and guides
+teams through adopting, extending, and distributing them. It is an entry point for anyone new to
+the framework and links out to the authoritative Decision Records for full details.
+
+## Content
+
+### What are XDRs?
+
+XDRs are structured Markdown documents that capture decisions made by teams. Three types exist:
+
+- **ADR (Architectural Decision Record)** — architectural and technical decisions: system context,
+  integration patterns, overarching corporate practices.
+- **BDR (Business Decision Record)** — business process, product strategy, compliance, and
+  operational decisions.
+- **EDR (Engineering Decision Record)** — engineering implementation details: library choices,
+  tooling standards, coding practices.
+
+Collectively they are called XDRs. See [_core-adr-001](../001-xdr-standards.md) for the full
+definition and mandatory template.
+
+### Objective
+
+As organizations grow, decisions accumulate across teams and domains. Without a consistent
+structure, AI agents cannot reliably locate the right decision for a given context, and humans
+struggle to maintain hundreds of documents. XDRs solve both problems by defining:
+
+- A predictable folder hierarchy that any agent can navigate.
+- Small, focused files (target under 100 lines) that are fast for LLMs to read.
+- Scope and subject grouping that limits the search space.
+- A root index as a single discovery entry point.
+
+### How it works
+
+Every XDR lives at a fixed path:
+
+```
+.xdrs/[scope]/[type]/[subject]/[number]-[short-title].md
+```
+
+**Scopes** represent ownership domains (e.g. `_core`, `business-x`, `team-43`). `_local` is
+reserved for project-specific decisions that must not be shared externally; it always sits last
+in `.xdrs/index.md` so its decisions override all others.
+
+**Types** are `adrs`, `bdrs`, or `edrs`.
+
+**Subjects** constrain the domain further (e.g. `principles`, `application`, `devops`, `finance`).
+See [_core-adr-001](../001-xdr-standards.md) for the full allowed subject list per type.
+
+**IDs** follow the pattern `[scope]-[type abbrev]-[number]`, e.g. `_core-adr-001`. Numbers are
+never reused. Gaps in the sequence indicate deleted records.
+
+Each scope+type has a canonical `index.md` that lists all XDRs with short descriptions. A root
+`.xdrs/index.md` points to all canonical indexes and defines scope precedence (later scopes
+override earlier ones).
+
+Skills — step-by-step procedural instructions for humans and AI agents — live in `[subject]/skills/` sub-directories and are
+distributed alongside the XDRs they implement. A skill may start as a human-only procedure and evolve toward partial or full
+AI automation over time, without needing to be restructured. See [_core-adr-003](../003-skill-standards.md).
+
+Articles — like this document — are synthetic views that combine XDRs and Skills for a specific
+topic. They never replace the Decision Records as source of truth. See
+[_core-adr-004](../004-article-standards.md).
+
+### Why it is implemented this way
+
+Key design choices and their rationale:
+
+- **Scoped folders over a flat list** — flat lists become unmanageable at scale; scopes give
+  clear ownership and allow selective adoption.
+- **Small focused files** — LLMs have limited context windows; small files make token budgets
+  predictable and keep decisions unambiguous.
+- **Canonical indexes** — agents read the index first to narrow the set of relevant files, rather
+  than scanning every document.
+- **npm distribution** — versioned packages let teams adopt specific decision sets at a specific
+  version without being forced to take all changes at once.
+- **Skills co-located with XDRs** — keeping procedural guidance next to the decisions it
+  implements reduces drift and makes discovery straightforward for humans and agents alike.
+  Because skills span a spectrum from fully manual to fully automated, co-location also
+  makes it easy to see when a human procedure is ready to be promoted to an agent workflow.
+
+### Getting started
+
+1. Create or open a project workspace.
+2. Run `npx xdrs-core` in the workspace root. This installs:
+   - `AGENTS.md` — instructs AI agents to always consult XDRs.
+   - `AGENTS.local.md` — project-specific agent instructions (editable).
+   - `.xdrs/index.md` — root index (editable, `keepExisting` mode).
+   - `_core` XDRs and skills under `.xdrs/_core/`.
+3. Start a conversation with your AI agent:
+   > Create an ADR about our decision to use Python for AI projects.
+
+### Guidelines
+
+Follow [_core-adr-001](../001-xdr-standards.md) strictly. Key rules:
+
+- Use **mandatory language** (`must`, `never`, `required`) for non-negotiable rules and
+  **advisory language** (`should`, `recommended`) for guidance.
+- Keep XDRs under 100 lines. Move procedural detail to a co-located Skill.
+- Always update the scope+type index and the root index after adding or changing an XDR.
+- Use `_local` scope when a decision is project-specific and must not be shared.
+- Never reuse a number once it has been assigned, even if the XDR is deleted.
+
+### How to extend
+
+- **New scope** — create `.xdrs/[scope]/[type]/index.md` and add it to `.xdrs/index.md`.
+- **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 skill** — add a `skills/[number]-[skill-name]/SKILL.md` inside the relevant subject
+  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](../004-article-standards.md).
+
+### Using XDRs in your own project
+
+1. **Install** — add the scope package as a dependency and run `npx xdrs-core extract` (or
+   `pnpm exec xdrs-core extract`) to unpack XDR 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
+   `AGENTS.local.md` and `.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.
+4. **Verify** — run `npx xdrs-core check` to confirm all managed files are in sync with the
+   installed packages.
+5. **Distribute your own scope** — pack `.xdrs/[scope]/` with `pnpm pack` and publish to an
+   npm registry (public or internal). Pin a tag for prerelease versions.
+
+## References
+
+- [_core-adr-001](../001-xdr-standards.md) - XDR 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
+- [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

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

@@ -0,0 +1,111 @@
+---
+name: 004-write-article
+description: >
+  Creates a new article document following XDR article standards: selects scope, type, subject, and number;
+  then writes a focused synthetic text that combines and links multiple XDRs and Skills around a topic.
+  Activate this skill when the user asks to create, add, or write a new article, guide, or overview document
+  within an XDR project.
+metadata:
+  author: flaviostutz
+  version: "1.0"
+---
+
+## Overview
+
+Guides the creation of a well-structured article by following `_core-adr-004`, researching the XDRs and
+Skills to synthesize, and producing a concise document that serves as a navigable view without duplicating
+decision content.
+
+## Instructions
+
+### Phase 1: Understand the Article Goal
+
+1. Read `.xdrs/_core/adrs/principles/004-article-standards.md` in full to internalize the template,
+   placement rules, numbering rules, and the constraint that articles are views, not decisions.
+2. Identify the topic and intended audience from user input or context. Do NOT proceed without a clear
+   topic.
+
+### Phase 2: Select Scope, Type, and Subject
+
+**Scope** — use `_local` unless the user explicitly names another scope.
+
+**Type** — match the type of the XDRs the article primarily synthesizes (`adrs`, `bdrs`, or `edrs`).
+If the topic spans multiple types, use `adrs`.
+
+**Subject** — pick the subject that best matches the article's topic (see `004-article-standards`).
+If the article spans more than one subject, place it in `principles`.
+
+### Phase 3: Assign a Number and Name
+
+1. List `.xdrs/[scope]/[type]/[subject]/articles/` (create the folder if it does not exist).
+2. Find the highest existing article number in that namespace and increment by 1. Never reuse numbers.
+3. Choose a short lowercase kebab-case title that describes the topic clearly.
+   - Good: `onboarding-guide`, `checkout-flow-overview`, `api-design-principles`
+   - Avoid: `summary`, `notes`, `misc`
+
+### Phase 4: Research XDRs and Skills to Synthesize
+
+1. Read all XDRs and Skills relevant to the article topic across all scopes listed in `.xdrs/index.md`.
+2. Identify the key points a reader needs to understand the topic end-to-end.
+3. Collect XDR IDs and file paths for cross-references. Never copy decision text verbatim; link to it.
+
+### Phase 5: Write the Article
+
+Use the mandatory template from `004-article-standards`:
+
+```
+# [scope]-article-[number]: [Short Title]
+
+## Overview
+
+[Brief description of what this article covers and its intended audience. Under 3 lines.]
+
+## Content
+
+[Synthetic text combining and explaining the topic. Use links to Decision Records and Skills
+when referencing information from those documents. Keep under 150 lines total.]
+
+## References
+
+- [XDR id or Skill name](relative/path/to/file.md) - Brief description of relevance
+```
+
+Rules to apply while drafting:
+
+- Write for the stated audience; avoid jargon unexplained elsewhere.
+- Every factual claim must link back to the authoritative XDR or Skill.
+- Never reproduce decision text verbatim; summarize and link.
+- Keep the article under 150 lines; move detailed content to XDRs or Skills.
+- Use lowercase file names. Never use emojis.
+- If a conflict exists between the article and a Decision Record, note it and defer to the XDR.
+
+### Phase 6: Place and Register
+
+1. Save the file at `.xdrs/[scope]/[type]/[subject]/articles/[number]-[short-title].md`.
+2. Add a link to the article in the canonical index for that scope+type (`.xdrs/[scope]/[type]/index.md`).
+3. Add back-references in the XDRs and Skills that the article synthesizes, under their `## References`
+   section.
+
+## Examples
+
+**Input:** "Write an article about how skills work in this project."
+
+**Expected actions:**
+1. Read `004-article-standards.md`.
+2. Topic: how skills work. Audience: developers new to the project.
+3. Scope: `_local`, type: `adrs`, subject: `principles`.
+4. Scan `.xdrs/_local/adrs/principles/articles/` — no articles exist → number is `001`.
+5. Research `_core-adr-003` and all existing skill SKILL.md files.
+6. Write `.xdrs/_local/adrs/principles/articles/001-skills-overview.md` following the template, linking
+   to `_core-adr-003` and the individual skill files.
+7. Update `.xdrs/_local/adrs/index.md` with a link to the new article.
+8. Add a reference to the article in `_core-adr-003` under `## References`.
+
+## Edge Cases
+
+- **Article vs. XDR confusion** — if the user asks for a document that makes a decision, write an XDR
+  (use the `002-write-xdr` skill), not an article.
+- **Cross-subject topic** — place the article in `principles`, not in any single subject folder.
+- **No existing articles folder** — create it; it is optional in the folder layout.
+- **Conflicting information found** — note the conflict in the article and always defer to the XDR.
+- **Article would exceed 150 lines** — move detailed content to a new Skills or XDR and link back.

package/README.md

@@ -10,6 +10,14 @@ Decision Records capture Architectural (ADR), Business (BDR), and Engineering (E
 
 This project defines a standard for organizing XDRs that satisfies the following requirements.
 
+## XDR elements
+
+Every XDR package contains three types of documents:
+
+- **Decision Records (XDRs)** — Architectural (ADR), Business (BDR), or Engineering (EDR) records that capture a single decision, its rationale, and the rules that follow from it. They are the source of truth.
+- **Skills** — Step-by-step procedural guides that can be followed by humans, AI agents, or both. A skill may start as a fully manual procedure and evolve toward partial or full AI automation over time. Co-located with the XDRs they implement.
+- **Articles** — Synthetic explanatory texts that combine information from multiple XDRs and Skills around a specific topic or audience. They never replace XDRs as source of truth.
+
 ## Getting started
 
 1. Create a new project workspace
@@ -68,19 +76,25 @@ This is especially important for BDRs: because business rules govern decisions t
       index.md                      # canonical index for this scope+type
       [subject]/
         [number]-[short-title].md   # individual decision record
-        skills/                     # optional agent skill packages
+        skills/                     # optional skill packages for humans and AI agents
           [number]-[skill-name]/
             SKILL.md
+        articles/                   # optional synthetic views over XDRs and Skills
+          [number]-[short-title].md
 ```
 
-Types of Decision Records:
+Document types:
 
 - **ADR** - Architectural Decision Record: architectural and technical decisions
 - **BDR** - Business Decision Record: business process and strategy decisions
 - **EDR** - Engineering Decision Record: engineering workflow and tooling decisions
+- **Skills** - Step-by-step procedural guides that can be followed by humans, AI agents, or both. Must comply with Decision Records, but add the execution detail they lack. A skill may start as a fully manual human procedure and evolve incrementally toward partial or full AI automation without being restructured. Co-located with the XDRs they implement inside `skills/` sub-directories.
+- **Articles** - Synthetic views that explain concepts or combine information from multiple Decision Records and Skills into a coherent text for a specific topic or audience. Articles are not the source of truth; Decision Records take precedence when there is a conflict. Useful as navigational indexes that link related DRs and Skills around a specific aspect.
 
 See [.xdrs/index.md](.xdrs/index.md) for the full list of active decision records.
 
+For a deeper overview of XDRs — objective, structure, guidelines, extension, and usage — see the [XDRs Overview article](.xdrs/_core/adrs/principles/articles/001-xdrs-overview.md).
+
 ## Flow: Decision -> Distribution -> Usage
 
 XDRs and skills follow a three-stage lifecycle that keeps decision-making decentralized while allowing controlled adoption across projects.
@@ -108,4 +122,5 @@ Multiple scope packages can be combined in the same workspace by listing them as
     [subject]/                                                        [subject]/
       *.md                                                              *.md
       skills/                                                           skills/
+      articles/                                                         articles/
 ```

package/package.json

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