agentme 0.3.2 → 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
@@ -8,7 +13,7 @@ What tooling and project structure should JavaScript/TypeScript projects follow
 
 ## Decision Outcome
 
-**Use pnpm, tsc, esbuild, eslint, and jest with a standard layout separating library code (`lib/`) from runnable usage examples (`examples/`), coordinated by root-level Makefiles.**
+**Use a Mise-managed Node.js and pnpm toolchain together with pnpm, tsc, esbuild, eslint, and jest in a standard layout separating library code (`lib/`) from runnable usage examples (`examples/`), coordinated by root-level Makefiles.**
 
 Clear, consistent tooling and layout enable fast onboarding, reliable CI pipelines, and a predictable developer experience across projects.
 
@@ -18,30 +23,40 @@ Clear, consistent tooling and layout enable fast onboarding, reliable CI pipelin
 
 | Tool | Purpose |
 |------|---------|
+| **Mise** | Tool version management for Node.js, pnpm, and project CLIs |
 | **pnpm** | Package manager — strict linking, workspace support, fast installs |
 | **tsc** | TypeScript compilation — type checking, declaration generation |
 | **esbuild** | Bundling — fast bundling for distribution or single-binary outputs |
 | **eslint** | Linting — code style and quality enforcement |
 | **jest** | Testing — unit and integration test runner |
 
-All commands are run exclusively through Makefiles, not through `package.json` scripts.
+All commands are run exclusively through Makefiles, not through `package.json` scripts. The repository root must define a `.mise.toml` that pins at least Node.js and pnpm, and Makefile targets must run through `mise exec --` or an activated Mise shell.
 
 #### ESLint
 
-Use `@stutzlab/eslint-config` as the base ESLint config. Use ESLint 9 flat config format (`lib/eslint.config.js`).
+Use `lib/eslint.config.mjs` as the ESLint entry point and configure it with `@stutzlab/eslint-config` plus `FlatCompat` from `@eslint/eslintrc`. Keep `package.json` in CommonJS mode without adding `"type": "module"`.
+
+In flat-config mode, Makefile lint targets MUST NOT use `--ext`; file matching is defined in `eslint.config.mjs` instead. The flat config MUST declare TypeScript file globs such as `src/**/*.ts` and point `parserOptions.project` to `./tsconfig.json`.
+
+#### TypeScript and Jest
+
+Use a single `lib/tsconfig.json` for both build and type-aware linting. Keep co-located `*.test.ts` files included in that config so ESLint can resolve them through `parserOptions.project`, and rely on the Makefile cleanup step to remove compiled test artifacts from `dist/` after `tsc` runs.
+
+When `tsconfig.json` extends `@tsconfig/node24/tsconfig.json`, the default `module` is `nodenext`. `ts-jest` still runs in CommonJS mode by default, so `lib/jest.config.js` MUST configure the `ts-jest` transform with an inline `tsconfig` override that sets `module: 'commonjs'`. Do not use the deprecated `globals['ts-jest']` configuration style.
 
 #### Project structure
 
 ```
 /                          # workspace root
+├── .mise.toml             # pinned Node.js and pnpm versions
 ├── Makefile               # delegates build/lint/test to /lib and /examples
 ├── README.md              # Quick Start first; used as npm registry page
 ├── lib/                   # the published npm package
 │   ├── Makefile           # build, lint, test, publish targets
 │   ├── package.json       # package manifest
-│   ├── tsconfig.json      # TypeScript config
+│   ├── tsconfig.json      # TypeScript config for build and linting
 │   ├── jest.config.js     # Jest config
-│   ├── eslint.config.js   # ESLint config (ESLint 9 flat config)
+│   ├── eslint.config.mjs  # ESLint config (ESLint 9 flat config)
 │   └── src/               # all TypeScript source files
 │       ├── index.ts       # public API re-exports
 │       └── *.test.ts      # test files co-located with source
@@ -53,7 +68,9 @@ Use `@stutzlab/eslint-config` as the base ESLint config. Use ESLint 9 flat confi
         └── package.json
 ```
 
-The root `Makefile` delegates every target to `/lib` then `/examples` in sequence.
+The root `Makefile` delegates every target to `/lib` then `/examples` in sequence and is expected to execute module commands inside the repository's Mise-managed environment.
+
+The commands below assume they are invoked through `mise exec -- make <target>` or from an activated Mise shell.
 
 #### lib/Makefile targets
 

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/001-create-javascript-project/SKILL.md

@@ -2,7 +2,7 @@
 name: 001-create-javascript-project
 description: >
   Scaffolds the initial boilerplate structure for a JavaScript/TypeScript library project following
-  the standard tooling and layout defined in _core-edr-003. Activate this skill when the user
+  the standard tooling and layout defined in agentme-edr-003. Activate this skill when the user
   asks to create, scaffold, or initialize a new JavaScript or TypeScript library project, npm
   package, or similar project structure.
 metadata:
@@ -42,27 +42,30 @@ Delegates every make target to `/lib` then `/examples` in sequence:
 
 ```makefile
 SHELL := /bin/bash
+MISE := mise exec --
 %:
 	@echo ''
 	@echo '>>> Running /lib:$@...'
-	@cd lib && make $@
+  @$(MISE) $(MAKE) -C lib $@
 	@echo ''
 	@echo '>>> Running /examples:$@...'
-	@cd examples && STAGE=dev make $@
+  @STAGE=dev $(MISE) $(MAKE) -C examples $@
 
 publish:
-	cd lib && make publish
+  @$(MISE) $(MAKE) -C lib publish
 
-prepare:
-	@echo "Run 'nvm use; corepack enable'"
+setup:
+  mise install
 ```
 
-**`./.nvmrc`**
+**`./.mise.toml`**
 
 ```
-24
+[tools]
+node = "24.0.0"
+pnpm = "10.14.0"
 ```
-(Replace `24` with the chosen Node.js version.)
+(Replace `24.0.0` with the chosen Node.js version and pin any additional project CLIs here.)
 
 **`./.gitignore`**
 
@@ -101,30 +104,31 @@ describe('hello', () => {
 
 ```makefile
 SHELL := /bin/bash
+MISE := mise exec --
 
 build: install
 	@rm -rf dist
-	pnpm exec tsc --outDir dist
+  $(MISE) pnpm exec tsc --outDir dist
 	@-find ./dist \( -regex '.*\.test\..*' -o -regex '.*__tests.*' \) -exec rm -rf {} \; 2> /dev/null
 	@# Create pack for use by examples to simulate real external usage
-	pnpm pack --pack-destination dist
+  $(MISE) pnpm pack --pack-destination dist
 
 build-module: install
 	@rm -rf dist
-	pnpm exec tsc --outDir dist
+  $(MISE) pnpm exec tsc --outDir dist
 	@-find ./dist \( -regex '.*\.test\..*' -o -regex '.*__tests.*' \) -exec rm -rf {} \; 2> /dev/null
 
 lint:
-	pnpm exec eslint ./src --ext .ts
+  $(MISE) pnpm exec eslint ./src
 
 lint-fix:
-	pnpm exec eslint . --ext .ts --fix
+  $(MISE) pnpm exec eslint ./src --fix
 
 test-watch:
-	pnpm exec jest --watch
+  $(MISE) pnpm exec jest --watch
 
 test:
-	pnpm exec jest --verbose
+  $(MISE) pnpm exec jest --verbose
 
 clean:
 	rm -rf node_modules
@@ -133,22 +137,25 @@ clean:
 all: build lint test
 
 install:
-	pnpm install --frozen-lockfile --config.dedupe-peer-dependents=false
+  mise install
+  $(MISE) pnpm install --frozen-lockfile --config.dedupe-peer-dependents=false
 
 publish:
-	npx -y monotag@1.26.0 current --bump-action=latest --prefix=
-	@VERSION=$$(node -p "require('./package.json').version"); \
+  $(MISE) npx -y monotag@1.26.0 current --bump-action=latest --prefix=
+  @VERSION=$$($(MISE) node -p "require('./package.json').version"); \
 	if echo "$$VERSION" | grep -q '-'; then \
 		TAG=$$(echo "$$VERSION" | sed 's/[0-9]*\.[0-9]*\.[0-9]*-\([a-zA-Z][a-zA-Z0-9]*\).*/\1/'); \
 		echo "Prerelease version $$VERSION detected, publishing with --tag $$TAG"; \
-		npm publish --no-git-checks --provenance --tag "$$TAG"; \
+    $(MISE) npm publish --no-git-checks --provenance --tag "$$TAG"; \
 	else \
-		npm publish --no-git-checks --provenance; \
+    $(MISE) npm publish --no-git-checks --provenance; \
 	fi
 ```
 
 **`lib/package.json`** (replace `[package-name]`, `[description]`, `[author]`, `[owner]`, `[repo]`):
 
+Use this dependency set.
+
 ```json
 {
   "name": "[package-name]",
@@ -161,7 +168,7 @@ publish:
     "package.json",
     "README.md"
   ],
-  "packageManager": "pnpm@8.9.0",
+  "packageManager": "pnpm@10.14.0",
   "scripts": {},
   "repository": {
     "type": "git",
@@ -174,19 +181,23 @@ publish:
   },
   "homepage": "https://github.com/[owner]/[repo]#readme",
   "devDependencies": {
-    "@babel/preset-typescript": "^7.21.0",
+    "@eslint/eslintrc": "^3.3.1",
     "@stutzlab/eslint-config": "^3.2.1",
-    "@tsconfig/node24": "^24.0.0",
-    "@types/jest": "^29.5.0",
+    "@tsconfig/node24": "^24.0.1",
+    "@types/jest": "^29.5.14",
+    "@typescript-eslint/eslint-plugin": "^8.31.0",
+    "@typescript-eslint/parser": "^8.31.0",
     "esbuild": "^0.20.0",
-    "eslint": "^8.57.0",
+    "eslint": "^9.25.1",
     "jest": "^29.7.0",
-    "ts-jest": "^29.1.0",
-    "typescript": "^5.3.0"
+    "ts-jest": "^29.4.0",
+    "typescript": "^5.9.0"
   }
 }
 ```
 
+Keep `package.json` without `"type": "module"`. Use `eslint.config.mjs` as the ESLint entry point so Jest can continue to run with its default CommonJS runtime.
+
 **`lib/tsconfig.json`**:
 
 ```json
@@ -200,39 +211,65 @@ publish:
     "sourceMap": true
   },
   "include": ["src/**/*"],
-  "exclude": ["node_modules", "dist", "**/*.test.ts"]
+  "exclude": ["node_modules", "dist"]
 }
 ```
 
+Use this single tsconfig for both build and type-aware linting. Keep `*.test.ts` included so ESLint can resolve them through `parserOptions.project`, and rely on the existing `dist/` cleanup in the Makefile to remove emitted test files after compilation.
+
 **`lib/jest.config.js`**:
 
 ```javascript
 module.exports = {
-  preset: 'ts-jest',
   testEnvironment: 'node',
   testMatch: ['**/*.test.ts'],
   collectCoverageFrom: ['src/**/*.ts', '!src/**/*.test.ts'],
+  transform: {
+    '^.+\\.tsx?$': [
+      'ts-jest',
+      {
+        tsconfig: {
+          module: 'commonjs',
+        },
+      },
+    ],
+  },
 };
 ```
 
-**`lib/eslint.config.js`** (ESLint 9 flat config format):
+This avoids the deprecated `globals['ts-jest']` configuration style while forcing `ts-jest` to transpile with CommonJS instead of the `nodenext` default inherited from `@tsconfig/node24`.
+
+**`lib/eslint.config.mjs`** (ESLint 9 flat config format):
 
 ```js
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { FlatCompat } from '@eslint/eslintrc';
 import baseConfig from '@stutzlab/eslint-config';
 
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+const compat = new FlatCompat({
+  baseDirectory: __dirname,
+});
+
 export default [
-  ...baseConfig,
+  ...compat.config(baseConfig),
   {
+    files: ['src/**/*.ts'],
     languageOptions: {
       parserOptions: {
         project: ['./tsconfig.json'],
-        tsconfigRootDir: process.cwd(),
+        tsconfigRootDir: __dirname,
       },
     },
   },
 ];
 ```
 
+Do not name this file `eslint.config.js` unless the generated package also opts into ESM with `"type": "module"`, because that produces Node.js warnings and conflicts with the recommended Jest CommonJS setup.
+
 ---
 
 ### Phase 4: Create `examples/`
@@ -335,17 +372,19 @@ Review all created files and confirm:
 - [ ] `lib/src/index.ts` exports at least one symbol
 - [ ] `lib/src/index.test.ts` has at least one passing test
 - [ ] `lib/package.json` has `main`, `types`, and `files` set correctly
+- [ ] `lib/tsconfig.json` includes co-located `src/**/*.test.ts` files for ESLint type-aware parsing
+- [ ] `lib/eslint.config.mjs` points `parserOptions.project` to `tsconfig.json`
 - [ ] `README.md` starts with Quick Start containing a code example
 - [ ] All `[package-name]` placeholders are replaced with the actual name
-- [ ] Structure matches the layout in [_core-edr-003](../../003-javascript-project-tooling.md)
+- [ ] Structure matches the layout in [agentme-edr-003](../../003-javascript-project-tooling.md)
 
 ## Examples
 
 **User:** "Create a new TypeScript library project called `retry-client`"
 
 **Agent action:** Gathers: name=`retry-client`, default Node.js 24, then creates:
-- `./Makefile`, `./.nvmrc`, `./.gitignore`
-- `lib/src/index.ts`, `lib/src/index.test.ts`, `lib/Makefile`, `lib/package.json`, `lib/tsconfig.json`, `lib/jest.config.js`, `lib/eslint.config.js`
+- `./Makefile`, `./.mise.toml`, `./.gitignore`
+- `lib/src/index.ts`, `lib/src/index.test.ts`, `lib/Makefile`, `lib/package.json`, `lib/tsconfig.json`, `lib/jest.config.js`, `lib/eslint.config.mjs`
 - `examples/Makefile`, `examples/usage-basic/package.json`, `examples/usage-basic/index.js`
 - `README.md` (Quick Start first)
 
@@ -354,7 +393,7 @@ All `[package-name]` replaced with `retry-client`.
 ## Edge Cases
 
 - **Existing files** — skip creation; adapt references to the existing structure
-- **Different Node.js version** — update `.nvmrc` and `tsconfig.json` `extends` (e.g. `@tsconfig/node22`)
+- **Different Node.js version** — update `.mise.toml` and `tsconfig.json` `extends` (e.g. `@tsconfig/node22`)
 - **CLI tool** — add `"bin": "dist/main.js"` to `package.json` and create `lib/src/main.ts` as the CLI entry point; add `esbuild` bundle target in `lib/Makefile`
 - **No examples needed** — omit the `examples/` directory; remove the `examples` delegation from root `Makefile`
 - **Binary bundling (Lambda/browser)** — add an esbuild step to `lib/Makefile`: `pnpm exec esbuild src/main.ts --bundle --platform=node --outfile=dist/bundle.js`

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/README.md

@@ -17,9 +17,9 @@ npx agentme
 If you want the version pinned in a project, add `agentme` to a repository that already has a `package.json` and run it through the local dependency:
 
 ```sh
-pnpm add -D agentme
-pnpm exec agentme extract --output . --presets basic
-pnpm exec agentme check --output . --presets basic
+mise exec -- pnpm add -D agentme
+mise exec -- pnpm exec agentme extract --output . --presets basic
+mise exec -- pnpm exec agentme check --output . --presets basic
 ```
 
 ## Overview
@@ -80,19 +80,27 @@ This is useful when you want to:
 
 ## Development
 
-Use the root `Makefile` as the entry point for local verification:
+Install [Mise](https://mise.jdx.dev/getting-started.html), then sync the pinned toolchain:
 
 ```sh
-make build
-make lint
-make test
+mise install
 ```
 
+Use the root `Makefile` as the entry point for local verification inside the Mise-managed environment:
+
+```sh
+mise exec -- make build
+mise exec -- make lint
+mise exec -- make test
+```
+
+Running `make build`, `make lint`, or `make test` from an already activated Mise shell is equivalent.
+
 What these targets do:
 
-- `make build` installs dependencies and creates a local npm package in `dist/`.
-- `make lint` runs the repository lint target.
-- `make test` rebuilds the package and validates the consumer extraction flow through the runnable example in `examples/`.
+- `mise exec -- make build` installs dependencies and creates a local npm package in `dist/`.
+- `mise exec -- make lint` runs the repository lint target.
+- `mise exec -- make test` rebuilds the package and validates the consumer extraction flow through the runnable example in `examples/`.
 
 ## Repository Map
 

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "agentme",
-  "version": "0.3.2",
+  "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": [