agentme 0.3.3 → 0.5.0

package/.xdrs/agentme/edrs/application/003-javascript-project-tooling.md

@@ -1,3 +1,8 @@
+---
+name: agentme-edr-003-javascript-project-tooling-and-structure
+description: Defines the standard JavaScript and TypeScript project toolchain and layout using Mise, pnpm, TypeScript, ESLint, Jest, and Makefiles. Use when scaffolding or reviewing JavaScript projects.
+---
+
 # agentme-edr-003: JavaScript project tooling and structure
 
 ## Context and Problem Statement

package/.xdrs/agentme/edrs/application/010-golang-project-tooling.md

@@ -1,3 +1,8 @@
+---
+name: agentme-edr-010-go-project-tooling-and-structure
+description: Defines the standard Go project toolchain, layout, and Makefile workflow for agentme-based projects. Use when scaffolding or reviewing Go projects.
+---
+
 # agentme-edr-010: Go project tooling and structure
 
 ## Context and Problem Statement

package/.xdrs/agentme/edrs/application/014-python-project-tooling.md

@@ -0,0 +1,112 @@
+---
+name: agentme-edr-014-python-project-tooling-and-structure
+description: Defines the standard Python project toolchain, layout, and Makefile workflow using uv, ruff, pyright, pytest, and pip-audit. Use when scaffolding or reviewing Python projects.
+---
+
+# agentme-edr-014: Python project tooling and structure
+
+## Context and Problem Statement
+
+Python projects often drift into mixed dependency managers, duplicated configuration files, and ad hoc quality checks, which makes onboarding and CI pipelines inconsistent.
+
+What tooling and project structure should Python projects follow to ensure consistency, quality, and ease of development?
+
+## Decision Outcome
+
+**Use a uv-managed Python project with `pyproject.toml`, `ruff`, `pyright`, `pytest`, `pytest-cov`, `pip-audit`, and a Makefile as the only development entry point.**
+
+A single dependency manager, one canonical config file, and standard targets keep Python projects predictable for contributors and CI.
+
+### Implementation Details
+
+#### Tooling
+
+| Tool | Purpose |
+|------|---------|
+| **uv** | Dependency management, lockfile management, virtualenv sync, build, publish |
+| **pyproject.toml** | Single source of truth for package metadata and tool configuration |
+| **ruff** | Formatting, import sorting, linting, and common code-quality checks |
+| **pyright** | Static type checking |
+| **pytest** | Test runner |
+| **pytest-cov** | Coverage reporting and threshold enforcement |
+| **pip-audit** | Dependency CVE audit |
+
+All routine commands must run through the project `Makefile`, never by calling `uv`, `ruff`, `pytest`, or `pyright` directly in docs, CI, or daily development workflows.
+
+When the repository defines a root `.mise.toml`, Python and uv must be pinned there and commands should run through `mise exec --` or an activated Mise shell.
+
+#### Project structure
+
+```text
+/
+├── .mise.toml              # optional but required when the repo uses Mise
+├── Makefile                # single entry point for build/lint/test/run tasks
+├── pyproject.toml          # package metadata + tool config
+├── uv.lock                 # committed lockfile
+├── README.md               # Getting Started near the top
+├── src/
+│   └── <package_name>/
+│       ├── __init__.py
+│       ├── __main__.py     # when the project exposes a CLI
+│       └── ...
+├── tests/
+│   ├── conftest.py         # shared fixtures when needed
+│   └── test_*.py
+└── examples/               # required for libraries and shared utilities
+    ├── Makefile
+    └── basic-usage/
+```
+
+Use the `src/` layout for import safety and packaging clarity. Keep tests under `tests/` and shared test setup in `tests/conftest.py`. Do not introduce `requirements.txt`, `setup.py`, `setup.cfg`, `tox.ini`, `ruff.toml`, or `pyrightconfig.json` by default; keep project metadata and tool configuration in `pyproject.toml`.
+
+Libraries and shared utilities must include an `examples/` folder and wire example execution into the root `test` flow, following [agentme-edr-007](../principles/007-project-quality-standards.md).
+
+#### `pyproject.toml`
+
+- Runtime dependencies belong in `[project.dependencies]`.
+- Development-only tooling belongs in `[dependency-groups].dev`.
+- Configure Ruff, Pyright, and Pytest in `pyproject.toml` under their `tool.*` sections.
+- Commit `uv.lock` and keep it in sync with `pyproject.toml`.
+- Expose CLI entry points with `[project.scripts]` when the project provides commands.
+
+Ruff is the default formatter and linter. Do not add Black, isort, or Flake8 unless another XDR for that repository explicitly requires them.
+
+Pyright must run on every lint pass. `typeCheckingMode = "standard"` is the minimum baseline; projects may raise this to `strict` when the codebase is ready.
+
+Pytest coverage must fail below 80% line and branch coverage, following [agentme-edr-004](../principles/004-unit-test-requirements.md).
+
+#### Makefile targets
+
+The commands below assume invocation through `mise exec -- make <target>` when the repository uses Mise, or plain `make <target>` inside an activated project environment.
+
+| Target | Description |
+|--------|-------------|
+| `install` | `uv sync --frozen --all-extras --dev` |
+| `build` | `uv sync --frozen --all-extras --dev && uv build` |
+| `lint` | `uv run ruff format --check . && uv run ruff check . && uv run pyright && uv run pip-audit` |
+| `lint-fix` | `uv run ruff format . && uv run ruff check . --fix && uv run pyright && uv run pip-audit` |
+| `test-unit` | `uv run pytest --cov=src/<package_name> --cov-branch --cov-report=term-missing --cov-fail-under=80` |
+| `test-examples` | Run `examples/` through its own `Makefile` when the project is a library/utility |
+| `test` | Run `test-unit`, then `test-examples` when applicable |
+| `clean` | Remove `.venv/`, `dist/`, `.pytest_cache/`, `.ruff_cache/`, `.coverage`, `htmlcov/` |
+| `all` | `build lint test` |
+| `update-lockfile` | `uv lock --upgrade` |
+| `run` | `uv run python -m <package_name>` or the project CLI entry point |
+| `dev` | Same as `run`, optionally with repository-specific dev defaults |
+| `publish` | `uv publish` after versioning and packaging are complete |
+
+The root `Makefile` must remain the only contract for CI and contributors, in line with [agentme-edr-008](../devops/008-common-targets.md).
+
+## Considered Options
+
+* (REJECTED) **Mixed Python tooling** - Separate tools and config files such as `pip`, `requirements.txt`, `setup.cfg`, `flake8`, and `mypy`.
+  * Reason: Increases cognitive load, duplicates configuration, and weakens the standard command surface across projects.
+* (CHOSEN) **uv + `pyproject.toml` + Ruff/Pyright/Pytest toolchain** - One dependency manager, one config file, and one Makefile entry point.
+  * Reason: Keeps packaging, dependency locking, static analysis, security auditing, and test execution consistent.
+
+## References
+
+- [agentme-edr-004](../principles/004-unit-test-requirements.md) - Coverage and unit-test baseline
+- [agentme-edr-007](../principles/007-project-quality-standards.md) - Examples and quality requirements
+- [agentme-edr-008](../devops/008-common-targets.md) - Standard Makefile target names
+- [005-create-python-project](skills/005-create-python-project/SKILL.md) - Scaffold a project following this EDR

package/.xdrs/agentme/edrs/application/015-cli-tool-standards.md

@@ -0,0 +1,107 @@
+---
+name: agentme-edr-015-cli-tool-standards
+description: Defines how distributable CLI tools should separate command handling from library logic and expose consistent command behavior. Use when designing or reviewing CLI interfaces.
+applied-to: Distributable CLI tools and their standalone libraries
+---
+
+# agentme-edr-015: CLI tool standards
+
+## Context and Problem Statement
+
+CLI projects often mix command parsing, business logic, config loading, and output formatting in one entry point, making them hard to reuse as libraries and inconsistent to operate.
+
+What structure and interface rules should distributable CLI tools follow so they remain discoverable, scriptable, and reusable outside the command line?
+
+## Decision Outcome
+
+**Use a command-oriented CLI as a thin adapter over a standalone library, with CLI-owned config discovery, mandatory help/version/verbose flags, and consistent progress and exit behavior.**
+
+This keeps the user-facing command predictable while preserving a clean library API for embedding, testing, and automation.
+
+### Implementation Details
+
+#### CLI command surface
+
+- CLI tools should default to the format `[tool] [command] [options] [arguments]`.
+- Example: `filedist extract --packages=test mydir`
+- A single-action tool may omit `[command]` only when adding a subcommand would be artificial and there is no meaningful action split.
+- Every CLI tool must expose:
+  - `--help` on the root command
+  - `--version` on the root command
+  - `--verbose` on the root command and on subcommands when flags are parsed per command
+- Root `--help` output must list all available commands, key options, and usage examples. Command-specific help must describe that command's arguments and options.
+
+#### CLI to library separation
+
+- Structure the software as `cli -> lib`.
+- The CLI layer must only parse arguments, load config, call the library, and format output.
+- Domain logic must live in the library and be usable without CLI globals such as `argv`, `stdout`, or process exit handlers.
+- Every feature available through the CLI must also be available through the library API.
+- Organize the library by action so the mapping stays direct and obvious.
+  - `extract` command -> `extract(...)`
+  - `validate` command -> `validate(...)`
+- Avoid one generic library `run()` entry point that hides action-specific contracts behind switches or string commands.
+
+#### Library API shape
+
+- Each CLI action should map to a dedicated exported API with typed inputs and outputs appropriate for the language.
+- Library APIs should accept in-memory options objects or typed parameters, not require config files or environment variables unless library-level config-file support is an explicit requirement.
+- The CLI layer is responsible for translating flags, positional arguments, and config-file contents into library inputs.
+- The library should return explicit results and errors so the CLI can decide what to print and which exit code to use.
+
+#### Configuration
+
+- Prefer flags and positional arguments for simple inputs.
+- When configuration becomes long, nested, or repetitive, support a config file instead of pushing all values into flags.
+- By default, config-file discovery and loading must happen in the CLI layer, not in the library layer.
+- When a config file is supported, the CLI should try to load a JSON config file from `[cwd]/.[cli-name]rc` by default.
+- The CLI should also support an explicit config path flag such as `--config`.
+- For JavaScript tools, `cosmiconfig` is an acceptable implementation. Equivalent discovery libraries are acceptable in other ecosystems.
+- The library must not depend on the presence of the config file; it should receive parsed configuration values from the CLI layer.
+- The library may load or parse config files only when that behavior is an explicit requirement of the library contract for non-CLI consumers as well.
+
+#### Output and progress
+
+- Standard output must show a start message when work begins and a result message when work completes successfully.
+- When processing is long-running or multi-stage, print concise intermediate progress messages.
+- `--verbose` must reveal more internal detail about what the tool is doing without changing the meaning of the command result.
+- Default output should stay concise and readable for humans.
+- Errors should be written to standard error with an actionable message. Stack traces or raw internal errors should stay hidden by default and may be shown in verbose mode.
+
+#### Exit behavior
+
+- Exit with `0` only when the requested action completed successfully.
+- Exit with `1` when the requested action could not be completed.
+- The library should surface failure as return values, result objects, or language-idiomatic errors; the CLI is responsible for converting that outcome into user-facing messages and process exit codes.
+
+#### Documentation
+
+- `README.md` must include at least 4 CLI usage examples.
+- `README.md` must include at least 2 library API examples for the same operation also available through the CLI.
+- If the tool supports config files, at least 1 README example should show config-file usage.
+- Examples must use the public command and public library API, not internal modules or private files.
+
+#### Distribution and versioning
+
+- The implementation language is project-dependent, but the packaging and entry-point strategy must match how users are expected to run the tool.
+- Choose language tooling that stays compatible with ecosystem launchers such as `npx`, `pnpm dlx`, `uvx`, or equivalent distribution commands for that ecosystem.
+- `--version` must print the same version declared in the published package or release artifact metadata.
+- Do not hard-code a second version string that can drift from the published package version.
+- Language-specific project structure and packaging rules still apply and should be combined with this XDR, especially [agentme-edr-003](003-javascript-project-tooling.md), [agentme-edr-010](010-golang-project-tooling.md), and [agentme-edr-014](014-python-project-tooling.md).
+
+## Considered Options
+
+* (REJECTED) **Ad hoc CLIs with embedded business logic** - Keep parsing, processing, config loading, and output formatting inside a single entry point.
+  * Reason: Makes the tool hard to test, hard to reuse as a library, and inconsistent across commands.
+* (CHOSEN) **Thin CLI adapter over action-oriented library APIs** - Keep the CLI responsible for user interaction and the library responsible for the actual behavior.
+  * Reason: Preserves a clean programmatic API, keeps command behavior discoverable, and makes the CLI-to-library mapping easy to maintain.
+
+## References
+
+- [agentme-edr-003](003-javascript-project-tooling.md) - JavaScript project packaging and structure
+- [agentme-edr-007](../principles/007-project-quality-standards.md) - README and examples baseline
+- [agentme-edr-008](../devops/008-common-targets.md) - Standard command names for project entry points
+- [agentme-edr-009](../principles/009-error-handling.md) - Process error signaling and error handling expectations
+- [agentme-edr-010](010-golang-project-tooling.md) - Go CLI structure and verbose logging baseline
+- [agentme-edr-014](014-python-project-tooling.md) - Python packaging and CLI entry-point guidance
+- [cosmiconfig](https://github.com/cosmiconfig/cosmiconfig) - Example JSON configuration discovery library for JavaScript CLIs

package/.xdrs/agentme/edrs/application/skills/005-create-python-project/SKILL.md

@@ -0,0 +1,289 @@
+---
+name: 005-create-python-project
+description: >
+  Scaffolds the initial boilerplate structure for a Python library or CLI project following the
+  standard tooling and layout defined in agentme-edr-014. Activate this skill when the user asks
+  to create, scaffold, or initialize a new Python package, CLI, library, or similar project
+  structure.
+metadata:
+  author: flaviostutz
+  version: "1.0"
+compatibility: Python 3.12+
+---
+
+## Overview
+
+Creates a complete Python project from scratch using `uv`, `pyproject.toml`, Ruff, Pyright,
+Pytest, and Makefiles. The default layout uses `src/<package_name>/`, `tests/`, and `examples/`
+for libraries and shared utilities.
+
+Related EDR: [agentme-edr-014](../../014-python-project-tooling.md)
+
+## Instructions
+
+### Phase 1: Gather information
+
+Ask for or infer from context:
+
+- **Package name** - Python distribution/import name, e.g. `my_tool`
+- **Short description** - one sentence
+- **Author** name or GitHub username
+- **Python version** - default `3.13`
+- **Project kind** - `library` or `cli`
+- **Primary entry point** - first module or command name to scaffold
+- **GitHub repo URL** - optional, for project metadata
+- **Confirm target directory** - default: current workspace root
+
+### Phase 2: Create root files
+
+Create these files first.
+
+**`./Makefile`**
+
+```makefile
+SHELL := /bin/bash
+
+PACKAGE_NAME ?= your_package
+MISE := mise exec --
+
+all: build lint test
+
+install:
+	uv sync --frozen --all-extras --dev
+
+build: install
+	uv build
+
+lint:
+	uv run ruff format --check .
+	uv run ruff check .
+	uv run pyright
+	uv run pip-audit
+
+lint-fix:
+	uv run ruff format .
+	uv run ruff check . --fix
+	uv run pyright
+	uv run pip-audit
+
+test: test-unit test-examples
+
+test-unit:
+	uv run pytest --cov=src/$(PACKAGE_NAME) --cov-branch --cov-report=term-missing --cov-fail-under=80
+
+test-examples:
+	@if [ -d examples ]; then $(MAKE) -C examples test PACKAGE_NAME=$(PACKAGE_NAME); else echo "No examples/ directory. Skipping"; fi
+
+run:
+	uv run python -m $(PACKAGE_NAME)
+
+dev: run
+
+update-lockfile:
+	uv lock --upgrade
+
+clean:
+	rm -rf .venv dist .pytest_cache .ruff_cache .coverage htmlcov
+	find . -type d -name __pycache__ -prune -exec rm -rf {} +
+```
+
+If the repository already uses Mise, adapt the commands to `$(MISE) uv ...` and pin both Python and uv in `.mise.toml`.
+
+**`./pyproject.toml`**
+
+Replace placeholders such as `[package-name]`, `[description]`, `[author]`, and `[python-version]`.
+
+```toml
+[project]
+name = "[package-name]"
+version = "0.0.1"
+description = "[description]"
+readme = "README.md"
+requires-python = ">=[python-version]"
+dependencies = []
+
+[[project.authors]]
+name = "[author]"
+
+[project.optional-dependencies]
+dev = []
+
+[dependency-groups]
+dev = [
+  "pip-audit>=2.9.0",
+  "pyright>=1.1.400",
+  "pytest>=8.4.0",
+  "pytest-cov>=6.1.0",
+  "ruff>=0.11.0",
+]
+
+[build-system]
+requires = ["hatchling>=1.27.0"]
+build-backend = "hatchling.build"
+
+[tool.ruff]
+line-length = 100
+target-version = "py313"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "B", "UP"]
+
+[tool.pyright]
+include = ["src", "tests"]
+venvPath = "."
+venv = ".venv"
+typeCheckingMode = "standard"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-q"
+```
+
+Use `pyproject.toml` as the single configuration file. Do not add `requirements.txt`,
+`setup.py`, `setup.cfg`, `ruff.toml`, or `pyrightconfig.json` by default.
+
+**`./.gitignore`**
+
+```gitignore
+.venv/
+dist/
+build/
+.pytest_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+__pycache__/
+*.pyc
+```
+
+**`./README.md`**
+
+Put Getting Started near the top.
+
+```markdown
+# [package-name]
+
+[description]
+
+## Getting Started
+
+```sh
+uv sync --dev
+make test
+```
+
+```python
+from [package-name] import hello
+
+print(hello("world"))
+```
+```
+
+### Phase 3: Create the package and tests
+
+Create this baseline structure.
+
+**`src/[package_name]/__init__.py`**
+
+```python
+from .core import hello
+
+__all__ = ["hello"]
+```
+
+**`src/[package_name]/core.py`**
+
+```python
+def hello(name: str) -> str:
+    return f"Hello, {name}!"
+```
+
+**`src/[package_name]/__main__.py`**
+
+Use this only for CLI-oriented projects.
+
+```python
+from .core import hello
+
+
+def main() -> None:
+    print(hello("world"))
+
+
+if __name__ == "__main__":
+    main()
+```
+
+**`tests/test_core.py`**
+
+```python
+from [package_name].core import hello
+
+
+def test_hello() -> None:
+    assert hello("world") == "Hello, world!"
+```
+
+If two or more test files need shared fixtures, create `tests/conftest.py` and move shared setup there.
+
+### Phase 4: Create examples for libraries and utilities
+
+If the project is a library or shared utility, add an `examples/` directory and execute it from the root `test` target.
+
+**`examples/Makefile`**
+
+```makefile
+test:
+	$(MAKE) -C basic-usage run PACKAGE_NAME=$(PACKAGE_NAME)
+```
+
+**`examples/basic-usage/Makefile`**
+
+```makefile
+run:
+	uv run python main.py
+```
+
+**`examples/basic-usage/main.py`**
+
+```python
+from [package_name] import hello
+
+
+print(hello("world"))
+```
+
+Examples must import the built package as a consumer would. Avoid relative imports back into `src/`.
+
+### Phase 5: Verify
+
+After creating the files:
+
+1. Run `uv lock`.
+2. Run `make lint-fix`.
+3. Run `make test`.
+4. Run `make build`.
+5. Fix all failures before finishing.
+
+## Examples
+
+**Input:** "Create a Python library called `event_tools`"
+- Create `pyproject.toml`, `Makefile`, `src/event_tools/`, `tests/`, and `examples/`
+- Configure `uv`, Ruff, Pyright, Pytest, `pytest-cov`, and `pip-audit`
+- Verify with `make lint-fix`, `make test`, and `make build`
+
+**Input:** "Scaffold a Python CLI package"
+- Add `src/<package_name>/__main__.py`
+- Add `[project.scripts]` in `pyproject.toml` when the command name must differ from the module name
+- Keep the same Makefile and quality checks
+
+## Edge Cases
+
+- If the repository already has a root `.mise.toml`, pin Python and uv there instead of assuming host-installed tools.
+- If the project is fewer than 100 lines and explicitly marked as a spike or experiment, examples and linting may be skipped only when another applicable XDR allows it.
+- If the user asks for an app with framework-specific needs such as FastAPI or Django, keep this baseline and add the framework config on top instead of replacing it.
+
+## References
+
+- [agentme-edr-014](../../014-python-project-tooling.md)
+- [_core-adr-003 - Skill standards](../../../../../_core/adrs/principles/003-skill-standards.md)

package/.xdrs/agentme/edrs/devops/005-monorepo-structure.md

@@ -1,3 +1,8 @@
+---
+name: agentme-edr-005-monorepo-structure
+description: Defines the standard monorepo layout, naming, and build conventions using shared areas, Mise, and Makefiles. Use when creating or reviewing monorepos.
+---
+
 # agentme-edr-005: Monorepo structure
 
 ## Context and Problem Statement

package/.xdrs/agentme/edrs/devops/006-github-pipelines.md

@@ -1,3 +1,8 @@
+---
+name: agentme-edr-006-github-ci-cd-pipelines
+description: Defines the standard GitHub Actions workflow split for CI, release tagging, and publishing. Use when configuring project automation.
+---
+
 # agentme-edr-006: GitHub CI/CD pipelines
 
 ## Context and Problem Statement
@@ -129,7 +134,7 @@ jobs:
 
 *Why rebuild on publish:* The checkout is done from the exact tag commit. Rebuilding ensures the published artifact matches exactly what is tagged, rather than relying on a prior CI artifact.
 
-*Why `id-token: write`:* Required for npm provenance attestation via `npm publish --provenance`, as specified in [agentme-edr-003](003-javascript-project-tooling.md).
+*Why `id-token: write`:* Required for npm provenance attestation via `npm publish --provenance`, as specified in [agentme-edr-003](../application/003-javascript-project-tooling.md).
 
 ---
 

package/.xdrs/agentme/edrs/devops/008-common-targets.md

@@ -1,3 +1,8 @@
+---
+name: agentme-edr-008-common-development-script-names
+description: Defines standard development command names and lifecycle groups across projects, regardless of the underlying runner. Use when designing build, lint, test, and release entry points.
+---
+
 # agentme-edr-008: Common development script names
 
 ## Context and Problem Statement

package/.xdrs/agentme/edrs/devops/skills/002-monorepo-setup/SKILL.md

@@ -13,12 +13,12 @@ metadata:
 
 ## Overview
 
-Creates or extends a monorepo that follows the standard layout from [agentme-edr-005](../../../.xdrs/agentme/edrs/devops/005-monorepo-structure.md):
+Creates or extends a monorepo that follows the standard layout from [agentme-edr-005](../../005-monorepo-structure.md):
 top-level application folders, a shared library area, Mise-managed tooling, and Makefiles at every
 level so any contributor can build, lint, and test any part of the monorepo with a single,
 predictable command.
 
-Related EDRs: [agentme-edr-005](../../../.xdrs/agentme/edrs/devops/005-monorepo-structure.md), [agentme-edr-013](../../../.xdrs/agentme/edrs/governance/013-contributing-guide-requirements.md)
+Related EDRs: [agentme-edr-005](../../005-monorepo-structure.md), [agentme-edr-013](../../../governance/013-contributing-guide-requirements.md)
 
 ## Instructions
 

package/.xdrs/agentme/edrs/governance/013-contributing-guide-requirements.md

@@ -1,3 +1,8 @@
+---
+name: agentme-edr-013-contributing-guide-requirements
+description: Defines the minimum contributor workflow guidance required in root CONTRIBUTING.md files. Use when scaffolding or reviewing contribution processes.
+---
+
 # agentme-edr-013: Contributing guide requirements
 
 ## Context and Problem Statement

package/.xdrs/agentme/edrs/index.md

@@ -26,6 +26,8 @@ Language and framework-specific tooling and project structure.
 
 - [agentme-edr-003](application/003-javascript-project-tooling.md) - **JavaScript project tooling and structure** *(includes skill: [001-create-javascript-project](application/skills/001-create-javascript-project/SKILL.md))*
 - [agentme-edr-010](application/010-golang-project-tooling.md) - **Go project tooling and structure** *(includes skill: [003-create-golang-project](application/skills/003-create-golang-project/SKILL.md))*
+- [agentme-edr-014](application/014-python-project-tooling.md) - **Python project tooling and structure** *(includes skill: [005-create-python-project](application/skills/005-create-python-project/SKILL.md))*
+- [agentme-edr-015](application/015-cli-tool-standards.md) - **CLI tool standards**
 - [004-select-relevant-xdrs](application/skills/004-select-relevant-xdrs/SKILL.md) - **Select relevant XDRs**
 
 ## Devops

package/.xdrs/agentme/edrs/observability/011-service-health-check-endpoint.md

@@ -1,3 +1,8 @@
+---
+name: agentme-edr-011-service-health-check-endpoint
+description: Defines the required health endpoint contract for service availability and dependency readiness checks. Use when implementing or reviewing service health endpoints.
+---
+
 # agentme-edr-011: Service health check endpoint
 
 ## Context and Problem Statement

package/.xdrs/agentme/edrs/principles/002-coding-best-practices.md

@@ -1,3 +1,8 @@
+---
+name: agentme-edr-002-coding-best-practices
+description: Defines cross-language coding practices for keeping code readable, modular, and synchronized with tests and documentation. Apply across projects adopting agentme engineering standards.
+---
+
 # agentme-edr-002: Coding best practices
 
 ## Context and Problem Statement

package/.xdrs/agentme/edrs/principles/004-unit-test-requirements.md

@@ -1,3 +1,8 @@
+---
+name: agentme-edr-004-unit-test-requirements
+description: Defines unit test requirements for assertions, offline execution, coverage, shared setup, and real-code preference. Use when writing or reviewing tests.
+---
+
 # agentme-edr-004: Unit test requirements
 
 ## Context and Problem Statement

package/.xdrs/agentme/edrs/principles/007-project-quality-standards.md

@@ -1,3 +1,8 @@
+---
+name: agentme-edr-007-project-quality-standards
+description: Defines minimum project quality standards for README onboarding, testing, linting, XDR compliance, and runnable examples. Use when scaffolding or reviewing projects.
+---
+
 # agentme-edr-007: Project quality standards
 
 ## Context and Problem Statement
@@ -60,7 +65,7 @@ A unit test suite must run automatically before every release. Failing tests mus
 
 ### 3. The project MUST comply with all applicable workspace XDRs
 
-All XDRs that apply to the project's scope (as listed in [.xdrs/index.md](../../../../index.md)) must be followed. A deviation requires a project-local XDR documenting the override.
+All XDRs that apply to the project's scope (as listed in [.xdrs/index.md](../../../index.md)) must be followed. A deviation requires a project-local XDR documenting the override.
 
 **Requirements:**
 - Review applicable XDRs before any significant implementation
@@ -80,7 +85,7 @@ Projects larger than 10 files or 200 lines of code must have a linter configured
 
 **Exception:** Projects with fewer than 100 lines of code, or whose `README.md` prominently marks them as a **Spike** or **Experiment**, are exempt from this requirement. Such projects must never be deployed to production.
 
-**Reference:** [agentme-edr-003](003-javascript-project-tooling.md) for JavaScript-specific tooling.
+**Reference:** [agentme-edr-003](../application/003-javascript-project-tooling.md) for JavaScript-specific tooling.
 
 ---
 

package/.xdrs/agentme/edrs/principles/009-error-handling.md

@@ -1,3 +1,8 @@
+---
+name: agentme-edr-009-error-handling
+description: Defines error handling practices for catching, propagating, surfacing, and testing failures consistently across projects. Use when implementing interfaces and failure paths.
+---
+
 # agentme-edr-009: Error handling
 
 ## Context and Problem Statement

package/.xdrs/agentme/edrs/principles/012-continuous-xdr-enrichment.md

@@ -1,3 +1,8 @@
+---
+name: agentme-edr-012-continuous-xdr-improvement-policy
+description: Defines how teams should promote reusable implementation guidance into shared XDRs instead of keeping it in prompts or local habits. Use when recurring decisions surface during delivery.
+---
+
 # agentme-edr-012: Continuous xdr improvement policy
 
 ## Context and Problem Statement
@@ -33,7 +38,7 @@ Developers must treat reusable missing guidance discovered during implementation
 
 ## References
 
-- [_core-adr-001](../../../_core/adrs/principles/001-xdr-standards.md)
+- [_core-adr-001](../../../_core/adrs/principles/001-xdrs-core.md)
 - [_core-article-001](../../../_core/adrs/principles/articles/001-xdrs-overview.md)
 - [agentme-article-001](articles/001-continuous-xdr-improvement.md)
 - [002-write-xdr skill](../../../../.github/skills/002-write-xdr/SKILL.md)

package/.xdrs/agentme/edrs/principles/articles/001-continuous-xdr-improvement.md

@@ -51,7 +51,7 @@ Good opening questions:
 
 ### How should you organize the XDR?
 
-Follow the XDR template from [_core-adr-001](../../../_core/adrs/principles/001-xdr-standards.md). Keep the document small, explicit, and decision-focused.
+Follow the XDR template from [_core-adr-001](../../../../_core/adrs/principles/001-xdrs-core.md). Keep the document small, explicit, and decision-focused.
 
 Use this checklist:
 
@@ -87,7 +87,7 @@ If the same clarification would likely be needed in another feature, by another
 
 ## References
 
-- [_core-adr-001](../../../_core/adrs/principles/001-xdr-standards.md) - XDR structure, numbering, and mandatory template
-- [_core-article-001](../../../_core/adrs/principles/articles/001-xdrs-overview.md) - XDR introduction and general adoption guidance
+- [_core-adr-001](../../../../_core/adrs/principles/001-xdrs-core.md) - XDR structure, numbering, and mandatory template
+- [_core-article-001](../../../../_core/adrs/principles/articles/001-xdrs-overview.md) - XDR introduction and general adoption guidance
 - [agentme-edr-012](../012-continuous-xdr-enrichment.md) - Shared-first XDR enrichment policy and 80% coverage target
 - [002-write-xdr skill](../../../../../.github/skills/002-write-xdr/SKILL.md) - Step-by-step procedure for drafting new XDRs

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "agentme",
-  "version": "0.3.3",
+  "version": "0.5.0",
   "description": "",
   "dependencies": {
     "filedist": "^0.26.0",
-    "xdrs-core": "^0.14.5"
+    "xdrs-core": "^0.16.0"
   },
   "bin": "bin/filedist.js",
   "files": [
@@ -90,11 +90,30 @@
             ".github/agents/speckit*",
             ".github/prompts/speckit*",
             ".specify/**"
+          ],
+          "exclude": [
+            ".specify/templates/**"
           ]
         },
         "output": {
           "path": ".",
-          "gitignore": false
+          "gitignore": false,
+          "readonly": true
+        },
+        "presets": [
+          "speckit"
+        ]
+      },
+      {
+        "selector": {
+          "files": [
+            ".specify/templates/**"
+          ]
+        },
+        "output": {
+          "path": ".",
+          "gitignore": false,
+          "readonly": false
         },
         "presets": [
           "speckit"
@@ -110,6 +129,7 @@
           "path": ".",
           "managed": false,
           "skipIfExists": true,
+          "readonly": false,
           "gitignore": false
         },
         "presets": [