claude_settings/CLAUDE.md

# Global Claude Code Instructions

## ⚠ 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

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

Falls Änderungen vorhanden:
```bash
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

```bash
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.

```markdown
# 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.

```markdown
# 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:

```bash
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:

```markdown
## 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:
```bash
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:**

   ```bash
   # Git initialisieren (falls nicht vorhanden)
   git init
   git branch -M main

   # Template aus infrastructure/_templates/ kopieren
   ```

3. **Repo auf Gitea erstellen (API):**
   ```bash
   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:**
   ```bash
   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` |

**Wichtig:** Das Repo muss auf Gitea ZUERST erstellt werden (API oder Web-UI).

### Workflow: Neues System-/Dienst-Repo anlegen

```bash
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 Dokumentations-Migration oder -Erstellung MUSS eine zweistufige Verifikation durchgeführt werden:**

#### Schritt 1: Erstvergleich

Nach Erstellung/Migration der Dokumentation, erstelle eine Vergleichstabelle:

```markdown
| 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:

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

3. Bestätige: **"X/X Abschnitte erfolgreich migriert. Keine Dokumentation wurde vergessen."**

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

### Skills-Referenz

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