# az-agent-defaults — Company-Default-Set für Agenten-Artefakte Dieses Repo ist die **eine Wahrheitsquelle** für die Standard-Artefakte, die jede Agenten-Workstation der AZ-Gruppe gespiegelt bekommt. Es ist ein **reines Content-Repo**: hier leben nur die Inhalte — die Technik, die sie ausliefert und absichert, gehört in das Fleet-Repo `az-fleet` (siehe [Trennung Content / Mechanismus](#trennung-content--mechanismus)). Das Repo hervorgegangen aus `az-agent-skills` und löst es ab: der alte Name würde lügen, seit neben Skills auch Commands, Agenten-Definitionen und MCP-Server-Anbindungen dazugekommen sind. --- ## Wohin gehört mein Beitrag? | Ich möchte beitragen … | Verzeichnis | Form | |---|---|---| | einen Skill (Verhaltens-Anweisung, die der Agent bei Bedarf lädt) | `skills//` | Ordner mit `SKILL.md` | | einen Command (/slash-Befehl, wiederverwendbarer Prompt) | `commands/.md` | Markdown-Datei mit Frontmatter | | einen Agenten (spezialisiertes Profil als Primäragent oder Subagent) | `agents/.md` | Markdown-Datei mit Frontmatter | | einen MCP-Server (Werkzeug-Anbindung) | `mcp/.yaml` | Konfigurations-Fragment | Kurzform zum Einsortieren: - **Verhalten beibringen** („mach X, wenn Y") → `skills/` - **Wiederkehrenden Prompt als Tastendruck** → `commands/` - **Eigenes Agenten-Profil / Prüf-Subagenten** → `agents/` - **Werkzeug anbinden** (API, Datenquelle) → `mcp/` Alle vier Verzeichnisse werden von der Delivery-Rolle des Fleet-Repos gelesen — und **nur** diese vier. Alles andere im Repo (z. B. `tests/fixtures/`, diese README, die Spec) wird nie ausgeliefert. --- ## Guard-Regeln je Artefakt-Typ Die Delivery-Rolle in `az-fleet` führt vor jedem Rollout einen **deterministischen Pre-Flight-Guard** aus: Struktur-, Frontmatter- und Platzhalter-Checks je Typ. Ein ungültiges Artefakt **bricht den Run kontrolliert ab** — kaputte Inhalte erreichen nie eine Maschine. Die Regeln unten beschreiben, was der Guard mindestens prüft; die Implementierung lebt in `az-fleet`, nicht hier. ### `skills/` — Skills **Struktur:** ein Ordner pro Skill, darin genau eine `SKILL.md`. ``` skills/ └── mein-skill/ └── SKILL.md ``` **Anforderungen:** - Ordnername = Skill-Name (kein Leerzeichen, keine Umlaute; kebab-case). - `SKILL.md` beginnt mit einem YAML-Frontmatter-Öffner (Delimited by `---`). - Frontmatter enthält **Pflichtfelder** `name` und `description`. - `name` muss zum Ordnernamen passen. - `description` ist ein Satz, der sagt, wann der Skill greift. - Darunter: Anweisungen als normales Markdown. **Minimalbeispiel:** ```markdown --- name: mein-skill description: Prüft Zugferd-Rechnungen auf formal korrektes XML, wenn der Nutzer eine XRechnung validieren will. --- # Zugferd-Validierung Prüfe die übergebene Datei gegen das CIUS-XRechnung-Schema … ``` **Typische Fehler, die der Guard abbricht:** fehlender Ordner, fehlende `SKILL.md`, fehlendes/leeres Frontmatter, `name` ≠ Ordnername, fehlende `description`. ### `commands/` — Commands (/slash-Befehle) **Struktur:** eine Markdown-Datei pro Command, direkt in `commands/`. ``` commands/ └── ticket-abarbeiten.md ``` **Anforderungen:** - Dateiname ohne `.md` = Command-Name → in der Sitzung als `/ticket-abarbeiten` verfügbar. - Frontmatter mit: - `description` (**Pflicht**) — erscheint in der Command-Übersicht; - `agent` (optional) — Agent, der den Command ausführt; - `model` (optional) — Modell für die Ausführung. - Body = **Template**. Argument-Platzhalter sind erlaubt und erwünscht: - `$ARGUMENTS` — alles, was der Nutzer nach dem Command tippt; - `$1` … `$n` — positionelle Argumente. **Minimalbeispiel:** ```markdown --- description: Arbeitet das genannte beads-Ticket ab (claimen, umsetzen, schließen). agent: build --- Arbeite das Ticket $ARGUMENTS ab: zeige es mir, claime es, setze es um und schließ es nach meiner Freigabe. ``` **Typische Fehler:** fehlendes Frontmatter, fehlende `description`, Command-Name mit Leerzeichen/Umlauten (die später zum /slash-Namen wird). ### `agents/` — Agenten-Definitionen **Struktur:** eine Markdown-Datei pro Agent, direkt in `agents/`. Dateiname = Agentenname. **Anforderungen:** - Frontmatter mit: - `description` (**Pflicht**) — sagt, wofür der Agent da ist; - `mode` (**Pflicht**) — `primary` (per Agentenwechsel wählbar) oder `subagent` (per @mention und automatisch über das Task-Tool startbar); - `model`, `temperature` (optional); - Permission-/Tool-Profil (optional, aber für Subagents empfohlen) — z. B. ein Read-only-Prüfer ohne Edit/Bash. - Body = Systemprompt des Agenten. **Harte Sicherheitsregeln (Guard prüft mit):** 1. **Subagent-Fähigkeit bleibt erhalten:** keine Definition darf das Task-Tool bzw. die Delegation an Subagents so einschränken, dass Subagents nicht mehr startbar wären. Spezialisierung ja — die Fähigkeit von Agenten, selbst zu delegieren und zu parallelisieren, wird nie verbaut. 2. **Niemals Rechte ausweiten:** Permission-Profile dürfen innerhalb des verwalteten Regelwerks (Managed-Layer) nur **einschränken**, nie erlauben, was der Managed-Layer verweigert. Provider-Lock und Permission-Regelwerk gelten unabhängig vom aktiven Agenten weiter. **Minimalbeispiel (Read-only-Subagent):** ```markdown --- description: Prüft Ergebnisse gegen Abnahme-Kriterien, ohne selbst zu ändern. mode: subagent temperature: 0.1 tools: - read - grep - glob --- Du bist ein Read-only-Prüfer. Gleiche das vorgelegte Ergebnis gegen die Abnahme-Kriterien ab und berichte nur — du editierst und schreibst nichts. ``` **Typische Fehler:** fehlende `mode`, `mode` mit ungültigem Wert, Frontmatter ohne `description`. ### `mcp/` — MCP-Server-Fragmente **Struktur:** eine YAML-Datei pro Server: `mcp/.yaml`. Jede Datei ist ein **Fragment für den `mcp`-Konfigurationsschlüssel** — der Server-Name steht als Schlüssel, darunter die Definition. Die Fragmente werden auf dem Controller in die verwaltete Konfiguration (Managed-Layer) gemerged — MCPs sind Werkzeuge und damit sicherheitsrelevant, sie gehören in den admin-kontrollierten Layer, nicht auf die nutzerbeschreibbare Ebene. **Anforderungen:** - **Standard ist remote/streamable** mit OAuth: `type: remote` plus `url`; die Anmeldung läuft zur Laufzeit einmalig pro Nutzer über dessen Microsoft-Konto — identitätsgebunden. Ein OAuth-Server braucht daher **kein** Credential-Feld im Fragment. - `enabled` (optional) — Standard ist an. - `local`-Server (`command`/`env`) nur als dokumentierte Ausnahme. - **Secrets niemals im Repo — ohne Ausnahme.** Wo ein statischer Key nötig ist (Nicht-OAuth-Ausnahme), steht im Fragment nur ein Platzhalter der Form `` ${VAULT:} ``; der echte Key liegt im Vault des Fleet-Repos und wird erst beim Merge auf dem Controller substituiert. Im Repo bleibt nie ein Secret. **Minimalbeispiel (OAuth-Standardfall):** ```yaml # mcp/zugferd-service.yaml zugferd-service: type: remote url: https://mcp.example.az.local/zugferd enabled: true ``` **Typische Fehler:** Server-Name fehlt (Datei ist keine Fragment-Struktur), fehlende `url`, `type` fehlt bei remote, ein Secret im Klartext (Guard bricht ab — auch in Kommentaren), Platzhalter in anderer Syntax als `${VAULT:…}`. --- ## Trennung Content / Mechanismus | Zuständigkeit | Repo | |---|---| | **Inhalte** (Skills, Commands, Agents, MCP-Fragmente) | **az-agent-defaults** (dieses Repo) | | **Mechanismus** (Guard-Engine, Auslieferung/Spiegel, Drift-Reparatur, Vault-Substitution) | **az-fleet** | Konsequenzen für Contributors: - Dieses Repo enthält **keine** Auslieferungs-Logik, kein Playbook, kein Secret. - Skills, Commands und Agenten-Definitionen werden als **exakter Nutzerebene-Spiegel** ausgeliefert (inklusive Entfernen gelöschter Artefakte). - MCP-Fragmente werden auf dem Controller in den **Managed-Layer** gemerged und unterliegen dessen Admin-ACL. - Der Stand dieses Repos wird über einen **Repo-Ref gepinnt** (Default: `main`). Jeder Rollout ist damit deterministisch reproduzierbar; die Pin-Logik lebt in `az-fleet`. ## `tests/fixtures/` — Testgegenstände, nie ausgeliefert Guard-Tests brauchen gültige und ungültige Artefakt-Exemplare als Testgegenstände. Diese **Fixtures** leben unter `tests/fixtures/` — denn die Delivery-Rolle liest **nur die vier Typ-Verzeichnisse**, also kann unter `tests/fixtures/` nichts „mitschwimmen" und versehentlich ausgeliefert werden. (Sonntags-Entscheidung: bewusst kein eigener Auslieferungs-Ausschluss-Mechanismus, sondern Trennung durch das Lese-Muster der Delivery-Rolle.) Konvention: je Artefakt-Typ ein Unterordner, darin `valid/`- und `invalid/`-Exemplare, an denen der Guard durch- bzw. abbricht. ``` tests/fixtures/ ├── skills/valid/… skills/invalid/… ├── commands/valid/… commands/invalid/… ├── agents/valid/… agents/invalid/… └── mcp/valid/… mcp/invalid/… ``` **Regel:** alles unter `tests/fixtures/` ist Testgegenstand und wird **nie ausgeliefert** — nichts daraus in die Typ-Verzeichnisse schieben; umgekehrt sind echte Artefakte dort fehl am Platz. --- ## Beitrags-Kurzanleitung 1. Richtiges Verzeichnis anhand der Tabelle oben wählen. 2. Artefakt gemäß Guard-Regeln des Typs anlegen (Minimalbeispiel als Vorlage). 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. 4. Commit/PR wie gewohnt. Der Guard läuft als Pre-Flight beim nächsten Rollout in `az-fleet`; erst nach Rollout und App-Neustart ist das Artefakt auf den Workstations.