Move check_agents to pytest; rename properties.yml.example

.claude/commands/docs.md

@@ -25,7 +25,7 @@ check:
    `.claude/commands/*.md`, `.claude/skills/*/SKILL.md`, `.clinerules/workflows/*.md` — these must
    describe the same behavior; if one changed, the other three need the matching edit (see
    `.github/instructions/prompts.instructions.md`).
-6. **`properties.yml.example`** and any other example/config file describing setup — if `setup.sh`,
+6. **`properties.example.yml`** and any other example/config file describing setup — if `setup.sh`,
    `setup.ps1`, or `modules/setup/properties.py` changed what gets generated.
 7. Any other `*.md` file that references a file, command, module, or behavior touched by the diff.
 

.claude/skills/docs/SKILL.md

@@ -17,6 +17,6 @@ uv run --no-sync invoke repo.pr_diff
 ```
 
 Then sweep every doc/AI-config surface the prompt lists (root `README.md`, module `README.md`s,
-`.github/instructions/*.md`, `AGENTS.md`/`CLAUDE.md`, the synced command dirs, `properties.yml.example`)
+`.github/instructions/*.md`, `AGENTS.md`/`CLAUDE.md`, the synced command dirs, `properties.example.yml`)
 and fix anything stale directly — this is a repo-local consistency sweep, so no confirmation is
 needed before editing.

.clinerules/workflows/docs.md

@@ -22,7 +22,7 @@ check:
    `.claude/commands/*.md`, `.claude/skills/*/SKILL.md`, `.clinerules/workflows/*.md` — these must
    describe the same behavior; if one changed, the other three need the matching edit (see
    `.github/instructions/prompts.instructions.md`).
-6. **`properties.yml.example`** and any other example/config file describing setup — if `setup.sh`,
+6. **`properties.example.yml`** and any other example/config file describing setup — if `setup.sh`,
    `setup.ps1`, or `modules/setup/properties.py` changed what gets generated.
 7. Any other `*.md` file that references a file, command, module, or behavior touched by the diff.
 

.github/instructions/index.instructions.md

@@ -25,17 +25,18 @@ scoped to one concern — load only the ones relevant to the task at hand:
 
 ## Project Structure
 ```
-pyproject.toml    # Dependencies, ruff/pylint config
+pyproject.toml    # Dependencies, ruff/pylint/pytest config
 invoke.yml        # Invoke config (auto_dash_names: false)
 setup.sh          # Shell-based setup script (uv venv + uv sync)
 properties.yml    # Project configuration (repo path/remote, template path/remote)
 template.ignore.yml # Paths /template pull/push must never touch (.gitignore handles the rest via git ls-files)
+tests/
+  test_check_agents.py # Verify .github/prompts/ mirrors are in sync, called by tests.check_agents
 modules/
   common/         # cli.py, properties.py, route_utils.py, utils.py — shared helpers
   repo/           # pull.py, push.py, log.py, squash.py, rebase.py, pr_*.py — git/PR workflow modules
   setup/          # properties.py — creates/stamps properties.yml, called by setup.sh/setup.ps1
   template/       # ignore.py, naming.py, pull.py, push.py, resolve.py, route.py, scope.py — sync shared tooling with the parent template repo for /template
-  tests/          # check_agents.py — verify .github/prompts/ mirrors are in sync, called by tests.check_agents
   versioning/     # libs.py, python.py, workflows.py, upgrade.py, project.py — check pyproject.toml deps & workflow action refs vs. latest releases, bump the repo's VERSION file
 tasks/
   __init__.py     # Wires the invoke Collection (debug, repo, ruff, setup, template, tests, upgrade, uv, versioning) plus top-level aliases (fix, test, update)
@@ -45,15 +46,15 @@ tasks/
   ruff.py         # ruff.fix, ruff.format
   setup.py        # setup.properties — creates/stamps properties.yml
   template.py     # template.pull, template.pull_copy, template.push_diff, template.push_apply, template.push_create_pr
-  tests.py        # tests.actionlint, tests.check_agents, tests.pylint, tests.rufflint, tests.yamllint
+  tests.py        # tests.actionlint, tests.check_agents, tests.pylint, tests.pytest, tests.rufflint, tests.yamllint
   upgrade.py      # upgrade (default), upgrade.python, upgrade.libs, upgrade.sync — installs; run ver.update first
   uv.py           # uv.upgrade_bin, uv.upgrade_libs
   versioning.py   # ver.libs, ver.python, ver.workflows, ver.all, ver.update, ver.upgrade, ver.project_bump_build, ver.project_bump_release
 .github/
   instructions/   # Copilot instruction files
   prompts/        # Copilot prompt files (/push, /pull, /squash, /rebase, /fix, /test, /docs, /pr-notes, /pr, /pr-cleanup, /ship-it, /template, /update, /upgrade, /repo, /setup) — source of truth for slash commands
   skills/         # Optional GitHub Copilot skills (SKILL.md), not a required mirror of every prompt — see skills.instructions.md
-  workflows/      # tests.yml — ruff + pylint + yamllint + actionlint + check_agents, on PRs to development/main
+  workflows/      # tests.yml — ruff + pylint + pytest + yamllint + actionlint + check_agents, on PRs to development/main
 .claude/
   commands/       # Claude Code slash commands, hand-maintained mirror of .github/prompts/ (see prompts.instructions.md)
   skills/         # Claude Code skills (auto-discovered), hand-maintained mirror of .github/prompts/ (see prompts.instructions.md)
@@ -83,6 +84,7 @@ addons/
 - `invoke` — task runner
 - `ruff` — fast Python linter/formatter
 - `pylint` — deep static analysis (10/10 required to pass `invoke test`)
+- `pytest` / `pytest-cov` — unit tests (`tests/`, e.g. `test_check_agents.py`)
 - `yamllint` — YAML linting
 - `actionlint-py` — GitHub Actions workflow linting (pip-installed, no Homebrew required)
 - `pyyaml` — reads `properties.yml`
@@ -93,7 +95,7 @@ addons/
 ## Running Tasks
 ```sh
 uv run --no-sync invoke          # List all tasks (or: uv run --no-sync invoke -l)
-uv run --no-sync invoke test     # ruff + pylint + yamllint + actionlint + check_agents
+uv run --no-sync invoke test     # ruff + pylint + pytest + yamllint + actionlint + check_agents
 uv run --no-sync invoke fix      # Ruff autocorrect + format
 uv run --no-sync invoke repo.pull   # Pull from git remote (stash → pull --rebase → restore)
 uv run --no-sync invoke repo.push   # Push to git remote (fix → test → commit → push)

.github/instructions/modules.instructions.md

@@ -14,9 +14,11 @@ Modules provide reusable Python logic consumed by invoke tasks, prompts, and scr
 | `modules/repo/` | Git/PR workflow logic (pull, push, log, squash, rebase, pr) |
 | `modules/setup/` | Repo bootstrap logic called by `setup.sh`/`setup.ps1` (`properties.py`) |
 | `modules/template/` | Syncs shared, generic tooling with the parent template repo for `/template` |
-| `modules/tests/` | Repo consistency checks called by `tasks/tests.py` (`check_agents.py`) |
 | `modules/versioning/` | Checks `pyproject.toml` deps and workflow action refs against latest releases, updates locks; bumps the repo's `VERSION` file for deploys/releases (`project.py`) |
 
+Repo consistency checks (`check_agents`) live under root `tests/` as pytest tests, not `modules/` —
+see `.github/instructions/tests.instructions.md`.
+
 ## Module Conventions
 - One concern per file; filename matches the concern in snake_case
 - Use module-level functions, not classes, unless state genuinely requires it

.github/instructions/tasks.instructions.md

@@ -56,6 +56,7 @@ namespace.add_collection(my_new_module, name="my_new_module")
       tests.actionlint(context)
       tests.check_agents(context)
       tests.pylint(context)
+      tests.pytest(context)
       tests.rufflint(context)
       tests.yamllint(context)
   ```
@@ -71,14 +72,15 @@ namespace.add_collection(my_new_module, name="my_new_module")
 | Task | Command | Description |
 |------|---------|-------------|
 | Fix | `uv run --no-sync invoke fix` | Run all auto-fixes (ruff fix + format) |
-| Test | `uv run --no-sync invoke test` | Run all tests (actionlint + check_agents + pylint + ruff + yamllint) |
+| Test | `uv run --no-sync invoke test` | Run all tests (actionlint + check_agents + pylint + pytest + ruff + yamllint) |
 
 ### Test Tasks
 | Task | Command | Description |
 |------|---------|-------------|
 | actionlint | `uv run --no-sync invoke tests.actionlint` | GitHub Actions workflow validation |
-| check_agents | `uv run --no-sync invoke tests.check_agents` | Verify `.github/prompts/` is mirrored into `.claude/commands/`, `.claude/skills/`, and `.clinerules/workflows/` |
+| check_agents | `uv run --no-sync invoke tests.check_agents` | Verify `.github/prompts/` is mirrored into `.claude/commands/`, `.claude/skills/`, and `.clinerules/workflows/` (`pytest tests/test_check_agents.py`) |
 | pylint | `uv run --no-sync invoke tests.pylint` | Python code quality |
+| pytest | `uv run --no-sync invoke tests.pytest` | Python unit test suite (`tests/`) |
 | rufflint | `uv run --no-sync invoke tests.rufflint` | Python linting and formatting |
 | yamllint | `uv run --no-sync invoke tests.yamllint` | YAML file validation |
 

.github/instructions/tests.instructions.md

@@ -31,6 +31,7 @@ uv run --no-sync invoke test
 uv run --no-sync invoke tests.actionlint
 uv run --no-sync invoke tests.check_agents
 uv run --no-sync invoke tests.pylint
+uv run --no-sync invoke tests.pytest
 uv run --no-sync invoke tests.rufflint
 uv run --no-sync invoke tests.yamllint
 
@@ -44,7 +45,8 @@ Do not run `uv run invoke ...` without `--no-sync`.
 ## When to Run Tests
 
 Run tests if you modified:
-- `*.py` — any Python file (pylint + ruff)
+- `*.py` — any Python file (pylint + ruff); files under `tests/` are excluded from pylint/ruff and
+  checked by pytest instead
 - `*.yml` or `*.yaml` — any YAML file (yamllint)
 - `.github/workflows/*.yml` — GitHub Actions (actionlint + yamllint)
 - `.github/prompts/`, `.claude/commands/`, `.claude/skills/`, `.clinerules/workflows/` — command mirror
@@ -56,10 +58,11 @@ Skip tests for: `*.md` (except the command mirror dirs above), config files, `*.
 
 1. **actionlint** — GitHub Actions workflow validation
 2. **check_agents** — `.github/prompts/` is mirrored into `.claude/commands/`, `.claude/skills/`, and
-   `.clinerules/workflows/`
+   `.clinerules/workflows/` (a pytest test under `tests/test_check_agents.py`)
 3. **pylint** — Python code quality
-4. **ruff** — Python linting and formatting
-5. **yamllint** — YAML file validation
+4. **pytest** — Python unit test suite (`tests/`)
+5. **ruff** — Python linting and formatting
+6. **yamllint** — YAML file validation
 
 ## Fix Issues — Never Disable Warnings
 

.github/prompts/docs.prompt.md

@@ -25,7 +25,7 @@ check:
    `.claude/commands/*.md`, `.claude/skills/*/SKILL.md`, `.clinerules/workflows/*.md` — these must
    describe the same behavior; if one changed, the other three need the matching edit (see
    `.github/instructions/prompts.instructions.md`).
-6. **`properties.yml.example`** and any other example/config file describing setup — if `setup.sh`,
+6. **`properties.example.yml`** and any other example/config file describing setup — if `setup.sh`,
    `setup.ps1`, or `modules/setup/properties.py` changed what gets generated.
 7. Any other `*.md` file that references a file, command, module, or behavior touched by the diff.
 

.github/workflows/tests.yml

@@ -75,6 +75,28 @@ jobs:
           uv run --no-sync invoke debug.env
           uv run --no-sync invoke tests.pylint
 
+  pytest:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - name: Check Out Code
+        uses: actions/checkout@v7
+
+      - name: Setup uv
+        uses: astral-sh/setup-uv@v8.3.2
+        with:
+          python-version: "3.14"
+          enable-cache: true
+
+      - name: Install Dependencies
+        run: uv sync
+
+      - name: Pytest
+        run: |
+          uv run --no-sync invoke debug.env
+          uv run --no-sync invoke tests.pytest
+
   ruff_lint:
     runs-on: ubuntu-latest
     permissions:

README.md

@@ -16,17 +16,18 @@ path before running tasks.
 
 ## Project Structure
 ```
-pyproject.toml    # Dependencies (Python >=3.14), ruff/pylint config
+pyproject.toml    # Dependencies (Python >=3.14), ruff/pylint/pytest config
 invoke.yml        # Invoke config (auto_dash_names: false)
 setup.sh          # Shell-based setup script (uv venv + uv sync)
 properties.yml    # Project configuration (repo path/remote, template path/remote)
 template.ignore.yml # Paths /template pull/push must never touch (.gitignore handles the rest via git ls-files)
+tests/
+  test_check_agents.py # Verify .github/prompts/ mirrors are in sync, called by tests.check_agents
 modules/
   common/         # cli.py, properties.py, route_utils.py, utils.py — shared helpers
   repo/           # pull.py, push.py, log.py, squash.py, rebase.py, pr_*.py — git/PR workflow modules
   setup/          # properties.py — creates/stamps properties.yml, called by setup.sh/setup.ps1
   template/       # ignore.py, naming.py, pull.py, push.py, resolve.py, route.py, scope.py — sync shared tooling with the parent template repo for /template
-  tests/          # check_agents.py — verify .github/prompts/ mirrors are in sync, called by tests.check_agents
   versioning/     # libs.py, python.py, workflows.py, upgrade.py, project.py — check pyproject.toml deps & workflow action refs vs. latest releases, bump the repo's VERSION file
 tasks/
   __init__.py     # Wires the invoke Collection (debug, repo, ruff, setup, template, tests, upgrade, uv, versioning) plus top-level aliases (fix, test, update)
@@ -36,7 +37,7 @@ tasks/
   ruff.py         # ruff.fix, ruff.format
   setup.py        # setup.properties — creates/stamps properties.yml
   template.py     # template.pull, template.pull_copy, template.push_diff, template.push_apply, template.push_create_pr
-  tests.py        # tests.actionlint, tests.check_agents, tests.pylint, tests.rufflint, tests.yamllint
+  tests.py        # tests.actionlint, tests.check_agents, tests.pylint, tests.pytest, tests.rufflint, tests.yamllint
   upgrade.py      # upgrade (default), upgrade.python, upgrade.libs, upgrade.sync — installs; run ver.update first
   uv.py           # uv.upgrade_bin, uv.upgrade_libs
   versioning.py   # ver.libs, ver.python, ver.workflows, ver.all, ver.update, ver.upgrade, ver.project_bump_build, ver.project_bump_release
@@ -45,7 +46,7 @@ tasks/
   prompts/        # /push, /pull, /squash, /rebase, /fix, /test, /docs, /pr-notes, /pr, /pr-cleanup, /ship-it, /template, /update, /upgrade, /repo, /setup — source of truth
   skills/         # Optional GitHub Copilot skills (SKILL.md), not a required mirror of every prompt
   workflows/
-    tests.yml       # CI: ruff + pylint + yamllint + actionlint + check_agents, on PRs to development/main
+    tests.yml       # CI: ruff + pylint + pytest + yamllint + actionlint + check_agents, on PRs to development/main
 .claude/
   commands/       # Claude Code slash commands, hand-maintained mirror of .github/prompts/
   skills/         # Claude Code skills (auto-discovered), hand-maintained mirror of .github/prompts/
@@ -61,7 +62,7 @@ addons/
 ## Invoke Tasks
 ```sh
 uv run --no-sync invoke             # List all available tasks
-uv run --no-sync invoke test        # Ruff + Pylint + yamllint + actionlint + check_agents
+uv run --no-sync invoke test        # Ruff + Pylint + pytest + yamllint + actionlint + check_agents
 uv run --no-sync invoke fix         # Ruff autocorrect + format
 uv run --no-sync invoke update      # Run every version check (libs, python, workflows) — top-level alias for ver.update
 uv run --no-sync invoke repo.pull    # Pull from git remote (stash → pull --rebase → restore)
@@ -121,9 +122,12 @@ uv run --no-sync invoke setup.properties # Create/stamp properties.yml
 | [`modules/repo/`](modules/repo/README.md) | Git workflow and session logging |
 | [`modules/setup/`](modules/setup/README.md) | Creates/stamps `properties.yml`, called by `setup.sh`/`setup.ps1` |
 | [`modules/template/`](modules/template/README.md) | Sync shared, generic tooling with the parent template repo for `/template` |
-| [`modules/tests/`](modules/tests/README.md) | Verify `.github/prompts/` is mirrored into `.claude/commands/`, `.claude/skills/`, and `.clinerules/workflows/` |
 | [`modules/versioning/`](modules/versioning/README.md) | Check `pyproject.toml` deps and workflow action refs vs. latest releases, update locks; bump the repo's `VERSION` file for deploys/releases |
 
+`tests/test_check_agents.py` (not a `modules/` package) verifies `.github/prompts/` is mirrored
+into `.claude/commands/`, `.claude/skills/`, and `.clinerules/workflows/` — run via
+`uv run --no-sync invoke tests.check_agents`.
+
 See [modules/README.md](modules/README.md) for full details.
 
 ## Addons
@@ -144,6 +148,6 @@ they aren't meant to lint clean from this repo's root.
 | [`addons/shopfiy_dawn_theme/`](addons/shopfiy_dawn_theme/) | `dawn.list` / `dawn.upgrade` invoke tasks for tracking and staging upstream Shopify/dawn theme upgrades | `modules/dawn/` (`__init__.py`, `list.py`, `upgrade.py`, `README.md`), `tasks/dawn.py`, `.github/workflows/{deploy,promote,release,tests,upgrade}.yml`, `.github/instructions/dawn.instructions.md`, `.github/prompts/dawn.prompt.md`, `.claude/commands/dawn.md` |
 
 ## CI
-GitHub Actions runs Ruff, Pylint, yamllint, actionlint, and check_agents on every pull request
-targeting `development` or `main` via `.github/workflows/tests.yml`.
+GitHub Actions runs Ruff, Pylint, pytest, yamllint, actionlint, and check_agents on every pull
+request targeting `development` or `main` via `.github/workflows/tests.yml`.
 

modules/README.md

@@ -11,11 +11,13 @@ modules/
   repo/         # pull, push, log, squash, rebase (git workflow)
   setup/        # creates/stamps properties.yml, called by setup.sh/setup.ps1
   template/     # sync shared, generic tooling with the parent template repo for /template
-  tests/        # verify .github/prompts/ mirrors are in sync, called by tasks/tests.py
   versioning/   # check pyproject.toml deps and workflow action refs vs. latest releases, update locks;
                 # bump the repo's VERSION file for deploys/releases
 ```
 
+Repo-consistency checks (`check_agents`) live under root `tests/` as pytest tests, not here — see
+`../tests/test_check_agents.py` and `.github/instructions/tests.instructions.md`.
+
 ## Submodules
 
 | Directory | Purpose |
@@ -24,7 +26,6 @@ modules/
 | [`repo/`](repo/README.md) | Git workflow, session logging, squash, and rebase |
 | [`setup/`](setup/README.md) | Creates/stamps `properties.yml`, called by `setup.sh`/`setup.ps1` |
 | [`template/`](template/README.md) | Sync shared, generic tooling with the parent template repo for `/template` |
-| [`tests/`](tests/README.md) | Verify `.github/prompts/` is mirrored into `.claude/commands/`, `.claude/skills/`, and `.clinerules/workflows/` |
 | [`versioning/`](versioning/README.md) | Check `pyproject.toml` deps and workflow action refs vs. latest releases, update locks; bump the repo's `VERSION` file for deploys/releases |
 
 ## Conventions