Organisation: 50-100 Agenten als Ziel, "hoechstens 5" zurueckgezogen (#682-#688)

Die Regel im InstanceSetupGuide war in der Beobachtung richtig und in der
Folgerung falsch: quadratisch steigen die Verbindungen, nicht die Agenten.
Ein Agent, der drei Nachbarn und eine Leitung kennt, kostet gleich viel, ob
die Instanz zehn oder hundert Agenten hat.

docs/Organisation-Konzept.md haelt fest, was heute bei 50 Agenten bricht
(flaches Adressbuch, synchrones send_message, Delegationstiefe 3,
unbegrenzte Parallelitaet, Kappung bei 500, zwei Arbeitsbereiche, ein Brett,
zwei Budgetebenen, eine Freigabe-Warteschlange) und schlaegt die fehlende
Ebene vor: die Einheit.

Zwei davon sind schon heute Fehler und gehoeren sofort behoben (#682).

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

docs/Basisagenten-Konzept.md

@@ -41,20 +41,20 @@ Instanz mit einem einzigen fachlichen Agenten braucht keine Aufsicht über sich
 | **Personalmanager** | Legt Agenten an, konfiguriert sie, führt Probelauf (#649) und Werkzeugproben ([Werkzeugproben-Konzept](Werkzeugproben-Konzept.md)) durch. | #649 beschreibt das Werkzeug, die Rolle fehlt |
 | **Security-Agent** | Bewertet Befunde, schlägt Quarantäne vor. | Bereits festgelegt als Profil des AgentInspector, [Security-Konzept](Security-Konzept.md) Abschnitt 9, #658 |
 
-### Der Einwand, der zuerst beantwortet gehört
+### Die Bedingung, ohne die es nicht trägt
 
-Der InstanceSetupGuide warnt ausdrücklich: mehr als fünf Agenten sind kritisch zu
+**Basisagenten reden nicht** — weder mit den fachlichen Agenten noch miteinander. Sie
-hinterfragen, weil der Koordinationsaufwand quadratisch steigt. Vier Basisagenten
+lesen (Audit, Receipts, Taskboard, Prompt-History) und schreiben Aufgaben.
-obendrauf scheinen dieser Regel ins Gesicht zu schlagen.
 
-Sie tun es nicht, aber nur unter einer Bedingung: **Basisagenten reden nicht mit den
+Das ist nicht Sparsamkeit, sondern die Rechnung: Jede Nachricht zwischen zwei Agenten
-fachlichen Agenten und nicht miteinander.** Sie lesen (Audit, Receipts, Taskboard,
+kostet auf beiden Seiten einen Lauf. Eine Aufsicht, die einmal täglich liest und eine
-Prompt-History) und schreiben Aufgaben. Die Warnung im Guide gilt dem Nachrichtenverkehr
+Aufgabe hinterlässt, kostet einen Lauf — nicht *n*. Eine Aufsicht, die nachfragt, kostet
-— jede Nachricht kostet auf beiden Seiten einen Lauf. Eine Aufsicht, die einmal täglich
+so viele Läufe, wie sie Agenten hat.
-liest und eine Aufgabe hinterlässt, kostet einen Lauf, nicht *n*.
 
-Wird diese Bedingung aufgeweicht, kippt die Rechnung sofort. Sie gehört deshalb nicht in
+Die Bedingung gehört deshalb in die Rechte, nicht in den Prompt: Basisagenten bekommen
-den Prompt, sondern in die Rechte: Basisagenten bekommen `AgentComm.send_message` nicht.
+`AgentComm.send_message` nicht. Im Aufbau aus dem
+[Organisation-Konzept](Organisation-Konzept.md) sind sie eine eigene Einheit neben der
+Fachorganisation, mit Lesesicht über alle Einheiten und ohne Adressbuch.
 
 ---
 

docs/InstanceSetupGuide.md

@@ -11,21 +11,43 @@ Bevor eine Instanz erstellt wird, muss klar definiert werden:
 | Frage | Beispiel |
 |-------|---------|
 | Welche Aufgabe(n) soll die Instanz als Ganzes erledigen? | "Social-Media-Monitoring mit automatischer Zusammenfassung" |
-| Wie viele Agenten werden benötigt? | 1–5 (mehr = höhere Koordinationskosten) |
+| Wie viele Agenten werden benötigt? | So viele, wie es Zuständigkeiten gibt — die Kosten stecken in den Verbindungen, nicht in der Zahl |
 | Welche externen Systeme sind beteiligt? | Telegram, E-Mail, Datenbank, APIs |
 | Wie hoch ist das Token-Budget pro Tag? | z.B. $1/Tag, $10/Tag |
 | Soll die Instanz autonom arbeiten oder manuell getriggert werden? | Cron-Jobs vs. manueller Start |
 
 ### Agentenanzahl richtig wählen
 
+> **Geändert am 2026-09-21.** Hier stand: „Mehr als 5 Agenten — kritisch hinterfragen,
+> Koordinationsoverhead steigt quadratisch." Die Beobachtung stimmt, die Folgerung war
+> falsch. Quadratisch steigen die **Verbindungen**, nicht die Agenten. Eine Instanz, die
+> einen Onlinehandel betreibt, braucht Einkauf, Buchhaltung, Marketing und Logistik mit je
+> mehreren Agenten — fünf reichen dafür nicht annähernd. Das Ziel von ClawdDotNet sind
+> 50 bis 100 Agenten, die geordnet zusammenarbeiten. Die Begründung und was dafür fehlt:
+> [Organisation-Konzept](Organisation-Konzept.md).
+
 | Szenario | Empfehlung |
 |----------|-----------|
 | Eine klar abgegrenzte Aufgabe | 1 Agent |
 | Aufgabe mit getrennten Zuständigkeiten (z.B. Recherche + Bericht) | 2–3 Agenten |
-| Komplexes System mit Koordination | 3–5 Agenten, davon 1 Koordinator |
+| Ein Fachgebiet mit mehreren Teilaufgaben | So viele Agenten wie Teilaufgaben, plus eine Leitung |
-| Mehr als 5 Agenten | Kritisch hinterfragen — Koordinationsoverhead steigt quadratisch |
+| Mehrere Fachgebiete | Je Gebiet eine Einheit mit eigener Leitung; die Leitungen reden miteinander, die Mitglieder nicht |
 
-**Faustregel:** Jeder Agent, der mit einem anderen kommuniziert, kostet Token auf beiden Seiten. Zwei Agenten, die jeweils 3 Nachrichten austauschen = 6 LLM-Runs.
+**Die Faustregel gilt weiter, aber sie zielt auf etwas anderes:** Jede Nachricht zwischen
+zwei Agenten kostet auf beiden Seiten einen Lauf. Zwei Agenten, die drei Nachrichten
+tauschen, sind sechs Läufe. Teuer wird also nicht der elfte Agent, sondern der elfte
+Agent, der **jeden** anderen ansprechen darf.
+
+Deshalb ist die eigentliche Entwurfsfrage nicht „wie viele Agenten?", sondern **„wer muss
+mit wem reden?"** Ein Agent, der drei Nachbarn und eine Leitung kennt, kostet gleich viel,
+ob die Instanz zehn oder hundert Agenten hat. Ein Agent, der eine Liste aller hundert
+bekommt, kostet bei jedem Blick in diese Liste.
+
+Bis die Strukturen aus dem [Organisation-Konzept](Organisation-Konzept.md) gebaut sind,
+ist das Adressbuch flach: `list_agents` zeigt jedem Agenten alle anderen. Bei mehr als
+etwa zehn Agenten heißt das, `AgentComm` nur den Agenten zu geben, die es wirklich
+brauchen — und den übrigen die Zusammenarbeit über das Taskboard zu geben, das keine
+Gegenseite wachhält.
 
 ---
 

docs/Organisation-Konzept.md

@@ -0,0 +1,230 @@
+# Organisation — 50 bis 100 Agenten geordnet zusammenarbeiten lassen
+
+*Stand: 21. September 2026. Konzept, noch nicht gebaut.*
+
+> Herkunft: Richtungsentscheidung des Nutzers am 2026-09-21. Die bisherige Regel im
+> [InstanceSetupGuide](InstanceSetupGuide.md) („mehr als 5 Agenten kritisch
+> hinterfragen") ist damit zurückgezogen.
+>
+> **Das Ziel:** ClawdDotNet ist der Harness — das Büro, der Konferenzraum, die Groupware
+> der Agenten. Eine Instanz betreibt einen Onlinehandel mit Einkauf, Buchhaltung,
+> Marketing und Logistik; jede Abteilung hat mehrere Agenten, dazu Leitungen und
+> beliebig viele weitere Ebenen. 50 bis 100 Agenten arbeiten parallel an einem großen
+> Vorhaben, nie alle gleichzeitig, aber alle an derselben Sache.
+
+---
+
+## 1 — Was an der alten Regel richtig war und was falsch
+
+Richtig: Der Aufwand steigt quadratisch. Falsch: dass er an der Zahl der Agenten hängt.
+
+Er hängt an der Zahl der **Verbindungen**. Zehn Agenten, von denen jeder jeden ansprechen
+darf, sind 45 mögliche Kanäle. Hundert Agenten in Teams von sieben, die nur ihre
+Nachbarn und ihre Leitung kennen, sind rund 700 — bei zehnmal so vielen Agenten nur
+fünfzehnmal so viele Kanäle statt hundertmal.
+
+**Die Entwurfsfrage lautet also nicht „wie viele Agenten?", sondern „wer muss mit wem
+reden?"** Ein Agent, der drei Nachbarn und eine Leitung kennt, kostet gleich viel, ob die
+Instanz zehn oder hundert Agenten hat.
+
+Der Logistiker spricht nie mit dem Amazon-Anzeigen-Agenten. Muss es doch einmal sein,
+trägt seine Abteilungsleitung es in die Leitungsrunde, und von dort geht es an die
+Leitung der Gegenseite. Das ist keine Bürokratie, sondern der Grund, warum echte
+Organisationen mit tausend Menschen funktionieren und eine Gruppenchat-Gruppe mit
+fünfzig nicht.
+
+---
+
+## 2 — Was heute bei 50 Agenten bricht
+
+Nicht Meinung, sondern Code-Stand 0.1.15. Das ist die eigentliche Antwort auf die Frage,
+was fehlt: **zwischen „Instanz" und „Agent" gibt es keine Ebene.** Alles, was heute nicht
+am einzelnen Agenten hängt, ist instanzweit — und damit ein gemeinsamer Engpass.
+
+| Stelle | Heute | Bei 50 Agenten |
+|---|---|---|
+| `AgentComm.list_agents` | liefert **alle** anderen Agenten, flach, mit Name, Rolle, Modell, Zustand | 49 Einträge im Prompt jedes Fragenden. Der Logistiker erfährt, dass es einen Amazon-Anzeigen-Agenten gibt — genau das, was er nicht wissen soll |
+| `AgentComm.send_message` | **wartet auf die Antwort** des Zielagenten | Eine Leitung, die vier Teams fragt, blockiert durch vier Läufe hindurch. Eine Besprechung ist kein Funktionsaufruf |
+| `MaxDelegationDepth = 3` | drei Weitergaben | Vorstand → Abteilung → Team → Agent ist bereits erschöpft |
+| Scanner: `Task.WhenAll(claimed…)` | **unbegrenzt parallel** | 50 fällige Aufgaben um Punkt 9 Uhr sind 50 gleichzeitige Modellaufrufe. Ratengrenzen, Kostenspitze — und die Budgetprüfung je Lauf lässt sie alle gleichzeitig passieren |
+| Scanner: `TaskQuery { Limit = 500 }` | stille Obergrenze | 100 Agenten mit je fünf Terminaufgaben liegen darüber. Aufgaben fallen lautlos aus dem Takt |
+| Arbeitsbereiche | genau zwei: `personal` und `shared` | Buchhaltung und Einkauf teilen sich einen Dorfplatz. Eine Abteilungsablage gibt es nicht |
+| `sharedAccessLevel` | eine Stufe für den ganzen gemeinsamen Bereich | „Buchhaltung darf ihre Ablage schreiben, die von Marketing nur lesen" ist nicht ausdrückbar |
+| Taskboard | ein Brett für alles; `task_list` kappt bei 8.000 Zeichen | Auf der Testinstanz mit 7 Agenten stehen 159 Aufgaben. Mit 50 Agenten ist die Liste als Übersicht wertlos |
+| Budget | zwei Ebenen: Agent und Instanz | „Marketing darf 20 $/Tag" ist nicht ausdrückbar |
+| Freigaben | eine Warteschlange, ein Mensch | Der Mensch wird zum Flaschenhals der gesamten Organisation |
+
+Zwei dieser Punkte sind schon heute Fehler, unabhängig von der Größe: die unbegrenzte
+Parallelität und die stille Kappung bei 500. Sie gehören sofort behoben (#682).
+
+---
+
+## 3 — Die fehlende Ebene: Einheiten
+
+Eine **Einheit** (Abteilung, Team, Gruppe) ist ein Knoten in einem Baum. Sie hat einen
+Namen, eine Leitung, Mitglieder und Untereinheiten. Alles, was heute instanzweit ist,
+bekommt sie als Ebene dazwischen:
+
+```
+Instanz „Onlinehandel"
+├── Einkauf ──────────── Leitung: einkauf-leitung
+│   ├── Produktsuche ──── produktscout-1, produktscout-2, trendbeobachter
+│   ├── Lieferanten ───── lieferantensuche, konditionen, nachverhandlung
+│   └── Qualität ──────── musterpruefung
+├── Buchhaltung ───────── Leitung: buchhaltung-leitung
+│   ├── Kreditoren ────── rechnungspruefung, zahlungslauf
+│   ├── Überwachung ───── zahlungsverkehr, mahnwesen
+│   └── Auswertung ────── monatsabschluss, kennzahlen
+├── Marketing ─────────── Leitung: marketing-leitung
+│   ├── Webshop ───────── shop-texte, shop-preise, shop-bilder
+│   ├── Marktplätze ───── amazon-listing, amazon-anzeigen, ebay-listing, …
+│   └── Inhalte ───────── social, newsletter
+├── Logistik ──────────── Leitung: logistik-leitung
+│   ├── Sendungen ─────── sendungsverfolgung, problemfaelle
+│   └── Retouren ──────── retourenbearbeitung
+└── Betrieb ───────────── (Basisagenten, siehe Basisagenten-Konzept)
+```
+
+### Was die Einheit trägt
+
+| Was | Heute | Mit Einheiten |
+|---|---|---|
+| **Adressbuch** | alle | die eigene Einheit, die eigene Leitung. Eine Leitung sieht zusätzlich die Leitungen der Geschwistereinheiten |
+| **Arbeitsbereich** | `personal`, `shared` | `personal`, `einheit`, `shared`. Die Abteilungsablage ist der Normalfall, `shared` die Ausnahme |
+| **Rechte** | je Agent | vererbt von der Einheit, je Agent verschärfbar. Was die Einheit nicht darf, kann ein Mitglied nicht bekommen |
+| **Taskboard** | ein Brett | ein Brett je Einheit; `task_list` zeigt die eigene Einheit, die Leitung sieht die Untereinheiten |
+| **Budget** | Agent, Instanz | Agent, Einheit, Instanz — jede Ebene deckelt die darunter |
+| **Freigaben** | ein Mensch | die Leitung innerhalb ihrer Grenzen, der Mensch für alles darüber (Geld, Außenwirkung) |
+| **Parallelität** | unbegrenzt | je Einheit und je Instanz eine Zahl gleichzeitiger Läufe, der Rest wartet |
+
+### Die eine Regel, die alles zusammenhält
+
+**Ein Agent kennt nur seine Einheit und seine Leitung.** Alles andere geht über die
+Leitung. Das ist keine Höflichkeitsform, sondern das, was die Kosten deckelt: Der
+Zuschnitt des Adressbuchs *ist* die Organisationsstruktur.
+
+Und weil das Adressbuch aus der Struktur kommt statt aus einer Einstellung, kann man es
+nicht versehentlich aufweichen. Wer einem Agenten mehr Reichweite geben will, verschiebt
+ihn im Baum — sichtbar und begründbar.
+
+---
+
+## 4 — Die Besprechung als eigenes Mittel
+
+Der Vorschlag nennt den Konferenzraum, und das ist mehr als ein Bild. Heute gibt es zwei
+Arten, wie Agenten sich austauschen: `send_message` (synchron, wartet, ein Gegenüber) und
+das Taskboard (asynchron, ein Auftrag, ein Bearbeiter). Für „die Teamleitungen stimmen
+sich ab" taugt beides nicht.
+
+Eine **Besprechung** ist:
+
+- **ein Termin**, kein Aufruf — sie steht im Taskboard wie jede andere wiederkehrende Sache
+- **eine Tagesordnung**, die vorher feststeht, und eine Teilnehmerliste, die vorher feststeht
+- **eine Leitung**, die eröffnet, die Runde macht und das Ergebnis schreibt
+- **eine Runde je Teilnehmer**, nicht *n* Nachrichten: jeder Teilnehmer wird einmal
+  aufgerufen, bekommt die Tagesordnung und die bisherigen Beiträge, antwortet einmal
+- **ein Protokoll** als Ergebnis — ein Dokument in der Ablage der Einheit, plus Aufgaben
+  für das, was beschlossen wurde
+
+Damit kostet eine Leitungsrunde mit sechs Teilnehmern sieben Läufe, nicht sechs mal
+sechs. Und sie hinterlässt etwas Nachlesbares statt einer Kette von Nachrichten, die
+niemand rekonstruieren kann.
+
+Das ist auch der Weg des Beispiels aus dem Vorschlag: Der Logistiker meldet ein Problem
+mit Amazon-Sendungen an seine Leitung. Die bringt es in die Leitungsrunde. Die
+Marketing-Leitung nimmt es mit und legt in ihrem Brett eine Aufgabe für den
+Amazon-Anzeigen-Agenten an. Vier Läufe, kein direkter Kanal, ein Protokoll.
+
+---
+
+## 5 — Was eine Organisation braucht und ein Agentenhaufen nicht
+
+Der Punkt, der beim Bauen am leichtesten übersehen wird: **Eine Organisation lebt von
+gemeinsamem, dauerhaftem Wissen, das in keinem Kopf steckt.**
+
+Im Beispiel: der Lieferantenstamm, der Artikelstamm, die offenen Bestellungen, die
+Retourengründe. Wenn drei Einkaufsagenten je ihre eigene Vorstellung der Lieferantenliste
+im Gedächtnis tragen, hat die Instanz drei Wahrheiten und keine davon stimmt. Das ist
+kein Modellproblem und kein Prompt-Problem — es ist die Frage, was Datenbank ist und was
+Kontext.
+
+Daraus drei Festlegungen:
+
+1. **Stammdaten gehören in die Datenbank**, nicht in das Gedächtnis von Agenten. Das
+   Gedächtnis ist für Erfahrungen („dieser Lieferant antwortet nie vor Dienstag"), nicht
+   für Fakten („Lieferant X, Mindestbestellmenge 50").
+2. **Dokumente gehören in die Ablage der Einheit**, mit einem Eigentümer. Ein Bericht,
+   den zwei Agenten gleichzeitig schreiben, ist ein verlorener Bericht.
+3. **Was mehrere Einheiten brauchen, ist eine bewusste Entscheidung** — ein
+   ausdrücklich geteilter Bereich mit benanntem Eigentümer, nicht das Standardverhalten.
+
+---
+
+## 6 — Was sich am Menschen ändert
+
+Bei fünf Agenten ist der Mensch der Koordinator. Bei fünfzig kann er es nicht sein, und
+der Versuch macht ihn zum Flaschenhals.
+
+- **Freigaben wandern in die Struktur.** Die Abteilungsleitung gibt frei, was innerhalb
+  ihrer Grenzen liegt. Der Mensch gibt frei, was Geld bewegt, nach außen wirkt oder die
+  Struktur selbst ändert. Das ist die natürliche Fortsetzung von #641 (Rechte in der
+  Werkzeugkonfiguration) — nur mit der Einheit als zusätzlicher Ebene.
+- **Berichtet wird verdichtet.** Nicht fünfzig Laufergebnisse, sondern vier
+  Abteilungsberichte und eine Lage.
+- **Die Aufsicht (#680) wird von einer Annehmlichkeit zur Notwendigkeit.** Bei fünf
+  Agenten kann ein Mensch die Läufe lesen. Bei fünfzig muss etwas anderes ihm sagen, wo
+  er hinsehen soll.
+
+---
+
+## 7 — Reihenfolge
+
+Nichts davon muss auf einmal entstehen. Die Reihenfolge ist so gewählt, dass jede Stufe
+für sich schon nützt und keine die nächste blockiert.
+
+| Stufe | Inhalt | Nutzen für sich |
+|---|---|---|
+| **0** | Parallelität deckeln, stille Kappung bei 500 beseitigen (#682) | Fehler, unabhängig von der Größe |
+| **1** | Einheiten als Struktur: Baum, Zugehörigkeit, vererbte Rechte, Adressbuch nach Einheit | Der Schnitt, der alles Weitere trägt |
+| **2** | Ablage und Brett je Einheit | Buchhaltung und Einkauf treten sich nicht mehr auf die Füße |
+| **3** | Budget und Parallelität je Einheit | Eine ausufernde Abteilung legt nicht die Instanz lahm |
+| **4** | Besprechung als Mittel, mit Protokoll | Leitungen können sich abstimmen, ohne *n²* Nachrichten |
+| **5** | Freigabe durch die Leitung innerhalb von Grenzen | Der Mensch hört auf, Flaschenhals zu sein |
+| **6** | Oberfläche: Organigramm statt Agentenliste, Lage je Abteilung | Bei fünfzig Agenten ist eine flache Liste keine Übersicht |
+
+Stufe 1 ist die einzige, die wirklich weh tut, weil sie Konfiguration, Werkzeuge,
+Arbeitsbereiche und Oberfläche gleichzeitig berührt. Sie zuerst zu bauen ist trotzdem
+richtig: jede spätere Stufe hängt daran, und jede Woche, die eine Instanz ohne Einheiten
+wächst, wird der Umzug teurer.
+
+---
+
+## 8 — Offene Entscheidungen
+
+- **Ist eine Einheit ein Agent?** Eine Leitung könnte ein gewöhnlicher Agent mit
+  besonderen Rechten sein — oder die Einheit hat eine Leitungsrolle, die auch unbesetzt
+  bleiben kann (dann übernimmt die übergeordnete Leitung). Vorschlag: das zweite. Eine
+  Einheit ohne Leitung muss möglich sein, sonst kostet jede Gliederung sofort einen Agenten.
+- **Wie tief?** `MaxDelegationDepth = 3` muss steigen, aber nicht auf unendlich — eine
+  Kette ohne Grenze ist wieder ein Zyklus in Zeitlupe. Vorschlag: Tiefe des Baums plus
+  eins, aus der Struktur berechnet statt als Zahl eingestellt.
+- **Gehören Einheiten in die Instanzkonfiguration oder in die Datenbank?** Die
+  Zugehörigkeit ändert sich selten, aber sie ändert Rechte — also gehört sie dorthin, wo
+  Änderungen im Audit stehen. Vorschlag: Datenbank, mit Abbild in der Konfiguration.
+- **Darf ein Agent in zwei Einheiten sein?** In echten Organisationen ja (Matrix). Das
+  macht das Adressbuch und die Rechtevererbung deutlich schwieriger. Vorschlag: zunächst
+  nein, und beobachten, ob es fehlt.
+
+---
+
+## 9 — Items
+
+| Item | Vorhaben |
+|---|---|
+| #682 | Läufe deckeln: Parallelität begrenzen, Kappung bei 500 beseitigen |
+| #683 | Einheiten: Baum, Zugehörigkeit, vererbte Rechte, Adressbuch nach Einheit |
+| #684 | Ablage und Taskboard je Einheit |
+| #685 | Budget und Parallelität je Einheit |
+| #686 | Besprechung: Termin, Tagesordnung, Runde, Protokoll |
+| #687 | Freigabe durch die Leitung innerhalb von Grenzen |
+| #688 | Organigramm in Oberfläche und WebUI |