DEVX-110: feat: centralize venv management in devx.mak

.devin/agents/ci-investigator/AGENT.md

@@ -34,12 +34,13 @@ permissions:
 
 You are a CI failure investigator for the devx repo.
 
-## Working Directory
+## Working Directory & Virtual Environment
 
-The devx repo is at `/home/emo/dev/ideas/oblachno/devx`. Always `cd` there first:
-```bash
-cd /home/emo/dev/ideas/oblachno/devx
-```
+The devx repo is at `/home/emo/dev/ideas/oblachno/devx`. Always `cd` there first.
+
+All Python tools run inside `.venv`. `make` targets handle activation
+automatically — always use `make <target>`, never raw `pytest` or `ruff`
+commands. If `.venv` doesn't exist, run `make setup` first.
 
 ## CI Job Dependency Graph
 
@@ -131,8 +132,8 @@ make build-images-dry-run      # dry-run build
 
 For doc coverage issues:
 ```bash
-python3 -m devx.ci.doc_coverage --fail-on-missing
-python3 -m devx.ci.lint_docs --root .
+.venv/bin/python -m devx.ci.doc_coverage --fail-on-missing
+.venv/bin/python -m devx.ci.lint_docs --root .
 ```
 
 ### Step 5: Check for related Vikunja tasks

.devin/agents/dep-upgrader/AGENT.md

@@ -30,10 +30,14 @@ permissions:
 
 You are a dependency upgrade specialist for the devx repo.
 
-## Working Directory
+## Working Directory & Virtual Environment
 
 The devx repo is at `/home/emo/dev/ideas/oblachno/devx`. Always `cd` there first.
 
+All Python tools run inside `.venv`. `make` targets handle activation
+automatically — always use `make <target>`, never raw `pytest` or `ruff`
+commands. If `.venv` doesn't exist, run `make setup` first.
+
 ## Dependency Reference Locations
 
 - **Primary**: `pyproject.toml` — `[project] dependencies` and `[project.optional-dependencies]`
@@ -81,8 +85,8 @@ If adding a new dependency without a comment, `check_pyproject_deps` will fail.
 pip install -e .[dev]    # reinstall with new deps
 make pytest-cov          # 100% coverage required
 make lint-all            # ruff + pyright + bandit + actionlint + hadolint
-python3 -m devx.tools.check_pyproject_deps  # verify dep docs
-python3 -m devx.tools.check_test_speed --max-seconds 4 --max-single-seconds 0.5
+.venv/bin/python -m devx.tools.check_pyproject_deps  # verify dep docs
+.venv/bin/python -m devx.tools.check_test_speed --max-seconds 4 --max-single-seconds 0.5
 ```
 
 All must pass. If `check_pyproject_deps` fails, add the missing comment.

.devin/agents/doc-sync-specialist/AGENT.md

@@ -25,10 +25,14 @@ permissions:
 
 You are a documentation sync specialist for the devx repo.
 
-## Working Directory
+## Working Directory & Virtual Environment
 
 The devx repo is at `/home/emo/dev/ideas/oblachno/devx`. Always `cd` there first.
 
+All Python tools run inside `.venv`. `make` targets handle activation
+automatically — always use `make <target>`, never raw `pytest` or `ruff`
+commands. If `.venv` doesn't exist, run `make setup` first.
+
 ## Documentation Structure
 
 ```
@@ -56,7 +60,7 @@ docs/
 
 ### Step 1: Check documentation coverage
 ```bash
-python3 -m devx.ci.doc_coverage --fail-on-missing
+.venv/bin/python -m devx.ci.doc_coverage --fail-on-missing
 ```
 If this fails, it lists undocumented items:
 - **CLI commands**: any `@click.command()` or `@click.group()` without a docs entry
@@ -69,7 +73,7 @@ for modules.
 
 ### Step 2: Lint documentation structure
 ```bash
-python3 -m devx.ci.lint_docs --root .
+.venv/bin/python -m devx.ci.lint_docs --root .
 ```
 Common issues:
 - **Broken internal links**: `[text](page.md)` where `page.md` doesn't exist
@@ -88,7 +92,7 @@ exist. If a script/module was renamed or deleted, update all doc references.
 
 ### Step 4: Verify wiki sync (if investigating a sync failure)
 ```bash
-python3 -m devx.ci.sync_wiki --repo oblachno-oss/devx --strict
+.venv/bin/python -m devx.ci.sync_wiki --repo oblachno-oss/devx --strict
 ```
 Common sync failures:
 - **Content mismatch**: wiki page content doesn't match local docs — usually means a previous sync was interrupted

.devin/agents/docker-image-builder/AGENT.md

@@ -34,10 +34,14 @@ permissions:
 
 You are a Docker image build specialist for the devx repo.
 
-## Working Directory
+## Working Directory & Virtual Environment
 
 The devx repo is at `/home/emo/dev/ideas/oblachno/devx`. Always `cd` there first.
 
+All Python tools run inside `.venv`. `make` targets handle activation
+automatically — always use `make <target>`, never raw `pytest` or `ruff`
+commands. If `.venv` doesn't exist, run `make setup` first.
+
 ## Image Architecture
 
 Three tier images built sequentially (each FROM the previous):
@@ -87,7 +91,7 @@ This builds all 3 tiers sequentially and pushes to the Gitea registry.
 
 If only one tier needs rebuilding:
 ```bash
-python3 -m devx.tools.build_image \
+.venv/bin/python -m devx.tools.build_image \
   --dockerfile docker/ci-quality/Dockerfile \
   --name oblachno-oss/runner-images/ci-quality \
   --tag latest \

.devin/agents/workflow-validator/AGENT.md

@@ -27,10 +27,14 @@ permissions:
 
 You are a Gitea Actions workflow validator for the devx repo.
 
-## Working Directory
+## Working Directory & Virtual Environment
 
 The devx repo is at `/home/emo/dev/ideas/oblachno/devx`. Always `cd` there first.
 
+All Python tools run inside `.venv`. `make` targets handle activation
+automatically — always use `make <target>`, never raw `pytest` or `ruff`
+commands. If `.venv` doesn't exist, run `make setup` first.
+
 ## Key Files
 
 - `.gitea/workflows/ci.yml` — PR pipeline (quality, detect-changes, release-dry-run, pr-review, auto-merge)