# Portabilität: SYSTEM
# Version: 1.1.0
# Zuletzt validiert: 2026-05-17
# Nächste Prüfung: 2026-11-17
# Ressourcen: [hub/agent_launcher.py, agents/, agents/_experts/]

AGENT - Agent-Launcher und Verwaltung
=====================================

STAND: 2026-05-17

Das Agent-System erlaubt das Starten und Verwalten von BACH-Agenten
als separate Claude-Code-Prozesse. Jeder Agent wird mit seiner eigenen
SKILL.md als Identität gestartet.

STRUKTUR
--------

  [Boss-Agent]         -- Koordiniert und delegiert
       |
       +-- [Experte 1] -- Spezialisierte Ausführung
       +-- [Experte 2]

Agenten-Verzeichnisse:
  agents/              Boss-Agenten (mit SKILL.md)
  agents/_experts/     Experten (mit SKILL.md)

CLI-BEFEHLE (bach agent)
------------------------

  list                        Alle verfügbaren Agents auflisten
  start <name>                Agent starten (neues Terminalfenster)
  stop <name>                 Laufenden Agent stoppen
  steer <name> "..."          Operator-Hinweis für laufenden Agenten vormerken
  clear-steer <name>          Vorgemerkte Operator-Hinweise gezielt löschen
  rename <name> <neu>         Display-Name eines Agenten/Experten ändern
  status                      Alle laufenden Agents anzeigen
  doctor [name]               Agent-Preflight und Recovery-Hinweise
  list --json                 Agenten inkl. Laufzeit-Metadaten als JSON
  start <name> --json         Startantwort maschinenlesbar als JSON
  stop <name> --json          Stop-Antwort maschinenlesbar als JSON
  steer <name> --json         Steer-Antwort inkl. Queue-Stand als JSON
  clear-steer <name> --json   Queue-Bereinigung inkl. Queue-Stand als JSON
  status --json               Laufende/registrierte Agenten als JSON
  doctor [name] --json        Diagnose maschinenlesbar als JSON

OPTIONEN FÜR START
------------------

  --mode plan|default         Modus (Standard: default)
  --model sonnet|opus|haiku   KI-Modell (Standard: sonnet)
  --dry-run                   Nur prüfen, nicht starten
  --json                      Maschinenlesbare Ausgabe für list/start/stop/status/doctor

BEISPIELE
---------

  # Alle Agents auflisten (inkl. Laufstatus)
  bach agent list

  # Agent starten
  bach agent start ati
  bach agent start research --model opus
  bach agent start entwickler --mode plan
  bach agent start ati --dry-run
  bach agent start ati --dry-run --json

  # Laufende Agents anzeigen und steuern
  bach agent status
  bach agent status --json
  bach agent steer ati "Bitte nur Statusflächen anfassen." --json
  bach agent clear-steer ati --json

  # Start-Voraussetzungen und Recovery prüfen
  bach agent doctor ati
  bach agent doctor Theodor --json

  # Agent stoppen (per Name)
  bach agent stop ati
  bach agent stop ati --json

VERFÜGBARE AGENTEN (Auswahl)
----------------------------

  [BERUFLICH]
    ati               Software-Entwickler-Agent (Scanner, Sessions)
    entwickler        Allgemeiner Entwickler-Agent
    production        Produktions-Workflow-Agent
    research          Wissenschaftliche Recherche
    bueroassistent    Steuern, Förderplanung, Dokumentation
    reflection        Selbstreflexion und Meta-Analyse

  [PRIVAT]
    persoenlicher-assistent   Terminverwaltung, Recherche
    gesundheitsassistent      Medizinische Dokumentation
    versicherungen            Versicherungs-Verwaltung

  [EXPERTEN]
    steuer            Steuer-Experte (unter _experts/)
    foerderplaner     Förderantrag-Experte
    haushaltsmanagement
    psycho-berater

Aktuelle Liste: bach agent list

WIE ES FUNKTIONIERT
-------------------

1. `bach agent start <name>` findet die SKILL.md des Agenten
2. Eine temporäre CLAUDE.md wird erstellt (`data/temp/agent_<name>/`)
3. Ein neues Terminalfenster öffnet sich mit Claude Code
4. PID wird in `data/agent_pids/<name>.pid` gespeichert
5. `bach agent steer <name> "..."` schreibt Operator-Hinweise in `OPERATOR_NOTES.md`
6. `bach agent status --json` zeigt Queue-Stand, `latest_operator_note` und verfügbare Aktionen maschinenlesbar
7. `bach agent clear-steer <name>` leert eine veraltete oder erledigte Hinweis-Queue gezielt
8. `bach agent stop <name>` beendet den Prozess und löscht die PID

VORAUSSETZUNGEN
---------------
- Claude Code CLI muss installiert sein (Befehl: `claude`)
- Agent muss eine SKILL.md haben (`agents/<name>/SKILL.md`)

RECOVERY / TROUBLESHOOTING
--------------------------

Wenn `bach agent start ...` fehlschlägt oder ein Agent-Fenster sofort wieder
schließt, zuerst die Diagnose ausführen:

  bach agent doctor ati
  bach agent doctor ati --json

`doctor` prüft:
- ob die Claude Code CLI im PATH gefunden wird
- ob `data/agent_pids/` und `data/temp/` beschreibbar sind
- ob der angefragte Agent und seine `SKILL.md` lesbar sind
- ob veraltete PID-Dateien bereinigt werden müssen

Typische nächste Schritte nach dem Report:
- `bach agent start <name> --dry-run` für einen sicheren Vorabtest
- `bach agent status --json` bei laufenden oder hängenden Sessions
- `bach agent clear-steer <name> --json`, wenn erledigte Hinweise in der Queue liegen
- Claude Code CLI installieren oder Login/Setup lokal prüfen

DATENBANK
---------
  bach.db:
    agents              Agenten-Registry
    agent_synergies     Synergien zwischen Agenten

DATEIEN
-------
  hub/agent_launcher.py     Handler-Implementation
  agents/                   Boss-Agenten-Ordner
  agents/_experts/          Experten-Ordner
  data/agent_pids/          PID-Dateien laufender Agents
  data/temp/agent_*/        Temporäre CLAUDE.md pro Agent
