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.

---

## Host Troubleshooting

### Automatische Erkennung

Wenn du in einem Verzeichnis unter `~/Nextcloud/hosts/` arbeitest:

1. **Lade die lokale Dokumentation**
   - Lies `copilot-instructions.md` falls vorhanden
   - Verstehe den System-Typ und Kontext

2. **Bei Troubleshooting-Aufgaben**
   - Nutze den Skill `/troubleshoot-host` für strukturiertes Vorgehen
   - Dokumentiere Lösungen in der `copilot-instructions.md`

### Verzeichnisstruktur

```
~/Nextcloud/hosts/
├── [kunde]/                    # z.B. vinos, egonetix
│   └── [hostname]/             # z.B. srv-monitor02, srv-db12
│       └── copilot-instructions.md
└── _templates/
    └── copilot-instructions-template.md   # Master-Template
```

### Neuen Host dokumentieren

1. Erstelle Verzeichnis: `mkdir -p ~/Nextcloud/hosts/[kunde]/[hostname]`
2. Kopiere Template: `cp ~/Nextcloud/hosts/_templates/copilot-instructions-template.md ./copilot-instructions.md`
3. Fülle während der Arbeit die relevanten Felder aus
4. Committe die Dokumentation

### Skills-Referenz

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