# Portabilität: UNIVERSAL
# Version: 1.2.0
# Zuletzt validiert: 2026-03-12 (Persona-System SUGAR v3.8.0 dokumentiert)
# Nächste Prüfung: 2026-09-12

BACH AGENTEN-SYSTEM
==================

Hierarchisches System aus Boss-Agenten und Experten mit Persona-System.

DREI EBENEN
-----------

  Skills     Das Substanzielle. Wissen, Code, Workflows.
             Portierbar, exportierbar, der eigentliche Wert.

  Personas   Das Interface. Name, Stil, Charakter.
             Personalisierbar (bach agent rename), Geschmackssache.

  Sessions   Die Laufzeit. Context Window, Tools, Turns.
             Technisches Detail.

STRUKTUR
--------

Boss-Agenten koordinieren, Experten sind spezialisiert:

  [Boss-Agent]
       |
       +-- [Experte 1]
       +-- [Experte 2]


VERFÜGBARE AGENTEN (agents/)
-------------------------------------

[BERUFLICH]

  ATI (ati/) — Persona: Atlas
    Software-Entwickler-Agent mit Scanner, Sessions
    Features: Task-Scanner, Headless Sessions, Tool Discovery

  Entwickler (entwickler)
    Allgemeiner Entwickler-Agent

  Production (production)
    Produktions-Workflow-Agent

  Research (research)
    Wissenschaftliche Recherche (PubMed, Perplexity, Consensus)

  Büroassistent (bueroassistent) — Persona: Clara
    Steuern, Förderplanung, Dokumentation
    Experten: Steuer (Theodor), Förderplaner (Florian)

  Reflection (reflection)
    Selbstreflexion und Meta-Analyse


[PRIVAT]

  Persönlicher Assistent (persoenlicher-assistent) — Persona: Paul
    Terminverwaltung, Recherche, Kommunikation
    Experten: Haushaltsmanagement (Martha)

  Gesundheitsassistent (gesundheitsassistent) — Persona: Helena
    Medizinische Dokumentation und Verwaltung
    Experten: Gesundheitsverwalter (Gustav), Psycho-Berater (Sophie)

  Versicherungen (versicherungen)
    Versicherungs-Verwaltung

  Finanz-Assistent (finanz-assistent) — Persona: Felix
    Finanzplanung und Budgetierung


[TEST]

  Test-Agent (test-agent)
    Für Tests und Experimente


PERSONA-SYSTEM (SUGAR v3.8.0)
------------------------------

Seit SUGAR v3.8.0 haben Agenten und Experten benannte Personas:
menschliche Vornamen + Charakter-Beschreibungen in der Datenbank.

  DB-Spalten:
    display_name    Persona-Vorname (z.B. "Atlas", "Theodor")
    persona         Charakter-Text (z.B. "Pragmatischer Handwerker...")

  Befehle:
    bach agent rename <name> <neuer-name>   Display-Name ändern
    bach agent list                          Zeigt Personas in Klammern
    bach agent info <name>                   Details inkl. Persona

  Namensauflösung (resolve_agent_name):
    1. Exakter System-Name (z.B. "steuer-agent")
    2. Display-Name (z.B. "Theodor")
    3. Substring (z.B. "theo")
    4. Fuzzy/Levenshtein (z.B. "teodor")

  Persona-Injektion:
    Beim Agent-Start wird die Persona als System-Prompt injiziert:
    "Dein Name ist \"Theodor\". Dein Charakter: Peniler Steuerberater..."
    Siehe: hub/agent_launcher.py (_get_persona_info)


  Boss-Agenten Personas:

    System-Name               | Persona | Charakter
    ati                       | Atlas   | Pragmatischer Handwerker
    bueroassistent            | Clara   | Strukturierte Organisatorin
    finanz-assistent          | Felix   | Aufmerksamer Sparfuchs
    gesundheitsassistent      | Helena  | Fürsorgliche Begleiterin
    persoenlicher-assistent   | Paul    | Vielseitiger Allrounder


  Experten Personas:

    System-Name               | Persona     | Charakter
    steuer-agent              | Theodor     | Peniler Steuerberater
    financial_mail            | Frieda      | Mail-Detektivin
    aboservice                | Anton       | Kündigungskönig
    gesundheitsverwalter      | Gustav      | Archivar der Befunde
    psycho-berater            | Sophie      | Einfühlsame Zuhörerin
    health_import             | Hugo        | Gewissenhafter Datenpfleger
    haushaltsmanagement       | Martha      | Sparsame Hauswirtschafterin
    foerderplaner             | Florian     | Fördermittel-Experte
    bewerbungsexperte         | Benjamin    | Karriere-Coach
    data-analysis             | Diana       | Zahlenflüsterin
    decision-briefing         | Dietrich    | Kühler Stratege
    report_generator          | Rita        | Effiziente Berichtsmaschine
    mr_tiktak                 | Mr. TikTak  | Strategischer Taktiker
    transkriptions-service    | Tristan     | Geduldiger Zuhörer
    wikiquizzer               | Wilhelm     | Quizmaster

  Template: skills/_templates/TEMPLATE_PERSONA.md
  Migration: data/schema/migrations/034_agent_personas.py


CLI-BEFEHLE
-----------

  # Agenten auflisten
  bach --agents list
  python tools/agent_cli.py list

  # Experten anzeigen
  python tools/agent_cli.py experts

  # Agent-Details
  python tools/agent_cli.py info <agent-name>

  # Persona umbenennen
  bach agent rename <name> <neuer-display-name>

  # User-Ordner initialisieren
  python tools/agent_cli.py init all
  python tools/agent_cli.py init <agent-name>

  # Datenbank einrichten
  python tools/agent_cli.py setup-db

  # System-Status
  python tools/agent_cli.py status


VERZEICHNISSE
-------------

  agents/     Boss-Agenten Definitionen (11 Agenten)
  agents/_experts/    Experten-Ordner mit CONCEPT.md (17 Experten)
  user/<agent>/       User-Datenordner pro Agent

WICHTIG: Agenten und Experten sind unterschiedliche Konzepte!
  - Agenten (Boss): Koordinieren und delegieren (agents/)
  - Experten: Spezialisierte Ausführung (agents/_experts/)
  - Einige in Help gelistete "Agenten" sind eigentlich Experten:
    * steuer-agent -> _experts/steuer/
    * foerderplaner -> _experts/foerderplaner/
    * haushaltsmanagement -> _experts/haushaltsmanagement/
    * psycho-berater -> _experts/psycho-berater/


DATENBANKEN
-----------

  bach.db:
    - bach_agents (Agenten-Registry + display_name + persona)
    - bach_experts (Experten-Registry + display_name + persona)
    - agent_synergies (Synergien zwischen Agenten)

  bach.db:
    - Tabellen je Experte (health_*, household_*, etc.)


WORKFLOW
--------

1. Agent aktivieren (über Skill oder CLI)
2. Agent lädt Skill-Definition und User-Daten
3. Persona wird als System-Prompt injiziert (display_name + persona)
4. Bei Spezialthema: Delegation an Experten
5. Experte führt aus, Boss-Agent fasst zusammen


GUI
---

  http://127.0.0.1:8000/agents     Agenten-Übersicht
  http://127.0.0.1:8000/ati        ATI-Agent Details
  http://127.0.0.1:8000/steuer     Steuer-Agent Details


DATEIEN
-------

  agents/ati/              ATI-Agent Ordner
  agents/ati/ATI.md        ATI Definition
  agents/persoenlicher-assistent.txt
  agents/gesundheitsassistent.txt
  agents/bueroassistent.txt
  agents/steuer-agent.txt
  agents/research.txt
  agents/entwickler.txt
  agents/production.txt
  agents/README.md


STANDARDS
---------

Pflicht-Dateien:

  1. Jeder Agent und Expert MUSS eine SKILL.md haben
     (nicht rolle.txt, nicht CONCEPT.md als Ersatz)
  2. SKILL.md MUSS YAML-Frontmatter enthalten:
     name, version, type, description (Minimum)
  3. CONCEPT.md ist OPTIONAL (für detaillierte Konzepte)
  4. rolle.txt ist DEPRECATED (in SKILL.md migrieren)

Persona-System (SUGAR v3.8.0 -- implementiert):

  Alle Agenten und Experten haben benannte Personas in der DB.
  Personas bestehen aus display_name (Vorname) und persona (Charakter).

  Konzept: Persona (wer) + Skill (was) + Session (wie)
    - Persona: Charakter mit Stil und Grenzen (DB + optional Datei)
    - Skill: Fähigkeit mit Code und Instruktionen (exportierbar)
    - Session: Laufzeitumgebung (tools, turns, model)

  Addressing: Agent über Persona-Name ansprechbar
    (z.B. "Frag Theodor wegen der Steuer")

  Zukunft: Persona-Dateien in agents/personas/ (schrittweise Migration)

Anthropic-Kompatibilität:

  - Skills sind exportierbar (offener Standard, LobeHub/Cursor etc.)
  - Personas/Agents sind NICHT portierbar (nur Claude Code / BACH)
  - Export: bach skills export <name> --format anthropic
  - Neuer Skill: bach skills create <name> --format anthropic

  Siehe: bach help skill_standards


SIEHE AUCH
----------

  bach help skill_standards  Anthropic Skill-Standards
  bach help actors           Überblick über Akteure
  bach help bach_paths       Verzeichnisstruktur
  bach help practices        Architektur-Prinzipien
  bach help ati              ATI Software-Entwickler Details
  bach wiki lobehub          LobeHub Marketplace
