agent-dev-tooling

Stars0

Forks0

UpdatedJuly 25, 2026 at 20:15

Backend build, test, lint, and verify workflows via WSL pytest, ruff, doctor, and docker compose. Use before claiming work complete or opening a PR. Do not invent ad hoc Python commands outside documented venvs.

Installation

Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.

Source

synthet

synthet/image-scoring-backend

View GitHub Repository View Creator Repositories

Download

SKILL.md

readonly

name	agent-dev-tooling
description	Backend build, test, lint, and verify workflows via WSL pytest, ruff, doctor, and docker compose. Use before claiming work complete or opening a PR. Do not invent ad hoc Python commands outside documented venvs.

Agent dev tooling

Task runners, lint, and verification for image-scoring-backend (Vexlum Scoring).

Purpose

Run the correct project commands instead of inventing ad hoc toolchains. Primary stack: Python in WSL with documented venvs.

When to use

After code changes: pytest subset, ruff, doctor
Before /pr-ready: verification per AGENTS.md
Docker Compose for Postgres or inference E2E
Inspecting scripts under scripts/ before running

Required tools

Backend (primary): WSL2, ~/.venvs/tf (app/scripts), ~/.venvs/image-scoring-tests (pytest -m wsl)
Lint: ruff, optional pyright via uv tools
Ops: docker, docker compose

Install baseline: agent-cli-hub/references/install-blocks.md

Full command list: AGENTS.md, .agent/COMMANDS.md

WSL venv selection: wsl-tf-python-runner

Common commands (backend — WSL first)

Fast CPU subset (from AGENTS.md):

cd /mnt/d/Projects/image-scoring-backend
source ~/.venvs/tf/bin/activate
python -m pytest -m "not gpu and not db and not ml" --ignore=tests/test_probe.py -q

Official WSL pytest suite (-m wsl):

bash ./scripts/wsl/run_wsl_tests.sh

Doctor / diagnostics:

python scripts/doctor.py --no-gpu

Lint:

ruff check modules/ --output-format=concise

Agent infra (when touching .cursor/ assets):

python scripts/sync_assistant_trees.py --check
python scripts/ci/check_agent_frontmatter.py
python scripts/validate_cli_hub_skills.py

Docker (Postgres / profiles per AGENTS.md):

docker compose config
docker compose up -d

Postgres integration E2E (when explicitly requested):

RUN_POSTGRES_TESTS=1 pytest tests/integration/ -m postgres -v

Agent-safe patterns

Use WSL + correct venv before any modules.* import.
Prefer marker-filtered pytest over full suite unless user asks.
docker compose down -v and GPU jobs need confirmation.
IPC/secrets rules: .agent/SAFETY.md.

Commands requiring confirmation

ruff check --fix on broad paths
docker compose down -v (data loss)
Postgres/integration E2E without user request
Side-effecting MCP dispatch without confirmed=True

See commands-requiring-confirmation.md.

Troubleshooting

Import errors on Windows Python: switch to WSL + tf venv.
Wrong pytest venv for -m wsl: use run_wsl_tests.sh, not tf venv.
Doctor fails on DB: document blocker; may need docker compose up -d.
Port 7860 listens but health fails (Connection reset / refused): docker ps may show image-scoring-webui Up and the host socket still bound while the app inside is dead; webui.lock alone is not liveness evidence. Check docker ps -a --filter name=image-scoring-webui, docker logs --tail 40 image-scoring-webui, then docker restart image-scoring-webui. Poll until logs show Uvicorn running on http://0.0.0.0:7860 and curl -s -o /dev/null -w "%{http_code}" http://127.0.0.1:7860/api/health returns 200 (startup often takes 2–3 minutes for model/DB init — do not conclude failure on the first refusal).

Verification checklist

python scripts/doctor.py --no-gpu
python -m pytest -m "not gpu and not db and not ml" --ignore=tests/test_probe.py -q --co -q | head
ruff check modules/ --output-format=concise

More from this repository

same repository

release-bump

synthet/image-scoring-backend

Bump semver + promote CHANGELOG Unreleased via compiled harness. Use for /release, version bumps, or tagging. Runs scripts/agent_skills/release_bump.py; LLM only when Unreleased is ambiguous. Never commit/push unless the user asks.

2026-07-280

image-scoring-mcp

synthet/image-scoring-backend

Vexlum Scoring MCP — compact search+dispatch on is-be-mcp / is-be-live and gallery is-ui-mcp / is-ui-live.

2026-07-250

agent-cli-hub

synthet/image-scoring-backend

Choose CLI tools and safe patterns before repo work. Install checklist, bounded search/read commands, and confirmation gates. Use when navigating the codebase, running shell commands, or setting up agent tooling on Windows, WSL2, or macOS.

2026-07-250

agent-data-config

synthet/image-scoring-backend

Inspect JSON, YAML, and API responses with jq, yq, dasel, curl, and httpie. Use for package.json, config.json, and backend health checks. Never output secrets or full credential-bearing config.

2026-07-250

agent-search

synthet/image-scoring-backend

Choose and run the right search tool: rg vs grep vs ast-grep vs fd vs fzf. Bounded repo navigation with ripgrep, fd, tree, bat, and structural search. Use when finding symbols, files, syntax patterns, or deciding which CLI search to use before reading or editing code.

2026-07-250

autonomous-run-contract

synthet/image-scoring-backend

Use before letting an agent run without step-by-step supervision — unattended or overnight runs, long scoring/backfill jobs, "keep iterating until it passes", ratchet loops, subagent fan-out, or swarm work. Also use to decide how much orchestration a task needs (single call vs loop vs chain vs parallel vs DAG). Produces a written contract with metric, budget, revert rule, and stop conditions before the run starts.

2026-07-250

name	agent-dev-tooling
description	Backend build, test, lint, and verify workflows via WSL pytest, ruff, doctor, and docker compose. Use before claiming work complete or opening a PR. Do not invent ad hoc Python commands outside documented venvs.

Agent dev tooling

Task runners, lint, and verification for image-scoring-backend (Vexlum Scoring).

Purpose

Run the correct project commands instead of inventing ad hoc toolchains. Primary stack: Python in WSL with documented venvs.

When to use

After code changes: pytest subset, ruff, doctor
Before /pr-ready: verification per AGENTS.md
Docker Compose for Postgres or inference E2E
Inspecting scripts under scripts/ before running

Required tools

Backend (primary): WSL2, ~/.venvs/tf (app/scripts), ~/.venvs/image-scoring-tests (pytest -m wsl)
Lint: ruff, optional pyright via uv tools
Ops: docker, docker compose

Install baseline: agent-cli-hub/references/install-blocks.md

Full command list: AGENTS.md, .agent/COMMANDS.md

WSL venv selection: wsl-tf-python-runner

Common commands (backend — WSL first)

Fast CPU subset (from AGENTS.md):

cd /mnt/d/Projects/image-scoring-backend
source ~/.venvs/tf/bin/activate
python -m pytest -m "not gpu and not db and not ml" --ignore=tests/test_probe.py -q

Official WSL pytest suite (-m wsl):

bash ./scripts/wsl/run_wsl_tests.sh

Doctor / diagnostics:

python scripts/doctor.py --no-gpu

Lint:

ruff check modules/ --output-format=concise

Agent infra (when touching .cursor/ assets):

python scripts/sync_assistant_trees.py --check
python scripts/ci/check_agent_frontmatter.py
python scripts/validate_cli_hub_skills.py

Docker (Postgres / profiles per AGENTS.md):

docker compose config
docker compose up -d

Postgres integration E2E (when explicitly requested):

RUN_POSTGRES_TESTS=1 pytest tests/integration/ -m postgres -v

Agent-safe patterns

Use WSL + correct venv before any modules.* import.
Prefer marker-filtered pytest over full suite unless user asks.
docker compose down -v and GPU jobs need confirmation.
IPC/secrets rules: .agent/SAFETY.md.

Commands requiring confirmation

ruff check --fix on broad paths
docker compose down -v (data loss)
Postgres/integration E2E without user request
Side-effecting MCP dispatch without confirmed=True

See commands-requiring-confirmation.md.

Troubleshooting

Import errors on Windows Python: switch to WSL + tf venv.
Wrong pytest venv for -m wsl: use run_wsl_tests.sh, not tf venv.
Doctor fails on DB: document blocker; may need docker compose up -d.
Port 7860 listens but health fails (Connection reset / refused): docker ps may show image-scoring-webui Up and the host socket still bound while the app inside is dead; webui.lock alone is not liveness evidence. Check docker ps -a --filter name=image-scoring-webui, docker logs --tail 40 image-scoring-webui, then docker restart image-scoring-webui. Poll until logs show Uvicorn running on http://0.0.0.0:7860 and curl -s -o /dev/null -w "%{http_code}" http://127.0.0.1:7860/api/health returns 200 (startup often takes 2–3 minutes for model/DB init — do not conclude failure on the first refusal).

Verification checklist

python scripts/doctor.py --no-gpu
python -m pytest -m "not gpu and not db and not ml" --ignore=tests/test_probe.py -q --co -q | head
ruff check modules/ --output-format=concise