Instructions file CodexOpenCode
Instructions for chipi/agentic-ai-homelab, covering agents.md — agentic-ai-homelab (repo-scoped), repo-wide conventions, scoped agents.md in this repo, what overrides this file and lean-ctx.
Instructions file
Instructions for chipi/agentic-ai-homelab: Repo-scoped rules live in AGENTS.md — the harness- agnostic convention this repo uses. Claude Code reads this file; we import AGENTS.md so every harness picks up the same rules.
Agent
Backend/API/business-logic bug fixer. Server-side code, data flow, algorithms, error handling, request/response logic. Use for bugs in application logic, API endpoints, computation, validation, and service behavior.
Agent
Database/data-layer bug fixer. SQL, schema, migrations, ORM queries, transactions, indexing, data integrity, connection handling. Use for bugs involving queries, migrations, data models, or persistence.
Agent
Documentation bug fixer. README/docstrings/comments, wrong or stale docs, broken examples, inaccurate instructions, doc-vs-code divergence. Use for bugs where the documentation is wrong, misleading, or out of date.
Agent
Infrastructure/deploy bug fixer. Dockerfiles, docker-compose, CI/CD workflows, deploy scripts, env/config, ports, healthchecks. Use for bugs in build, containerization, pipelines, or deployment configuration.
Agent
Active triager — normalizes a raw bug issue into a fix-ready L1 problem or rejects it. First pass on every bug-labeled issue; re-entered on harness kick-back with the failed attempt as evidence. Never fixes, never localizes on first pass.
Agent
Frontend/UI bug fixer. Components, rendering, state, events, layout/CSS, accessibility, client-side logic. Use for bugs in the user interface, display, interaction, or frontend behavior.
Agent
Deep-reasoning advisor for hard sub-decisions — architecture choices, tricky bug diagnosis, ambiguous specs, risky trade-offs. Consulted by the sonnet-tier executor subagents (planner/implementer/reviewer) via Agent(advisor) when they hit something needing opus-level reasoning. Read-only; returns guidance, does not…
Agent
Documentation writer — docstrings, code comments, README/CHANGELOG, and scaffolding new ADR/RFC/recipe docs. Keeps docs honest and the strict docs build green. Bounded utility executor.
Agent
Autonomous implementer for server/API and frontend code — writes and edits code to satisfy a plan or spec, runs the right local validation, keeps changes tight. Consults the advisor for hard design/bug forks; runs secrets-scan before proposing a commit. Never pushes without approval.
Agent
Strategic planner — decompose a task into a concrete ordered plan, surface the critical files, and freeze the contracts/interfaces before implementation. Use before non-trivial multi-step work. Consults the advisor for hard architectural forks. Read-only.
Agent
Ruthless code reviewer — reviews a diff for correctness bugs, security issues, and rule violations, returns structured findings by severity. Read-only, does not fix. Consults the advisor to confirm a subtle finding; runs secrets-scan over the diff.
Agent
Bounded test writer/runner — writes focused unit/integration tests (including the failing repro for a bug), runs the right test target, reports pass/fail. Mechanical executor; escalates blockers back to its caller, not to an advisor.
Skill Claude CodeCodex
Close a work arc — write the next docs/history/NNNN- .md continuity entry, update the history index and mkdocs nav, strike completed items in docs/wip/NEXTSTEPS.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…
Skill Claude CodeCodex
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…
Skill Claude CodeCodex
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.
Skill Claude CodeCodex
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…
Skill Claude CodeCodex
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…
Skill Claude CodeCodex
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:// :9000/v1 or :8003/v1), when a vLLM call fails to connect, or when asked to…
Skill Claude CodeCodex
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.
Skill Claude CodeCodex
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.
Skill Claude CodeCodex
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…
Skill Claude CodeCodex
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.