claude_settings/CLAUDE.md

Global Claude Code Instructions

🚨 PFLICHT-CHECKLISTE BEI TASK-ABSCHLUSS 🚨

DIESE CHECKLISTE IST NICHT OPTIONAL. SIE MUSS BEI JEDER ABGESCHLOSSENEN AUFGABE DURCHGEFÜHRT WERDEN.

BEVOR du dem User sagst, dass du fertig bist, gehe diese Liste durch:

Bei JEDER Dokumentationsarbeit (README, Config-Docs, etc.):

• Verifikation durchgeführt?

  • Vergleichstabelle: Quelle ↔ Dokumentation erstellt
  • ALLE Abschnitte geprüft (nicht nur die offensichtlichen)
  • Finale Checkliste mit Zeilennummern erstellt
  • Bestätigung: "X/X Abschnitte vollständig dokumentiert"

• Infrastructure-Repo aktualisiert?

  • Wenn Kunde erkannt (~/Nextcloud/[kunde]/):
    • infrastructure/hosts/[host].md aktualisiert?
    • infrastructure/dependencies.md aktualisiert?
  • Änderungen committet und gepusht?

Bei JEDEM Task-Abschluss:

• Alle Änderungen committet und gepusht?

  • Aktuelles Repo
  • Infrastructure-Repo (falls relevant)

• Settings-Sync geprüft?

  cd ~/dotfiles/claude_settings && git fetch origin && git status
  

⚠️ WICHTIG

Du darfst NICHT:

• Sagen "Erledigt" ohne diese Checkliste durchzugehen
• Den User fragen ob er die Checkliste will - sie ist PFLICHT
• Schritte überspringen weil sie "offensichtlich nicht nötig" sind
• Warten bis der User dich an fehlende Schritte erinnert

Der User verlässt sich darauf, dass du diese Anweisungen IMMER befolgst.

---

⚠ MANDATORY: Settings-Synchronisierung

Repository: git@gitea.egonetix.de:root/claude_settings.git (Port 222) Lokaler Pfad: ~/dotfiles/claude_settings

Bei jedem Session-Start prüfen

cd ~/dotfiles/claude_settings && git fetch origin && git status

Falls Änderungen vorhanden:

git pull origin main

Nach Änderungen an Settings pushen

Wenn du Änderungen an folgenden Dateien vornimmst, MUSST du diese committen und pushen:

• settings.json - Globale Einstellungen
• CLAUDE.md - Diese Instruktionen
• agents/*.md - Benutzerdefinierte Agenten
• rules/*.md - Modulare Regeln
• statusline-command.sh - Statuszeilen-Script

cd ~/dotfiles/claude_settings
git add -A
git commit -m "Beschreibung der Änderung"
git push origin main

---

Copilot Instructions Skill

Maintain living documentation for every coding project via copilot-instructions.md in the project root.

---

Mandatory Workflow

Step 1: Determine Project Type

Check for existing project indicators:

• Git repository (.git/ directory)
• copilot-instructions.md file
• PROJECT_OVERVIEW.md file

If ANY exist → Ongoing Project: Follow full documentation workflow.

If NONE exist → Ask the user:

"This looks like a new workspace. Should I treat this as a one-time task, or set it up as an ongoing project with documentation and git?"

If user wants an ongoing project:

1. Initialize git repo if missing (git init)
2. Create copilot-instructions.md with initial structure
3. Optionally create PROJECT_OVERVIEW.md for complex systems

Step 2: For Ongoing Projects

1. Read existing copilot-instructions.md and PROJECT_OVERVIEW.md to understand the system
2. Scan the codebase/system to gather context and minimize follow-up questions
3. Update documentation if the current work affects architecture, patterns, entities, or conventions
4. Commit all changes to git immediately after completion

---

Document Structure

copilot-instructions.md (Development Guidelines)

Procedural knowledge for working on the project — patterns, conventions, pitfalls, workflows.

# Project Name - Copilot Instructions

## ⚠ MANDATORY RULES - NON-NEGOTIABLE
[Project-specific rules, commit conventions, critical warnings]

## Architecture Overview
[High-level system description, key integrations, tech stack]

## File Structure
[Directory tree with annotations]

## [Domain-Specific Sections]
[Devices, APIs, services, databases - whatever is relevant]
- Working code examples with explanations
- Configuration snippets that actually work
- Debug commands

## Patterns & Conventions
[Reusable patterns, naming conventions, code examples]

## Development Workflow
[How to test, deploy, access systems]

## Pitfalls to Avoid
[Gotchas, inverted logic, non-obvious behaviors, troubleshooting]

PROJECT_OVERVIEW.md (System Reference)

Factual inventory of what exists — devices, integrations, entities, IPs. Use for complex systems with many components.

# Project Overview

## System Information
[Version, host, IP, access details]

## Network Architecture
[Diagram or list of hosts/devices]

## Installed Components
[Add-ons, plugins, integrations with purpose]

## Entity/Device Inventory
[Tables of devices, entity IDs, purposes]

## Quick Reference
[Common commands, URLs, access methods]

When to create PROJECT_OVERVIEW.md:

• Systems with many devices/entities (IoT, home automation)
• Infrastructure projects with multiple hosts
• Projects where entity/device inventory changes frequently

---

Content Guidelines

Include:

• Working code/config snippets (tested and verified)
• Actual entity names, IPs, paths (not placeholders)
• Debug commands and troubleshooting tables
• Lessons learned from debugging sessions
• Non-obvious behavior ("contact sensor: on=OPEN, off=CLOSED")
• Git commit references for significant changes

Exclude:

• Secrets, tokens, passwords (reference secrets.yaml or .env instead)
• Obvious boilerplate explanations
• Duplicate information

Language: Match the user's language. Mixed language is acceptable when technical terms are clearer in English.

---

Git Commit Convention

After every change:

cd /path/to/project
git add -A
git commit -m "Descriptive message in user's language"
git push origin main  # or appropriate branch

Commit messages should describe what changed, not just "updated docs".

---

Referencing Git Commits

For significant development work, reference the relevant commit(s) in the documentation:

## Tasmota SML Integration

**Implemented:** 2025-01-21 | Commits: `a3f2b1c`, `e7d4a9f`

[Documentation of the feature...]

When to add commit references:

• New features or integrations
• Major refactors
• Complex bug fixes that required multiple attempts
• Configuration changes that took significant debugging

Format options:

• Single commit: Commit: a3f2b1c
• Multiple commits: Commits: a3f2b1c, e7d4a9f, b2c3d4e
• Commit range: Commits: a3f2b1c..e7d4a9f

Get the short hash after committing:

git log -1 --format="%h"  # Most recent commit
git log -3 --format="%h %s"  # Last 3 with messages

---

When to Update copilot-instructions.md

Update when:

• Adding new integrations, devices, or services
• Discovering non-obvious behavior or gotchas
• Establishing new patterns or conventions
• Fixing bugs that reveal important system behavior
• Changing architecture or file structure

Don't update for:

• Minor code changes that don't affect understanding
• Temporary debugging that will be removed

---

New Project Onboarding

When a user requests to set up a new ongoing project:

1. Connect and explore the system to understand what exists
2. Scan broadly — gather device lists, integrations, file structures, configurations
3. Create documentation based on findings:
   • copilot-instructions.md for development guidelines and patterns
   • PROJECT_OVERVIEW.md for system inventory (if complex)
4. Initialize git if not present
5. Commit initial documentation

This upfront investment minimizes questions in future sessions and enables faster, more informed development.

---

Infrastruktur-Dokumentationssystem

Organisation pro Kunde

Gitea-Struktur:

├── Vinos/                       ← Organisation für Kunde "vinos"
│   ├── infrastructure.git       ← Landkarte für vinos
│   ├── zabbix.git               ← System-Repo
│   └── [weitere].git            ← Dienst-/System-Repos
│
└── Egonetix/                    ← Organisation für Kunde "egonetix"
    ├── infrastructure.git       ← Landkarte für egonetix
    └── [weitere].git

Lokale Struktur:

~/Nextcloud/
├── vinos/                       ← Kunde vinos
│   ├── infrastructure/          ← Landkarte (dependencies.md, hosts/)
│   ├── zabbix/                  ← System-Repo
│   └── [weitere]/               ← Dienst-/System-Repos
│
└── egonetix/                    ← Kunde egonetix
    ├── infrastructure/
    └── [weitere]/

Repo-Typen

Repo-Typ	Gitea-Ort	Inhalt
Infrastructure	[Kunde]/infrastructure.git	Landkarte, Abhängigkeiten, Host-Übersichten
System-Repo	[Kunde]/[system].git	README, Konfig-Dateien, Troubleshooting
Dienst-Repo	[Kunde]/[dienst].git	docker-compose.yml, Code, Workflows

Automatische Erkennung (Hook-gesteuert)

Der Session-Start Hook erkennt Kunden-Verzeichnisse unter ~/Nextcloud/[kunde]/.

Wenn du <REPO_SETUP_REQUIRED> in der Hook-Ausgabe siehst:

1. Frage den User:

   "Ich habe erkannt, dass für dieses Repo noch Setup erforderlich ist. Soll ich das automatisch durchführen?"

2. Bei Zustimmung - führe alle fehlenden Schritte aus:

   # Git initialisieren (falls nicht vorhanden)
   git init
   git branch -M main
   
   # Template aus infrastructure/_templates/ kopieren
   

3. Repo auf Gitea erstellen (API):

   curl -X POST -H "Authorization: token $GITEA_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{"name":"repo-name","description":"..."}' \
     https://gitea.egonetix.de/api/v1/orgs/[Kunde]/repos
   

4. Remote hinzufügen und pushen:

   git remote add origin ssh://git@gitea.egonetix.de:222/[Kunde]/[repo-name].git
   git push -u origin main
   

Gitea Remote-Konfiguration

URL-Format:

ssh://git@gitea.egonetix.de:222/[Kunde]/[repo-name].git

Beispiele:

Kunde	Repo	Remote URL
Vinos	infrastructure	ssh://git@gitea.egonetix.de:222/Vinos/infrastructure.git
Vinos	zabbix	ssh://git@gitea.egonetix.de:222/Vinos/zabbix.git
Egonetix	infrastructure	ssh://git@gitea.egonetix.de:222/Egonetix/infrastructure.git

Gitea Tooling

Token-Speicherort (NICHT im Git-Sync!):

~/.config/gitea/token

Verfügbare Tools:

Tool	Befehl	Anwendung
tea CLI	~/bin/tea	Vollständige Gitea-Interaktion
curl + API	curl -H "Authorization: token $(cat ~/.config/gitea/token)"	Einfache API-Aufrufe

tea CLI Beispiele:

# Repos auflisten
~/bin/tea repos list

# Neues persönliches Repo erstellen
~/bin/tea repos create --name mein-repo --description "Beschreibung"

# Neues Repo in Organisation erstellen
~/bin/tea repos create --owner Vinos --name repo-name

# Issues auflisten
~/bin/tea issues list

# PR erstellen
~/bin/tea pr create --title "Feature X" --description "..."

curl API Beispiele:

# Persönliches Repo erstellen
curl -X POST -H "Authorization: token $(cat ~/.config/gitea/token)" \
  -H "Content-Type: application/json" \
  -d '{"name":"repo-name","description":"...","private":false}' \
  https://gitea.egonetix.de/api/v1/user/repos

# Repo in Organisation erstellen
curl -X POST -H "Authorization: token $(cat ~/.config/gitea/token)" \
  -H "Content-Type: application/json" \
  -d '{"name":"repo-name","description":"..."}' \
  https://gitea.egonetix.de/api/v1/orgs/[Org]/repos

Wichtig: Der Token wird LOKAL gespeichert und NICHT nach ~/dotfiles/claude_settings synchronisiert.

Workflow: Neues System-/Dienst-Repo anlegen

cd ~/Nextcloud/[kunde]
git init [repo-name]
cd [repo-name]
# Template aus ../infrastructure/_templates/ kopieren
# Repo auf Gitea erstellen
# git remote add origin ...
# git push -u origin main

Dokumentations-Verifikation (PFLICHT)

Bei jeder Dokumentationsarbeit MUSS eine zweistufige Verifikation durchgeführt werden:

• Neue Dokumentation erstellen
• Bestehende Dokumentation umstrukturieren
• Inhalte aus anderen Quellen übernehmen
• Dokumentation aufteilen oder zusammenführen

Schritt 1: Erstvergleich

Nach Abschluss der Dokumentationsarbeit, erstelle eine Vergleichstabelle:

| Abschnitt (Original) | Neue Datei | Status |
|---------------------|------------|--------|
| [Abschnitt 1] | [datei.md:zeilen] | ✅/❌ |
| [Abschnitt 2] | [datei.md:zeilen] | ✅/❌ |
...

• Liste JEDEN Abschnitt der Quelldokumentation auf
• Prüfe ob er in der neuen Struktur vorhanden ist
• Markiere fehlende Abschnitte mit ❌

Schritt 2: Fehlende Inhalte ergänzen

• Ergänze alle mit ❌ markierten Abschnitte
• Committe die Änderungen

Schritt 3: Erneute Verifikation (PFLICHT)

Nach dem Ergänzen MUSS eine erneute, vollständige Prüfung erfolgen:

1. Lies alle neuen Dateien nochmals
2. Erstelle eine finale Checkliste mit Zeilennummern:

| # | Abschnitt | Datei:Zeilen | Status |
|---|-----------|--------------|--------|
| 1 | [Name] | README.md:15-18 | ✅ |
| 2 | [Name] | hosts.md:5-8 | ✅ |
...

3. Bestätige: "X/X Abschnitte vollständig dokumentiert. Keine Inhalte wurden vergessen."

Dieser Prozess ist nicht optional. Dokumentationsverlust durch unvollständige Arbeit ist inakzeptabel.

Skills-Referenz

Skill	Zweck
/troubleshoot-host	Strukturierter Troubleshooting-Workflow
/session-end	Session beenden, Commits erstellen
/new-project	Neues Projekt anlegen