diff --git a/.beads/issues.jsonl b/.beads/issues.jsonl index 5ae2f1e..28b64cc 100644 --- a/.beads/issues.jsonl +++ b/.beads/issues.jsonl @@ -1,4 +1,10 @@ {"_type":"issue","id":"az-agent-defaults-j35","title":"Repo-Gerüst: vier Artefakt-Verzeichnisse + README mit Guard-Regeln je Artefakt-Typ","description":"Quelle: Spec 01-az-agent-defaults-spec.md (lokal, wird nicht gepusht).\n\naz-agent-defaults wird als reines Content-Repo die eine Wahrheitsquelle für das Company-Default-Set. Dieses Ticket liefert das Gerüst: die vier Artefakt-Verzeichnisse (skills/, commands/, agents/, mcp/) und ein README, das die Contribution-Guard-Regeln je Artefakt-Typ so dokumentiert, dass ein Fachbereichs-Contributor ohne Architektur-Wissen richtig beisteuern kann:\n\n- Skills: Ordner mit SKILL.md und Frontmatter-Öffner (wie heute)\n- Commands: Markdown mit Frontmatter (description, optional agent/model) und Template-Body (Argument-Platzhalter erlaubt)\n- Agents: Markdown mit Frontmatter (description, mode primary/subagent, optional model/temperature, Permission-Profil); Subagent-Definitionen müssen über das Task-Tool aufrufbar bleiben\n- MCP: Fragmente für den mcp-Konfigurationsschlüssel, remote/streamable als Standard, Secrets grundsätzlich nur als Platzhalter\n\nDas README hält außerdem fest: Auslieferung und Guard-Engine (Pre-Flight auf dem Controller) leben im Fleet-Repo az-fleet; dieses Repo ist Content-only und über den Repo-Ref pinbar (Default: main). Zudem die Fixtures-Konvention: Testgegenstände für die Guard-Tests leben unter tests/fixtures/ und werden nie ausgeliefert, weil die Delivery-Rolle nur die vier Typ-Verzeichnisse liest (Sonntags-Entscheidung). Das Repo verabschiedet damit den Namen az-agent-skills (User Story 2).","acceptance_criteria":"- Die vier Artefakt-Verzeichnisse skills/, commands/, agents/, mcp/ sind im Repo angelegt\n- README dokumentiert die Guard-Regeln je Artefakt-Typ vollständig (Struktur-/Frontmatter-/Platzhalter-Anforderungen gemäß Spec B1)\n- README erklärt die Content/Mechanismus-Trennung zu az-fleet (Guard-Engine und Auslieferung dort) und das Ref-Pinning\n- Die Fixtures-Konvention tests/fixtures/ ist dokumentiert (nie ausgeliefert; Begründung: Delivery liest nur die vier Typ-Verzeichnisse)\n- Ein Contributor ohne Architektur-Wissen kann anhand des README allein entscheiden, wohin ein neues Artefakt gehört und ob es die Guard-Regeln erfüllt","status":"closed","priority":1,"issue_type":"task","assignee":"m3tam3re","owner":"p@m3ta.dev","created_at":"2026-08-22T07:57:14Z","created_by":"m3tam3re","updated_at":"2026-08-22T08:02:44Z","started_at":"2026-08-22T07:59:36Z","closed_at":"2026-08-22T08:02:44Z","close_reason":"Closed","labels":["ready-for-agent"],"dependency_count":0,"dependent_count":4,"comment_count":0} +{"_type":"issue","id":"az-agent-defaults-jtp","title":"Dogfooding + Smoke-Tests der perfektionierten Agents","description":"Abschlussvalidierung: Der perfektionierte az-pruefer läuft über alle 5 perfektionierten Agenten (Dogfooding — der Prüfer prüft als Erstes die perfektionierten Kollegen); Befunde werden eingearbeitet bis der Prüf-Report grün ist. Danach manueller Orchestrator-Smoke-Test: (1) Routing-Korrektheit — Recherche-Anfrage delegiert an az-researcher, Basecamp-Anfrage an az-basecamp, Office an az-office, Repo-Beitrag bleibt beim Orchestrator mit Formal-Check an az-pruefer; (2) Sprachregel — tschechische Testanfrage wird tschechisch beantwortet. Testprotokoll als Beleg ablegen (tests/ oder Notes).\n\n## Context\nGrilling-Entscheidung 8: Dogfooding + Smoke-Test statt Fleet-VM-Test (gehört nach az-fleet).","acceptance_criteria":"1) az-pruefer-Report über agents/*.md: alle Befunde behoben, Report grün. 2) Smoke-Test-Protokoll Routing liegt vor und zeigt korrekte Delegation. 3) Smoke-Test-Protokoll Sprachregel liegt vor (tschechische Anfrage → tschechische Antwort). 4) Vollständige Fleet-VM-Tests bleiben bewusst az-fleet überlassen (Spec-Trennung Content/Mechanismus).","status":"open","priority":2,"issue_type":"task","owner":"m3ta-chiron@agentmail.to","created_at":"2026-09-20T17:43:52Z","created_by":"m3ta-chiron","updated_at":"2026-09-20T17:43:52Z","labels":["ready-for-agent"],"dependencies":[{"issue_id":"az-agent-defaults-jtp","depends_on_id":"az-agent-defaults-74g","type":"blocks","created_at":"2026-09-20T17:43:52Z","created_by":"m3ta-chiron","metadata":"{}"},{"issue_id":"az-agent-defaults-jtp","depends_on_id":"az-agent-defaults-99v","type":"blocks","created_at":"2026-09-20T17:43:52Z","created_by":"m3ta-chiron","metadata":"{}"},{"issue_id":"az-agent-defaults-jtp","depends_on_id":"az-agent-defaults-bfj","type":"blocks","created_at":"2026-09-20T17:43:52Z","created_by":"m3ta-chiron","metadata":"{}"},{"issue_id":"az-agent-defaults-jtp","depends_on_id":"az-agent-defaults-h2j","type":"blocks","created_at":"2026-09-20T17:43:52Z","created_by":"m3ta-chiron","metadata":"{}"},{"issue_id":"az-agent-defaults-jtp","depends_on_id":"az-agent-defaults-m4t","type":"blocks","created_at":"2026-09-20T17:43:52Z","created_by":"m3ta-chiron","metadata":"{}"}],"dependency_count":5,"dependent_count":0,"comment_count":0} +{"_type":"issue","id":"az-agent-defaults-m4t","title":"az-office perfektionieren","description":"az-office nach dem Agenten-Prompt-Standard neu schreiben: Skill-Load „officecli“ als verpflichtender erster Schritt (Formulierung schärfen — aus „lade zu Beginn“ wird eine nicht verhandelbare erste Aktion, ausdrückliches Muster-Referenz des Prometheus-Ansatzes). Ebenenweise-Arbeitsweise (L1/L2/L3) und Grenzen bleiben, Trigger-Description mit Beispielfragen, Output-Vertrag (Ergebnis / Datei \u0026 Prüfbefund / Offene Punkte), Sprachregel, Temperatur-Mikro-Korrektur 0.2 → 0.1.\n\n## Context\nGrilling-Session 20.09. Skill-Delegation ist das ausdrückliche Muster (dünner Agent-Prompt über gut gepflegtem Skill).","acceptance_criteria":"1) Arbeitsweise Schritt 1 = Skill-Load officecli, verpflichtend formuliert. 2) L1/L2/L3-Prinzip erhalten. 3) Description trigger-optimiert. 4) Output-Vertrag mit Datei-\u0026-Prüfbefund-Sektion. 5) Sprachregel enthalten. 6) Demo: docx-Erstellung mit Prüfbefund-Sektion in der Antwort.","status":"open","priority":2,"issue_type":"task","owner":"m3ta-chiron@agentmail.to","created_at":"2026-09-20T17:43:44Z","created_by":"m3ta-chiron","updated_at":"2026-09-20T17:43:44Z","labels":["ready-for-agent"],"dependency_count":0,"dependent_count":1,"comment_count":0} +{"_type":"issue","id":"az-agent-defaults-bfj","title":"az-basecamp perfektionieren + Skill-Nutzung verankern","description":"az-basecamp nach Prometheus-Muster neu schreiben (dünne Shell über Skill): Verpflichtender erster Schritt = Skill „basecamp“ laden (Skill wird via az-fleet aus external/ auf die Nutzerebene ausgerollt — Lieferweg ist gesichert). Inline-CLI-Wissen („Typische Befehle …“) raus, ersetzt durch Skill-Load + 1-Zeilen-Fallback (basecamp --agent --help bei Unbekanntem). Trigger-Description mit Beispielfragen, Output-Vertrag (Ergebnis / Belege mit IDs-Links / Offene Punkte), Beleg-Pflicht je Aktion (keine Aktion ohne Beleg-ID), Sprachregel, Auth- und Fleet-Grenzen bleiben.\n\n## Context\nGrilling-Session 20.09.: external/-Skills werden über az-fleet ausgerollt (Nutzer-Entscheidung b). Muster-Vorbild: az-office + officecli-Skill.","acceptance_criteria":"1) Arbeitsweise Schritt 1 = Skill-Load basecamp (verpflichtend). 2) Keine inline-CLI-Befehlsliste mehr im Prompt. 3) Description trigger-optimiert. 4) Output-Vertrag mit Belege-Sektion. 5) Sprachregel enthalten. 6) Demo: Delegations-Anfrage erzeugt Basecamp-Objekt + Antwort mit Beleg-ID.","status":"open","priority":2,"issue_type":"task","owner":"m3ta-chiron@agentmail.to","created_at":"2026-09-20T17:43:37Z","created_by":"m3ta-chiron","updated_at":"2026-09-20T17:43:37Z","labels":["ready-for-agent"],"dependency_count":0,"dependent_count":1,"comment_count":0} +{"_type":"issue","id":"az-agent-defaults-99v","title":"az-researcher perfektionieren","description":"az-researcher neu schreiben nach dem Agenten-Prompt-Standard: Modell az-litellm/claude-haiku-4-5 → az-litellm/claude-sonnet-5 (Recherchequalität: Quellenbewertung/Synthese braucht das stärkere Modell, Fehlerkosten unsichtbar und teuer). Trigger-Description mit Beispielfragen, Klassifikation Web-vs-lokal als erster Arbeitschritt, geschärfter Output-Vertrag (Kernantwort / Belege mit URL bzw. Datei:Zeile / Offene Punkte), Sprachregel, Failure-Bedingung: Behauptung ohne Quelle = gescheitert.\n\n## Context\nGrilling-Entscheidung 6(a): Researcher auf Sonnet-Klasse, alle anderen Modelle bleiben.","acceptance_criteria":"1) Frontmatter: model=az-litellm/claude-sonnet-5, temperature 0.1–0.2. 2) Description trigger-optimiert mit Beispielfragen. 3) Arbeitsweise beginnt mit Web-vs-lokal-Klassifikation. 4) Output-Vertrag mit Belege- und Offene-Punkte-Sektion. 5) Sprachregel enthalten. 6) Demo: @mention-Recherche liefert sektionierte Antwort mit Quellen.","status":"open","priority":2,"issue_type":"task","owner":"m3ta-chiron@agentmail.to","created_at":"2026-09-20T17:43:29Z","created_by":"m3ta-chiron","updated_at":"2026-09-20T17:43:29Z","labels":["ready-for-agent"],"dependency_count":0,"dependent_count":1,"comment_count":0} +{"_type":"issue","id":"az-agent-defaults-h2j","title":"az-orchestrator perfektionieren","description":"az-orchestrator als schlanker Router + Verifikator neu schreiben (~150 Zeilen, bleibt glm-5-2): geschärfte Routing-Tabelle mit Trigger-Beispielen je Subagent, Verifikations-Checkliste gegen die Output-Verträge der Subagents (Belege fehlen → nachbessern lassen; Offene Punkte die der Nutzer nie fragte → Rückfrage), Eskalations-Regeln, Sprachregel „Antworte in der Sprache der Nutzeranfrage“, „selber machen wenn schneller“ bleibt. Kein Certainty-/Plan-Zwang (bewusst gegen OMO-Voll-Doktrin entschieden — Kostenarchitektur glm-5-2).\n\n## Context\nGrilling-Entscheidung 5(a): schlanker Router + Verifikator. Zielgruppe: ganze AZ-Gruppe (deutsch/tschechisch/englisch).","acceptance_criteria":"1) Prompt folgt dem Agenten-Prompt-Standard (Skelett, Sprachregel, \u003c10k Zeichen). 2) Description trigger-optimiert, erste 80 Zeichen = Missionssatz. 3) Routing-Tabelle nennt Beispielfragen. 4) Verifikations-Checkliste referenziert die Subagent-Output-Verträge. 5) Smoke-Test: Recherche-Anfrage delegiert an az-researcher; tschechische Anfrage wird tschechisch beantwortet.","status":"open","priority":2,"issue_type":"task","owner":"m3ta-chiron@agentmail.to","created_at":"2026-09-20T17:43:21Z","created_by":"m3ta-chiron","updated_at":"2026-09-20T17:43:21Z","labels":["ready-for-agent"],"dependency_count":0,"dependent_count":1,"comment_count":0} +{"_type":"issue","id":"az-agent-defaults-74g","title":"Agenten-Prompt-Standard definieren + az-pruefer perfektionieren","description":"README-Sektion „Agenten-Prompt-Standard“ anlegen (Prompt-Skelett mit Arbeitsweise/Ausgabeformat/Grenzen, Trigger-Description-Regel mit Beispielfragen in den ersten 80 Zeichen, Output-Vertrags-Pflicht für Subagents mit Belege- und Offene-Punkte-Sektion, Sprachregel „Antworte in der Sprache der Anfrage“ in jedem Agenten, 10k-Zeichen-Grenze) plus einen Satz zum external/-Lieferweg (Skills aus external/ werden via az-fleet auf die Nutzerebene ausgerollt). Danach az-pruefer nach dem neuen Standard perfektionieren: prüft die deterministischen Guard-Regeln aus dem README UND den Agenten-Prompt-Standard (LLM-Prüfung), mit eigenem Output-Vertrag und Trigger-Description. Grundlage ist die OMO-Analyse-Session (Trigger-Descriptions, Output-Verträge, Prometheus-Muster).\n\n## Context\nEntscheidungen aus Grilling-Session 20.09.: Struktur (a) deutsch+OMO-Elemente; Descriptions voll trigger-optimiert; Output-Verträge Markdown-Sektionen; Standard weiche Regel (LLM-geprüft, keine harten Guards).","acceptance_criteria":"1) README enthält die Sektion „Agenten-Prompt-Standard“ mit Skelett, Trigger-Regel, Output-Vertrags-Pflicht, Sprachregel, 10k-Grenze und external/-Hinweis. 2) az-pruefer prüft Guard-Regeln + Prompt-Standard. 3) Demo: az-pruefer meldet an einer absichtlich schlechten Agent-Datei genau die Standard-Verstöße (fehlende Beispielfragen, fehlender Output-Vertrag, fehlende Sprachregel).","status":"closed","priority":2,"issue_type":"task","assignee":"m3ta-chiron","owner":"m3ta-chiron@agentmail.to","created_at":"2026-09-20T17:43:10Z","created_by":"m3ta-chiron","updated_at":"2026-09-20T17:58:11Z","started_at":"2026-09-20T17:50:54Z","closed_at":"2026-09-20T17:58:11Z","close_reason":"Umgesetzt: (1) README-Sektion 'Agenten-Prompt-Standard' (Prompt-Skelett Arbeitsweise/Ausgabeformat/Grenzen, Trigger-Description-Regel mit Beispielfragen in den ersten 80 Zeichen, Output-Vertrags-Pflicht für Subagents mit Ergebnis/Belege/Offene Punkte, Sprachregel 'Antworte in der Sprache der Anfrage', 10k-Zeichen-Grenze, external/-Lieferweg-Satz) — klar als weiche Regel (LLM-geprüft, kein Guard) abgetrennt; Fixtures-Sektion um agents/demo/ ergänzt. (2) agents/az-pruefer.md neu nach eigenem Standard: Trigger-Description mit Beispielfragen, prüft Guard-Regeln + Prompt-Standard getrennt, eigener Output-Vertrag, Sprachregel, Read-only-Profil bleibt. (3) Demo real gelaufen: Subagent mit neuem az-pruefer-Prompt prüfte tests/fixtures/agents/demo/schlechter-agent.md (guard-gültig) und meldete exakt die 3 Standard-Verstöße (Trigger-Description ohne Beispielfragen m. 80-Zeichen-Zitat, fehlender Output-Vertrag bei mode:subagent, fehlende Sprachregel) bei bestandener Größen-Grenze mit Messwert.","labels":["ready-for-agent"],"dependency_count":0,"dependent_count":1,"comment_count":0} {"_type":"issue","id":"az-agent-defaults-1ub","title":"Skills: ow-hello entfernen, durch Onboarding-/Hilfe-Skill (az-hilfe, Entwurf) ersetzen","description":"Entscheidung des Nutzers (22.08.2026): ow-hello wird nicht mehr benötigt. Stattdessen ein Onboarding-/Hilfe-Skill für AZ-Anwender als Entwurf — orientiert am ask-matt-Muster (Router: welche Artefakt-Art wofür, wie beitragen, an wen wenden). Guard-Regeln des README müssen erfüllt sein (name/description-Frontmatter, kebab-case, Ordner=Name).","status":"closed","priority":2,"issue_type":"feature","assignee":"m3tam3re","owner":"p@m3ta.dev","created_at":"2026-08-22T08:12:43Z","created_by":"m3tam3re","updated_at":"2026-08-22T08:13:40Z","started_at":"2026-08-22T08:12:52Z","closed_at":"2026-08-22T08:13:40Z","close_reason":"ow-hello entfernt; az-hilfe als Onboarding-/Hilfe-Skill (Entwurf) angelegt — Router-Prinzip wie ask-matt: vier Artefakt-Typen erklärt, typische Anfragen mit Antwortmustern, Beitragsweg (IT/Repo), Problemeskalation; ehrlicher Ausbaustand (Commands/Agents/MCP als in Vorbereitung). Guard-konform (Frontmatter name+description, Ordner=Name, kebab-case); 14/14 Verifikations-Checks PASS; Fixtures unangetastet.","dependency_count":0,"dependent_count":0,"comment_count":0} {"_type":"issue","id":"az-agent-defaults-95y","title":"MCP-Slice: Fragment-Format (remote/streamable) + Vault-Platzhalter-Konvention + Guard-Fixtures","description":"Quelle: Spec 01-az-agent-defaults-spec.md.\n\nDefinition des MCP-Fragment-Formats für den mcp-Konfigurationsschlüssel: ein Fragment pro Server, remote/streamable als Standard (url, enabled-Flag; OAuth läuft zur Laufzeit pro Nutzer über das Microsoft-Konto — keine statischen Secrets im Fragment). Für Ausnahmen mit statischem Key definiert das Format einen Platzhalter samt Vault-Key-Namensschema: der Key liegt im Vault des Fleet-Repos und wird erst beim Merge auf dem Controller substituiert — im Repo bleibt nie ein Secret (B3).\n\nZwei Referenz-Fragmente in mcp/ (eine OAuth-Server-Anbindung, eine Key-Ausnahme mit Platzhalter) dienen als Testgegenstände für die Fleet-Szenarien „Fragmente in der aufgelösten Konfiguration sichtbar (Sidecar-Debug)\" und „Vault-Substitution funktioniert, Nutzerebene enthält kein Secret aus dem Repo\". Zusätzlich ungültige MCP-Fixtures unter tests/fixtures/ — insbesondere ein Fragment mit Inline-Secret, das der Guard rot abbrechen muss.\n","acceptance_criteria":"- Das Fragment-Format ist im README dokumentiert (ein Fragment pro Server; Felder für remote/streamable; enabled-Flag)\n- Die Platzhalter-Konvention für Key-Ausnahmen ist definiert (Syntax + Vault-Key-Namensschema; Substitution nur beim Merge auf dem Controller)\n- Ein OAuth-Referenz-Fragment und ein Key-Ausnahme-Referenz-Fragment liegen in mcp/ — beide ohne jedes Secret\n- Ungültige MCP-Testgegenstände existieren unter tests/fixtures/ (mindestens: Fragment mit Inline-Secret)\n- Keine Fixture liegt in einem ausgelieferten Typ-Verzeichnis","status":"closed","priority":2,"issue_type":"feature","assignee":"m3tam3re","owner":"p@m3ta.dev","created_at":"2026-08-22T07:57:49Z","created_by":"m3tam3re","updated_at":"2026-08-22T08:26:45Z","started_at":"2026-08-22T08:24:40Z","closed_at":"2026-08-22T08:26:45Z","close_reason":"README um Vault-Key-Namensschema (\u003cserver-name\u003e-\u003cverwendungszweck\u003e, kebab-case) + Key-Ausnahme-Beispiel ergänzt (Format selbst war seit Scaffold dokumentiert). Zwei Referenz-Fragmente in mcp/: zugferd-service.yaml (OAuth-Standardfall, kein Credential-Feld) + az-zoll-service.yaml (Key-Ausnahme mit ${VAULT:az-zoll-service-api-key}) — beide ohne jedes Secret. 5 ungültige MCP-Fixtures (inline-secret, ohne-server-name, ohne-url, ohne-type, falscher-platzhalter) — alle README-dokumentierten Fehlertypen. 17/17 Checks PASS.","labels":["ready-for-agent"],"dependencies":[{"issue_id":"az-agent-defaults-95y","depends_on_id":"az-agent-defaults-j35","type":"blocks","created_at":"2026-08-22T09:57:48Z","created_by":"m3tam3re","metadata":"{}"}],"dependency_count":1,"dependent_count":0,"comment_count":0} {"_type":"issue","id":"az-agent-defaults-gj1","title":"Commands-Slice: Referenz-Command mit Argument-Platzhaltern + Guard-Fixtures","description":"Quelle: Spec 01-az-agent-defaults-spec.md.\n\nErster exemplarischer Company-Command in commands/: Markdown mit Frontmatter (description, optional agent/model) und Template-Body mit Argument-Platzhaltern ($ARGUMENTS, $1..$n) — Format gemäß verifizierter OpenCode-Doku (global ~/.config/opencode/commands/, pro Projekt .opencode/commands/; Shell-Output-Injection und Datei-Referenzen unterstützt). Der Command ist zugleich Referenz-Beitrag für Contributor und Testgegenstand für das Fleet-Szenario „/command ist in der OpenWork-/OpenCode-Sitzung verfügbar und löst das Template aus\". Inhaltlich bewusst trivial (Platzhalter-Niveau wie ow-hello; konkrete Inhalte sind Phase 2).\n\nZusätzlich ungültige Command-Fixtures unter tests/fixtures/ (z. B. Frontmatter ohne description, Datei ohne Frontmatter).\n","acceptance_criteria":"- Ein gültiger Referenz-Command liegt in commands/ und erfüllt die README-Guard-Regeln (description im Frontmatter, Template-Body, Argument-Platzhalter genutzt)\n- Der Command folgt dem OpenCode-Command-Format, sodass er nach Fleet-Auslieferung als /slash-Befehl verfügbar ist und das Template auslöst\n- Ungültige Command-Testgegenstände existieren unter tests/fixtures/ (mindestens: ohne description, ohne Frontmatter)\n- Keine Fixture liegt in einem ausgelieferten Typ-Verzeichnis","status":"closed","priority":2,"issue_type":"feature","assignee":"m3tam3re","owner":"p@m3ta.dev","created_at":"2026-08-22T07:57:49Z","created_by":"m3tam3re","updated_at":"2026-08-22T08:21:22Z","started_at":"2026-08-22T08:20:43Z","closed_at":"2026-08-22T08:21:22Z","close_reason":"Referenz-Command commands/az-hilfe.md (Gegenstück zum az-hilfe-Skill): description-Frontmatter, Template-Body mit $ARGUMENTS + $1, kebab-case-Name → /az-hilfe nach Fleet-Auslieferung. 4 ungültige Command-Fixtures unter tests/fixtures/commands/invalid/ (ohne-frontmatter, ohne-description, leere-description, prüfung.md mit Umlaut-Dateinamen) — decken alle im README dokumentierten Command-Fehlertypen ab. 17/17 Verifikations-Checks PASS.","labels":["ready-for-agent"],"dependencies":[{"issue_id":"az-agent-defaults-gj1","depends_on_id":"az-agent-defaults-j35","type":"blocks","created_at":"2026-08-22T09:57:48Z","created_by":"m3tam3re","metadata":"{}"}],"dependency_count":1,"dependent_count":0,"comment_count":0} diff --git a/README.md b/README.md index 79f5d14..d94ee00 100644 --- a/README.md +++ b/README.md @@ -215,6 +215,83 @@ ab — auch in Kommentaren), Platzhalter in anderer Syntax als `${VAULT:…}`. --- +## Agenten-Prompt-Standard + +Die Guard-Regeln oben sagen deterministisch, was ein Artefakt **gültig** macht. +Dieser Abschnitt sagt, was ein Agenten-Prompt **gut** macht — und ist bewusst +eine **weiche Regel**: Der Fleet-Guard erzwingt sie nicht. Geprüft wird vom +Prüfer-Agenten `az-pruefer` (LLM-Prüfung) — ein Verstoß bricht keinen Rollout +ab, wird aber im Prüfbericht als Mangel benannt und muss behoben oder +ausdrücklich begründet werden. + +### Prompt-Skelett + +Jeder Agenten-Body folgt diesem Skelett (Reihenfolge einhalten; Überschriften +dürfen sinngemäß abweichen): + +```markdown + + +## Arbeitsweise +1. **** — . + +## Ausgabeformat + + +## Grenzen +- +``` + +- **Arbeitsweise:** nummerierte Schritte, jeder mit erkennbarem + Abschlusskriterium. Gibt es einen gepflegten Skill fürs Thema — auch aus + `external/`, deren Skills via az-fleet auf die Nutzerebene ausgerollt + werden —, ist **Skill-Load der erste Schritt** („dünne Agent-Shell über + gepflegtem Skill", Muster: `az-office` + `officecli`). Inline-Wissen, das + der Skill bereits trägt, bleibt draußen. +- **Grenzen:** bewusste Begrenzungen — Auth-Flows, Fleet-Verwaltung, + destruktive Aktionen, Eskalationsweg. + +### Trigger-Description + +Die Frontmatter-`description` entscheidet, ob Orchestrator oder Nutzer den +Agenten auswählen. Deshalb: + +- **In den ersten 80 Zeichen stehen konkrete Beispielfragen/-aufträge**, so + wie Nutzer sie tatsächlich stellen — z. B. „Erstelle ein Angebot als + Word-Dokument", „Welche To-dos habe ich diese Woche?". +- Danach Kurzform der Fähigkeiten; Rolle/Zugehörigkeit ans Ende. + +Abstrakte Selbstbeschreibungen („hilft bei …", „unterstützt bei …") triggern +nicht — die ersten 80 Zeichen müssen die Anfrage-Lautung abbilden. + +### Output-Vertrag (Subagent-Pflicht) + +Jeder Subagent definiert eine Sektion `## Ausgabeformat` mit mindestens: + +- **Ergebnis** — Antwort bzw. Arbeitsergebnis zuerst; +- **Belege** — je Behauptung/Aktion eine Fundstelle: URL, `Datei:Zeile` oder + Beleg-ID; +- **Offene Punkte** — was unklar, ungeprüft oder Annahme blieb. + +Der Vertrag ist die Verifikations-Grundlage des Orchestrators: Fehlen +Belege, lässt er nachbessern. Failure-Regel: **eine Behauptung ohne Beleg ist +ein gescheiterter Auftrag** — keine abgeschlossene Arbeit. + +### Sprachregel + +In jedem Agenten steht die Regel: **„Antworte in der Sprache der Anfrage."** +Die Gruppe arbeitet deutsch, tschechisch und englisch — die Antwort folgt der +Anfrage, nicht der Sprache des Prompts. + +### Größen-Grenze + +Agenten-Prompts bleiben unter **10.000 Zeichen**. Wird ein Prompt länger, +wandert Inhalt in einen Skill, den der Agent als ersten Schritt lädt +(Progressive Disclosure). Dünner Prompt über gepflegtem Skill schlägt fetten +Inline-Prompt. + +--- + ## Trennung Content / Mechanismus | Zuständigkeit | Repo | @@ -249,7 +326,7 @@ Konvention: je Artefakt-Typ ein Unterordner, darin `valid/`- und tests/fixtures/ ├── skills/valid/… skills/invalid/… ├── commands/valid/… commands/invalid/… -├── agents/valid/… agents/invalid/… +├── agents/valid/… agents/invalid/… agents/demo/… └── mcp/valid/… mcp/invalid/… ``` @@ -257,12 +334,17 @@ tests/fixtures/ ausgeliefert** — nichts daraus in die Typ-Verzeichnisse schieben; umgekehrt sind echte Artefakte dort fehl am Platz. +Die Exemplare unter `agents/demo/` bestehen den **Guard**, verstoßen aber +gegen den (weichen) Agenten-Prompt-Standard — sie sind Prüfgut für +`az-pruefer`, nicht für den Fleet-Guard. + --- ## Beitrags-Kurzanleitung 1. Richtiges Verzeichnis anhand der Tabelle oben wählen. -2. Artefakt gemäß Guard-Regeln des Typs anlegen (Minimalbeispiel als Vorlage). +2. Artefakt gemäß Guard-Regeln des Typs anlegen (Minimalbeispiel als Vorlage) + — bei Agenten zusätzlich: [Agenten-Prompt-Standard](#agenten-prompt-standard). 3. Prüfen: erfüllt das Artefakt **alle** Pflichtpunkte der Checkliste seines Typs? Wenn unsicher — die Checklisten sind vollständig; es braucht kein Architektur-Wissen. diff --git a/agents/az-pruefer.md b/agents/az-pruefer.md index ff73195..9a6c6e2 100644 --- a/agents/az-pruefer.md +++ b/agents/az-pruefer.md @@ -1,5 +1,5 @@ --- -description: Prüft vorgeschlagene Agenten-Artefakte gegen die Guard-Regeln des Repos — rein lesend, ohne selbst zu ändern. +description: „Prüfe dieses Artefakt gegen die Repo-Regeln“ · „Ist der Agent konform?“ · „Finde Verstöße gegen den Agenten-Prompt-Standard“ — az-pruefer prüft Skills, Commands, Agents und MCP-Fragmente gegen Guard-Regeln und Agenten-Prompt-Standard, rein lesend. mode: subagent model: az-litellm/claude-haiku-4-5 temperature: 0.1 @@ -9,21 +9,55 @@ tools: grep: true --- -Du bist ein Read-only-Prüfer der AZ-Gruppe. Wenn dich ein Nutzer per @mention -oder ein anderer Agent über das Task-Tool ruft, prüfst du das übergebene -Artefakt gegen die Guard-Regeln aus dem README des Repos `az-agent-defaults`: +Du bist der Prüf-Agent der AZ-Gruppe — ein Read-only-Prüfer. Wenn dich ein +Nutzer per @mention oder ein Agent über das Task-Tool ruft, prüfst du das +übergebene Artefakt gegen zwei Regelwerke aus dem README des Repos +`az-agent-defaults`. -- **Skills:** Ordner mit genau einer `SKILL.md`, Frontmatter-Öffner `---`, - Pflichtfelder `name` (≈ Ordnername, kebab-case) und `description`. -- **Commands:** Markdown-Datei mit Frontmatter, Pflichtfeld `description`, - Template-Body (Argument-Platzhalter erlaubt), Dateiname kebab-case ohne - Umlaute. -- **Agents:** Frontmatter mit `description` und `mode` (`primary`|`subagent`); - Permission-Profile dürfen nur einschränken, nie erweitern. -- **MCP:** Fragment für den `mcp`-Konfigurationsschlüssel (Server-Name als - Schlüssel), `type: remote` plus `url`; Secrets nur als `${VAULT:…}` - Platzhalter — jeder Klartext-Key ist ein Fund. +## Arbeitsweise -Berichte pro Regel bestanden/fehlgeschlagen mit Fundstelle (Datei:Zeile) und -einer Empfehlung, was zu ändern ist. Du editierst, schreibst und löschst -nichts — reines Prüfen und Berichten. +1. **Artefakt-Typ bestimmen** — Skill (Ordner + `SKILL.md`), Command + (`commands/*.md`), Agent (`agents/*.md`) oder MCP-Fragment (`mcp/*.yaml`). + Liegt das Artefakt nicht vor, melde das als Offenen Punkt und stoppe. +2. **Guard-Regeln prüfen** (deterministisch, je Typ): + - **Skills:** genau eine `SKILL.md`, Frontmatter-Öffner `---`, Pflichtfelder + `name` (= Ordnername, kebab-case) und `description`. + - **Commands:** Frontmatter mit `description`, Dateiname kebab-case ohne + Umlaute, Template-Body (Argument-Platzhalter erlaubt). + - **Agents:** Frontmatter mit `description` und `mode` + (`primary`|`subagent`); Permission-Profile dürfen nur einschränken, nie + erweitern; die Subagent-Fähigkeit (Task-Tool) bleibt erhalten. + - **MCP:** Server-Name als Schlüssel, `type: remote` plus `url`; Secrets nur + als `${VAULT:…}`-Platzhalter — jeder Klartext-Key ist ein Fund (auch in + Kommentaren). +3. **Agenten-Prompt-Standard prüfen** (nur bei Agents; weiche Regel, README- + Sektion „Agenten-Prompt-Standard"): + - **Trigger-Description:** konkrete Beispielfragen in den ersten 80 Zeichen + der `description`; + - **Prompt-Skelett:** Sektionen Arbeitsweise / Ausgabeformat / Grenzen; + - **Output-Vertrag** (bei `mode: subagent`): `## Ausgabeformat` mit + Ergebnis / Belege / Offene Punkte; + - **Sprachregel:** „Antworte in der Sprache der Anfrage." vorhanden; + - **Größen-Grenze:** Body unter 10.000 Zeichen. +4. **Befund erheben** — je Regel bestanden oder Verstoß, immer mit Fundstelle + (`Datei:Zeile`) und konkreter Änderungsempfehlung. Guard-Verstoß und + Standard-Verstoß getrennt ausweisen. + +## Ausgabeformat + +- **Ergebnis:** Gesamtbefund in einem Satz (konform / Guard-Verstöße / + Standard-Verstöße) plus Tabelle je Regel: bestanden oder Verstoß → + Fundstelle → Empfehlung. +- **Belege:** je Befund `Datei:Zeile`; bei der Größen-Grenze den gemessenen + Zeichenwert angeben; bei der Trigger-Description die ersten 80 Zeichen + zitieren. +- **Offene Punkte:** was du nicht prüfen konntest und warum (Artefakt + unvollständig, Regel mehrdeutig, externe Voraussetzung unbekannt). + +## Grenzen + +- Du editierst, schreibst und löschst nichts — reines Prüfen und Berichten. +- Du prüfst Konformität gegen die README-Regeln, nicht inhaltliche Qualität + („ist das Konzept gut?"). + +Antworte in der Sprache der Anfrage. diff --git a/tests/fixtures/agents/demo/schlechter-agent.md b/tests/fixtures/agents/demo/schlechter-agent.md new file mode 100644 index 0000000..ede0197 --- /dev/null +++ b/tests/fixtures/agents/demo/schlechter-agent.md @@ -0,0 +1,23 @@ +--- +description: Hilft bei Basecamp-Themen und unterstützt das Team bei der Verwaltung von Projekten und To-dos. +mode: subagent +model: az-litellm/claude-haiku-4-5 +temperature: 0.2 +tools: + bash: true + read: true +--- + +Du bist ein Basecamp-Helfer. Wenn dich jemand ruft, bearbeitest du +Basecamp-Anfragen mit dem CLI. + +## Arbeitsweise + +1. **CLI erkunden** — bei Unsicherheit liefert `basecamp --agent --help` alle + Befehle und Flags. +2. **Anfrage ausführen** — setze die Anfrage mit dem CLI um. + +## Grenzen + +- Du installierst nichts — das CLI ist Fleet-verwaltet. Fehlt es, melde das + dem Auftraggeber.