netwatch/AGENTS.md

AGENTS.md

Ziel der Datei

Dieses Dokument beschreibt, welche Informationen ich als Agent für p:\netwatch erwarten würde: Projektziel, Setup, Regeln, Skills, bekannte Issues, Kontext & Einschränkungen.

Ziel

Codex soll bei der Pflege von NEXT_STEPS.md immer die zugehörigen Gitea-Issues berücksichtigen und erledigte Aufgaben über Commit-Messages schließen.

Projektüberblick

• Name: netwatch – ein Netzwerk-Dokumentations- und Verkabelungsverwaltungs-Tool (Alpha v0.2, Core-Module funktionsfähig, Stand: 13. Februar 2026).
• Features: Dashboard, Gerätetypen-/Geräteverwaltung, Racks/Floors mit SVG-Planung, Verbindungen inkl. VLANs, Module, grafische Ansichten (Rack, Netzwerkgraph, Stockwerke/Räume).
• Datenmodell: zentrales SQL-Schema (locations, device_types, devices, connections etc.) mit JSON-Erweiterungsmöglichkeiten.
• Projektphasen (Phase 1–4) sind im README gelistet, siehe letzte Abschnitte.

Schneller Projektstart

docker-compose up -d --build
# danach: http://localhost

Das Docker-Setup (Compose + Portainer) liegt in docker-compose.yml und docker-portainer.yml, ergänzende Infos in Dockerfile.

Verbindliche Regeln

1. Vor jeder Änderung an NEXT_STEPS.md müssen offene Issues geladen werden.
2. Jeder umsetzbare Punkt in NEXT_STEPS.md muss eine Issue-Referenz im Format [#<id>] enthalten.
3. Ein Punkt darf nur als erledigt markiert werden, wenn:
   • die Umsetzung im Code erfolgt ist, und
   • ein Commit mit closes #<id> erstellt wird.
4. Kein „done“ ohne Issue-ID und kein Commit ohne passende closes #<id>-Referenz.
5. Wenn mehrere Issues betroffen sind, alle in der Commit-Message aufführen (z. B. closes #12, closes #18).
6. Beim Erstellen neuer NEXT_STEPS-Punkte sollen möglichst bestehende offene Issues verlinkt statt Duplikate erzeugt werden.

Workflow für Codex

1. Offene Issues abrufen (Skill gitea-issues):
   • python C:/Users/s.titz/.codex/skills/gitea-issues/scripts/list_issues.py <owner> <repo> --state open --limit 100 --json
2. NEXT_STEPS.md aktualisieren:
   • Punkte mit [#<id>] ergänzen oder korrigieren.
3. Umsetzung durchführen.
4. Commit mit Schließ-Referenz erstellen:
   • git commit -m "Kurzbeschreibung der Änderung; closes #<id>"
5. Prüfen, dass jede als erledigt markierte Aufgabe eine geschlossene Issue-Referenz hat.

Formatvorgabe für NEXT_STEPS.md

• Beispiel offen:
  • - [ ] [#42] Backup-Runbook erstellen
• Beispiel erledigt:
  • - [x] [#42] Backup-Runbook erstellen

Annahmen

• Gitea ist so konfiguriert, dass closes #<id> in Commit-Messages das Issue schließt.
• GITEA_TOKEN ist gesetzt, damit Issue-Abfragen funktionieren.

Skills & Nutzungshinweise

• skill-creator – Anleitung zum Erstellen bzw. Erweitern eigener Skills. Pfad: C:/Users/s.titz/.codex/skills/.system/skill-creator/SKILL.md.
• skill-installer – Anleitung zum Installieren zusätzlicher Skills aus Kurationslisten oder GitHub. Pfad: C:/Users/s.titz/.codex/skills/.system/skill-installer/SKILL.md.

Wenn ein Skill genannt wird (z. B. $skill-creator) oder die Aufgabe exakt zur Beschreibung passt, muss dieser Skill in dem Turn verwendet werden. Skills immer erst öffnen (SKILL.md), nur nötige Teile lesen, relative Pfade innerhalb des Skill-Verzeichnisses auflösen. Bei mehreren Skills: minimaler Satz in sinnvoller Reihenfolge, kurz ankündigen, warum welche Skills genutzt wurden.

Lokale Arbeitsregeln

• Arbeitsumgebung: Windows, Pfad P:\netwatch, Shell powershell. Schreibzugriff für mich hier ist verboten; Änderungen müssen vom Nutzer übernommen werden.
• Suche: Nutze rg/rg --files statt grep/find für Geschwindigkeit.
• Codeänderungen: Nur ASCII-Zeichen einführen (außer bestehende Dateien nutzen Unicode); Formate ohne apply_patch nur wenn nötig; bevorzuge apply_patch.
• Keine destruktiven Git-Befehle ohne ausdrückliche Aufforderung (z. B. keinen reset --hard).
• Tests/Builds: Wenn nötig, nenne passende Tests/Prüfmethoden als nächsten Schritt.
• Kommunikation: Verwende beim Antworten absolute Datumsangaben (z. B. „13. Februar 2026“), wenn sich jemand auf „heute/morgen“ bezieht, um Missverständnisse zu vermeiden.

Bekannte Bugs (aus BUGS.md)

• Gerät löschen funktioniert nicht (Status unklar).
• Gerätetypen SVG-Modul: Malfunktion.
• Ports Drag & Drop (Funktion unklar).
• Beim Erstellen von Gerätetypen soll ein voreingestelltes Rechteck basierend auf 19-Zoll & HE-Größe erzeugt werden, das als Grundgerüst dient.
• Device-Typ-Erstellung: Klick auf Objekt-Typ-Button, dann Drag-Drop für Diagonale und Loslassen fixiert Position.

Weitere Ressourcen

• NEXT_STEPS.md (aktuelles ToDo/Roadmap).
• IMPLEMENTATION_STATUS.md (Status-Tracking).
• README.md (Feature- und Architekturübersicht).

Besonderheiten / Kommunikation

• Aktuelles Datum: Freitag, 13. Februar 2026 (nicht überschreiben).
• Keine Netzwerkanfragen möglich; Referenzen nur lokal nutzen.
• Wenn ein Agent spezielle Instruktionen benötigt (z. B. Skill-Anwendung), immer darauf hinweisen und ggf. den Nutzer nach Bestätigung fragen.

Einschränkungen

• Sandbox ist lesend; bitte selbst AGENTS.md anlegen.
• Jegliche Ausgaben/Antworten sollten den Developer-Guidelines folgen (kurz, teamorientiert, klare nächste Schritte).

Wichtig

• Nutze UTF-8, wenn nicht anders angegeben.