xdrs-core 0.49.0 → 0.50.0

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

@@ -26,6 +26,7 @@ Foundational standards, principles, and guidelines.
 - [_core-adr-policy-018](principles/018-external-path-symlinks.md) - **External path symlinks** — How to make XDRS files accessible from paths outside the .xdrs/ root using symlinks
 - [_core-adr-policy-019](principles/019-compiled-scope-type.md) - **compiled scope type** — Defines the `compiled` scope type: scopes whose policies are compiled from external authoritative sources with strict source traceability and no invented content
 - [_core-adr-policy-020](principles/020-media-and-asset-standards.md) - **Media and asset standards** — Canonical diagram format preference order and non-Markdown asset rules for all XDRS document types
+- [_core-adr-policy-021](principles/021-skill-bundling.md) - **Skill bundling** — Optional per-skill Makefile mechanism to stage a self-contained dist/ output for standalone distribution
 
 ## Skills
 

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

@@ -73,32 +73,73 @@ Examples:
 - `.xdrs/business-x/edrs/devops/skills/ci-pipeline-debug/SKILL.md`
 - `.xdrs/_local/adrs/principles/skills/my-nice-skill/SKILL.md`
 
+Multiple skills under the same `[subject]/skills/` folder MAY share common instruction modules through a sibling `.assets/` directory placed directly under `skills/` (not inside any individual skill package) — for example `skills/.assets/shared-check.md`, referenced with a relative link from any skill in that folder. This keeps shared procedures DRY without duplicating instructions across skills.
+
+A skill MAY optionally be distributed as a self-contained standalone package (for example, to share it outside this repository) using the bundling mechanism defined in [`_core-adr-policy-021`](021-skill-bundling.md). Bundling is optional; skills that are always consumed as part of the full package do not need it.
+
+**Directory roles**
+
+| Path | Purpose |
+|---|---|
+| `SKILL.md` | Required entry point: frontmatter + instructions. |
+| `scripts/` | Optional executable scripts the agent may run. |
+| `references/` | Optional deep reference material split out of `SKILL.md`. |
+| `.assets/` | Optional images, templates, and other local resource files. |
+
 **Skill naming**
 
-Unlike Policies, Research, Articles, and Initiatives, skill packages MUST NOT use a numeric prefix. A skill is identified by a descriptive name alone, keeping it compatible with the wider agentskills ecosystem, where clients (including this framework's own agentskills-format consumers) expect a plain descriptive identifier rather than a sequence number. Each skill name MUST be unique within its `scope/type/subject/skills/` namespace; check for an existing skill with the same name before creating a new one.
+Unlike Policies, Research, Articles, and Initiatives, skill packages are not auto-numbered. A skill is identified by a descriptive name, keeping it compatible with the wider agentskills ecosystem, where clients (including this framework's own agentskills-format consumers) expect a plain descriptive identifier rather than an auto-generated sequence number. The name MAY still contain digits, including as a prefix, when that is simply part of the descriptive name (e.g., `2fa-setup`). Each skill name MUST be unique within its `scope/type/subject/skills/` namespace; check for an existing skill with the same name before creating a new one.
 
 **SKILL.md format** (agentskills spec)
 
 ```
 ---
 name: [skill-name]              # required: matches the folder name exactly; max 64 chars
-description: >            # required: what the skill does AND when to activate it; max 1024 chars
+description: >            # required: what the skill does AND when to activate it; max 1024 chars (SHOULD stay near 250 when the trigger can be stated that tightly)
   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
+metadata:                 # required
+  author: <team-or-person>       # required
+  version: "1.0.0"                # required: full semantic versioning
+  updated: YYYY-MM-DD              # required: date of the last material content change
 ---
 
 ## Overview
 
 Brief description of the skill goal.
 
+### Inputs
+
+#### Required
+- Bare minimum the skill needs to start working, one bullet per item, or "None".
+
+#### Optional
+- Extra helpful context the skill can use if given, one bullet per item, or "None".
+
+### Outputs
+
+#### Contents
+- Generated files or chat-delivered results, one bullet per item, or "None".
+
+#### Changes
+- External system mutations that are part of the skill's main objective, one bullet per item, or "None".
+
+### Halt Conditions
+- Specific triggers that make the skill stop before completing, one bullet per item, or "None".
+
+### User Interaction
+
+Optional section: human-in-the-loop (HITL) exchanges during execution — a clarifying question or
+an approval gate — one bullet per item, or "None". Omit this section entirely when none apply.
+
+### Runtime Requirements
+
+Optional section: tooling, network access, or environment prerequisites beyond the LLM itself,
+one bullet per item. Omit this section entirely when none apply.
+
 ## Instructions
 
-Step-by-step instructions the agent should follow.
+Step-by-step instructions the agent should follow. State one clearly recommended approach first when several are viable; note alternatives briefly afterward.
 
 ## Examples
 
@@ -107,19 +148,58 @@ Concrete input/output examples that illustrate correct behavior.
 ## Edge Cases
 
 Known gotchas and how to handle them.
+
+## Anti-Patterns
+
+At least 3 entries, each grounded in a real observed mistake:
+- **Mistake:** what an agent or author incorrectly did.
+  **Why it happens:** the reasoning or shortcut that leads there.
+  **Instead:** the correct approach.
 ```
 
 Rules:
 - The `name` field MUST match the folder name exactly (e.g., `code-review`). This keeps skill identifiers simple and aligned with the filesystem hierarchy.
-- The directory name and the `name:` field MUST contain only lowercase alphanumeric characters and hyphens (e.g., `code-review`), with no numeric prefix.
-- `## Overview` SHOULD state the task objective, expected outcome, and relevant prerequisites or tools when they matter.
-- `## Instructions` SHOULD include verification steps or acceptance criteria at the end of the task, or at the end of major phases when partial validation matters.
+- The directory name and the `name:` field MUST contain only lowercase alphanumeric characters and hyphens (e.g., `code-review`, `2fa-setup`).
+- `metadata` is REQUIRED. `metadata.version` MUST use full semantic versioning (`MAJOR.MINOR.PATCH`, e.g. `1.0.0`), consistent with [`_core-adr-policy-005`](005-semantic-versioning-for-xdrs-packages.md); `metadata.author` MUST be non-empty; `metadata.updated` MUST be an ISO `YYYY-MM-DD` date, refreshed whenever the skill's content materially changes.
+- `description` SHOULD stay near 250 characters when the activation trigger can be stated that tightly, even though the hard cap remains 1024 characters — it is loaded into context on every activation scan.
+- `## Overview` SHOULD state the task objective, expected outcome, and relevant prerequisites or tools when they matter, and MUST contain nested subsections, in order, for `### Inputs`, `### Outputs`, `### Halt Conditions`, then the optional `### User Interaction` and `### Runtime Requirements`.
+- `### Inputs` MUST contain `#### Required` (the bare minimum needed to invoke the skill) then `#### Optional` (helpful extra context), in that order.
+- `## Instructions` SHOULD state one clearly recommended approach first when multiple are viable, noting alternatives briefly afterward, and SHOULD include verification steps or acceptance criteria at the end of the task or major phases.
+- `## Examples` SHOULD include 2-3 example prompts a user could give as input, alongside a short description of what to expect during execution and as output for each.
+- `### Outputs` covers only end-objective results, not intermediary items, and MUST contain `#### Contents` (generated files or chat-delivered results) then `#### Changes` (external system mutations that are part of the main objective), in that order.
+- `### Halt Conditions` MUST list this skill's specific stop-before-completing triggers, grounded in at least missing required input, dubious/ambiguous input, and insufficient agent confidence — distinct from `## Edge Cases` (activation/boundary conditions) and `## Anti-Patterns` (execution mistakes). A partial or empty result the skill still finishes and returns belongs in `### Outputs`, not `### Halt Conditions`.
+- `### User Interaction` is OPTIONAL: documents human-in-the-loop (HITL) exchanges during execution — a clarifying question or an approval gate — distinct from `### Halt Conditions` (which stop execution rather than pause-and-resume it) and `### Runtime Requirements` (static prerequisites, not an interactive exchange); omit the section entirely when the skill has none.
+- `### Runtime Requirements` is OPTIONAL: free-form bullets for tooling, network, or environment prerequisites beyond the LLM itself; omit the section entirely when none apply.
+- Every bullet in `#### Required`, `#### Optional`, `#### Contents`, `#### Changes`, `### Halt Conditions`, and `### User Interaction` MUST be under 10 words, or the section MUST contain a single "None" bullet instead.
+- `## Anti-Patterns` is REQUIRED with a minimum of 3 entries, each naming a Mistake, Why it happens, and the correct approach Instead, grounded in real observed issues rather than theoretical ones. Keep it distinct from `## Edge Cases`: Edge Cases are activation/boundary conditions, Anti-Patterns are execution mistakes.
+- Key recommendations MAY be tagged `[PROVEN]`, `[RECOMMENDED]`, or `[EXPERIMENTAL]` when a skill offers several viable approaches at different confidence levels.
 - For diagram format preferences and non-Markdown asset rules, see [`_core-adr-policy-020`](020-media-and-asset-standards.md).
-- Keep `SKILL.md` under 6500 words. Move lengthy reference material to `references/`.
+- `SKILL.md` MUST stay under 7000 words. Move lengthy reference material to `references/`; each `references/*.md` file MUST stay under 4000 words, splitting further when a single file grows unwieldy.
 - Use relative paths for all links; MUST NOT use absolute paths starting with `/`.
 - File names MUST be lowercase.
 - MUST NOT use emojis in skill content.
 
+**Script standards**
+
+When a skill includes `scripts/`:
+- Each script MUST declare its runtime/interpreter at the top (shebang or equivalent header comment).
+- SHOULD use the language already used by the consuming project when known, rather than mandating one language repo-wide.
+- MUST avoid non-essential external dependencies, or document install steps in `SKILL.md` when unavoidable.
+- SHOULD support both human-readable and machine-readable (JSON) output when producing analysis or report output.
+- SHOULD stay single-purpose.
+
+**Quality gate**
+
+Before creating a skill, confirm it removes real ambiguity or repetitive effort compared to not having it. Skills that only restate a Policy, or that handle a one-off task unlikely to recur, SHOULD NOT be created.
+
+**Clarify First**
+
+Generative skills — those producing a deliverable document (Policy, Skill, Article, Research, Initiative, Presentation) — SHOULD list the 2-4 inputs they need confirmed (e.g., topic, scope, audience) and ask the user when any is unknown, stopping once those inputs are confirmed rather than over-interrogating. Skills that route, review, or report instead of authoring a new deliverable do not need this pattern.
+
+**Halt behavior**
+
+Skills MUST halt on missing required input, dubious/ambiguous input, or insufficient agent confidence, unless the user explicitly instructs the agent to proceed anyway. This override applies generally; a skill's own `## Halt Conditions` list does not need to restate it.
+
 **Validation**
 
 Use the [skills-ref](https://github.com/agentskills/agentskills/tree/main/skills-ref) CLI to validate before committing:
@@ -134,6 +214,10 @@ skills-ref validate .xdrs/[scope]/[type]/[subject]/skills/[skill-name]
   * Reason: Breaks the natural association between a decision (Policy) 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 XDRS scope/subject hierarchy, and keeps skills close to the decisions they implement.
+* (REJECTED) **Fully self-contained skills, no shared assets** - Every skill package repeats any instruction shared with another skill.
+  * Reason: Duplicates maintenance burden across skills and drifts out of sync over time.
+* (CHOSEN) **Shared `.assets/` modules plus optional bundling** - Keep shared instruction modules DRY in-repo, and offer an optional per-skill bundling mechanism for standalone distribution.
+  * Reason: Preserves DRY authoring for the common case while still allowing a single skill to be distributed as a self-contained artifact when needed ([`_core-adr-policy-021`](021-skill-bundling.md)).
 
 ## References
 
@@ -142,4 +226,6 @@ skills-ref validate .xdrs/[scope]/[type]/[subject]/skills/[skill-name]
 - [skills-ref validation library](https://github.com/agentskills/agentskills/tree/main/skills-ref)
 - [_core-adr-policy-001 - XDRS standards](001-xdrs-standards.md)
 - [_core-adr-policy-004 - Article standards](004-article-standards.md)
+- [_core-adr-policy-005 - Semantic versioning for XDRS packages](005-semantic-versioning-for-xdrs-packages.md)
 - [_core-adr-policy-006 - Research standards](006-research-standards.md)
+- [_core-adr-policy-021 - Skill bundling](021-skill-bundling.md)

package/.xdrs/_core/adrs/principles/021-skill-bundling.md

@@ -0,0 +1,85 @@
+---
+name: _core-adr-policy-021-skill-bundling
+description: Defines how a skill package MAY be bundled into a self-contained standalone distributable via a per-skill Makefile, including dist/ staging, recursive dependency delegation, and selective copying. Use when packaging a skill for standalone distribution outside the full xdrs-core package.
+apply-to: Skill packages that need standalone distribution outside the full xdrs-core package
+valid-from: 2026-09-19
+---
+
+# _core-adr-policy-021: Skill bundling
+
+## Context and Problem Statement
+
+Skills sometimes need to be shared or distributed as standalone artifacts outside the full `xdrs-core` package — for example, published separately or handed to a team that does not consume the whole repository. A skill that references shared `.assets/` modules (see `_core-adr-policy-003`) or embeds another skill as a dependency cannot simply be copied as a single `SKILL.md` file without breaking those references. No automated bundling utility exists yet, so each skill's own build process must resolve its dependencies; this means the same short recursive-copy pattern is duplicated across every bundling-enabled skill's `Makefile`, an accepted tradeoff until a shared build utility exists.
+
+Question: How should a skill package that depends on shared assets or other skills be packaged into a self-contained standalone distributable?
+
+## Decision Outcome
+
+**Optional per-skill `Makefile` that stages a self-contained `dist/` output, recursively delegating to each dependency's own bundling `Makefile`**
+
+A skill MAY add its own `Makefile` to become bundling-enabled. Running `make build` inside the skill's folder stages a self-contained copy of the skill and everything it needs in a local, gitignored `dist/` folder, with exactly two top-level entries: `dist/build/` (the skill's own files, ready to use standalone) and `dist/<skill-name>.zip` (a packaged archive of it) — see Details for the exact layout. Inside `dist/build/`, the skill's own resources stay flat while every bundled dependency is corralled into its own `dist/<dependency-name>/` subfolder, so it is always immediately recognizable as a separate bundled/copied skill rather than merged into the skill's own files. When the skill embeds another skill as a dependency and that dependency is itself bundling-enabled, `build` delegates to the dependency's own `make build` and copies its output wholesale, so the mechanism nests recursively without a central build utility. This is independent of the repository-level `.filedist-package.yml` distribution flow used to publish whole XDRS packages; it operates entirely within a single skill's own folder.
+
+### Details
+
+#### 01-bundling-is-optional
+A skill MAY opt into standalone bundling by adding its own `Makefile` with `build`, `test`, and `clean` targets inside its own package folder (`skills/[skill-name]/Makefile`). Skills that are always consumed as part of the full `xdrs-core` package are not required to add one.
+
+#### 02-dist-output-location
+When present, the bundling `Makefile` MUST stage the skill's own unpacked files in `dist/build/`, relative to the root of the skill's own package (`skills/[skill-name]/dist/build/`). `dist/` MUST NOT be committed: a `.gitignore` entry covering `dist` (a bare `dist` or `**/dist` line) MUST exist in either the repository root `.gitignore` or a `.gitignore` local to the skill package. If the root `.gitignore` already covers it, no additional local entry is needed.
+
+#### 03-works-without-bundling
+A skill's `SKILL.md` MUST remain fully functional when consumed directly from its normal in-repo location, without ever running `make build`. The `dist/` output is an additional, optional artifact for standalone distribution; `SKILL.md` MUST NOT hard-depend on `dist/` existing.
+
+#### 04-selective-copy
+`make build` MUST copy only the files strictly necessary for the skill to run: its own `SKILL.md`, whichever of `scripts/`, `references/`, or `.assets/` it actually uses, and the specific shared modules or dependency skills it references. Tests, fixtures, or unrelated repository resources MUST NOT be copied into `dist/`.
+
+#### 05-preserve-relative-paths
+Files that belong to the skill's own package (`scripts/`, `references/`, its own `.assets/`) MUST be copied preserving their path relative to `SKILL.md` unchanged, since `SKILL.md` and its own files move into `dist/build/` together as a unit and their relative relationship to each other does not change. Links to a bundled dependency (a shared `.assets/` module elsewhere or another skill) are the one exception: `dist/build/` sits two directory levels below the original `SKILL.md`, so an unrewritten external link would no longer resolve once the target has been copied. `build` MUST rewrite such links inside the copied `SKILL.md` (and any other copied file that references them) to the flattened path defined by rule `06-recursive-delegation`, using a mechanical text substitution (for example `sed`).
+
+#### 06-recursive-delegation
+When a skill's `build` target embeds another skill as a dependency, `build` MUST stage that dependency under `dist/build/dist/<dependency-name>/` (a `dist/` subfolder nested inside `dist/build/` itself, not a sibling of it): if the dependency has its own bundling `Makefile`, run `$(MAKE) -C <dependency-path> build` first and copy the contents of its already-built `dist/build/` (not its whole `dist/` output, so its own zip is not carried along) into `dist/build/dist/<dependency-name>/`; if it does not, create `dist/build/dist/<dependency-name>/` and copy only its bare `SKILL.md` into it. Using the same `dist/build/dist/<dependency-name>/` shape in both cases keeps the bundle consistent regardless of whether the dependency is itself bundling-enabled, and — because the copied subtree carries its own already-rewritten links unchanged — nested transitive dependencies resolve correctly with no further rewriting. After staging, `build` MUST rewrite the original cross-package reference inside the copied `SKILL.md` (per rule `05-preserve-relative-paths`) to `dist/<dependency-name>/SKILL.md` (relative from inside `dist/build/`). A minimal illustrative pattern:
+
+```makefile
+DEPS := ../shared-skill ../another-skill
+BUILD := dist/build
+
+build: clean
+	mkdir -p $(BUILD)
+	cp SKILL.md $(BUILD)/
+	@for d in $(DEPS); do \
+	  name=$$(basename $$d); \
+	  mkdir -p $(BUILD)/dist/$$name; \
+	  if [ -f $$d/Makefile ]; then \
+	    $(MAKE) -C $$d build; \
+	    cp -R $$d/dist/build/. $(BUILD)/dist/$$name/; \
+	  else \
+	    cp $$d/SKILL.md $(BUILD)/dist/$$name/; \
+	  fi; \
+	  sed -i.bak "s#$$d/SKILL.md#dist/$$name/SKILL.md#g" $(BUILD)/SKILL.md && rm -f $(BUILD)/SKILL.md.bak; \
+	done
+
+test: build
+clean:
+	rm -rf dist
+```
+
+#### 07-dependency-must-have-own-makefile
+A skill that is itself listed as another skill's bundling dependency, and that has cross-skill references of its own, MUST have its own bundling `Makefile`. Without one, only its bare `SKILL.md` can be copied and its own references cannot be resolved automatically. This is not mechanically lint-enforceable; authors MUST self-check it when wiring a dependency into another skill's `Makefile`, and a `make test` run that exercises every resolved reference is the practical backstop for catching a violation.
+
+#### 08-no-cycle-detection
+The recursive delegation described in rule `06-recursive-delegation` has no cycle detection. Authors MUST NOT introduce circular bundling dependencies between skills, since that would cause unbounded recursive `make build` invocations.
+
+#### 09-standard-targets
+The bundling `Makefile` MUST expose `build`, `test`, and `clean` targets, mirroring the repository root `Makefile` convention. `clean` MUST remove only its own `dist/` and MUST NOT cascade into dependency skills' own `dist/` folders. `test` SHOULD cascade into each bundling-enabled dependency's own `test` target and SHOULD verify the skill still works from its bundled `dist/` output.
+
+#### 10-zip-artifact
+`make build` SHOULD also produce a single zip archive of the complete `dist/build/` tree (which already includes every bundled dependency folder from rule `06-recursive-delegation`) as `dist/<skill-name>.zip`. Since `dist/build/` is a subdirectory of `dist/`, the archive naturally cannot include itself: create it directly, for example with `cd dist/build && zip -rq ../<skill-name>.zip .`.
+
+#### 11-build-depends-on-clean
+The `build` target MUST depend on the `clean` target (`build: clean`) so every build starts from a clean `dist/`, instead of duplicating `clean`'s removal logic inline.
+
+## References
+
+- [_core-adr-policy-001 - XDRS standards](001-xdrs-standards.md)
+- [_core-adr-policy-003 - Skill standards](003-skill-standards.md)
+- [_core-adr-policy-008 - Policy structured standards](008-policy-structured-standards.md)

package/.xdrs/_core/adrs/principles/skills/compile-scope/SKILL.md

@@ -4,13 +4,50 @@ description: >
   Compiles or updates any scope declaring `scope-type: compiled` from its configured external sources. Reads compilation meta-policies to discover sources, fetches content (git clone, local copy, or web scrape), plans policy changes, migrates policies one at a time with structured format, `## Source` sections, and `**compilation-note:**` markers, then runs lint and review. Documents source inconsistencies without inventing fixes. Activate when the user asks to compile, update, sync, refresh, or recompile a compiled scope.
 metadata:
   author: flaviostutz
-  version: "1.0"
+  version: "1.0.0"
+  updated: 2026-09-19
 ---
 
 ## Overview
 
 Performs a full compilation cycle for any scope declaring `scope-type: compiled`: discovers compilation meta-policies across all type folders, fetches sources into a temporary directory, plans which policies to create, update, or remove, migrates them one at a time with full source traceability, runs lint and review, and documents any inconsistencies found in the source. Works for both initial compilation and re-compilation (updates). Requires `_core-adr-policy-019-compiled-scope-type` to be present in the workspace.
 
+### Inputs
+
+#### Required
+
+- Name of the compiled scope to sync.
+
+#### Optional
+
+- None.
+
+### Outputs
+
+#### Contents
+
+- Updated compiled scope, linted and reviewed.
+
+#### Changes
+
+- Policy files created, updated, or removed.
+
+### Halt Conditions
+
+- No local meta-policy found in the scope.
+- Scope does not declare scope-type: compiled.
+- A source cannot be fetched or converted.
+
+### User Interaction
+
+- Confirmation of the CREATE/UPDATE/REMOVE plan before migrating.
+
+### Runtime Requirements
+
+- Network/git access for remote sources.
+- `uvx markitdown` for non-Markdown source conversion, if needed.
+- `npx @playwright/cli` as a web-scraping fallback.
+
 ## Instructions
 
 ### Phase 0: Prerequisites Gate
@@ -119,3 +156,17 @@ After writing each policy:
    - Inconsistencies documented (with file path).
    - Any sources that could not be fetched.
    - Lint and review pass/fail status.
+
+## Anti-Patterns
+
+- **Mistake:** Inventing content to fill gaps when source material is incomplete or ambiguous.
+  **Why it happens:** The agent wants to produce a "complete" policy and fills gaps with plausible-sounding text.
+  **Instead:** Transcribe faithfully, preserve ambiguities as-is, and record inconsistencies in Phase 7 instead of guessing.
+
+- **Mistake:** Skipping the Phase 2 confirmation and migrating policies before the user approves the CREATE/UPDATE/REMOVE plan.
+  **Why it happens:** Momentum from prior compilations makes the plan feel obviously correct.
+  **Instead:** Always present the TODO list and wait for explicit confirmation before Phase 3.
+
+- **Mistake:** Leaving the temporary `.tmp/compilation-[ts]/` directory behind after a run.
+  **Why it happens:** Phase 8 cleanup is easy to forget once the summary is reported.
+  **Instead:** Always remove the temporary directory as the first Phase 8 step, even on partial failures.

package/.xdrs/_core/adrs/principles/skills/review/SKILL.md

@@ -6,13 +6,46 @@ description: >
    Also activate when you identify a need to check compliance with Policies during implementation.
 metadata:
   author: flaviostutz
-  version: "1.0"
+  version: "1.0.0"
+  updated: 2026-09-19
 ---
 
 ## Overview
 
 Performs a structured review of code changes or files against the Policies in the repository, categorizing findings by severity and type, and reporting them without modifying any code.
 
+### Inputs
+
+#### Required
+
+- A git diff, file set, or documents to review.
+
+#### Optional
+
+- Specific Policies or scope to focus on.
+
+### Outputs
+
+#### Contents
+
+- Structured ERROR/WARNING findings report in chat.
+
+#### Changes
+
+- None.
+
+### Halt Conditions
+
+- A declared follows scope is missing or unreadable.
+- A declared extends scope is missing or unreadable.
+- A local meta-policy file exists but cannot be read.
+- The declared scope-type has no governance policy.
+
+### Runtime Requirements
+
+- `git` available for diff-scoped reviews.
+- `npx @mermaid-js/mermaid-cli` for Mermaid diagram checks.
+
 ## Instructions
 
 ### Phase 1: Code Gathering
@@ -112,10 +145,23 @@ Scope: [scope identifier]
 - If no Policies apply to the scope, output "No applicable Policies found" and skip reporting.
 - If a potential violation is in pre-existing code outside the diff, report it as WARNING only.
 
+## Anti-Patterns
+
+- **Mistake:** Reporting a finding based on general good-practice opinion with no specific Policy citation.
+  **Why it happens:** The reviewer conflates "seems wrong" with "violates a documented rule".
+  **Instead:** Drop any finding that cannot be traced to a specific rule in an Accepted Policy.
+
+- **Mistake:** Skipping the prerequisites gate (follows/extends/local meta-policy checks) when the scope looks simple.
+  **Why it happens:** The gate feels like overhead for a quick review request.
+  **Instead:** Always run the full prerequisites gate first; a silent FAIL on a missing governance layer is safer than an unreliable PASS.
+
+- **Mistake:** Editing the reviewed code directly to "just fix it" instead of only reporting findings.
+  **Why it happens:** Fixing feels faster than describing the fix.
+  **Instead:** This skill MUST NOT edit code; only report findings and suggested actions.
+
 ## References
 
 - [_core-adr-policy-001 - XDRS standards](../../001-xdrs-standards.md)
 - [_core-adr-policy-002 - Policy standards](../../002-policy-standards.md)
 - [_core-adr-policy-003 - Skill standards](../../003-skill-standards.md)
 - [_core-adr-policy-020 - Media and asset standards](../../020-media-and-asset-standards.md)
-

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

@@ -4,13 +4,42 @@ description: >
    Creates a new article document following XDRS article standards: selects scope, type, subject, and number; then writes a focused synthetic text that combines and links multiple Policies, Research documents, 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 XDRS project.
 metadata:
   author: flaviostutz
-  version: "1.0"
+  version: "1.0.0"
+  updated: 2026-09-19
 ---
 
 ## Overview
 
 Guides the creation of a well-structured article by following `_core-adr-policy-004`, consulting `policy-standards` for every core element definition, researching the Policies, Research documents, and Skills to synthesize, and producing a concise document that serves as a navigable view without duplicating decision content.
 
+### Inputs
+
+#### Required
+
+- A topic for the article.
+
+#### Optional
+
+- Target audience, scope, or XDRS elements to synthesize.
+
+### Outputs
+
+#### Contents
+
+- A new article file.
+
+#### Changes
+
+- Index entry and back-references in synthesized documents.
+
+### Halt Conditions
+
+- No relevant Policies, Research, or Skills exist to synthesize.
+
+### User Interaction
+
+- Clarification of target audience when unspecified.
+
 ## Instructions
 
 ### Phase 0: Clarify Intent
@@ -151,6 +180,22 @@ Follow the lint verification steps in `.xdrs/_core/adrs/principles/skills/.asset
 - MUST NOT create documents in external scopes (scopes whose files appear in the workspace root `.filedist.lock`).
 - MUST defer to active and applicable Policies when article synthesis conflicts with them.
 
+## Anti-Patterns
+
+- **Mistake:** Reproducing decision text verbatim from a Policy instead of summarizing and linking to it.
+  **Why it happens:** Copying feels safer/more accurate than paraphrasing.
+  **Instead:** Articles are views, not decisions; summarize and link back to the authoritative Policy.
+
+- **Mistake:** Writing an article that spans multiple unrelated subjects without splitting it into chapters.
+  **Why it happens:** A broad topic feels easier to cover in one long document.
+  **Instead:** Once content approaches ~2000 words or covers distinct sub-topics, split into separate chapter articles per Phase 5/Edge Cases guidance.
+
+- **Mistake:** Skipping Phase 0 clarifying questions (topic/audience/scope) because the request seems clear.
+  **Why it happens:** The request looks self-explanatory, so asking feels like unnecessary friction.
+  **Instead:** Always ask the mandatory Phase 0 questions in a single batch before reading standards; audience in particular is easy to assume wrongly.
+
+## References
+
 - [_core-adr-policy-004 - Article standards](../../004-article-standards.md)
 - [_core-adr-policy-006 - Research standards](../../006-research-standards.md)
 - [_core-adr-policy-001 - XDRS standards](../../001-xdrs-standards.md)

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

@@ -6,13 +6,42 @@ description: >
   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"
+  version: "1.0.0"
+  updated: 2026-09-19
 ---
 
 ## Overview
 
 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.
 
+### Inputs
+
+#### Required
+
+- A problem statement and proposed solution.
+
+#### Optional
+
+- Expected timeline or milestones.
+
+### Outputs
+
+#### Contents
+
+- A new initiative file.
+
+#### Changes
+
+- Index entry and back-references in related documents.
+
+### Halt Conditions
+
+- Rejects an expected end date beyond 2 years.
+
+### User Interaction
+
+- Clarifying questions about stakeholders and constraints, one batch.
+
 ## Instructions
 
 ### Phase 0: Scope Placement and Prerequisites Gate — MUST complete before writing
@@ -32,7 +61,6 @@ Guides the creation of a well-structured initiative document by following `_core
    - 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.
 
-
 ### Phase 2: Select Scope, Type, and Subject
 
 Consult `001-xdrs-standards` while making each choice in this phase. The summaries below are orientation only; when any detail is unclear, the standard decides.
@@ -154,6 +182,20 @@ Follow the lint verification steps in `.xdrs/_core/adrs/principles/skills/.asset
 - 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.
 
+## Anti-Patterns
+
+- **Mistake:** Writing a heavy, generic project-management document instead of focusing on problem/solution/approach.
+  **Why it happens:** Initiative templates have many optional sections, tempting the author to fill all of them.
+  **Instead:** Only fill optional sections when they add real value; keep the document focused and ephemeral.
+
+- **Mistake:** Leaving a completed initiative in the repository indefinitely instead of deleting it after implementation.
+  **Why it happens:** Deleting a finished document feels like discarding useful history.
+  **Instead:** Initiatives are ephemeral; delete them after full implementation once outputs are linked/indexed elsewhere.
+
+- **Mistake:** Setting an Expected end date more than 2 years out instead of splitting the initiative.
+  **Why it happens:** A large effort feels like one continuous initiative.
+  **Instead:** Break initiatives whose scope exceeds 2 years into multiple smaller, independently actionable initiatives.
+
 ## References
 
 - [_core-adr-policy-001 - XDRS standards](../../001-xdrs-standards.md)

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

@@ -5,13 +5,42 @@ description: >
   Activate this skill when the user asks to create, add, or write a new Policy (ADR, BDR, or EDR).
 metadata:
   author: flaviostutz
-  version: "1.0"
+  version: "1.0.0"
+  updated: 2026-09-19
 ---
 
 ## Overview
 
 Guides the creation of a well-structured Policy by following the standards in `_core-adr-policy-001`, consulting `policy-standards` for every core element definition, researching existing policies for conflicts, checking redundancy across related artifacts, and iterating until the document is concise, decision-focused, and clear about when the decision should be used.
 
+### Inputs
+
+#### Required
+
+- A decision topic to document.
+
+#### Optional
+
+- Preferred Policy type, if already known.
+
+### Outputs
+
+#### Contents
+
+- A new Policy file.
+
+#### Changes
+
+- Index entries added in the relevant scope.
+
+### Halt Conditions
+
+- Decision conflicts with an existing Policy, unresolved.
+
+### User Interaction
+
+- Clarifying questions when the decision topic is ambiguous.
+
 ## Instructions
 
 ### Phase 0: Scope Placement and Prerequisites Gate — MUST complete before writing
@@ -187,6 +216,20 @@ Follow the lint verification steps in `.xdrs/_core/adrs/principles/skills/.asset
 - 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`).
 
+## Anti-Patterns
+
+- **Mistake:** Creating a new Policy that duplicates a decision already captured elsewhere instead of extending or linking it.
+  **Why it happens:** Writing a fresh Policy feels faster than researching existing ones in Phase 4.
+  **Instead:** Always research related Policies first; extend or reference an existing decision rather than duplicating it.
+
+- **Mistake:** Using lowercase "must"/"should" for normative requirements instead of uppercase BCP 14 keywords.
+  **Why it happens:** Natural writing style favors lowercase, and the distinction feels pedantic.
+  **Instead:** Use uppercase MUST/SHOULD/MAY for every normative statement in Details and Decision Outcome; verify in Phase 7.
+
+- **Mistake:** Skipping the Phase 0 prerequisites gate for a scope that "obviously" has no follows/extends chain.
+  **Why it happens:** The gate feels unnecessary when the scope looks simple.
+  **Instead:** Always run the prerequisites gate before writing; a missing governance layer produces an unreliable Policy.
+
 ## References
 
 - [_core-adr-policy-001 - XDRS standards](../../001-xdrs-standards.md)