xdrs-core 0.2.18 → 0.3.1

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

@@ -5,9 +5,9 @@
 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
+- BDR (Business Decision Record): Captures business process, product features, procedures and strategic decisions. Examples: business rules, product policies, customer service, business workflow, control frameworks for regulators for finance, product procedures and manuals, KYC requirements, business requirements in general
+- ADR (Architectural Decision Record): Wider architectural and technical decisions. Examples: how big topics relate to each other, system contexts, overview without realy deciding on details, integration patterns, overarching topics, corporate wide practices, corporate systems, external and internal partners etc
+- EDR (Engineering Decision Record): captures engineering details about how to implement things. Examples: specific tools and libraries selection, framework usage, best practices on coding, testing, quality, project structure, pipelines etc
 
 Collectively, these are referred to as XDRs.
 
@@ -67,9 +67,9 @@ All XDRs MUST follow this template
 ## 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)
+What is the problem we are trying to solve? Who is being impacted? (<3 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?"]
+Question: 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
 

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

@@ -0,0 +1,109 @@
+---
+name: 002-write-xdr
+description: >
+  Creates a new XDR (Decision Record) interactively: selects type, scope, subject, and writes a focused, conflict-checked decision document.
+  Activate this skill when the user asks to create, add, or write a new XDR, ADR, BDR, or EDR.
+metadata:
+  author: flaviostutz
+  version: "1.0"
+---
+
+## Overview
+
+Guides the creation of a well-structured XDR by following the standards in `_core-adr-001`, researching existing records for conflicts, and iterating until the document is concise and decision-focused.
+
+## Instructions
+
+### Phase 1: Understand the Decision
+
+1. Read `.xdrs/index.md` to discover all active scopes and their canonical indexes.
+2. Read `.xdrs/_core/adrs/principles/001-xdr-standards.md` in full to internalize structure rules, mandatory language, and the XDR template.
+3. Ask the user (or infer from context) the topic of the decision. Do NOT proceed to Phase 2 without a clear topic.
+
+### Phase 2: Select Type, Scope, and Subject
+
+**Type** — choose exactly one based on the nature of the decision:
+- **BDR**: business process, product policy, strategic rule, operational procedure
+- **ADR**: system context, integration pattern, overarching architectural choice
+- **EDR**: specific tool/library, coding practice, testing strategy, project structure
+
+**Scope** — use `_local` unless the user explicitly names another scope.
+
+**Subject** — pick one from the allowed list for the chosen type (from `001-xdr-standards`):
+- 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** — format: `[scope]-[type]-[next available number]`
+- Scan `.xdrs/[scope]/[type]/` for the highest existing number in that scope+type and increment by 1.
+- Never reuse numbers from deleted XDRs.
+
+### Phase 3: Choose the Title
+
+Choose a title that clearly states the question this XDR answers, not the answer itself. The title should let a reader know at a glance what decision scope this record covers.
+
+- Good: "Package manager for Node.js projects", "Phone marketing procedures", "Integration patterns for systems connectivity"
+- Avoid: "Use pnpm", "We chose pnpm", or overly vague titles like "Tooling decisions"
+
+### Phase 4: Research Related XDRs
+
+1. Read all existing XDRs relevant to the topic across all scopes listed in `.xdrs/index.md`.
+2. Identify decisions that already address the topic (full or partial overlap).
+3. Note decisions that might conflict with the intended outcome.
+4. Collect XDR IDs and file paths for cross-references.
+
+### Phase 5: Write the First Draft
+
+Use the mandatory template from `001-xdr-standards`:
+
+```
+# [scope]-[type]-[number]: [Short Title]
+
+## Context and Problem Statement
+[4 lines max: background, who is impacted, and the explicit question being answered]
+
+## Decision Outcome
+
+**[Chosen Option Title]**
+[One sentence: what is the decision]
+
+### Implementation Details
+[Rules, specifics, examples — under 100 lines]
+
+## Considered Options (if meaningful options exist)
+
+## Conflicts (mandatory if conflicts found in Phase 3)
+
+## References (optional)
+```
+
+Mandatory rules to apply while drafting:
+- Use mandatory language ("must", "always", "never") only for hard requirements; use advisory language ("should", "recommended") for guidance.
+- Do not duplicate content already in referenced XDRs — link instead.
+- No emojis. Lowercase filenames.
+- Target under 100 lines total; 200 lines max for complex decisions.
+
+### Phase 6: Review the Draft
+
+Check every item before finalizing:
+
+1. **Length**: Is it under 100 lines? Trim verbose explanations. Move detailed skills to a separate file and link.
+2. **Originality**: Does every sentence add value that cannot be found in a generic web search? Remove obvious advice. Keep only the project-specific decision.
+3. **Clarity**: Is the chosen option unambiguous? Is the "why" clear in one reading?
+4. **Conflicts section**: Is it present and filled if Phase 3 found any conflicts?
+5. **Index entries**: Will the new XDR be added to `[scope]/[type]/index.md` and `.xdrs/index.md`?
+
+If any check fails, revise and re-run this phase before proceeding.
+
+### Phase 7: Write Files
+
+1. Create the XDR file at `.xdrs/[scope]/[type]/[subject]/[number]-[short-title].md`.
+2. Add an entry to `.xdrs/[scope]/[type]/index.md` (create the file if it does not exist).
+3. Add or verify the scope entry in `.xdrs/index.md`.
+
+### Constraints
+
+- MUST follow the XDR template from `001-xdr-standards` exactly.
+- MUST NOT add personal opinions or general best-practice content not tied to a decision.
+- MUST NOT create an XDR that duplicates a decision already captured in another XDR — extend or reference instead.
+- MUST keep scope `_local` unless the user explicitly states otherwise.

package/AGENTS.md

@@ -13,9 +13,12 @@
    - Analyse your work against the XDRs and ensure implementation decisions follow guidelines and patterns
    - Fix any issues
 
-4. **Do not perform git operations unless explicitelly asked**
+4. **Document decisions as XDRs when appropriate**
+   - Check if what is being performed shouldn't be documented as an XDR in _local scope (because the decision has potential to be reused in the future or the topic is complex and would benefit from a document for clarity). Create or update existing documents accordingly.
+
+5. **Do not perform git operations unless explicitelly asked**
    - The developer should be in control of possible destructive operations on the workspace
 
-Check for additional instructions on [AGENTS-LOCAL.md](AGENTS-LOCAL.md).
+Check for additional instructions on [AGENTS.local.md](AGENTS.local.md).
 
 **This AGENTS.md file was created with xdrs-core and shouldn't be changed**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "xdrs-core",
-  "version": "0.2.18",
+  "version": "0.3.1",
   "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",
@@ -20,12 +20,11 @@
     "bin/npmdata.js"
   ],
   "dependencies": {
-    "npmdata": "^0.16.0"
+    "npmdata": "^0.18.12"
   },
   "npmdata": {
     "sets": [
       {
-        "package": "xdrs-core",
         "selector": {
           "files": [
             "AGENTS.md",
@@ -47,7 +46,6 @@
         }
       },
       {
-        "package": "xdrs-core",
         "selector": {
           "files": [
             ".xdrs/index.md"
@@ -56,7 +54,7 @@
         "output": {
           "path": ".",
           "gitignore": false,
-          "unmanaged": true,
+          "managed": false,
           "keepExisting": true
         }
       }