// Reference for running lint, test, build, and pod commands via tox. Agents MUST use tox for all quality gates — never invoke pytest, ruff, mypy, prek, or shell scripts directly. This skill is the canonical lookup table for which tox environment to use.
Audit documentation coverage against common user questions. Generates a Q&A matrix, searches docs/code for answers, flags gaps, and creates DRs for missing content. Use when asked to "audit docs", "check documentation coverage", "what questions can users answer", or before releases/demos.
Review and help prepare a contributor's pull request (upstream or fork). Use when the user asks to review a PR, get a contributor PR ready, update a contributor's branch, or ensure a PR meets project standards before merge. Follow this skill so contributor PRs are reviewed consistently and avoid rework (lint/test failures, outdated base, weak description).
Prepare and submit a pull request for the APME project. Syncs with upstream, creates a feature branch, runs quality gates (tox -e lint, tox -e unit), updates documentation and ADRs as needed, commits with conventional commits, then creates the PR via gh. Use when the user asks to submit, create, or open a pull request, or says "submit PR", "open PR", "create PR", "new PR".
Guide for handling pull request reviews, including automated (Copilot) and human reviewer feedback. Use when responding to PR comments, resolving review threads, or updating PRs after review.
Align branch name with artifact ID when they mismatch. Use when: renumbering a REQ/DR/ADR after branch creation, "branch name is wrong", "rename branch to match", or when PR review flags branch/artifact mismatch. Handles the git branch rename and remote update.
Guide for writing and modifying GitHub Actions workflows in this repository. Use when creating CI/CD pipelines, adding workflow jobs, modifying build steps, or debugging CI failures. Enforces the project's lean CI philosophy.
| name | tox |
| description | Reference for running lint, test, build, and pod commands via tox. Agents MUST use tox for all quality gates — never invoke pytest, ruff, mypy, prek, or shell scripts directly. This skill is the canonical lookup table for which tox environment to use. |
| argument-hint | [environment-name] |
| user-invocable | true |
| metadata | {"author":"APME Team","version":"1.0.0"} |
/tox # Show full environment reference
/tox lint # How to run lint
/tox unit # How to run unit tests
/tox up # How to start the pod
/tox build-clean # How to do a clean rebuild
/tox <env> # Lookup any tox environment
tox is the only way to run lint, test, build, and pod commands in this
project. Do not invoke pytest, ruff, mypy, prek, or shell scripts
directly. Every task maps to a tox -e <env> command.
pytest directly. Use tox -e unit, tox -e integration,
tox -e ai, or tox -e ui.ruff, mypy, or prek directly. Use tox -e lint../scripts/gen_grpc.sh directly. Use tox -e grpc../containers/podman/*.sh directly. Use tox -e build,
tox -e up, tox -e down, or tox -e cli.--. Example: tox -e unit -- -k test_sbom.uvx --with tox-uv tox -e <env> instead of installing tox.| Environment | What it runs | When to use |
|---|---|---|
tox -e lint | prek run --all-files (ruff, mypy, pydoclint, uv-lock) | Before every commit. Verification step for all tasks. |
| Environment | What it runs | When to use |
|---|---|---|
tox -e unit | pytest with --cov-fail-under=36 | After any code change. |
tox -e unit -- -k <pattern> | Single test or test pattern | Debugging a specific test. |
tox -e unit -- --no-cov | Tests without coverage overhead | Quick iteration. |
tox -e integration | pytest tests/integration/ (needs OPA binary) | After engine or validator changes. |
tox -e ai | pytest with AI extras (abbenay) | After AI/remediation changes. |
tox -e ui | pytest -m ui (Playwright, needs running pod) | After Gateway or UI changes. |
| Environment | What it runs | When to use |
|---|---|---|
tox -e grpc | scripts/gen_grpc.sh | After modifying any .proto file. |
| Environment | What it runs | When to use |
|---|---|---|
tox -e graph | tools/visualize_graph.py | Visualize a project's ContentGraph as interactive HTML. |
tox -e graph -- path/to/project | Visualize a specific project | Inspect execution flow of any Ansible content. |
| Environment | What it runs | When to use |
|---|---|---|
tox -e up | Build images + start the pod | After any code/config change. The common case. |
tox -e up -- --no-cache | Full rebuild + start | When cached layers are stale. |
tox -e build | containers/podman/build.sh | Build images only (no start). |
tox -e down | containers/podman/down.sh | Stop the APME pod. |
tox -e wipe | Stop + wipe DB and sessions | Preserve images, wipe state. |
tox -e build-clean | Wipe + rebuild --no-cache | Full clean rebuild (no start). |
tox -e up-clean | Wipe + rebuild --no-cache + start | Nuclear option — clean slate. |
tox -e cli -- <args> | containers/podman/run-cli.sh | Run CLI commands in the pod. |
tox -e pm | Build + start + health-check + open browser | Demo the product. |
Running tox with no -e flag executes: lint, unit, integration, ai,
ui. This is the full quality gate.
tox -e lint # check style + types
tox -e unit # run tests
tox -e grpc # regenerate stubs
tox -e lint # check generated code compiles
tox -e unit # verify nothing broke
tox -e unit -- -k test_scan_detects_fqcn
tox -e unit -- tests/test_validators.py::test_native_rule_discovery
tox -e up # builds + starts
tox -e cli -- health-check
tox -e cli -- check /workspace
tox -e down
tox l
uv tool install tox --with tox-uv
All tox configuration lives in tox.ini at the repo root. Environment
definitions, extras, pass-through env vars, and commands are all there.
Do not scatter test/lint invocations across Makefiles, scripts, or
workflow YAML.