feat: scaffold content repo with guard rules per artifact type
- add skills/, commands/, agents/, mcp/ artifact directories - document contribution guard rules per artifact type (spec B1) - document content/mechanism split with az-fleet and ref pinning - document tests/fixtures/ convention (never delivered) Closes az-agent-defaults-j35
This commit is contained in:
m3ta-chiron
@@ -0,0 +1,255 @@
|
||||
# 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.
|
||||
|
||||
**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.
|
||||
Reference in New Issue
Block a user