az-agent-defaults/README.md

# 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/<name>/` | Ordner mit `SKILL.md` |
| einen Command (/slash-Befehl, wiederverwendbarer Prompt) | `commands/<name>.md` | Markdown-Datei mit Frontmatter |
| einen Agenten (spezialisiertes Profil als Primäragent oder Subagent) | `agents/<name>.md` | Markdown-Datei mit Frontmatter |
| einen MCP-Server (Werkzeug-Anbindung) | `mcp/<name>.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/<server-name>.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:<key-name>} ``; der echte Key liegt im Vault des Fleet-Repos und
  wird erst beim Merge auf dem Controller substituiert. Im Repo bleibt nie ein
  Secret.
  - **Vault-Key-Namensschema:** `<server-name>-<verwendungszweck>` in
    kebab-case — z. B. `${VAULT:az-zoll-service-api-key}` für den API-Key
    des Servers `az-zoll-service`. Ein Key pro Credential, im Vault der IT
    eindeutig zuordenbar.

**Minimalbeispiel (OAuth-Standardfall):**

```yaml
# mcp/zugferd-service.yaml
zugferd-service:
  type: remote
  url: https://mcp.example.az.local/zugferd
  enabled: true
```

**Beispiel (dokumentierte Key-Ausnahme):**

```yaml
# mcp/az-zoll-service.yaml — kein OAuth verfügbar: statischer Key aus dem Vault
az-zoll-service:
  type: remote
  url: https://mcp.example.az.local/zoll
  headers:
    Authorization: Bearer ${VAULT:az-zoll-service-api-key}
  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:…}`.

---

## 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
<Rollen-Eröffnung: wer du bist, wer dich ruft>

## Arbeitsweise
1. **<Schritt>** — <Anweisung mit erkennbarem Abschlusskriterium>.

## Ausgabeformat
<Output-Vertrag — für Subagents Pflicht, siehe unten>

## Grenzen
- <Was der Agent nie tut; Auth, Fleet-Verwaltung, Eskalation>
```

- **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.
- **Tool-/MCP-Freigabe:** Schränkt ein Agent Tools ein (`tools:` bzw.
  `permission:`), muss er jedes benötigte MCP-Tool **explizit freigeben** —
  MCP-Tools heißen `<ServerName>_<ToolName>` (z. B.
  `Websearch_web_search_exa` für den Exa-Server `Websearch` aus `mcp/`).
  Ohne Profil gelten die Defaults des Harness.

### Trigger-Description

Die Frontmatter-`description` entscheidet, ob Orchestrator oder Nutzer den
Agenten auswählen. Deshalb:

- **Subagents** (vom Orchestrator über die Routing-Tabelle gewählt): **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.
- **Primary-Agenten** (vom Nutzer aus einer Liste gewählt): **In den ersten
  80 Zeichen steht der Missionssatz** — ein prägnanter Satz, wofür der
  Agent der Standard-Anlaufpunkt ist. Danach Trigger-Beispiele und
  Fähigkeiten.

### 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."**
(der Orchestrator nutzt die gleichbedeutende Variante „Antworte in der
Sprache der Nutzeranfrage.") 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 |
|---|---|
| **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/…   agents/demo/…
└── 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.

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)
   — 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.
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.