oskar/homelab-codex-ws
1
0
Fork 0
Code Issues Pull requests Actions Packages Projects Releases Wiki Activity
homelab-codex-ws/kb/subsystems/agent-operating-procedures.md
oskar 6dffa5c565 fix(kb): przepiecie wszystkich odwolan wewnetrznych po migracji 
126 plikow (md, yaml, sh, py) odwolywalo sie do sciezek sprzed migracji.

  15  markdown-linkow [..](..) -> policzona sciezka WZGLEDNA wobec pliku
      odsylajacego (wczesniej czesc z nich byla repo-root-relative i nie
      rozwiazywala sie z katalogu, w ktorym lezala)
 200  odwolan tekstowych (backticki, proza, yaml, importy w kodzie)
      -> nowa sciezka repo-root-relative, zgodnie z konwencja repo
   5  linkow rodzenstwa (gole nazwy plikow, np. "](DEPLOY.md)") — dzialaly
      tylko w starym katalogu; przeliczone recznie

Objete m.in.: CLAUDE.md (scripts/onboard/README.md -> kb/runbooks/
node-onboarding-tool.md, docs/backlog.md -> kb/phases/backlog.md),
README.md, .claude/skills/, 20 session logow, kod jobow.

Ostatnie 5 odwolan pochodzi z tresci wciagnietej rebasem z origin/master
(session log 2026-07-31, override node-agenta na SOLARII, dwie pozycje
backlogu) — wskazywaly na docs/incidents/, docs/kb/modules/ i
services/narty27/README.md sprzed migracji.

Dodany wzajemny link miedzy kb/services/control-plane.md (stub kodu)
a kb/subsystems/control-plane.md (opis, deprecated) — dwa dokumenty o tym
samym systemie, latwe do pomylenia.

Weryfikacja na 790 plikach: 0 odwolan do starych sciezek,
0 martwych linkow markdown. Lint OKF: 190/190 plikow ZGODNE.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-08-04 16:21:16 +02:00

3.2 KiB
Raw Blame History

okf type visibility status updated links
0.1 subsystem public active 2026-05-20

Agent Operating Procedures

This document defines the operating procedures, constraints, and interaction protocols for non-human agents (AI agents, autonomous scripts) within the Homelab Codex ecosystem.

1. Core Principles for Agents

  1. Read-Only by Default: Agents should assume read-only access to the /opt/homelab runtime unless explicitly executing an approved action.
  2. Git as Authority: The repository on SATURN is the source of truth. Agents must not modify the runtime state on nodes directly without corresponding (or pending) Git state, unless it's an emergency mitigation.
  3. Human-in-the-Loop (HIL): All destructive or structural changes (restarts, deployments, config changes) must follow the Action Approval Model.
  4. Idempotency: All scripts and actions proposed or executed by agents MUST be idempotent.
  5. Context-Awareness: Agents MUST read the README.md and kb/subsystems/agent-operating-procedures.md at the start of every session to align with current infrastructure standards.

2. Agent Roles

Role Responsibility Scope
Observer Monitors health, logs, and events. Read-only access to /opt/homelab/events and logs.
Stability Agent Local node watchdog, event emitter. Local node runtime, service.yaml healthchecks.
Orchestrator High-level planning, workload placement. Repository-wide, multi-node topology.
Materializer Translates high-level intent into Docker/System state. Execution of approved actions.

3. Discovery Protocol

Agents must use the following entry points to understand the system:

  1. Topology: inventory/topology.yaml for node list and roles.
  2. Capabilities: hosts/<node>/capabilities.yaml to understand hardware/software constraints.
  3. Service Contract: services/<service>/service.yaml to understand how to check health and manage a service.
  4. Operational State: /opt/homelab/state/ on local nodes for real-time status.

4. Interaction with Humans

Agents communicate with the operator via the agent-system/telegram-bot.

  • Alerting: Agents emit events to the event system. Critical events are forwarded to Telegram.
  • Proposals: When an agent identifies a need for change (e.g., "Service X is failing, suggest restart"), it creates a pending action in /opt/homelab/actions/pending/.
  • Approval: Agents must wait for the action status to transition to approved before execution.

5. Decision Logic (Reasoning)

When making decisions, agents MUST prioritize:

  1. Safety: Do not violate power constraints (see capabilities.yaml).
  2. Stability: Prefer keeping services on their owner_node unless it's down.
  3. Connectivity: On intermittent nodes (CHELSTY), avoid actions requiring heavy WAN traffic during low-signal periods.

6. Access Control for Agents

  • Filesystem: Agents should run as the homelab user or equivalent with restricted sudo access to docker compose.
  • Secrets: Agents MUST NOT attempt to read .env files unless specifically tasked with credential rotation. They should treat secrets as opaque handles.