diff --git a/docs/Organisation-Konzept.md b/docs/Organisation-Konzept.md index 626fee5..babb291 100644 --- a/docs/Organisation-Konzept.md +++ b/docs/Organisation-Konzept.md @@ -1,6 +1,6 @@ # Organisation — 50 bis 100 Agenten geordnet zusammenarbeiten lassen -*Stand: 21. September 2026. Konzept, noch nicht gebaut.* +*Stand: 24. September 2026 (ergänzt um 7a, 9a, 10a). Konzept, noch nicht gebaut.* > Herkunft: Richtungsentscheidung des Nutzers am 2026-09-21. Die bisherige Regel im > [InstanceSetupGuide](InstanceSetupGuide.md) („mehr als 5 Agenten kritisch @@ -609,6 +609,76 @@ Und quer dazu: Jedes Werkzeug bringt seine Eignungsproben mit das angenehm; bei fünfzig ist es die einzige Art, den Überblick zu behalten, welches Modell womit umgehen kann. +--- + +## 7a — Fremde Laufzeiten + +*Ergänzt am 2026-09-24, angeregt durch Paperclip. Items #712, #713.* + +Der vorige Abschnitt legt fest, dass nur die Entwicklungsabteilung Code hervorbringt. +Daraus folgt eine Frage, die bisher offen war: **Womit programmiert sie?** Ein +nachgebautes Schreib-und-Ausführ-Werkzeug von uns wird nie so gut wie Claude Code, das +auf nichts anderes ausgelegt ist. Und mit einem Abo kann es billiger sein als Tokens über +OpenRouter. + +Also bekommt jeder Agent eine **Laufzeit**: + +| Laufzeit | Was läuft | Wofür | +|---|---|---| +| `native` | unsere Engine mit OpenRouter, wie heute | Voreinstellung, alles außer Programmieren | +| `claude-code` | Claude Code im Kopflos-Modus | die Entwicklungsabteilung | +| `codex` | OpenAI Codex CLI | dasselbe, anderer Anbieter | +| `command` | ein Befehl, dessen Ausgabe das Ergebnis ist | Sonderfälle | +| `http` | ein Aufruf an einen fremden Dienst | Agenten, die woanders laufen | + +**Was die Instanz behält:** Organisation, Taskboard, Budget, Audit, Freigaben. **Was die +fremde Laufzeit übernimmt:** die Arbeit innerhalb eines einzelnen Laufs. Paperclip trennt +das vollständig: *„control plane, not execution plane"*. Wir tun das nicht, und das ist +Absicht. Unsere Sicherheit liegt in der Ausführung (StagingGate, Werkzeugrechte, +UntrustedContent). Eine fremde Laufzeit ist deshalb die Ausnahme für einen bestimmten +Zweck, nicht das Modell für alles. + +### Eine fremde Laufzeit gilt als weniger vertrauenswürdig + +Was innerhalb von Claude Code geschieht, sieht keine unserer Prüfstellen. Daraus folgen +vier Regeln: + +1. **Eigener Arbeitsplatz.** Ein Worktree oder eine Sandbox (#654), nie der + Arbeitsbereich der Instanz selbst. +2. **Freigabelisten statt Rechte-Umgehung.** `--allowedTools` und `--max-turns`, nie + `--dangerously-skip-permissions`. Bei Paperclip ist die Umgehung die Voreinstellung; + bei uns ist sie ausgeschlossen. +3. **Das Ergebnis ist ein Vorschlag.** Ein Diff oder ein fertiges Skript zur Abnahme, nie + ein direkter Einsatz. Ob es eingesetzt wird, entscheidet die Lieferkette aus + Abschnitt 7 (#695). Dass es Claude Code geschrieben hat, erspart keine Prüfung. +4. **Nach außen nur über uns.** Mit Taskboard, Leitung und Ablage spricht die fremde + Laufzeit über einen **MCP-Server, den die Instanz je Lauf bereitstellt** (#713). Jeder + Aufruf dort durchläuft dieselbe Kette wie ein nativer Werkzeugaufruf. Der Server + bietet nur an, was der Agent laut Konfiguration hat, und ist damit kein zweiter Weg + an den Rechten vorbei. Das Token gilt einen Lauf lang und wird nie in der + Befehlszeile übergeben. + +### Kosten, die nichts kosten + +Mit einem Abo kostet ein Lauf 0 $ und verbraucht trotzdem etwas: Kontingent. Die +Token-Zahlen aus `--output-format stream-json` gehen deshalb wie jeder andere Lauf in +RunUsage. In der Kostenanalyse (Abschnitt 8a) erscheinen sie als Kontingentverbrauch, nicht +als „kostenlos". Sonst wird genau die Abteilung unsichtbar, die am meisten Tokens +verbraucht. + +### Zwei Vorbehalte vor dem Bau + +- **Das Kontingent teilt der Mensch mit sich selbst.** Ein Pro-Plan, auf dem die + Entwicklungsabteilung läuft, ist derselbe, mit dem der Mensch arbeitet. Entweder ein + eigener Account oder eine Vorfahrtsregel, die die Abteilung anhält, bevor der Mensch + an die Grenze stößt. +- **Die Nutzungsbedingungen sind nicht geprüft.** Ob der automatisierte Dauerbetrieb + eines Verbraucher-Abos durch ein Agentensystem gedeckt ist, ist offen. Deshalb werden + beide Anmeldewege gebaut, Abo und API-Schlüssel, und die Entscheidung bleibt eine + Frage der Konfiguration statt eine des Umbaus. + +--- + ## 8 — Kontrolle: eine Leitung delegiert nicht nur Modelle machen Fehler. Das ist keine Randbedingung, sondern die Arbeitsgrundlage — vier @@ -889,6 +959,87 @@ Daraus drei Festlegungen: --- +## 9a — Von Paperclip gelernt + +*Ergänzt am 2026-09-24 nach Durchsicht des Paperclip-Quellcodes. Items #714, #715.* + +[Paperclip](https://github.com/paperclipai/paperclip) ist das Projekt, das diesem Konzept +am nächsten kommt: Firma, Organigramm, Budgets, der Mensch als „Board" mit Vetorecht. +Einiges davon lohnt sich zu übernehmen, anderes bewusst nicht. + +### Übernommen: die Zielkette (#714) + +Jede Aufgabe hat eine **Elternaufgabe**, ganz oben steht das Ziel der Einheit. Damit kann +jeder Agent beantworten, *warum* er etwas tut. Die Kette geht als kurzer Absatz in den +Lauf mit. Das ist etwas anderes als `blocked_by`: Die Elternaufgabe ist der Zweck +(„wofür"), der Blocker die Voraussetzung („wann"). Heute kennt `TaskItem` nur den Blocker. + +Daraus folgt eine zweite Fähigkeit, Paperclips *Task Watchdog*: **Kommt ein ganzer +Teilbaum zur Ruhe**, alle Blätter erledigt, abgebrochen, blockiert oder in Prüfung, und +es gibt keinen Weg mehr, auf dem er weiterläuft, dann prüft jemand, ob der Stillstand +berechtigt ist. Denn Agenten hören aus falschen Gründen auf: „erledigt" ohne Beleg, eine +Prüfung ohne Prüfer, ein falsch gelesener Blocker. Ohne Prüfung liegt der Baum einfach +still, und niemand merkt es. Die Aufteilung ist dieselbe wie überall: Ob der Baum ruht, +erkennt eine Abfrage (#646). Ob das in Ordnung ist, deutet die Aufsicht (#680) oder die +Leitung. Der Prüfer gibt zurück, er bessert nicht selbst nach. + +### Übernommen: Rückmeldung nach Vertrauensstufe (#715) + +Das ist der wertvollste Gedanke aus Paperclip, und er schließt eine Lücke, die dieses +Konzept bisher hatte. Ein Agent, der Rezensionen, Mails oder Webseiten liest, hat fremden +Text im Kontext. UntrustedContent (K2) rahmt diesen Text beim Lesen. Schreibt der Agent +seiner Leitung aber einen Kommentar in eigenen Worten, trägt er den fremden Text eine +Ebene höher, in einen Kontext mit mehr Rechten, und dort ist er nicht mehr gerahmt. +**Prompt-Injection über die Hierarchie.** + +Nach oben gibt es deshalb genau drei Wege: + +1. **Das Erledigt-Signal.** Immer an. Die Leitung wird geweckt und liest das Ergebnis im + Vorgang selbst. +2. **Ein Kommentar genau eine Ebene nach oben.** Nur ein Kommentar, keine Status- oder + Feldänderung, nie an die übernächste Ebene oder an Geschwister. **Nur für die + Standardstufe.** +3. **Für Agenten, die fremde Inhalte lesen: kein Freitext nach oben.** Stattdessen + verfasst der Code eine Systemmeldung „blockiert" oder „abgebrochen". Sie löst keine + weitere Meldung aus und geht je Zustand nur einmal hinaus. + +**Woher die Stufe kommt:** aus den Werkzeugen, nicht aus einer Einstellung. Wer WebFetch, +Mail, Rocket.Chat oder ein Skript mit Außenkontakt hat, liest fremde Inhalte. Das weiß +der Code aus der Konfiguration, eine Selbstauskunft des Agenten ist dafür nicht nötig. +Eine Einstellung darf die Stufe nur verschärfen, nie lockern. + +Für Querverbindungen gilt das **„Courier Pattern"**: Wer seitlich etwas braucht, schreibt +nicht in fremde Vorgänge, sondern legt beim Ziel eine vollständige, in sich geschlossene +Aufgabe an. Das ist die Adressbuchregel aus Abschnitt 3 und die Stille-Post-Regel aus +Abschnitt 5, nur zu Ende gedacht: Der Empfänger darf die Vorgänge des Absenders womöglich +gar nicht lesen, also muss alles Nötige in der Aufgabe selbst stehen. + +**Reihenfolge:** vor der Freigabe durch die Leitung (#687). Eine Leitung, die Freigaben +erteilt, darf keinen Kontext haben, in den ein Untergebener fremden Text schreiben kann. + +### Übernommen, im Kleinen + +- **Budget in zwei Stufen.** Die harte Grenze gibt es schon (`BudgetGuard`, Tagesbudget + je Agent und Instanz). Dazu kommt eine Warnung bei 80 % an die Leitung, damit das + Anhalten keine Überraschung ist. Gehört zu #699. +- **Gestaffelte Anzeige.** Oben die lesbare Zusammenfassung, darunter die Schritte, ganz + unten das Rohprotokoll. Gilt für die Teamübersicht (Abschnitt 10a) und die + Laufansichten aus #660. + +### Bewusst nicht übernommen + +- **Rechte-Umgehung als Voreinstellung.** Der Claude-Code-Adapter startet mit + `dangerouslySkipPermissions = true`, und Skills sind „open by default". Das ist das + Gegenteil unserer Linie, jedem Agenten nur die Rechte zu geben, die er braucht. +- **Die ganze Firma sieht alle Arbeit.** Bei Paperclip ist das ausdrücklich gewollt. + Hier trennen die gemeinsamen Bereiche je Einheit bewusst (Abschnitt 3). +- **Die reine Steuerungsebene.** Siehe Abschnitt 7a. +- **Als Warnsignal: die Komplexität.** Allein die Regeln zur Ausführung umfassen dort + über 1.400 Zeilen, bei knapp 5.000 offenen Issues und im Wesentlichen einem einzigen + Hauptentwickler. Das mahnt, nur zu übernehmen, was eine Lücke schließt. + +--- + ## 10 — Was sich am Menschen ändert Bei fünf Agenten ist der Mensch der Koordinator. Bei fünfzig kann er es nicht sein, und @@ -906,6 +1057,91 @@ der Versuch macht ihn zum Flaschenhals. --- +## 10a — Das Lagebild + +*Ergänzt am 2026-09-24 auf Vorschlag des Nutzers. Item #711, baut auf #688 auf.* + +Die **Teamübersicht**: eine grafische Ansicht wie über ein Büro. Nodes für Agenten, Kanten +für ihre Beziehungen. Auf einen Blick sieht man, wer gerade arbeitet, wer mit wem in den +letzten Sekunden gesprochen hat und wo es klemmt. Ein Klick führt zum Agenten. + +Bei fünf Agenten ist das eine Annehmlichkeit. Bei fünfzig ist es die einzige Art, ein +Problem zu bemerken, bevor die Rechnung kommt oder ein Ergebnis fehlt. Abschnitt 10 sagt, +bei fünfzig Agenten müsse etwas anderes dem Menschen sagen, wo er hinsehen soll. Das +Lagebild ist dieses Etwas, zum Hinsehen, neben der Aufsicht (#680) zum Nachlesen. + +### Drei Festlegungen + +1. **Die Anordnung kommt aus der Struktur, nicht aus der Hand.** In n8n oder Node-RED ist + der Graph das Programm, dort zieht man Nodes, und das soll so sein. Hier zeigt der + Graph eine Wahrheit, die woanders liegt: Einheiten, Leitung, Adressbuch. Sind die + Nodes frei platzierbar und verbindbar, zeigt das Bild bald etwas anderes als die + Organisation. Verschieben per Drag & Drop kommt später als Bedienung für den Umzug + (Abschnitt 3), mit gestoppter Instanz, Bestätigung und Audit-Eintrag, nicht als + Zeichenwerkzeug. +2. **Einheiten sind aufklappbare Container, Probleme wandern nach oben.** Hundert Nodes + mit wechselnden Kanten sind ein Knäuel. Standardansicht sind die Abteilungen mit einer + Zusammenfassung: „4 arbeiten · 1 Problem · 2 Freigaben offen". Eine Markierung am + Container heißt „irgendwo darin", und man klappt auf, bis man den Agenten findet. + Kanten zwischen Einheiten werden gebündelt, mit Zähler. +3. **„Problem" stellt der Code fest, nicht das Modell.** Die Zustände: + + | Zustand | Woher | + |---|---| + | arbeitet | aktiver Lauf | + | wartet auf Freigabe | offene StagedCalls | + | wartet auf Kollegen | laufende Delegation | + | Problem | letzter Lauf gescheitert, LoopGuard-Abbruch, Eskalation über Frist, Budget erschöpft | + | hängt | Lauf deutlich länger als bei diesem Agenten üblich | + | pausiert / aus | Konfiguration | + + Immer Farbe **und** Symbol. + +### Der Klick führt in die Seitenleiste, nicht direkt in den Chat + +Die meisten Probleme löst man nicht im Gespräch: Oft wartet eine Freigabe, oder ein +Werkzeug ist dreimal gescheitert. Die Seitenleiste zeigt den laufenden Lauf, den letzten +Fehler im Wortlaut, offene Aufgaben und Freigaben (dort bestätigbar), die Kosten von heute +gegen den Durchschnitt und den Knopf „Chat öffnen". Das ist ein Klick mehr, dafür ist +der richtige Handgriff meist schon da. + +### Technik + +- **Datenquelle** ist der vorhandene Ereignisstrom (`MergedEventStream`). Neu sind + Ereignistypen mit Absender und Empfänger: Delegation, Task-Zuweisung, später Besprechung + und Eskalation, jeweils mit eigener Linienart. Das Verblassen nach einigen Sekunden + geschieht im Browser. +- **Bibliothek:** Cytoscape.js mit ELK-Layout. Es kann verschachtelte Container und + hierarchisches Layout und bleibt bei Hunderten Nodes flüssig, ohne React. Als Datei im + `wwwroot`, nicht über ein CDN. +- **Nur in der WebUI.** Ein zweiter Graph-Renderer in Avalonia wäre doppelte Arbeit, die + auseinanderläuft. Der Desktop bettet die Ansicht ein oder verlinkt sie. +- Englisch, Texte über Sprachpakete (#661). + +### Stufen + +- **Stufe 0**, ohne Einheiten: die vorhandenen Agenten mit Delegationskanten und + Zuständen. Das nützt sofort, auf der Test-VM mit sieben Agenten. +- **Stufe 1**, mit #683: Container und nach oben gereichte Probleme. Ab hier fällt das + Lagebild mit dem Organigramm aus #688 zusammen; es gibt nicht zwei Ansichten der + Organisation. +- **Später: die Zeitleiste.** „Wie sah das Büro um 3:12 Uhr aus?" Das kostet wenig, weil + nichts gelöscht wird (Abschnitt 8a): Das AuditLog wird nur neu abgespielt. Für die Frage, + wie ein Projekt gescheitert ist, ist das vielleicht das wertvollste Werkzeug überhaupt. + +### Wie andere es machen + +Paperclip hat ein statisches Organigramm mit einem Statuspunkt je Agent und daneben eine +Liste der laufenden Läufe, aber keine Ansicht der Kommunikation. LangGraph Studio zeigt den +laufenden Node eines *Ablaufgraphen*, also eines Programms, nicht einer Organisation. +AutoGen Studio, Flowise und Langflow sind Baukästen („Nodes ziehen = Programm"), gut zum +Bauen, schwach als Lagebild. ChatDev und AI Town zeigen das Büro wörtlich als +Pixelgrafik: charmant, aber mit wenig Information. Die Verbindung aus aufklappbarer +Organisation, Live-Zuständen und nach oben gereichten Problemen mit Direktzugriff hat +keines davon. + +--- + ## 11 — Reihenfolge Nichts davon muss auf einmal entstehen. Die Reihenfolge ist so gewählt, dass jede Stufe @@ -914,10 +1150,11 @@ 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 | +| **0a** | Lagebild ohne Einheiten (#711, Stufe 0) | Der Mensch sieht auf der Test-VM sofort, wer arbeitet und wo es klemmt | | **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** | Ursprungsverweis in jedem Vorgang (#697) | Entscheidungen stützen sich auf das Original, nicht auf die vierte Nacherzählung | +| **4** | Ursprungsverweis in jedem Vorgang (#697); Zielkette (#714); Rückmeldung nach Vertrauensstufe (#715) | Entscheidungen stützen sich auf das Original, jede Aufgabe kennt ihren Zweck, und fremder Text steigt nicht in der Hierarchie auf | | **5** | Eskalation, Konflikt und Beschluss (#689) | Eine Frage, die niemand beantworten kann, versandet nicht mehr | | **6** | Besprechung als Mittel, mit Protokoll | Leitungen können sich abstimmen, ohne *n²* Nachrichten | | **7** | Entscheidungsinstanz an der Spitze (#690) | Der Betrieb läuft weiter, wenn der Mensch schläft | @@ -925,11 +1162,11 @@ für sich schon nützt und keine die nächste blockiert. | **9** | Kontrollpflicht der Leitung, abgestufte personelle Mittel (#693); Doctrine (#698) | Fehler findet die Leitung, nicht erst der Mensch — und sie kann steuern | | **9a** | Kosten je Einheit, Abweichungsmeldung (#699), Archiv (#700) | Ineffizienz wird sichtbar, bevor sie einen Monat lang läuft | | **9b** | Abstimmung als dritte Freigabeform (#702) | Vier Blickwinkel statt einer Unterschrift, wo es sich lohnt | -| **10** | Oberfläche: Organigramm statt Agentenliste, Lage je Abteilung | Bei fünfzig Agenten ist eine flache Liste keine Übersicht | +| **10** | Oberfläche: Organigramm und Lagebild in einem (#688, #711 Stufe 1) | Bei fünfzig Agenten ist eine flache Liste keine Übersicht | | **11** | Organisationsvorlagen (#691) | Ein Haus lässt sich weitergeben statt nachbauen | Quer dazu, unabhängig von der Reihenfolge: der Werkzeugkasten (#692), der A/B-Vergleich -von Modellen (#694) und die Schemaauskunft (#676) — letztere ist Vorbedingung für +von Modellen (#694), die fremden Laufzeiten samt MCP-Server (#712, #713; nach der Sandbox #654) und die Schemaauskunft (#676) — letztere ist Vorbedingung für Stufe 5, weil eine Eskalation einen belastbaren Negativbefund braucht. **Zum Umzug (Abschnitt 3):** Er gehört zu Stufe 1. Eine Struktur, die sich nach dem @@ -984,6 +1221,11 @@ Gegenlesen am 2026-09-22 als zu grob aufgefallen: Maschinerie, solange niemand nachsieht. Vorschlag: Das Eskalationswerkzeug sucht von sich aus, bevor es einen Vorgang anlegt — genau wie `task_find` vor `task_create` (#674). Ein Beschluss, den man aktiv lesen müsste, wird nicht gelesen (Stufe 5). +- **Auf welchem Account läuft eine fremde Laufzeit?** (Abschnitt 7a, vor #712.) Ein + Pro-Plan teilt sein Kontingent mit dem Menschen, und ob der automatisierte + Dauerbetrieb eines Verbraucher-Abos von den Nutzungsbedingungen gedeckt ist, ist + ungeprüft. Vorschlag: beide Anmeldewege bauen, als Voreinstellung den API-Schlüssel + nehmen und das Abo erst nach Prüfung der Bedingungen freigeben. - ~~**Was passiert, wenn die Eskalationsgrenze erreicht ist?**~~ **Entschieden am 2026-09-22, und schärfer als vorgeschlagen: Eine Eskalation, die nicht gelöst werden kann, darf es nicht geben.** Finden die Agenten binnen einer einstellbaren Frist keine @@ -1024,3 +1266,8 @@ nur nicht selbst an. | #654, #196, #657 | Sandbox, Shell, Skriptprüfung — der eigentliche Werkzeugkasten | | #687 | Freigabe durch die Leitung innerhalb von Grenzen | | #688 | Organigramm in Oberfläche und WebUI | +| #711 | Lagebild (Teamübersicht): wer arbeitet, wer spricht mit wem, wo klemmt es | +| #712 | Fremde Laufzeiten: Claude Code, Codex, Befehl, HTTP | +| #713 | ClawdDotNet als MCP-Server für fremde Laufzeiten | +| #714 | Zielkette und Prüfung ruhender Aufgabenbäume | +| #715 | Rückmeldung nach Vertrauensstufe, Courier Pattern |