xdrs-core 0.47.0 → 0.48.1

package/.xdrs/_core/adrs/principles/skills/{006-write-plan → 006-write-initiative}/SKILL.md

@@ -1,9 +1,9 @@
 ---
-name: 006-write-plan
+name: 006-write-initiative
 description: >
-  Creates a new plan document following XDRS plan standards: selects scope, type, subject, and number;
-  then writes a focused execution plan with problem context, proposed solution, approach, milestones, and deliverables.
-  Activate this skill when the user asks to create, add, or write a plan, project plan, or execution plan within an XDRS project.
+  Creates a new initiative document following XDRS initiative standards: selects scope, type, subject, and number;
+  then writes a focused execution initiative with problem context, proposed solution, approach, milestones, and deliverables.
+  Activate this skill when the user asks to create, add, or write an initiative, plan, project plan, roadmap, or execution plan within an XDRS project.
 metadata:
   author: flaviostutz
   version: "1.0"
@@ -11,24 +11,24 @@ metadata:
 
 ## Overview
 
-Guides the creation of a well-structured plan document by following `_core-adr-policy-007`, consulting `xdrs-core` for every core element definition, researching related Policies and existing plans, and producing a focused execution document that connects to the decisions, research, and skills it relates to.
+Guides the creation of a well-structured initiative document by following `_core-adr-policy-007`, consulting `xdrs-core` for every core element definition, researching related Policies and existing initiatives, and producing a focused execution document that connects to the decisions, research, and skills it relates to.
 
 ## Instructions
 
 ### Phase 0: Scope Placement and Prerequisites Gate — MUST complete before writing
 
 1. Run the scope placement analysis from the shared module at `.xdrs/_core/adrs/principles/skills/.assets/scope-placement.md` to determine and confirm the target scope.
-2. Once the scope is confirmed, run the prerequisites gate from the shared module at `.xdrs/_core/adrs/principles/skills/.assets/prerequisites-gate.md`. Substitute `[DOCUMENT TYPE]` with `plan`.
+2. Once the scope is confirmed, run the prerequisites gate from the shared module at `.xdrs/_core/adrs/principles/skills/.assets/prerequisites-gate.md`. Substitute `[DOCUMENT TYPE]` with `initiative`.
 
-### Phase 1: Understand the Plan Goal
+### Phase 1: Understand the Initiative Goal
 
-1. Read `.xdrs/_core/adrs/principles/007-plan-standards.md` in full to internalize the template, placement rules, numbering rules, and the constraint that plans are ephemeral and must be deleted after implementation.
-2. Read `.xdrs/_core/adrs/principles/001-xdrs-standards.md` in full before defining the plan's core elements. Treat it as the canonical source for how to choose and write type, scope, subject, numbering, naming, and folder placement.
+1. Read `.xdrs/_core/adrs/principles/007-initiative-standards.md` in full to internalize the template, placement rules, numbering rules, and the constraint that initiatives are ephemeral and must be deleted after implementation.
+2. Read `.xdrs/_core/adrs/principles/001-xdrs-standards.md` in full before defining the initiative's core elements. Treat it as the canonical source for how to choose and write type, scope, subject, numbering, naming, and folder placement.
 3. Identify the problem being solved, the proposed solution, and the expected timeline from user input or context. Do NOT proceed without a clear problem statement and proposed solution.
-4. Ask the user clarifying questions to fill any gaps before writing the plan. Use the following rules:
+4. Ask the user clarifying questions to fill any gaps before writing the initiative. Use the following rules:
    - Ask all initial questions in a single batch so the user can answer them together.
    - After receiving the answers, evaluate whether any answer introduces new ambiguity or opens a related topic that requires further clarification. If it does, ask a focused follow-up question (or a small batch of follow-up questions) before proceeding.
-   - Repeat this question-answer loop until you have enough information to write the plan with confidence.
+   - Repeat this question-answer loop until you have enough information to write the initiative with confidence.
    - Typical questions cover: the problem being solved, the proposed solution, the expected timeline, the scope, the key stakeholders, and any known constraints or risks.
    - Do NOT ask questions whose answers are already clear from context.
 
@@ -39,34 +39,34 @@ Consult `001-xdrs-standards` while making each choice in this phase. The summari
 
 **Scope** — confirmed in Phase 0. Follow the external-scope validation in `.xdrs/_core/adrs/principles/skills/.assets/scope-selection.md`.
 
-**Type** — match the type of the Policies the plan primarily implements or relates to (`adrs`, `bdrs`, or `edrs`).
+**Type** — match the type of the Policies the initiative primarily implements or relates to (`adrs`, `bdrs`, or `edrs`).
 - **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, pipelines
 
-**Subject** — pick the subject that best matches the plan's topic (required list per type is in `_core-adr-policy-001`). If the plan spans more than one subject, place it in `principles`.
+**Subject** — pick the subject that best matches the initiative's topic (required list per type is in `_core-adr-policy-001`). If the initiative spans more than one subject, place it in `principles`.
 
 ### Phase 3: Assign a Number and Name
 
-1. List `.xdrs/[scope]/[type]/[subject]/plans/` (create the folder if it does not exist).
-2. Find the highest existing plan number in that namespace and increment by 1. Never reuse numbers.
+1. List `.xdrs/[scope]/[type]/[subject]/initiatives/` (create the folder if it does not exist).
+2. Find the highest existing initiative number in that namespace and increment by 1. Never reuse numbers.
 3. Choose a short lowercase kebab-case title that describes the initiative clearly.
    - Good: `checkout-performance`, `onboarding-redesign`, `api-migration-v2`
-   - Avoid: `plan`, `project`, `misc`
+   - Avoid: `initiative`, `project`, `misc`
 
 ### Phase 4: Research Related Artifacts
 
-1. Read all Policies, Research documents, Skills, and existing Plans relevant to the plan topic across all scopes listed in the Policy root `index.md`.
+1. Read all Policies, Research documents, Skills, and existing Initiatives relevant to the initiative topic across all scopes listed in the Policy root `index.md`.
 2. Evaluate Policy metadata before treating any decision as current context. All documents present in the collection are considered active. `valid-from:` determines the convergence date for adoption, `apply-to:` determines whether the decision fits the intended context, and the decision text defines any remaining boundaries.
-3. Identify Decisions that this plan implements, Research that informs the planning, and any existing Plans that overlap.
+3. Identify Decisions that this initiative implements, Research that informs the planning, and any existing Initiatives that overlap.
 4. Collect artifact IDs and file paths for cross-references.
 
-### Phase 5: Write the Plan
+### Phase 5: Write the Initiative
 
-Use the mandatory template from `007-plan-standards`:
+Use the mandatory template from `007-initiative-standards`:
 
 ```markdown
-# [scope]-[type]-plan-[number]: [Short Title]
+# [scope]-[type]-initiative-[number]: [Short Title]
 
 ## Executive Summary
 
@@ -74,7 +74,7 @@ Use the mandatory template from `007-plan-standards`:
 
 ## Context and Problem Statement
 
-[Required. Why are we executing this plan? What is the impact? Who is impacted? Under 200 words.]
+[Required. Why are we executing this initiative? What is the impact? Who is impacted? Under 200 words.]
 
 ## Proposed Solution
 
@@ -114,22 +114,22 @@ Expected end date: YYYY-MM-DD
 Rules to apply while drafting:
 
 - Focus on the problem, solution, and approach. Avoid bloating with generic project management content.
-- Link to Decisions the plan implements, Research that informs it, and Skills that guide execution.
-- The Expected end date must be in ISO format (YYYY-MM-DD), placed inside the `## Proposed Solution` section, and should not be more than 2 years from the plan creation date.
-- If the plan scope is too large for 2 years, break it into multiple plans.
-- Remember that this plan must be deleted after full implementation. Write it with that ephemeral nature in mind.
+- Link to Decisions the initiative implements, Research that informs it, and Skills that guide execution.
+- The Expected end date must be in ISO format (YYYY-MM-DD), placed inside the `## Proposed Solution` section, and should not be more than 2 years from the initiative creation date.
+- If the initiative scope is too large for 2 years, break it into multiple initiatives.
+- Remember that this initiative must be deleted after full implementation. Write it with that ephemeral nature in mind.
 - For diagrams and non-Markdown assets, follow `_core-adr-policy-020`: prefer plain Markdown tables/lists first, then ASCII art for very simple cases, then Mermaid.js for complex diagrams, then draw.io when Mermaid is insufficient — save as Editable Vector (File → Save As → Editable Vector) and store as `.svg` in the sibling `.assets/` folder.
-- If the plan genuinely needs local images or supporting files, store them in `.xdrs/[scope]/[type]/[subject]/plans/.assets/` and link them using a same-folder relative path (e.g., `.assets/image.png`).
+- If the initiative genuinely needs local images or supporting files, store them in `.xdrs/[scope]/[type]/[subject]/initiatives/.assets/` and link them using a same-folder relative path (e.g., `.assets/image.png`).
 - Use relative paths for all links; never use absolute paths starting with `/`.
 - Use lowercase file names. Never use emojis.
 
 ### Phase 6: Place and Register
 
-1. Save the file at `.xdrs/[scope]/[type]/[subject]/plans/[number]-[short-title].md`.
-2. Add a link to the plan in the canonical index for that scope+type (`.xdrs/[scope]/[type]/index.md`).
-3. Add back-references in the Policies, Research documents, and Skills that the plan relates to, under their `## References` section.
-4. Evaluate whether the scope index at `.xdrs/[scope]/index.md` should be updated to reflect the new plan. If the scope index does not exist, create it following article standards and the scope index rules in `_core-adr-policy-001`.
-5. **Meta-policy compliance**: Run the shared module at `.xdrs/_core/adrs/principles/skills/.assets/meta-policy-compliance.md`. Substitute `[DOCUMENT]` with `plan`.
+1. Save the file at `.xdrs/[scope]/[type]/[subject]/initiatives/[number]-[short-title].md`.
+2. Add a link to the initiative in the canonical index for that scope+type (`.xdrs/[scope]/[type]/index.md`).
+3. Add back-references in the Policies, Research documents, and Skills that the initiative relates to, under their `## References` section.
+4. Evaluate whether the scope index at `.xdrs/[scope]/index.md` should be updated to reflect the new initiative. If the scope index does not exist, create it following article standards and the scope index rules in `_core-adr-policy-001`.
+5. **Meta-policy compliance**: Run the shared module at `.xdrs/_core/adrs/principles/skills/.assets/meta-policy-compliance.md`. Substitute `[DOCUMENT]` with `initiative`.
 
 ### Phase 7: Verify with Lint
 
@@ -140,29 +140,29 @@ Follow the lint verification steps in `.xdrs/_core/adrs/principles/skills/.asset
 **Input:** "Create a plan for migrating our API to v2."
 
 **Expected actions:**
-1. Read `007-plan-standards.md`.
+1. Read `007-initiative-standards.md`.
 2. Topic: API v2 migration. Scope: `_local`.
 3. Type: `adrs` (architectural). Subject: `application`.
 4. Research related Policies about API design and integration patterns.
-5. Draft the plan with clear problem, solution, milestones, and expected end date.
+5. Draft the initiative with clear problem, solution, milestones, and expected end date.
 6. Save, register in canonical index, and lint.
 
 ## Edge Cases
 
-- If a plan is too large (more than 2 years), split it into multiple smaller plans. Each plan should be independently actionable and produce its own deliverables.
-- If a plan spawns sub-plans during implementation, each sub-plan is a separate plan document in the appropriate subject folder. Link them in the References section.
-- If a plan is fully implemented, delete it and confirm that all lasting outputs (Decisions, Skills, Articles, etc.) are properly linked and indexed.
-- If the user asks for a plan that is really just a decision, guide them to create a Policy instead.
+- If an initiative is too large (more than 2 years), split it into multiple smaller initiatives. Each initiative should be independently actionable and produce its own deliverables.
+- If an initiative spawns sub-initiatives during implementation, each sub-initiative is a separate initiative document in the appropriate subject folder. Link them in the References section.
+- If an initiative is fully implemented, delete it and confirm that all lasting outputs (Decisions, Skills, Articles, etc.) are properly linked and indexed.
+- If the user asks for an initiative that is really just a decision, guide them to create a Policy instead.
 
 ## References
 
 - [_core-adr-policy-001 - XDRS standards](../../001-xdrs-standards.md)
-- [_core-adr-policy-007 - Plan standards](../../007-plan-standards.md)
+- [_core-adr-policy-007 - Initiative standards](../../007-initiative-standards.md)
 - [_core-adr-policy-002 - Policy standards](../../002-policy-standards.md)
 
 ## Constraints
 
-- MUST follow the plan template and section-goal rules from `007-plan-standards`.
+- MUST follow the initiative template and section-goal rules from `007-initiative-standards`.
 - MUST consult `001-xdrs-standards` 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.lock`).

package/.xdrs/_core/adrs/principles/skills/007-write-presentation/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: 007-write-presentation
 description: >
-  Creates a Marp slide presentation for an existing XDRS document (policy, research, article, or plan).
+  Creates a Marp slide presentation for an existing XDRS document (policy, research, article, or initiative).
   Activate this skill when the user asks to create slides, a presentation, or a slide deck for an XDRS document.
 metadata:
   author: flaviostutz
@@ -22,7 +22,7 @@ Identify the target scope from the parent document's path or the user's request;
 
 1. Read `.xdrs/_core/adrs/principles/009-presentation-standards.md` in full to internalize all presentation rules.
 2. Read `.xdrs/_core/adrs/principles/001-xdrs-standards.md` for `.assets/` placement rules and general framework structure.
-3. Identify the parent document (policy, research, article, or plan) that the slides will support. The parent document must already exist. If no parent document exists, inform the user that slides cannot be standalone and suggest creating the parent document first.
+3. Identify the parent document (policy, research, article, or initiative) that the slides will support. The parent document must already exist. If no parent document exists, inform the user that slides cannot be standalone and suggest creating the parent document first.
 4. If the user wants slides covering content from multiple documents, check whether an article already exists that synthesizes those documents. If not, suggest creating an article first (using the 004-write-article skill) and then creating slides for that article.
 
 ### Phase 2: Define the Presentation Scope
@@ -120,7 +120,7 @@ Rules:
    - Articles: `[xdrs-root]/[scope]/[type]/[subject]/articles/.assets/[slide-file].md`
    - Research: `[xdrs-root]/[scope]/[type]/[subject]/researches/.assets/[slide-file].md`
    - Skills: `[xdrs-root]/[scope]/[type]/[subject]/skills/[number]-[skill-name]/.assets/[slide-file].md`
-   - Plans: `[xdrs-root]/[scope]/[type]/[subject]/plans/.assets/[slide-file].md`
+   - Initiatives: `[xdrs-root]/[scope]/[type]/[subject]/initiatives/.assets/[slide-file].md`
 2. Update the parent document with the link to the slide file.
 3. Verify that the slide file name is <= 64 characters and lowercase.
 

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

@@ -1,7 +1,7 @@
 ---
 name: 008-write-xdrs-doc
 description: >
-  Use when writing documents such as decisions, policies, skills, procedures, research, plans, articles, or presentations.
+  Use when writing documents such as decisions, policies, skills, procedures, research, initiatives, articles, or presentations.
   Activate this skill when the user asks to create or write any XDRS element.
 metadata:
   author: flaviostutz
@@ -20,11 +20,11 @@ Routes the request to the appropriate XDRS authoring skill based on the type of
    - **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
+   - **Initiative** — 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.
+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, Initiative, Article, or Presentation?"* Wait for the answer before proceeding.
 
 ### Phase 1.5: Prerequisites Gate — MUST complete before writing
 
@@ -40,9 +40,19 @@ Read the full content of the skill file for the inferred type, then follow all i
 | 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` |
+| Initiative | `.xdrs/_core/adrs/principles/skills/006-write-initiative/SKILL.md` |
 | Presentation | `.xdrs/_core/adrs/principles/skills/007-write-presentation/SKILL.md` |
 
+### Phase 3: Validate Mermaid Diagrams
+
+1. After the delegated skill completes, scan all files written in this session for fenced ` ```mermaid ` code blocks.
+2. For each diagram found, extract the content to a temporary `.mmd` file and run:
+   ```bash
+   npx -y @mermaid-js/mermaid-cli -i <tempfile>.mmd --quiet 2>&1
+   ```
+3. For each diagram that fails validation, report the error to the user and ask them to correct the diagram before saving.
+4. Delete all temporary files created in this step.
+
 ### Constraints
 
 - MUST read the full target SKILL.md before proceeding — do not rely on summaries or prior knowledge of the target skill.

package/.xdrs/_core/index.md

@@ -10,13 +10,13 @@ valid-from: 2025-01-01
 
 ## Overview
 
-The `_core` scope defines the XDRS framework itself: how policies, skills, research, articles, and plans are structured, written, versioned, and discovered. This scope is aimed at engineers, architects, and business analysts who build or consume xdrs-based documentation.
+The `_core` scope defines the XDRS (eXtensible Decision Record System) framework itself: how policies, skills, research, articles, and initiatives are structured, written, versioned, and discovered. This scope is aimed at engineers, architects, and business analysts who build or consume xdrs-based documentation.
 
 ## Content
 
 ### What this scope covers
 
-The `_core` scope is the foundation that all other scopes inherit from. It establishes the rules and conventions that every Policy document, skill, article, research, and plan must follow regardless of which team, product, or domain produces them.
+The `_core` scope is the foundation that all other scopes inherit from. It establishes the rules and conventions that every Policy document, skill, article, research, and initiative must follow regardless of which team, product, or domain produces them.
 
 If you are evaluating whether to adopt XDRS, setting up a new XDRS project, or extending the framework with your own scopes, start here.
 
@@ -35,7 +35,7 @@ Each artifact type has its own writing standard:
 - **Skills** follow [_core-adr-policy-003](adrs/principles/003-skill-standards.md), using the agentskills format so they work for both humans and AI agents on an automation gradient from fully manual to fully automated.
 - **Articles** follow [_core-adr-policy-004](adrs/principles/004-article-standards.md), providing synthetic views that combine and link multiple Policies, research, and skills without replacing them as the source of truth.
 - **Research** follows [_core-adr-policy-006](adrs/principles/006-research-standards.md), using an IMRAD-based structure for studies that back decisions with reproducible evidence.
-- **Plans** follow [_core-adr-policy-007](adrs/principles/007-plan-standards.md), capturing ephemeral execution plans with problem context, proposed solutions, milestones, and deliverables that are deleted after implementation.
+- **Initiatives** follow [_core-adr-policy-007](adrs/principles/007-initiative-standards.md), capturing ephemeral execution initiatives with problem context, proposed solutions, milestones, and deliverables that are deleted after implementation.
 
 ### Versioning and distribution
 
@@ -68,7 +68,7 @@ The `_core` scope ships with seven skills that automate the most common framewor
 - **003-write-skill** guides creation of a new skill package
 - **004-write-article** guides creation of a new article
 - **005-write-research** guides creation of a new research document
-- **006-write-plan** guides creation of a new execution plan
+- **006-write-initiative** guides creation of a new execution initiative
 - **007-write-presentation** guides creation of Marp slide presentations
 
 ### Getting started

package/.xdrs/index.md

@@ -1,6 +1,6 @@
 # XDRS Index
 
-This index points to all type- and scope-specific XDRS indexes. It covers Architectural (ADR), Business (BDR), and Engineering (EDR) contents. Each scope has its own canonical index that lists all Policies, Skills, Articles and Plans for that scope, organized by subject.
+This index points to all type- and scope-specific XDRS (eXtensible Decision Record System) indexes. It covers Architectural (ADR), Business (BDR), and Engineering (EDR) contents. Each scope has its own canonical index that lists all Policies, Skills, Articles and Initiatives for that scope, organized by subject.
 
 ## Scope Indexes
 

package/README.md

@@ -1,6 +1,8 @@
 # xdrs-core
 
-XDRS is 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. Decision Records are decomposed into Research (why), Policies (what), Skills (how), Plan (when) and Articles (views) with a well structured index structure and the definition of hierarchical scopes.
+**XDRS — eXtensible Decision Record System**
+
+XDRS is 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. Decision Records are decomposed into Research (why), Policies (what), Skills (how), Initiative (when) and Articles (views) with a well structured index structure and the definition of hierarchical scopes.
 
 After preparation those elements can be downloaded anywhere and used to compose xdrs corpus, which can be used as a context source for AI agents, web site publishing, RAG applications etc.
 
@@ -21,7 +23,7 @@ This project defines a standard for organizing XDRS that satisfies the following
 A traditional Decision Record normally combines several concerns in the same document:
 - A **reason** (why the decision was made, options considered, evidence gathered)
 - A **policy** (rules, core decision, what must be followed)
-- A **plan** (consequences, implementation approach, how to roll out the decision)
+- An **initiative** (consequences, implementation approach, how to roll out the decision)
 - A **how-to** (step-by-step procedure for executing under the decision)
 - A **view** (overview of the topic connecting related decisions together)
 
@@ -31,7 +33,7 @@ The XDRS framework separates these concerns into different document types, each
 - **Research** — Exploratory documents that capture the problem being investigated, constraints or requirements, findings, and option tradeoffs that back a decision during its lifecycle. One research document may inform multiple downstream decisions, but it is not a replacement for the Policy.
 - **Skills** — Step-by-step procedural guides that can be followed by humans, AI agents, or both. Skills are task-based artifacts with a concrete outcome and should include enough detail to verify the task was completed correctly. A skill may start as a fully manual procedure and evolve toward partial or full AI automation over time.
 - **Articles** — Synthetic explanatory texts that combine information from multiple Policies, Research documents, and Skills around a specific topic or audience. They never replace Policies as source of truth.
-- **Plans** — Ephemeral execution documents that describe a problem, proposed solution, and the approach and activities needed to solve it. Plans have a clear start and end and must be deleted after full implementation. Lasting outputs are captured as Policies, Skills, Articles, or other artifacts.
+- **Initiatives** — Ephemeral execution documents that describe a problem, proposed solution, and the approach and activities needed to solve it. Initiatives have a clear start and end and must be deleted after full implementation. Lasting outputs are captured as Policies, Skills, Articles, or other artifacts.
 
 The compilation process of a raw Decision Record is to distribute it into those different documents and create links between them. You can also use the framework standalone, generating these elements individually directly during the writing process without starting from a raw Decision Record.
 
@@ -167,7 +169,7 @@ This is especially important for BDRs: because business rules govern decisions t
         articles/                   # optional synthetic views over Policies, Research, and Skills
           [number]-[short-title].md
           .assets/
-        plans/                      # optional ephemeral execution plans
+        initiatives/                # optional ephemeral execution initiatives
           [number]-[short-title].md
           .assets/
 ```
@@ -180,7 +182,7 @@ Document types:
 - **Research** - Exploratory support material used while evaluating or updating a decision. Research captures constraints, findings, options, and proposal tradeoffs, but it is not the source of truth.
 - **Skills** - Step-by-step procedural guides that can be followed by humans, AI agents, or both. Must comply with Policies, but add the execution detail they lack. Skills are not mandatory by themselves unless referenced by a Policy or another policy artifact. 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 Policies they implement inside `skills/` sub-directories.
 - **Articles** - Synthetic views that explain concepts or combine information from multiple Policies, Research documents, and Skills into a coherent text for a specific topic or audience. Articles are not the source of truth; Policies take precedence when there is a conflict. Useful as navigational indexes that link related artifacts around a specific aspect.
-- **Plans** - Ephemeral execution documents that describe a problem, proposed solution, and the approach and activities needed to solve it. Plans have a clear start and end and must be deleted after full implementation. Lasting outputs are captured as Policies, Skills, Articles, or other artifacts. Co-located with Policies inside `plans/` sub-directories.
+- **Initiatives** - Ephemeral execution documents that describe a problem, proposed solution, and the approach and activities needed to solve it. Initiatives have a clear start and end and must be deleted after full implementation. Lasting outputs are captured as Policies, Skills, Articles, or other artifacts. Co-located with Policies inside `initiatives/` sub-directories.
 
 See [.xdrs/index.md](.xdrs/index.md) for the full list of active policies.
 
@@ -232,12 +234,12 @@ The `lint` command reads `./.xdrs/**` from the given workspace path and checks c
 - skill numbering uniqueness per `scope/type/subject/skills`
 - article numbering uniqueness per `scope/type/subject/articles`
 - research numbering uniqueness per `scope/type/subject/researches`
-- plan numbering uniqueness per `scope/type/subject/plans`
-- plan `Expected end date:` field presence and ISO date format
+- initiative numbering uniqueness per `scope/type/subject/initiatives`
+- initiative `Expected end date:` field presence and ISO date format
 - canonical index presence and link consistency
 - root index coverage for all discovered canonical indexes
 - Policy metadata section placement and `valid-from` / `apply-to` field format
-- local markdown links between Policy documents, skills, articles, researches, and plans (excluding fenced code blocks)
+- local markdown links between Policy documents, skills, articles, researches, and initiatives (excluding fenced code blocks)
 - local image and `.assets/` links resolving inside the sibling `.assets/` folder for each document
 
 Examples:

package/lib/lint.js

@@ -21,7 +21,7 @@ const RESERVED_SCOPES = new Set(['_core', '_local']);
 const NUMBERED_FILE_RE = /^(\d{3,})-([a-z0-9-]+)\.md$/;
 const NUMBERED_DIR_RE = /^(\d{3,})-([a-z0-9-]+)$/;
 const REQUIRED_ROOT_INDEX_TEXT = 'XDRS scopes listed last override the ones listed first';
-const SUBJECT_ARTIFACT_DIRS = new Set(['skills', 'articles', 'researches', 'plans']);
+const SUBJECT_ARTIFACT_DIRS = new Set(['skills', 'articles', 'researches', 'initiatives']);
 const RESOURCE_DIR_NAME = '.assets';
 const SKILL_PACKAGE_OPTIONAL_DIRS = new Set(['scripts', 'references', RESOURCE_DIR_NAME]);
 
@@ -69,7 +69,7 @@ const DOC_TYPE_POLICY_REF = {
   Skill: '[_core-adr-policy-003]',
   Article: '[_core-adr-policy-004]',
   Research: '[_core-adr-policy-006]',
-  Plan: '[_core-adr-policy-007]',
+  Initiative: '[_core-adr-policy-007]',
   Slide: '[_core-adr-policy-009]',
 };
 
@@ -854,8 +854,8 @@ function lintSubjectDirectory(xdrsRoot, scopeName, typeName, subjectName, xdrsNu
         artifacts.push(...lintResearchDirectory(xdrsRoot, scopeName, typeName, subjectName, entryPath, errors, externalScopes));
         continue;
       }
-      if (entry.name === 'plans') {
-        artifacts.push(...lintPlansDirectory(xdrsRoot, scopeName, typeName, subjectName, entryPath, errors, externalScopes));
+      if (entry.name === 'initiatives') {
+        artifacts.push(...lintInitiativesDirectory(xdrsRoot, scopeName, typeName, subjectName, entryPath, errors, externalScopes));
         continue;
       }
 
@@ -1217,57 +1217,57 @@ function lintResearchDirectory(xdrsRoot, scopeName, typeName, subjectName, resea
   return artifacts;
 }
 
-function lintPlansDirectory(xdrsRoot, scopeName, typeName, subjectName, plansPath, errors, externalScopes = new Set()) {
+function lintInitiativesDirectory(xdrsRoot, scopeName, typeName, subjectName, initiativesPath, errors, externalScopes = new Set()) {
   const artifacts = [];
-  const planNumbers = new Map();
-  const entries = safeReadDir(plansPath, errors, `read plans directory ${scopeName}/${typeName}/${subjectName}/plans`);
+  const initiativeNumbers = new Map();
+  const entries = safeReadDir(initiativesPath, errors, `read initiatives directory ${scopeName}/${typeName}/${subjectName}/initiatives`);
 
   for (const entry of entries) {
-    const entryPath = path.join(plansPath, entry.name);
+    const entryPath = path.join(initiativesPath, entry.name);
     if (entry.isDirectory() && entry.name === RESOURCE_DIR_NAME) {
       continue;
     }
 
     if (!entry.isFile()) {
-      errors.push(`Unexpected directory in plans folder: ${toDisplayPath(entryPath)} [_core-adr-policy-007]`);
+      errors.push(`Unexpected directory in initiatives folder: ${toDisplayPath(entryPath)} [_core-adr-policy-007]`);
       continue;
     }
 
     const match = entry.name.match(NUMBERED_FILE_RE);
     if (!match) {
-      errors.push(`Invalid plan file name: ${toDisplayPath(entryPath)} [_core-adr-policy-007]`);
+      errors.push(`Invalid initiative file name: ${toDisplayPath(entryPath)} [_core-adr-policy-007]`);
       continue;
     }
 
     artifacts.push(entryPath);
 
     const number = match[1];
-    const previous = planNumbers.get(number);
+    const previous = initiativeNumbers.get(number);
     if (previous) {
-      errors.push(`Duplicate plan number ${number} in ${scopeName}/${typeName}/${subjectName}/plans: ${toDisplayPath(previous)} and ${toDisplayPath(entryPath)} [_core-adr-policy-007]`);
+      errors.push(`Duplicate initiative number ${number} in ${scopeName}/${typeName}/${subjectName}/initiatives: ${toDisplayPath(previous)} and ${toDisplayPath(entryPath)} [_core-adr-policy-007]`);
     } else {
-      planNumbers.set(number, entryPath);
+      initiativeNumbers.set(number, entryPath);
     }
 
     if (entry.name !== entry.name.toLowerCase()) {
-      errors.push(`Plan file name must be lowercase: ${toDisplayPath(entryPath)} [_core-adr-policy-007]`);
+      errors.push(`Initiative file name must be lowercase: ${toDisplayPath(entryPath)} [_core-adr-policy-007]`);
     }
 
     const content = fs.readFileSync(entryPath, 'utf8');
     const typeId = TYPE_TO_ID[typeName].split('-')[0]; // 'adr', 'bdr', or 'edr'
-    const expectedHeader = `# ${scopeName}-${typeId}-plan-${number}:`;
+    const expectedHeader = `# ${scopeName}-${typeId}-initiative-${number}:`;
     const firstLine = firstNonEmptyLine(content);
     if (!firstLine.startsWith(expectedHeader)) {
-      errors.push(`Plan title must start with "${expectedHeader}": ${toDisplayPath(entryPath)} [_core-adr-policy-007]`);
+      errors.push(`Initiative title must start with "${expectedHeader}": ${toDisplayPath(entryPath)} [_core-adr-policy-007]`);
     }
 
-    lintRequiredSections(content, entryPath, PLAN_REQUIRED_SECTIONS, 'Plan', errors);
-    lintPlanExpectedEndDate(content, entryPath, errors);
-    lintNoEmojis(content, entryPath, 'Plan', errors);
+    lintRequiredSections(content, entryPath, INITIATIVE_REQUIRED_SECTIONS, 'Initiative', errors);
+    lintInitiativeExpectedEndDate(content, entryPath, errors);
+    lintNoEmojis(content, entryPath, 'Initiative', errors);
     lintDocumentLinks(entryPath, xdrsRoot, scopeName, errors, externalScopes);
   }
 
-  lintOrphanAssets(path.join(plansPath, RESOURCE_DIR_NAME), artifacts, xdrsRoot, errors);
+  lintOrphanAssets(path.join(initiativesPath, RESOURCE_DIR_NAME), artifacts, xdrsRoot, errors);
 
   return artifacts;
 }
@@ -1355,7 +1355,7 @@ function lintResearchIntroductionQuestion(content, filePath, errors) {
 const XDRS_REQUIRED_SECTIONS = ['## Context and Problem Statement', '## Decision Outcome'];
 const ARTICLE_REQUIRED_SECTIONS = ['## Overview', '## Content', '## References'];
 const RESEARCH_REQUIRED_SECTIONS = ['## Abstract', '## Introduction', '## Methods', '## Results', '## Discussion', '## Conclusion', '## References'];
-const PLAN_REQUIRED_SECTIONS = ['## Executive Summary', '## Context and Problem Statement', '## Proposed Solution'];
+const INITIATIVE_REQUIRED_SECTIONS = ['## Executive Summary', '## Context and Problem Statement', '## Proposed Solution'];
 const SKILL_REQUIRED_SECTIONS = ['## Overview', '## Instructions'];
 
 function lintRequiredSections(content, filePath, requiredSections, docType, errors) {
@@ -1368,23 +1368,23 @@ function lintRequiredSections(content, filePath, requiredSections, docType, erro
   }
 }
 
-function lintPlanExpectedEndDate(content, filePath, errors) {
+function lintInitiativeExpectedEndDate(content, filePath, errors) {
   const lines = content.split(/\r?\n/);
   const ignoredLines = findIgnoredMarkdownLines(lines);
   const expectedEndDateLines = findFieldLines(lines, ignoredLines, 'Expected end date:');
 
   if (expectedEndDateLines.length === 0) {
-    errors.push(`Plan must include an Expected end date: field: ${toDisplayPath(filePath)} [_core-adr-policy-007]`);
+    errors.push(`Initiative must include an Expected end date: field: ${toDisplayPath(filePath)} [_core-adr-policy-007]`);
     return;
   }
 
   if (expectedEndDateLines.length > 1) {
-    errors.push(`Plan must not repeat Expected end date: ${toDisplayPath(filePath)} [_core-adr-policy-007]`);
+    errors.push(`Initiative must not repeat Expected end date: ${toDisplayPath(filePath)} [_core-adr-policy-007]`);
   }
 
   const value = lines[expectedEndDateLines[0]].slice('Expected end date:'.length).trim().replace(/\.$/, '');
   if (!isIsoDate(value)) {
-    errors.push(`Plan Expected end date: must be a valid ISO date in YYYY-MM-DD format: ${toDisplayPath(filePath)} [_core-adr-policy-007]`);
+    errors.push(`Initiative Expected end date: must be a valid ISO date in YYYY-MM-DD format: ${toDisplayPath(filePath)} [_core-adr-policy-007]`);
   }
 }