225 lines
8 KiB
Markdown
225 lines
8 KiB
Markdown
# AGENT CONTRACTS — Rollen-Verträge
|
|
|
|
> **Geltungsbereich:** Red Queen Autonomous Engineering System v1
|
|
> **Status:** Verbindliche Verträge für alle Sub-Agenten-Rollen
|
|
> **Sprache:** Deutsch (verbindlich)
|
|
|
|
---
|
|
|
|
## 0. Allgemeine Vertrags-Regeln (für alle Rollen)
|
|
|
|
- **TASK_ID (Pflicht):** Jede delegierte Aufgabe hat eine eindeutige ID, die in jedem Output
|
|
und jeder Meldung referenziert wird.
|
|
- **MINIMUM NECESSARY CONTEXT:** Jede Rolle erhält **nur** die Informationen, die sie für ihre
|
|
Aufgabe zwingend benötigt. Kein Kontext-Teilen über den Bedarf hinaus.
|
|
- **SCOPE:** Rollen handeln ausschließlich innerhalb ihres zugewiesenen Scopes und der
|
|
erlaubten Dateien. **FORBIDDEN_FILES** sind unantastbar.
|
|
- **SAFETY GATES:** Alle Limits aus `SAFETY_CONTRACT.md` gelten. Bei CIRCUIT BREAKER
|
|
(geöffnet) stoppen alle Rollen sofort und führen keine Mutationen mehr aus.
|
|
- **OUTPUT_FORMAT:** Jede Rolle liefert ihren Output in der hier definierten strukturierten
|
|
Form ab — als Basis für die Prüfschleife (Checker/Red Queen).
|
|
- **Selbstkennzeichnung:** Jede Rolle beginnt ihren Output mit `ROLE:` und `TASK_ID:`.
|
|
|
|
---
|
|
|
|
## 1. PLANNER
|
|
|
|
**Zweck:** Zerlegt eine Mission in ausführbare Work Packages (WP), priorisiert, ordnet
|
|
Abhängigkeiten und schätzt Aufwand.
|
|
|
|
**Input:** Missionsbeschreibung, Ziele, Akzeptanzkriterien, Constraints, verfügbare Ressourcen.
|
|
|
|
**Output (strukturiert):**
|
|
```
|
|
ROLE: PLANNER
|
|
TASK_ID: <id>
|
|
GOAL: <Ziel der Mission>
|
|
SCOPE: <Umfang>
|
|
WORK_PACKAGES:
|
|
- WP_ID: <id>
|
|
DESCRIPTION: <Beschreibung>
|
|
CLASSIFICATION: SMALL|MEDIUM|LARGE|CRITICAL|DIFFICULT|SELF-MOD
|
|
DEPENDENCIES: <[WP_ID]>
|
|
ESTIMATE: <Aufwand>
|
|
OWNER_ROLE: <MAKER|DEBUGGER|...>
|
|
ORDER / SEQUENCING: <Reihenfolge>
|
|
RISKS / OPEN QUESTIONS: <Liste>
|
|
```
|
|
|
|
**Regeln:**
|
|
- Erstellt ausschließlich einen Plan, **implementiert nicht selbst**.
|
|
- Jede WP trägt eine Klassifikation gemäß `ARCHITECTURE.md` §5 (bestimmt Rollenzuordnung).
|
|
- Berücksichtigt die Prioritätsprinzip (Hermes NATIVE > … > EXTERNAL).
|
|
- Zeitbudget der Ausführung mit einplanen.
|
|
|
|
---
|
|
|
|
## 2. MAKER
|
|
|
|
**Zweck:** Implementiert die zugewiesene Änderung korrekt innerhalb des Scopes.
|
|
|
|
**Input:**
|
|
- `TASK_ID`, `GOAL`, `SCOPE`, `ACCEPTANCE_CRITERIA`
|
|
- `ALLOWED_FILES` / `FORBIDDEN_FILES`
|
|
- `INPUT` (Spezifikation, Vorlagen, Referenz-Test)
|
|
- `TOOLS` / `PERMISSIONS` / `TIME_BUDGET`
|
|
|
|
**Output (Pflicht, strukturiert):**
|
|
```
|
|
IDENTIFIER: MAKER
|
|
TASK_ID: <id>
|
|
IMPLEMENTATION_SUMMARY: <Kurzfassung der Umsetzung>
|
|
FILES_CHANGED: [<Pfad> ...]
|
|
TESTS_RUN: [<Beschreibung> ...]
|
|
TEST_RESULTS: [<PASS|FAIL ...>]
|
|
KNOWN_RISKS: [<Liste>]
|
|
UNRESOLVED_ISSUES: [<Liste>]
|
|
```
|
|
|
|
**Regeln:**
|
|
- **MAKER darf NIEMALS final PASS entscheiden.** Der PASS muss immer durch eine unabhängige
|
|
Prüfung (CHECKER/Test/Red Queen) erfolgen.
|
|
- Berichtet ehrlich auch über fehlgeschlagene Tests und offene Risiken.
|
|
- Verändert nur `ALLOWED_FILES`; `FORBIDDEN_FILES` bleiben unberührt.
|
|
- Hält TIME_BUDGET ein; bei Überschreitung STOP und an Red Queen melden.
|
|
- Führt Tests aus, wo möglich, und dokumentiert die Ergebnisse.
|
|
|
|
---
|
|
|
|
## 3. CHECKER
|
|
|
|
**Zweck:** Unabhängige, objektive Prüfung eines MAKER-Ergebnisses gegen Requirement,
|
|
Akzeptanzkriterien und Architektur-/Security-Regeln.
|
|
|
|
**Input (ohne Maker-Argumentation):**
|
|
- Requirement + Akzeptanzkriterien (AC)
|
|
- Diff / geänderte Dateien
|
|
- Test-Ergebnisse / Ausführungsergebnisse
|
|
- Architektur- und Security-Regeln (z. B. Prioritätsprinzip, Safety-Regeln)
|
|
|
|
**Regeln:**
|
|
- **CHECKER MUSS ein FRESH child sein** (frische, unabhängige Instanz, getrennt vom Maker).
|
|
- **CHECKER erhält NICHT die Maker-Argumentation** (kein Rechtfertigungstext des Makers).
|
|
Prüfung allein gegen Requirement/AC/Diff/Tests/Regeln.
|
|
- **CHECKER entscheidet ausschließlich:** `PASS`, `FAIL` oder `BLOCKED`.
|
|
- **Bei FAIL:** liefert `FAIL_REASON` + `EVIDENCE` + `REQUIRED_CORRECTION`.
|
|
- **Bei BLOCKED:** liefert Grund für den Block (fehlende Info/Klärungsbedarf).
|
|
- **CHECKER implementiert standardmäßig nicht selbst.** Er gibt Anweisungen zur Korrektur,
|
|
der MAKER führt sie aus. Ausnahme nur auf explizite Anweisung von Red Queen.
|
|
|
|
**Output (strukturiert):**
|
|
```
|
|
IDENTIFIER: CHECKER
|
|
TASK_ID: <id>
|
|
VERDICT: PASS|FAIL|BLOCKED
|
|
FAIL_REASON: <bei FAIL>
|
|
EVIDENCE: <objektive Belege>
|
|
REQUIRED_CORRECTION: <bei FAIL, konkrete Anweisung>
|
|
```
|
|
|
|
**Zusätzlich bei PASS:** Checker bestätigt, dass Safety-Regeln und Architektur eingehalten wurden.
|
|
|
|
---
|
|
|
|
## 4. DEBUGGER
|
|
|
|
**Zweck:** Findet die Grundursache (Root Cause) eines Fehlers und empfiehlt eine neue Strategie.
|
|
|
|
**Input:**
|
|
- `TASK_ID`, `GOAL`, `SCOPE`
|
|
- Fehlerbeschreibung, Logs, Stacktrace, konkrete Symptome
|
|
- `ERROR_SIGNATURE` (normalisiert)
|
|
- `ATTEMPT_LEDGER` (bisherige Versuche aus dem Ledger)
|
|
- Liste bisheriger Lösungsansätze
|
|
|
|
**Regeln:**
|
|
- **Debugger MEIDET dieselbe fehlgeschlagene Strategie** (kein blindes Wiederholen).
|
|
- Untersucht die Ursache, NICHT nur das Symptom.
|
|
- Nutzt den `ATTEMPT_LEDGER`, um Duplikat-Strategien zu vermeiden.
|
|
- Liefert eine **neue**, begründete Strategie.
|
|
|
|
**Output (strukturiert):**
|
|
```
|
|
IDENTIFIER: DEBUGGER
|
|
TASK_ID: <id>
|
|
ROOT_CAUSE_HYPOTHESIS: <vermutete Ursache>
|
|
EVIDENCE: <Belege für die Hypothese>
|
|
NEW_STRATEGY: <neuer Ansatz, anders als bisherige>
|
|
RISKS: <Liste der Risiken der neuen Strategie>
|
|
RECOMMENDED_NEXT_ATTEMPT: <konkreter nächster Schritt>
|
|
```
|
|
|
|
---
|
|
|
|
## 5. TESTER
|
|
|
|
**Zweck:** Reproduzierbare, deterministische Validierung. **LLM-Ersatz:** Der Test sorgt
|
|
dafür, dass "Erfolg" maschinell und wiederholbar belegt wird, nicht durch LLM-Behauptungen.
|
|
|
|
**Input:**
|
|
- `TASK_ID`, `GOAL`
|
|
- Die durchzuführenden Validierungsschritte / Testfälle
|
|
- Erwartete Ergebnisse (EXPECTED)
|
|
|
|
**Regeln:**
|
|
- Tests MÜSSEN reproduzierbar sein (feste Befehle, deterministische Umgebung).
|
|
- Tester ersetzt nicht das LLM, sondern macht Ergebnisse maschinell prüfbar.
|
|
- Liefert nüchterne, nachprüfbare Fakten (keine Interpretation).
|
|
|
|
**Output (strukturiert, pro Test):**
|
|
```
|
|
IDENTIFIER: TESTER
|
|
TASK_ID: <id>
|
|
TEST_NAME: <Name>
|
|
COMMAND: <exakter auszuführender Befehl>
|
|
EXIT_CODE: <0|1|...>
|
|
EXPECTED: <erwartetes Ergebnis>
|
|
ACTUAL: <tatsächliches Ergebnis>
|
|
PASS/FAIL: <PASS|FAIL>
|
|
```
|
|
|
|
---
|
|
|
|
## 6. KNOWLEDGE AGENT
|
|
|
|
**Zweck:** Konsolidierung und Ablage von Wissen (Dokumentation, Notes) auf Basis
|
|
**validierter** Ergebnisse.
|
|
|
|
**Regeln:**
|
|
- **KNOWLEDGE arbeitet NUR nach validierten Ergebnissen** (erst wenn PASS/verifiziert vorliegt).
|
|
Keine Wissensbildung aus ungeprüften oder abgebrochenen Versuchen.
|
|
- **Konsolidiert:** fasst Erkenntnisse aus mehreren WPs zusammen, vermeidet Duplikate.
|
|
- **Erkennt Duplikate/Konflikte** zwischen bestehenden und neuen Inhalten.
|
|
- Ablauf: `DETECT → VERIFY → RESOLVE`; andernfalls **HUMAN DECISION**.
|
|
- **KEINE stillen Überschreibungen:** existierende Inhalte werden nicht einfach überschrieben;
|
|
Konflikte werden offengelegt und gemeldet.
|
|
- DETECT: Konflikt/Duplikat entdecken. VERIFY: mit validierten Fakten prüfen.
|
|
RESOLVE: bereinigen/konsolidieren. Ohne eindeutige Validierung → HUMAN DECISION an Christian.
|
|
|
|
**Output (strukturiert):**
|
|
```
|
|
IDENTIFIER: KNOWLEDGE
|
|
TASK_ID: <id>
|
|
BASIS_TASKS: <validierte TASK_IDs>
|
|
ACTIONS_TAKEN: [<z.B. dokumentiert, konsolidiert, konflikt gemeldet>]
|
|
NEW_KNOWLEDGE: <Pfad/Beschreibung>
|
|
CONFLICTS_DETECTED: [<Liste>]
|
|
NEEDS_HUMAN_DECISION: <ja|nein>
|
|
```
|
|
|
|
---
|
|
|
|
## 7. Zuständigkeiten & Safety Gates
|
|
|
|
| Rolle | WHO | DARF NICHT | STATE GATE |
|
|
|-------|-----|-----------|------------|
|
|
| PLANNER | sub-agent | implementieren | Plan validiert, bevor READY |
|
|
| MAKER | sub-agent | final PASS, Forbidden Files ändern | Ergebnis → Checker |
|
|
| CHECKER | **FRESH child**, unabhängig | Maker-Argumentation erhalten, selbst implementieren (Standard) | PASS→OK, FAIL→Repair |
|
|
| DEBUGGER | sub-agent | fehlgeschlagene Strategie wiederholen | Root Cause+Neue Strategie |
|
|
| TESTER | sub-agent | LLM-Behauptungen statt Tests | Testdurchlauf + PASS/FAIL |
|
|
| KNOWLEDGE | sub-agent | unvalidierte Übernahme, stille Überschreibung | validiertes Ergebnis |
|
|
|
|
- **STOP:** Jede Rolle stoppt und ruft Red Queen (oder Escalation) bei: Block, unklarem Scope,
|
|
wiederholter Fehler-Signatur, offenem Circuit Breaker, oder fehlender gültiger
|
|
Zustands-Transition.
|