APM-Packages/apm-omos-agent-teams-v3.md

# APM, Agent-Teams und das kleine Problem namens Realität

*Wie APM-Packages Team-Empfehlungen ausliefern können – mit oh-my-opencode-slim als erstem konkretem Target.*

Der Agenten-Stack entwickelt sich gerade mit der Geschwindigkeit eines explodierenden Werkzeugschuppens. Jeden Monat erscheint ein neues Manifest, ein neues Plugin-Format oder eine neue Orchestrierungsebene. Alles löst einen legitimen Teil des Problems. Fast nichts passt nahtlos zusammen.

Das ist kein Vorwurf. Es ist der normale Zustand eines jungen Ökosystems. Der interessante Teil beginnt dort, wo die bestehenden Stücke bereits ausreichen, um eine sinnvolle Brcke zu bauen.

Diese Brcke kann so aussehen:

> Ein APM-Package liefert Skills, Instructions, MCP-Abhngigkeiten und eine deklarative Empfehlung fr ein Agenten-Team. Ein Harness-spezifischer Adapter übersetzt diese Empfehlung in die lokale Team- und Modellkonfiguration.

Fr oh-my-opencode-slim nenne ich diesen Adapter im Folgenden **`omos`**.

`omos` ist dabei ein Design fr eine Erweiterung bzw. ein Sidecar-Tool. Es ist heute kein offiziell eingebautes APM-Target.

## Das Ökosystem heute

Die vorhandenen Formate lassen sich grob in fnf Gruppen einteilen.

| Ebene | Beispiele | Zustndigkeit |
|---|---|---|
| Portable Komponenten | Agent Plugins | Skills und MCP-Server verteilen |
| Dependency Management | APM | Packages, Lockfile, Policies, Deployment |
| Team-Komposition | Spawnfile, Harness-Configs | Rollen, Delegation, Agentenbeziehungen |
| Runtime-Profile | oh-my-opencode-slim Presets | Modelle und Optionen je Agent |
| Governance | Agent Manifest | Identitt, Grenzen, Verantwortung, Auditierbarkeit |

Das Problem ist nicht fehlende Funktionalitt. Das Problem ist die Lcke zwischen diesen Schichten.

### Agent Plugins

Agent Plugins 1.0 definiert ein bewusst kleines, portables Plugin-Format. Im Kern enthlt ein Plugin eine `plugin.json` und kann Skills sowie MCP-Server bereitstellen. Erweiterungen sind mglich, mssen aber im `extensions`-Block ber einen Reverse-Domain-Namespace isoliert werden.

Das ist sehr gut fr Interoperabilitt. Ein Skill bleibt ein Skill. Ein MCP bleibt ein MCP. Der Standard versucht nicht, die Laufzeit eines jeden Agentenframeworks zu regieren.

Offen bleiben jedoch Dependencies, getestete Versionen, Teamrollen, Modellprofile und die Aktivierung im konkreten Harness.

### APM

APM besetzt die nchste Ebene: Package- und Dependency-Management fr Agent-Kontext.

Ein APM-Manifest kann Abhngigkeiten auf andere APM-Packages, MCP-Server und LSP-Server beschreiben. APM verwaltet Auflsung, Lockfile und Installation. ber Targets kompiliert es Primitives in Harness-spezifische Dateien. Das native `opencode`-Target installiert Skills, Agents und Commands in die passenden `.opencode/`-Pfade.

```yaml
name: acme/research-assistant
version: 1.0.0
type: hybrid

targets:
  - opencode

dependencies:
  apm:
    - acme/base-engineering
  mcp:
    - name: repository-search
      registry: false
      transport: stdio
      command: repository-search-mcp
      tools: [search_code, read_file]
```

APM beantwortet damit: Welche Artefakte gehren zusammen? Welche Versionen wurden zusammen getestet? Welche MCPs werden bentigt? Wohin werden Skills und Instructions installiert?

Was APM aktuell nicht standardisiert beschreibt, ist Team-Semantik: Rollen, Delegation, Modell-Empfehlungen und Aktivierung eines Team-Profils.

### Spawnfile

Spawnfile adressiert die Teamachse. Agenten und Teams knnen deklarativ mit Rollen, Zustndigkeiten, Kommunikationswegen und Subagenten beschrieben werden. Die offene Stelle liegt bei Dependencies und Verteilung: Ein Team-Manifest installiert keine versionierten Skills, MCPs und Policies.

### oh-my-opencode-slim

oh-my-opencode-slim sitzt nahe an der Runtime. Sein Preset-System kann je Agent Modell, Temperatur, Variante und provider-spezifische Optionen umschalten. Presets werden ber `/preset <name>` whrend einer laufenden Session aktiviert.

```jsonc
{
  "presets": {
    "deep-review": {
      "orchestrator": { "model": "provider/strong-generalist" },
      "oracle": { "model": "provider/high-reasoning", "variant": "thinking" },
      "librarian": { "model": "provider/fast-research" }
    }
  }
}
```

Das beantwortet die Frage, wie unterschiedliche Rollen unterschiedliche Modellprofile erhalten. Es fehlt die Herkunft: Welches Package empfiehlt dieses Team? Welche Skills und MCPs gehren dazu? Welche Version wurde getestet?

## Die Lcke

```mermaid
flowchart LR
    AP[Agent Plugins] -->|Skills und MCPs| PK[Package-Inhalt]
    APM[APM] -->|Dependencies, Lockfile, Installation| PK
    SF[Spawnfile] -->|Rollen und Teamstruktur| TM[Team-Modell]
    OMOS[oh-my-opencode-slim] -->|Presets, Modelle, Runtime-Switching| RT[aktive Runtime]
    PK -. fehlende Verbindung .-> TM
    TM -. fehlende Verbindung .-> RT
```

Die Lcke verlangt kein zehntes allumfassendes YAML-Format. Sie verlangt eine kleine Kompositionsschicht.

## Die APM-OMOS-Idee

Ein APM-Package bleibt Source of Truth fr Skills, Instructions, MCP-Abhngigkeiten, Versionen, Dependency-Closure und Policies. Zusstzlich enthlt es ein Team-Profil als Empfehlung fr Harness-Adapter.

```yaml
schema: acme.team-profile/v1
id: acme.document-research
description: Team-Profil fr Recherche, Erstellung und Qualittsprfung quellenbasierter Dokumente.

roles:
  - id: orchestrator
    purpose: Zerlegt Aufgaben, delegiert, integriert Ergebnisse
    model_class: strong-generalist
  - id: researcher
    purpose: Sammelt und bewertet Quellen
    model_class: fast-research
    capabilities:
      mcps: [web-research, repository-search]
      skills: [job-matching]
  - id: writer
    purpose: Erstellt strukturierte Dokumententwrfe
    model_class: strong-writing
    capabilities:
      mcps: [document-write]
      skills: [application-writing]
  - id: checker
    purpose: Prft Quellenbezug, Konsistenz und Vollstndigkeit
    model_class: high-reasoning
    capabilities:
      mcps: [document-read]
      skills: [application-review]
```

Das Profil verwendet Modellklassen wie `high-reasoning` statt konkreter Modell-IDs. Der Nutzer hinterlegt in einer lokalen Mapping-Tabelle, welche Modell-IDs fr welche Modellklasse verwendet werden sollen.

```yaml
# ~/.config/apm-team/model-mapping.yaml
model_classes:
  strong-generalist: anthropic/claude-sonnet-4-6
  fast-research: openai/gpt-5.4-mini
  strong-writing: anthropic/claude-sonnet-4-6
  high-reasoning: openai/gpt-5.5
```

## Was `omos` macht

`omos` ist der Übersetzer zwischen Team-Profil und oh-my-opencode-slim. Er liest installierte APM-Packages, findet Team-Profile, schlägt Modellklassen gegen die lokale Mapping-Tabelle nach und generiert namespacete Presets fr das Projekt.

```mermaid
flowchart TD
    P[APM Package: team-profile.yaml] --> O[omos liest]
    M[~/.config/apm-team/model-mapping.yaml] --> O
    O -->|Prfe| X{Alle Modellklassen gemappt?}
    X -->|Nein| E[Fehler: fehlendes Mapping fr Rolle Y]
    X -->|Ja| G[Generiere OMOS-Preset mit konkreten Modell-IDs]
    G --> V[Validiere: Modelle in OMOS verfgbar?]
    V -->|Nein| F[Fehler: Modell Z nicht im OMOS-Setup]
    V -->|Ja| C[Schreibe .opencode/oh-my-opencode-slim.json]
    C --> D[Fertig]
```

`omos` rtt nicht. Er übersetzt deterministisch:

1. Team-Profil lesen (Modellklassen + MCP/Skill-Capabilities).
2. Lokale Mapping-Tabelle laden (Modellklasse → konkrete Modell-ID).
3. OMOS-Preset generieren (konkrete Modell-IDs + MCP/Skill-Allowlists).
4. Validieren: Sind die Modelle im OMOS-Setup verfgbar?
5. Preset in `.opencode/oh-my-opencode-slim.json` schreiben.

## Mehrere Packages, ein Projekt

Jedes Profil erhlt eine globale, stabile ID wie `acme.job-applications`, `acme.security-audit` oder `acme.code-review`. `omos` merged Presets anhand dieser IDs. Das aktive Team wird nicht durch die letzte Installation gewhlt.

```mermaid
flowchart LR
    A[Package: Job Applications] --> M[Preset Merge]
    B[Package: Security Audit] --> M
    C[Package: Code Review] --> M
    M --> P[Projekt-Preset-Registry]
    P --> U[Nutzer oder expliziter Workflow]
    U --> S[/preset acme-job-applications]
```

## Beispiel: Autobewerber als Team-Package

Ein Bewerbungsassistent eignet sich gut als Beispiel: Web-Recherche, personenbezogene Daten, Dokumentenproduktion, Qualittsprfung, Benachrichtigungen und externe Aktionen treffen zusammen. Der Mechanismus bleibt derselbe fr Code-Review, Sales Research, Compliance oder Incident Response.

### Rollen und OMOS-Mapping

| Fachliche Rolle | OMOS-Rolle | Zweck |
|---|---|---|
| Koordination | `orchestrator` | Zerlegt Aufgaben, delegiert, integriert |
| Recherche | `librarian` (Alias `researcher`) | Sucht und bewertet Stellen |
| Schreiben | Custom Agent `writer` | Erstellt Anschreiben und Unterlagen |
| Prfung | `oracle` (Alias `checker`) | Prft Fakten, Ton, Vollstndigkeit |
| Benachrichtigung | Custom Agent `notifier` | Informiert den Nutzer |

### Was OMOS tatschlich begrenzen kann

OMOS bietet pro Agent zwei brauchbare Kontrollflchen:

1. **MCP-Zugriff** (`mcps`-Array)
2. **Skill-Zugriff** (`skills`-Array)

Beides kann je Agent in einem Preset als Allowlist formuliert werden. `[]` bedeutet keine Freigabe, `["!*"]` verweigert alles; bei Konflikten gewinnt die Verweigerung.

```jsonc
{
  "presets": {
    "acme-job-applications": {
      "orchestrator": {
        "model": "anthropic/claude-sonnet-4-6",
        "mcps": [],
        "skills": ["job-orchestration"]
      },

      "librarian": {
        "displayName": "researcher",
        "model": "openai/gpt-5.4-mini",
        "mcps": ["job-search", "candidate-profile-read"],
        "skills": ["job-matching"]
      },

      "writer": {
        "model": "anthropic/claude-sonnet-4-6",
        "mcps": ["candidate-profile-read", "overleaf"],
        "skills": ["application-writing"]
      },

      "oracle": {
        "displayName": "checker",
        "model": "openai/gpt-5.5",
        "variant": "high",
        "mcps": ["candidate-profile-read", "overleaf"],
        "skills": ["application-review"]
      },

      "notifier": {
        "model": "openai/gpt-5.4-mini",
        "mcps": ["notification-draft"],
        "skills": []
      }
    }
  }
}
```

Damit erhlt der Researcher keinen Overleaf-Zugang. Der Writer sieht keine Job-Suchtools. Der Notifier bekommt keinen Browser und keinen Schreibzugriff auf die Bewerbung.

### Die wichtige Einschrnkung

`mcps` und `skills` schtzen nur den Zugriff auf genau diese zwei Ebenen. Die Aussage „der Agent darf niemals eine Bewerbung absenden" bentigt Verteidigung in mehreren Schichten:

| Schicht | Durchsetzung |
|---|---|
| OMOS-Rollenprompt | Klare Verhaltensregel: nie einreichen |
| OMOS MCP-Allowlist | `application-submit` MCP gar nicht zuweisen |
| MCP-Server selbst | Submission-Tool verlangt Approval-Token |
| Workflow-State | `submit` nur aus Zustand `user_approved` erlaubt |
| OpenCode-/Sandbox-Policy | Schreib-, Shell- und Browserrechte begrenzen |
| User Interface | Explizite, sichtbare Freigabe vor jeder Auenwirkung |

Die echte Autorisierungsgrenze muss am **MCP beziehungsweise Backend** liegen. Ein Prompt ist eine Verhaltensanweisung. Eine MCP-Allowlist ist Capability Scoping. Ein Server, der ohne gltiges Freigabe-Token keine Submission annimmt, ist die harte Grenze.

Fr deinen Use Case wrde ich den Notification-MCP so schneiden:

```text
notification-draft       → darf Entwurf erzeugen
notification-send        → braucht userApprovalId
application-submit       → braucht userApprovalId + applicationDraftId
```

Und im Backend:

```mermaid
sequenceDiagram
    participant C as Checker
    participant N as Notifier MCP
    participant U as Nutzer
    participant S as Submission MCP

    C->>N: createDraftNotification(applicationDraftId)
    N-->>U: Stelle gefunden, Entwurf geprft
    U->>U: Prft PDF und Fakten
    U->>S: approve(applicationDraftId)
    S-->>S: issue userApprovalId
    U->>S: submit(applicationDraftId, userApprovalId)
    S-->>U: Bewerbung eingereicht
```

Der Notifier kann dann technisch niemals eine Bewerbung absenden, weil er keinen Submission-MCP besitzt und das Submission-Backend einen vom Nutzer stammenden Freigabenachweis verlangt.

### Das Team-Profil

```yaml
schema: acme.team-profile/v1
id: acme.job-applications
description: Human-in-the-loop-Team zur Recherche, Vorbereitung und Prfung individueller Bewerbungsunterlagen.

roles:
  - id: orchestrator
    purpose: Zerlegt Aufgaben, delegiert, integriert Ergebnisse
    model_class: strong-generalist
    capabilities:
      mcps: []
      skills: [job-orchestration]

  - id: researcher
    purpose: Sucht und bewertet Stellenausschreibungen
    model_class: fast-research
    capabilities:
      mcps: [job-search, candidate-profile-read]
      skills: [job-matching]

  - id: writer
    purpose: Erstellt auf Fakten basierende Anschreiben
    model_class: strong-writing
    capabilities:
      mcps: [candidate-profile-read, overleaf]
      skills: [application-writing]

  - id: checker
    purpose: Prft Fakten, Ton und Vollstndigkeit
    model_class: high-reasoning
    capabilities:
      mcps: [candidate-profile-read, overleaf]
      skills: [application-review]

  - id: notifier
    purpose: Informiert den Nutzer ber geprfte Entwrfe
    model_class: cheap-reliable
    capabilities:
      mcps: [notification-draft]
      skills: []
```

Die lokale Mapping-Tabelle:

```yaml
# ~/.config/apm-team/model-mapping.yaml
model_classes:
  strong-generalist: anthropic/claude-sonnet-4-6
  fast-research: openai/gpt-5.4-mini
  strong-writing: anthropic/claude-sonnet-4-6
  high-reasoning: openai/gpt-5.5
  cheap-reliable: openai/gpt-5.4-mini
```

Das generierte OMOS-Preset:

```jsonc
{
  "presets": {
    "acme-job-applications": {
      "orchestrator": {
        "model": "anthropic/claude-sonnet-4-6",
        "mcps": [],
        "skills": ["job-orchestration"]
      },
      "librarian": {
        "displayName": "researcher",
        "model": "openai/gpt-5.4-mini",
        "mcps": ["job-search", "candidate-profile-read"],
        "skills": ["job-matching"]
      },
      "writer": {
        "model": "anthropic/claude-sonnet-4-6",
        "mcps": ["candidate-profile-read", "overleaf"],
        "skills": ["application-writing"]
      },
      "oracle": {
        "displayName": "checker",
        "model": "openai/gpt-5.5",
        "variant": "high",
        "mcps": ["candidate-profile-read", "overleaf"],
        "skills": ["application-review"]
      },
      "notifier": {
        "model": "openai/gpt-5.4-mini",
        "mcps": ["notification-draft"],
        "skills": []
      }
    }
  }
}
```

Das Ganze lsst sich ber ein OMOS-Preset aktivieren:

```text
/preset acme-job-applications
```

Der Nutzer erhlt danach keine unsichtbare Bewerbungsmaschine. Er erhlt ein explizit aktiviertes, nachvollziehbares Team mit klaren Zustndigkeiten.

## Wie das heute beginnen kann

Die Idee muss nicht auf eine APM-Spec-nderung warten.

Ein erster Prototyp braucht nur drei Bausteine:

1. **Ein normales APM-Package**  
   Skills, Instructions und MCP-Abhngigkeiten werden ber APM installiert.

2. **Ein Team-Profil als zustzliche Package-Datei**  
   Zum Beispiel `team-profile.yaml`, mit versioniertem Schema und eindeutiger ID.

3. **Ein `omos` Sidecar-CLI**  
   Es liest die installierten Packages, generiert namespacete OMOS-Presets und validiert Konflikte.

Der Ablauf wre:

```bash
apm install acme/job-application-team
apm-team render --harness omos
opencode
```

Dann:

```text
/preset acme-job-applications
```

APM selbst muss dafr zunchst keine unbekannten Targets akzeptieren. Tatschlich kennt das aktuelle Manifest nur einen festen Satz dokumentierter Targets; unbekannte Zielnamen fhren zu einem Fehler.

Das Sidecar ist daher der pragmatische Anfang. Es kann als externes Tool reifen, Daten ber realistische Nutzung liefern und spter als offizieller APM-Adapter oder als Erweiterung im APM-Ö´kosystem landen.

## Der Kern

Die Idee lautet nicht: „APM wird jetzt ein Multi-Agent-Framework."

APM soll sein, was es gut kann: Package-Management fr Agent-Kontext.

oh-my-opencode-slim soll sein, was es gut kann: konkrete Rollen, Modelle und Laufzeit-Presets verwalten.

Dazwischen liegt ein kleines, wertvolles Stck Infrastruktur:

> Ein APM-Package beschreibt nicht nur, welche Fhigkeiten installiert werden. Es kann auch erklren, welches Team diese Fhigkeiten sinnvoll verwendet.

Damit wird ein Package vom Ordner voller Skills zu einem reproduzierbaren Arbeitsmodell:

- versionierte Rollen;
- berprfbare Tool-Zugriffe;
- lokale Modell-Policies;
- mehrere Teams pro Projekt;
- explizite Aktivierung;
- menschliche Freigabe an kritischen Grenzen.

Und das ist wesentlich ntzlicher als ein weiterer „autonomer Agent", der nach drei Minuten Browserzugriff beschliet, dass er nun Personalabteilung spielen darf.