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.

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.

{
  "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

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.

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.

# ~/.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.

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.

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.

{
  "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:

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

Und im Backend:

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

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:

# ~/.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:

{
  "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:

/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:

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

Dann:

/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.