xdrs-core 0.1.1-beta.0

package/.xdrs/_general/adrs/index.md

@@ -0,0 +1,12 @@
+# general ADRs Index
+
+This index covers cross-business architectural and technical decisions that apply to all scopes. Owned by the platform team. Propose changes via pull request.
+
+This index lists all ADRs for the general scope, organized by subject.
+
+## Principles
+
+Foundational standards, principles, and guidelines.
+
+- [_general-adr-001](principles/001-xdr-standards.md) - **XDR standards** (includes XDR template)
+- [_general-adr-003](principles/003-skill-standards.md) - **Skill standards**

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

@@ -0,0 +1,139 @@
+# _general-adr-001: XDR standards
+
+## Context and Problem Statement
+
+We need a consistent way to capture decisions that scales across scopes and subjects, remains easy to navigate, and works well with AI agents.
+
+Decision Records can be of different kinds, depending on the nature of the decision:
+- ADR (Architectural Decision Record): captures architectural and technical decisions
+- BDR (Business Decision Record): captures business process and strategy decisions
+- EDR (Engineering Decision Record): captures engineering workflow and tooling decisions
+
+Collectively, these are referred to as XDRs.
+
+How should XDRs be structured and organized across types, teams, and scopes?
+
+## Decision Outcome
+
+**Scoped + typed + subject folders**
+
+Provides clear ownership by scope, predictable navigation, and reusable decisions that work well with AI agents by keeping files small and focused.
+
+### Implementation 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.
+- 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"
+- Always the following folder structure:
+  `.xdrs/[scope]/[type]/[subject]/[number]-[short-title].md`
+- **Scopes:** 
+  - examples: `business-x`, `business-y`, `team-43`, `_general`
+  - `_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. When a scope name is not specified, `_local` is the standard scope to use.
+  - **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:
+  - **ADR:** `principles`, `application`, `data`, `integration`, `platform`, `controls`, `operations`
+  - **BDR:** `principles`, `marketing`, `product`, `controls`, `operations`, `organization`, `finance`, `sustainability`
+  - **EDR:** `principles`, `application`, `infra`, `ai`, `observability`, `devops`, `governance`
+- **XDR Id:** [scope]-[type]-[xdr number unique in scope] (the xdr id must be unique among all XDRs of the same type in the different scopes and 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
+- Never use emojis in contents
+- Always use file names with lowercase
+- Avoid using lengthy instructions on the XDR. If there are long and detailed instructions related to the XDR, or instructions that are outside the decision, create another file with a guide. If the guide is small, keep it in the XDR itself.
+- If there is a README.md file in the root of the xdrs folder, always keep it up to date. Never use emojis
+- Keep a canonical index with all XDRs of a certain type+scope in `.xdrs/[scope]/[type]/index.md`
+  - Organize XDRs by subject for easier navigation
+  - 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.
+  - Document decision conflicts in "Conflicts" section for the XDR that is overriding another XDR in other scopes
+  - **Within-scope conflicts:** XDRs within the same type+scope must not conflict. If two XDRs appear to conflict, one should be updated, deprecated, or the conflict resolved through a new XDR.
+  - In the index add a short description of what is this scope about (responsibilities, general worries, teams involved, link to discussion process etc)
+- Outside the scopes, keep an index pointing to all canonical indexes in `.xdrs/index.md`. Add the text "XDRs in scopes listed last override the ones listed first"
+- Always verify if the index is up to date after making changes
+- XDRs should be less than 100 lines long as a rule of thumb
+  - This is important to make them focused on a clear decision
+  - Exceptions can reach 200 lines (templates, more elaborate decision implementations etc)
+
+**XDR template**
+
+All XDRs MUST follow this template
+
+```markdown
+# [scope]-[type]-[number]: [Short Title]
+
+## Context and Problem Statement
+
+[Describe the context, background, or need that led to this decision.
+What is the problem we are trying to solve? Who is being impacted? (~4 lines)
+
+In the end, state explicitly the question that needs to be answered. E.g: "Which platform should I use when implementing an AI agent?"]
+
+## Decision Outcome
+
+**[Chosen Option Title]**
+[Very short description of what is the decision, aligned with the titles on the Considered Options section]
+
+[Short description of implementation details for the chosen path]
+
+### Implementation Details
+
+[Optional section with implementation specifics, rules, examples or impact. This is the answer to the question in the "Context and Problem Statement". (<100 lines)]
+
+## Considered Options
+
+[Optional section present only when there are meaningful options to be discussed.]
+
+* (REJECTED) **Option 1** - Brief description of option 1
+  * Reason: Brief description why this was rejected with important aspects to be re-checked in the case we want to change this decision
+* (CHOSEN) **Option 2** - Brief description of option 2
+  * Reason: Brief description of why this option was accepted, containing the strengths, strategical motivations and it's differential over the other options.
+* (REJECTED) **Option 3** - [same as above, if we have more than 2 options to choose from]
+
+## Conflicts
+
+[If this XDR has conflicts with other scopes, this section is MANDATORY and needs to have an explanation why the conflict is accepted]
+
+* Conflict with [XDR id] (e.g.: adr-business-x-001)
+  * Summary: Brief description of the conflict
+  * Reason to accept: Brief description of why it was decided to accept this conflict, possibly overriding or diverging from the other decision/scopes
+
+## References
+
+[optional section]
+[useful links related to this implementation]
+[links to the discussion (PRs, meetings etc)]
+[links to related skills]
+```
+
+**Examples:**
+- `.xdrs/business-x/edrs/devops/003-required-development-workflow.md`
+- `.xdrs/business-x/adrs/governance/010-security-and-secrets-management.md`
+- `.xdrs/general/adrs/devops/001-multi-repo.md`
+
+**XDR ID Examples:**
+- `business-x-adr-001` (not `ADR-business-x-001` or `business-x-adr-1`)
+- `business-x-edr-042` (not `EDR-BUSINESS-X-042`)
+- `business-x-bdr-007`
+
+## Procedures
+
+1. Choose the correct type (ADR, BDR, EDR), scope, and subject for each new XDR.
+2. Create the XDR using the template in the Implementation Details section above, adapting it for the chosen type and required sections.
+3. Update or create the scope `README.md` with examples if needed.
+4. Add/update the new/updated XDRs to `.xdrs/[scope]/[type]/index.md` and to the main `.xdrs/index.md`
+5. Keep decision texts short and link to other XDRs for shared rules
+
+## Considered Options
+
+* (REJECTED) **Flat list of decisions** - Simple but becomes unmanageable as the number grows.
+  * Reason: Does not scale and makes navigation difficult over time.
+* (REJECTED) **Per-team folders without scope** - Easier ownership but loses organization hierarchy.
+  * Reason: Lacks a clear hierarchy and makes cross-team reuse harder.
+* (CHOSEN) **Scoped + typed + subject folders** - Clear ownership by scope first, then decision type, with predictable navigation and reusable decisions.
+  * Reason: Scales well, supports AI agents with focused files, enables reuse across scopes, and groups all decisions for a given scope together regardless of type.
+
+## References
+
+- [001-xdr-lint skill](skills/001-xdr-lint/SKILL.md) - Skill for reviewing code changes against XDRs

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

@@ -0,0 +1,110 @@
+# _general-adr-003: Skill standards
+
+## 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.
+
+How should skills be authored, structured, and organized within a project so that they are consistent, LLM-friendly, and easy to discover?
+
+## Decision Outcome
+
+**agentskills-compatible skill packages, co-located with XDRs**
+
+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.
+
+### Implementation Details
+
+**Relation with XDRs**
+Skills are procedures, XDRs are guardrails and decisions.
+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:
+- **EDR skills** - engineering workflows, tool usage, coding procedures, implementation how-tos (e.g. how to design a webpage, how to run a CI pipeline, how to debug a service)
+- **ADR skills** - architectural evaluation, pattern compliance checks, technology selection guidance (e.g. how to review an architecture diagram, how to assess API design)
+- **BDR skills** - business process execution, market analysis, operations procedures, business rules
+
+Quick test:
+- "Is the skill about *how to implement or operate* something?" → EDR.
+- "Is the skill about *how to evaluate or decide on* architecture?" → ADR.
+- "Is the skill about *how to execute a business process, policy, or market activity*?" → BDR.
+
+**Folder layout**
+
+```
+.xdrs/[scope]/[type]/[subject]/skills/[number]-[skill-name]/
+    SKILL.md              # required
+    scripts/              # optional: executable scripts the agent may run
+    references/           # optional: detailed reference material
+    assets/               # optional: templates, images, data files
+```
+
+Examples:
+- `.xdrs/general/adrs/principles/skills/001-code-review/SKILL.md`
+- `.xdrs/business-x/edrs/devops/skills/001-ci-pipeline-debug/SKILL.md`
+
+**Skill numbering**
+
+- Each skill has a number unique within its `scope/type/subject/skills/` namespace.
+- Determine the next number by checking the highest number already present in that namespace. Never reuse numbers of deleted skills.
+- Gaps in the sequence are expected and allowed.
+
+**SKILL.md format** (agentskills spec)
+
+```
+---
+name: 001-skill-name      # required: must match the parent directory name exactly; max 64 chars
+description: >            # required: what the skill does AND when to activate it; max 1024 chars
+  Concise explanation of the skill and the situations in which an agent should load it.
+license: <license>        # optional
+metadata:                 # optional: arbitrary key/value pairs
+  author: <team-or-person>
+  version: "1.0"
+compatibility: <env>      # optional: system requirements or intended products
+allowed-tools: <tools>    # optional (experimental): space-delimited pre-approved tools
+---
+
+## Overview
+
+Brief description of the skill goal.
+
+## Instructions
+
+Step-by-step instructions the agent should follow.
+
+## Examples
+
+Concrete input/output examples that illustrate correct behavior.
+
+## Edge Cases
+
+Known gotchas and how to handle them.
+```
+
+Rules:
+- The `name` field must match the parent directory name exactly (e.g., directory `001-code-review` uses `name: 001-code-review`). This preserves agentskills spec compliance while encoding the ordering number.
+- Keep `SKILL.md` under 500 lines. Move lengthy reference material to `references/`.
+- Reference other files with relative paths from the skill root.
+- Always use lowercase file names.
+- Never use emojis in skill content.
+
+**Validation**
+
+Use the [skills-ref](https://github.com/agentskills/agentskills/tree/main/skills-ref) CLI to validate before committing:
+
+```
+skills-ref validate .xdrs/[scope]/[type]/[subject]/skills/[number]-[skill-name]
+```
+
+## Considered Options
+
+* (REJECTED) **Top-level `skills/` directory separate from XDRs** - Decouples skills from the decisions that govern them.
+  * Reason: Breaks the natural association between a decision (XDR) and the skill that implements it; makes navigation harder.
+* (CHOSEN) **agentskills-compatible packages co-located with XDRs** - Standardized format with scoped discovery and clear ownership.
+  * Reason: Reuses proven agentskills tooling, aligns with the existing XDR scope/subject hierarchy, and keeps skills close to the decisions they implement.
+
+## References
+
+- [agentskills specification](https://agentskills.io/specification)
+- [agentskills/agentskills repository](https://github.com/agentskills/agentskills)
+- [skills-ref validation library](https://github.com/agentskills/agentskills/tree/main/skills-ref)
+- [_general-adr-001 - XDR standards](001-xdr-standards.md)

package/.xdrs/_general/adrs/principles/skills/001-xdr-lint/SKILL.md

@@ -0,0 +1,117 @@
+---
+name: 001-xdr-lint
+description: >
+  Reviews code changes or files against applicable XDRs (Decision Records) and reports
+  violations as structured findings. Activate this skill when the user asks to review,
+  lint, or audit code, or when you identify a need to check compliance with XDRs during implementation.
+metadata:
+  author: flaviostutz
+  version: "1.0"
+---
+
+## Overview
+
+Performs a structured review of code changes or files against the XDRs in the repository,
+categorizing findings by severity and type, and reporting them without modifying any code.
+
+## Instructions
+
+### Phase 1: XDR Compilation
+
+1. Gather all Decision Records from `.xdrs/index.md` starting from the working directory.
+   - XDR scopes are controlled by nested folders; some are broad, others domain-specific.
+   - Extract metadata first (status, impact, scope, applicability) to filter relevant XDRs before deep analysis.
+2. Filter relevance based on file types, domains, and architectural patterns in scope.
+
+### Phase 2: Code Analysis
+
+1. Identify changes based on requested scope:
+   - For diffs: run and parse `git diff origin/main`
+   - For files: analyze file contents directly
+   - For services: scan all files in the service directory
+2. Categorize potential findings:
+   - Architecture: violations of structural decisions
+   - Coding Standards: style and pattern violations
+   - Testing: missing or inadequate test coverage
+   - Documentation: missing or outdated documentation
+   - Security: security practice violations
+   - Performance: performance best practice violations
+3. Compile specific, measurable rules from each XDR and compare against the changes.
+4. Prioritize by criticality: Accepted > Proposed; Impact: critical > high > medium > low.
+
+### Phase 3: Review and Judgment
+
+1. Cross-reference each finding against applicable XDRs.
+   - **Drop any finding that cannot be traced to a specific rule in an Accepted XDR.** General good-practice observations, personal opinions, or inferred issues without an explicit XDR backing must not be reported.
+   - Classify as ERROR (mandatory) or WARNING (advisory).
+   - Include: location, description, XDR reference (file + line), suggestion.
+2. Reduce false positives:
+   - Re-evaluate ERROR findings for mandatory language in the XDR ("must", "always", "never", "required", "mandatory"). Drop or downgrade to WARNING if the language is advisory ("should", "recommended", "advised").
+   - Remove findings unrelated to actual changes.
+   - Consolidate duplicates.
+   - Consider context (existing style, legacy sections, etc.).
+3. Judgment criteria (all must be true to keep a finding):
+   - Is the violation explicitly stated in an Accepted XDR? (If no, drop it.)
+   - Is there concrete evidence in the code or diff?
+   - Is the finding actionable?
+   - Would fixing it meaningfully improve compliance with the XDR?
+
+### Phase 4: Reporting
+
+Format each finding as:
+
+```
+>> [ERROR|WARNING] [CATEGORY] filename:line_number: Description
+   - XDR Reference: .xdrs/scope/type/subject/number-title.md:line_number
+   - Rule: Specific rule text from XDR
+   - Severity: [ERROR|WARNING]
+   - Suggestion: Specific action to fix this issue
+   - Context: Why this matters / What to watch for
+```
+
+Full output structure:
+
+```
+=== Code Review Against XDRs ===
+Scope: [scope identifier]
+Files Analyzed: [number]
+Changes: [+X lines, -Y lines]
+
+=== Findings ===
+[findings list]
+
+=== Summary ===
+- Errors Found: [count]
+- Warnings Found: [count]
+- Review Status: [PASS|FAIL]
+
+Affected Files Requiring Changes
+[bullet list of files with issues, linked to specific findings and severity]
+```
+
+### Constraints
+
+- MUST NOT include any text or explanations outside the required output format.
+- MUST NOT edit code. Instruct the user on how to request code changes in suggestions.
+
+## Examples
+
+User: "Review my changes against XDRs"
+Agent action: runs `git diff origin/main`, reads `.xdrs/` hierarchy, filters applicable XDRs,
+produces structured findings report.
+
+User: "Lint the auth service"
+Agent action: scans all files under the auth service directory, applies relevant XDRs,
+produces structured findings report.
+
+## Edge Cases
+
+- If no XDRs apply to the scope, output "No applicable XDRs found" and skip reporting.
+- If `git diff` fails (no git repo, no remote), fall back to analyzing staged or working tree files.
+- If a potential violation is in pre-existing code outside the diff, report it as WARNING only.
+
+## References
+
+- [_general-adr-001 - XDR standards](../../001-xdr-standards.md)
+- [_general-adr-003 - Skill standards](../../003-skill-standards.md)
+

package/.xdrs/_general/edrs/index.md

@@ -0,0 +1,10 @@
+# general EDRs Index
+
+General engineering decisions covering cross-business standards and practices. Applies to all AI coding agents working in any scope. Owned by the platform team. Propose changes via pull request.
+
+## Principles
+
+Foundational standards, principles, and guidelines.
+
+- [_general-edr-001](principles/001-coding-agent-behavior.md) - **AI coding agent behavior**
+

package/.xdrs/_general/edrs/principles/001-coding-agent-behavior.md

@@ -0,0 +1,42 @@
+# _general-edr-001: AI coding agent behavior
+
+## Context and Problem Statement
+
+AI coding agents (such as GitHub Copilot) require clear guidelines about expected behavior to ensure consistency, proper verification of work, and respect for developer workflows.
+
+What behavioral standards should AI coding agents follow when working on code?
+
+## Decision Outcome
+
+**AI agents must follow a defined instruction hierarchy, verify work with automated checks, and defer git operations to developers**
+
+Clear behavior standards ensure consistency through EDR compliance, maintain code quality through automated verification, and respect the developer's role in version control decisions.
+
+### Implementation Details
+
+**Mandatory behaviors for AI coding agents:**
+
+1. **Follow instruction hierarchy when making implementation decisions**
+   1. **Closest AGENTS.md** to the file being changed (search from target directory up to workspace root). Instructions in those files override the global EDRs. If multiple AGENTS.md files exist in the path, merge their instructions; the closest AGENTS.md overrides those farther away.
+   2. **Global EDR** – Follow scope-based precedence defined in [.xdrs/index.md](../../../../index.md). EDRs in scopes listed last override EDRs in scopes listed first.
+
+2. **Verify all work with build, tests and linting before completion**
+   - Check EDRs for workspace tooling: [.xdrs/index.md](../../../../index.md)
+   - Run quality checks in sequence relative to the module directory: `STAGE=dev make build-module`, `make lint-module`, then `make test-module`
+   - Use `make lint-fix` to fix lint issues
+   - Do not run commands outside Makefiles
+
+3. **Verify implementation complies with EDRs**
+   - Review relevant EDRs before marking work complete
+   - Ensure implementation decisions follow EDR guidelines and patterns
+
+4. **Do not perform git operations**
+   - Do not run git commands (add, commit, push, branch creation, etc.)
+   - Inform the developer when work is ready for version control
+
+## Considered Options
+
+* (REJECTED) **Minimal guidance** - Let agents operate with default behavior
+  * Reason: Results in inconsistent code quality, missed verification steps, and developers losing control of git workflow
+* (CHOSEN) **EDR-compliant agents** - Clear behavior standards
+  * Reason: Ensures consistency through EDR compliance, maintains code quality through verification, and respects developer control of version control

package/.xdrs/index.md

@@ -0,0 +1,26 @@
+# XDR Standards Index
+
+This index points to all type- and scope-specific XDR indexes. XDRs (Decision Records) cover Architectural (ADR), Business (BDR), and Engineering (EDR) decisions. Each scope has its own canonical index that lists all XDRs for that scope, organized by subject.
+
+## Scope Indexes
+
+XDRs in scopes listed last override the ones listed first
+
+### ADRs - general
+
+General architectural decisions covering cross-business standards and practices.
+
+[View general ADRs Index](_general/adrs/index.md)
+
+### EDRs - general
+
+General engineering decisions covering cross-business standards and practices.
+
+[View general EDRs Index](_general/edrs/index.md)
+
+---
+
+### _local (reserved)
+
+Project-local XDRs that must not be shared with other contexts. Always keep this scope last so its decisions override or extend all scopes listed above. Add specific `_local` ADR/BDR/EDR index links here when present.
+

package/AGENTS.md

@@ -0,0 +1,18 @@
+# AGENTS.md
+
+**Purpose:** This file is intentionally brief. All project decisions and working instructions are captured as XDRs.
+
+1. **Always consult XDRs before making implementation decisions**
+   - Follow coding agent behavior and decision hierarchy rules in [.xdrs/_general/edrs/principles/001-coding-agent-behavior.md](.xdrs/_general/edrs/principles/001-coding-agent-behavior.md)
+   - Search for XDRs in [.xdrs/index.md](.xdrs/index.md) during design, plan and implementation steps
+   - Follow XDRs as the source of truth for all decisions and procedures
+
+2. **Verify all work with build, tests and linting before completion**
+   - Fix any issues
+
+3. **Verify if implementation complies with XDRs**
+   - Re-analyse your work against the XDRs and ensure implementation decisions follow guidelines and patterns
+
+4. **Do not perform git operations**
+   - Do not run git commands (add, commit, push, branch creation, etc.)
+

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Flavio Stutz
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,111 @@
+# xdr-standards
+
+A standard way to organize Decision Records (XDRs) across scopes, subjects, and teams so that AI agents can reliably query and follow them.
+
+> **Note:** This repository contains a minimum set of standards and very basic set of ADRs that describe the proposed decisions structure. It is intended to be used as a foundation that other projects can reference, extend, or install as a dependency in order to bootstrap and create their own XDRs.
+
+## Objective
+
+Decision Records capture Architectural (ADR), Business (BDR), and Engineering (EDR) decisions. As organizations grow, hundreds of decisions accumulate across teams, levels, and domains. Without a consistent structure, AI agents cannot efficiently locate the right decisions for a given context, and humans cannot maintain or evolve them sustainably.
+
+This project defines a standard for organizing XDRs that satisfies the following requirements.
+
+## Getting started
+
+1. Create a new project workspace
+
+2. On the workspace root folder, run `npx xdrs-core`
+
+   The basic xdrs tooling should be installed in your workspace along with:
+     - AGENTS.md pointing to the XDRs structure
+     - XDR related skills and prompts for Copilot
+
+3. Run a prompt such as:
+
+   > Create an ADR about our decision on using Python for AI related projects. For high volume projects (expected >1000 t/s), an exception can be made on using Golang.
+
+## Requirements
+
+### Multi-scope support
+
+Different teams at different organizational levels make decisions that apply to different audiences. XDRs are organized by scope (e.g. `_general`, `business-x`, `business-y-mobileapp`) so that each team owns its own decision space. Scopes can extend or override decisions from broader scopes, with explicit precedence rules: scopes listed later in an index override those listed earlier.
+
+### Subject grouping
+
+Within each scope and type, decisions are grouped by subject (e.g. `application`, `data`, `platform` for ADRs; `product`, `finance` for BDRs). This keeps related decisions together, improves human navigation, and allows AI agents to narrow their search to the relevant subject folder before reading individual records.
+
+### Extensibility
+
+Over time, decisions from various teams and domains accumulate in a shared workspace. The folder structure `.xdrs/[scope]/[type]/[subject]/` is designed to accommodate new scopes, types, and subjects without reorganizing existing content. A root index at `.xdrs/index.md` points to all canonical scope indexes, and each canonical index is updated incrementally as new XDRs are added.
+
+### Distributability
+
+XDR packages are versioned and distributed via the npm registry. This allows teams to adopt specific decision sets at a specific version, rather than accepting all decisions at once. It avoids "all or nothing" situations when linting or checking adherence to decisions in the context of tech debt management. Teams can pin, upgrade, or override only the scopes that are relevant to them.
+
+### AI-agent friendliness
+
+The folder layout, file naming, and document format are designed so that AI agents can efficiently work with hundreds of decisions:
+
+- Each XDR is a small, focused Markdown file (target under 100 lines), covering one decision.
+- The canonical index per scope and type lists all XDRs with short descriptions, enabling agents to identify relevant records without reading every file.
+- The root index at `.xdrs/index.md` provides a single entry point for discovery.
+- Decisions cross-reference each other by XDR ID rather than duplicating content, keeping individual files concise.
+- Subject folders reduce the search space when a query maps to a known domain.
+
+### Multi-agent framework support
+
+XDRs and skills must be usable by any type of AI agent, not only coding agents (e.g. GitHub Copilot, Cursor, Cline). General-purpose agent frameworks such as LangGraph, CrewAI, AutoGen, and similar orchestration runtimes must be able to consume XDRs without relying on IDE-specific tooling or conventions.
+
+This is especially important for BDRs: because business rules govern decisions that span both technical and non-technical workflows, agents built with any framework must be able to discover, fetch, and apply BDRs programmatically using only standard file-system or HTTP access to Markdown files.
+
+## Structure
+
+```
+.xdrs/
+  index.md                          # root index pointing to all scope indexes
+  [scope]/
+    [type]/                         # adrs | bdrs | edrs
+      index.md                      # canonical index for this scope+type
+      [subject]/
+        [number]-[short-title].md   # individual decision record
+        skills/                     # optional agent skill packages
+          [number]-[skill-name]/
+            SKILL.md
+```
+
+Types of Decision Records:
+
+- **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
+
+See [.xdrs/index.md](.xdrs/index.md) for the full list of active decision records.
+
+## Flow: Decision -> Distribution -> Usage
+
+XDRs and skills follow a three-stage lifecycle that keeps decision-making decentralized while allowing controlled adoption across projects.
+
+### Decision
+
+Each scope manages its own set of XDRs independently. Scope owners discuss and evolve decisions through whatever process fits their team, such as RFCs, pull requests, or architecture review boards. XDRs and skills are authored, reviewed, and merged within the scope's folder in the repository.
+
+### Distribution
+
+Once a set of decisions is ready to share, scope owners pack the relevant `.xdrs/[scope]/` folder into a versioned npm package using a tool such as [npmdata](https://github.com/flaviostutz/npmdata) and publish it to an npm registry, either public or a company-internal one. Versioning gives consumers explicit control over which revision of a scope's decisions they adopt, avoiding situations where a single breaking policy change is forced on all consumers at once.
+
+The same applies to skills: because they live alongside XDRs inside the scope folder, they are included in the same package and published together.
+
+### Usage
+
+A project that wants to follow a scope's decisions adds the corresponding npm package as a regular dependency. Using a tool such as [npmdata](https://github.com/flaviostutz/npmdata), the package contents are unpacked into the project's `.xdrs/` folder at install or update time. Updating the dependency version pulls in the latest XDRs and skills for that scope, keeping the project aligned with the scope owners' current decisions.
+
+Multiple scope packages can be combined in the same workspace by listing them as separate dependencies. Scope precedence (defined in `.xdrs/index.md`) determines which decisions take effect when scopes overlap.
+
+```
+[Scope repo] --> npm publish --> [npm registry] --> npm install --> [Project workspace]
+  .xdrs/[scope]/                  versioned pkg                    .xdrs/[scope]/
+    adrs/ bdrs/ edrs/                                                adrs/ bdrs/ edrs/
+    [subject]/                                                        [subject]/
+      *.md                                                              *.md
+      skills/                                                           skills/
+```

package/bin/npmdata.js

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+
+// DON'T EDIT THIS FILE MANUALLY - this script is generated by "npmdata init" command
+require('npmdata/dist/runner.js').run(__dirname);

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "xdrs-core",
+  "version": "0.1.1-beta.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.",
+  "keywords": [
+    "xdr",
+    "adr",
+    "decision-records",
+    "ai-agents"
+  ],
+  "license": "MIT",
+  "files": [
+    ".xdrs/**",
+    "package.json",
+    "AGENTS.md",
+    "bin/npmdata.js"
+  ],
+  "dependencies": {
+    "npmdata": "^0.6.1-beta.0"
+  },
+  "npmdata": [
+    {
+      "package": "xdrs-core",
+      "outputDir": ".",
+      "files": [
+        "AGENTS.md",
+        ".xdrs/**"
+      ]
+    }
+  ],
+  "bin": "bin/npmdata.js"
+}