agentic-ai-homelab

Close a work arc — write the next docs/history/NNNN-<arc>.md continuity entry, update the history index and mkdocs nav, strike completed items in docs/wip/NEXT_STEPS.md, append any D-NNNN operational decisions to 0002-decisions.md, and suggest the version tag. Use when wrapping up a multi-step session or a milestone. Keeps the strict docs build green.

Pre-deploy sanity check for Docker Compose stacks. Validates each compose file with `docker compose config` (read-only), then flags undefined interpolation variables and missing .env before the stack is brought up. Use before `docker compose up`, when editing a compose file, or whenever asked to validate or check a compose stack. Never brings stacks up or down.

One-shot read-only health snapshot of the DGX host — GPU mode, GPU utilization and compute-app count, nvidia-smi memory and processes, and running containers. Use to answer "what is the DGX doing right now" before deploying, switching GPU mode, or debugging a stuck endpoint. Strictly read-only; never changes state.

Validate that the docs site builds cleanly in strict mode before committing or pushing docs changes. Detects the project's docs toolchain (Makefile docs target, MkDocs, Sphinx, Docusaurus, mdBook) and runs its strict build, then reports PASS/FAIL with the exact unresolved refs or warnings. Use when about to commit or push changes under docs/, mkdocs.yml, or docs config, or whenever asked to check or validate the docs build.

Show per-subagent invocation counts and token/cost spread by model tier from the current Claude Code transcript — proves whether the model-tiered fleet (haiku/sonnet/opus) actually spreads token cost. Use to see who was invoked, how often, tokens per agent/model, and escalation rate. Local and read-only (no Grafana/OTEL needed).

Coordinate which vLLM owns the single DGX GPU before using a local vLLM endpoint. Checks the active mode (code/research/idle/BROKEN-BOTH) read-only, and switches only on explicit request. Use before pointing any tool at a local vLLM (http://<dgx>:9000/v1 or :8003/v1), when a vLLM call fails to connect, or when asked to bring the coder-next or autoresearch vLLM up or down. Switching is shared-state — never switch without explicit approval.

Resolve a homelab service name to its real endpoint URL and how to call it — DGX host, vLLM coder-next/autoresearch slots, Ollama, observability labels. Use when an agent or client needs to point at a homelab service, when writing config that consumes one, or when asked "what's the URL for X". Read-only.

Scaffold a new documentation file — ADR, RFC, recipe, or wip note — from the repo's conventions, assign the next number/slug, wire it into the mkdocs nav, update the section index, and keep the strict build green. Use when starting an ADR/RFC/recipe/design note, or when asked to write up a decision or a runbook.

Boot or verify the Grafana Alloy observability stack (DGX → Grafana Cloud). Walks the runbook — Grafana Cloud creds → .env → docker compose up → verify in Grafana Explore → import dashboards → pin image tags. Read and verify steps are safe; the compose up is gated on explicit approval. Use when standing up or checking the observability stack.

For a real bug, write a failing test (or fixture / matrix row) that reproduces it BEFORE fixing — the test becomes the regression guard. Use when starting on a reported bug, a production incident, or any "it's broken" investigation. Enforces reproduce-before-fix and never-invent-root-causes.

Scaffold a per-folder AGENTS.md and wire it into the repo-root AGENTS.md scoped table. Use when adding folder-specific agent rules, splitting a monolithic root AGENTS.md into per-folder files, or when asked to create or scope an AGENTS.md for a subdirectory. Enforces that AGENTS.md is the source of truth and CLAUDE.md stays a thin @-import.

Scan for secrets (API keys, tokens, private keys, credentials, real .env files) before committing or pushing — enforces "never commit secrets". Prefers gitleaks if installed; otherwise uses high-signal patterns. Reports findings by file:line with the value redacted. Use before any commit/push, when adding config or fixtures, or whenever asked to check for leaked secrets. Read-only.

The pre-push ritual — rebase onto the trunk, run the right validation gates, confirm green, show the diff, and push only after explicit approval. Enforces never-push-without-approval, always-rebase-before-push, and green-local-then-push. Use when about to push a feature branch or open a PR. The push itself is gated on explicit approval.

Safely bring a local vLLM stack up. Runs the read-only preflight (gpu-mode check, compose-check, .env presence) then hands you the exact deploy command for approval. Use when deploying or restarting coder-next / autoresearch / openwebui. Never runs up/down itself — the mutating step is gated on explicit approval.