homelab-upgrade/AGENTS.md

homelab-upgrade — instrukcje

Kolejka kroków (SQLite) + driver + appka web do nocnych aktualizacji aplikacji Docker Compose na VM103. Pełny, zatwierdzony projekt: docs/DESIGN.md — przeczytaj przed pracą nad architekturą lub nowym krokiem. Stary system (do portu, tylko odczyt): /root/homelab-modernization. Nie czytaj tam backups/ (kopie z .env).

Gdzie co zapisywać (żeby dokumentacja nie rosła bez końca): docs/DESIGN.md to zatwierdzona architektura — zmienia się rzadko. docs/IMPLEMENTATION.md to plan etapów i ich status, zwięźle, bez narracji sesyjnej. TASK_STATE.md to jedyne miejsce na bieżący stan: cel, decyzje, zrobione, pozostałe, następny krok — nadpisuj go, nie dopisuj kolejnych sekcji historii. Co się stało w danej sesji zostaje w commitach (git log), nie w osobnej sekcji dokumentu.

Środowisko

• Ten host to Proxmox (Debian 11) — tylko do rozwoju i testów. Docelowo kod działa na VM103 w Dockerze.
• Node 24 przez nvm (.nvmrc). W powłoce nieinteraktywnej przed node/npm: . ~/.nvm/nvm.sh.
• Nic nie instalujesz globalnie. Nie ruszasz Proxmoxa, VM103 ani działających kontenerów — poza odczytem (właściciel zezwolił 2026-10-23). Stan działającej appki (runy, osie czasu, modele) czytasz przez tools/vm-api.sh /api/... (GET przez SSH na VM103, z pominięciem Traefika i Keycloaka), np. /api/workflow-instances?app=<app> i /api/workflow-instances/<id>/timeline; ograniczaj wyjście (| head -c, wyciągaj węzły). Wdrożenia nadal tylko na polecenie.
• Skryptów ze starego repo, które mutują (apply.sh, rollback.sh, backup.sh), nie uruchamiasz bez zlecenia właściciela. Testy idą na fejkach i zapisanych fixture'ach.
• Sekrety (.env, klucze, tokeny) nigdy w repo, logach ani wyjściu.
• Remote: ssh://git@git.mariuszpacek.pl:2244/mariusz.pacek/homelab-upgrade.git, gałąź master. Commity małe i opisowe; commit/push tylko na prośbę właściciela.

Kod

• TypeScript strict, ESM, Node 24. Kod, identyfikatory, komentarze, commity i UI appki po angielsku; dokumenty (docs/, instrukcje) po polsku.
• Warstwy: domain (czyste typy i reguły, bez I/O) → app (handlery kroków, driver) → infra (adaptery) → http/web. Zależności tylko do środka; reguła lintu to pilnuje.
• Abstrakcja tylko tam, gdzie jest szew testowy albo wymienność: StepStore, CommandRunner, ModelExecutor, Notifier, RegistryClient, Clock. Reszta to zwykłe funkcje.
• Małe funkcje i moduły, wstrzykiwanie zależności przez argumenty/fabryki, discriminated unions zamiast flag, brak any, brak globalnego stanu.
• Walidacja na granicach (zod): wyjście skryptów, odpowiedź modelu, HTTP. Ten sam schemat daje typ.
• Testy Vitest obok kodu; domain i app pisz test-first. Przed commitem npm run check (typecheck + lint + test) musi być zielone.
• Nie dodawaj zależności bez powodu; każda nowa to jedna linia uzasadnienia w PR/commicie.

Token / Context Efficiency

Optimize for minimal context usage rather than minimum latency.

Repository exploration

• Search before reading.
• Prefer rg, symbol search, filenames, and targeted ranges.
• Never scan the entire repository unless explicitly required.
• Do not reopen files already inspected unless necessary.
• Read only relevant portions of large files.

Command output

Any command that may generate large output must be filtered or capped.

Prefer:

• targeted grep
• tail/head
• test filters
• selected log ranges

Never load large raw logs, JSON dumps, generated files, or build output into context.

Changes

• Make the smallest correct patch.
• Do not perform unrelated refactoring.
• Do not update unrelated documentation.
• Preserve existing project conventions.

Validation

Validate narrow-to-broad.

1. relevant unit test
2. relevant module tests
3. broader tests only when warranted by scope/risk

Do not repeatedly run the same validation after every small edit.

Agents

Do not spawn subagents by default.

Spawn one only if:

• the task is clearly independent, and
• delegation substantially reduces main-agent context.

Prefer Luna Medium for search/exploration/simple tasks.

Do not recursively spawn agents. Do not create multiple agents investigating overlapping areas.

Sessions

Prefer fresh sessions over repeatedly compacting very large contexts.

Before a session ends, maintain TASK_STATE.md with:

• current objective
• decisions
• completed work
• remaining work
• next exact step
• relevant tests

Keep it concise.