APM-Packages/omos/README.md

# omos

Adapter zwischen APM-Packages mit Team-Profil und [oh-my-opencode-slim](https://github.com/alvinunreal/oh-my-opencode-slim).

`omos` liest eine `team-profile.yaml` aus einem APM-Package, löst abstrakte Modellklassen gegen deine lokale Mapping-Tabelle auf und generiert ein namespacetes oh-my-opencode-slim-Preset. Deterministisch – `omos` rät nicht.

```
APM-Package                Nutzer                     Runtime
team-profile.yaml   +   model-mapping.yaml   →  omos render  →  .opencode/
(Rollen, Modell-         (Modellklasse →            oh-my-opencode-slim.json
 klassen, MCPs/Skills)    konkrete Modell-ID)
```

## Voraussetzungen

- Python 3.10+ mit PyYAML (`pip install pyyaml`)
- OpenCode mit installiertem Plugin [oh-my-opencode-slim](https://ohmyopencodeslim.com/)
- Ein APM-Package mit `team-profile.yaml`

## Schnellstart

```bash
# 1. Modell-Mapping anlegen – interaktiv, mit Auswahl aus deinen opencode-Modellen
python3 omos.py init --fill

# 2. Geführt: Team-Profil lesen, Mapping prüfen/auffüllen, rendern
cd <projekt>
python3 /pfad/zu/omos.py setup --package /pfad/zum/package

# 3. Aktivieren
opencode          # Projekt-Config wird geladen
/preset acme-job-applications
# Reload OpenCode → Team aktiv (by Design: kein Hot-Swap)
```

Alternativ manuell:

```bash
# 1. Modell-Mapping einmalig anlegen
mkdir -p ~/.config/apm-team
cp examples/model-mapping.yaml ~/.config/apm-team/model-mapping.yaml
$EDITOR ~/.config/apm-team/model-mapping.yaml   # an eigene Modelle anpassen

# 2. Validieren (Dry-Run)
python3 omos.py check --package examples/package

# 3. Rendern
cd <projekt>
python3 /pfad/zu/omos.py render --package /pfad/zum/package
```

## Die drei Dateien

| Datei | Gehört | Zweck | Manuell editieren? |
|---|---|---|---|
| `team-profile.yaml` | Package-Autor | Rollen, Modellklassen, MCP-/Skill-Allowlists pro Rolle | Ja (Autor) |
| `~/.config/apm-team/model-mapping.yaml` | Nutzer | Modellklasse → konkrete Modell-ID (+ optional variant/temperature) | Ja (Nutzer) |
| `.opencode/oh-my-opencode-slim.json` | generiert | OMOS-Preset mit konkreten Modell-IDs | **Nein** – immer neu rendern |

Dazu eine Provenance-Datei `.opencode/oh-my-opencode-slim.omos-provenance.json`, die dokumentiert, welche Rolle welches Modell erhalten hat.

## Kommandoreferenz

```bash
python3 omos.py init   [--mapping FILE] [--fill]          # Mapping anlegen/füllen
python3 omos.py setup  --package DIR [--mapping F] ...    # geführter Ablauf
python3 omos.py render --package DIR [--mapping F] [--output F] [--dry-run]
python3 omos.py check  --package DIR [--mapping F]        # Dry-Run-Validierung
```

### `init` – Mapping anlegen

Erstellt `~/.config/apm-team/model-mapping.yaml` (falls nicht vorhanden). Mit `--fill` werden alle `PLACEHOLDER`-Klassen interaktiv abgefragt: `omos` listet alle Modelle aus deiner `opencode.json(c)` auf, du wählst per Nummer oder gibst eine Modell-ID manuell ein.

### `setup` – Geführter Ablauf

Der Ein-Kommando-Weg: zeigt das Team-Profil verständlich an, legt fehlendes Mapping an, fragt fehlende Modellklassen interaktiv ab (gleiche Auswahl wie `init --fill`), rendert und gibt die Aktivierungsschritte aus. Entspricht dem Resolve–Validate–Render-Ablauf.

### `render` / `check`

| Option | Default | Bedeutung |
|---|---|---|
| `--package` | `.` | APM-Package-Verzeichnis mit `team-profile.yaml` |
| `--mapping` | `~/.config/apm-team/model-mapping.yaml` | Lokale Mapping-Tabelle |
| `--output` | `<package>/.opencode/oh-my-opencode-slim.json` | Zieldatei |
| `--team-file` | `team-profile.yaml` (alternativ `team.yaml`) | Alternativer Profilname |

**Merge-Verhalten:** Existierende Presets in der Zieldatei bleiben unberührt; nur das Preset der Team-ID wird ersetzt. Mehrere Packages koexistieren damit im selben Projekt. Aktiviert wird explizit per `/preset <name>`.

## Team-Profil-Schema (`corentic.team-profile/v1`)

```yaml
schema: corentic.team-profile/v1
id: acme.job-applications          # wird zum Preset-Namen (namespaced)
description: ...

roles:
  - id: researcher                 # fachliche Rolle
    purpose: ...                   # wird zu Prompt/Description für Custom Agents
    omos_agent: librarian          # optional: OMOS-Builtin oder 'custom'
                                   # (Default: role-id als Custom Agent)
    model_class: fast-research     # Pflicht, muss im Mapping existieren
    capabilities:
      mcps: [websearch, openviking]  # MCP-Allowlist ([] = keine)
      skills: [job-application]      # Skill-Allowlist ([] = keine)
```

Erkannte OMOS-Builtins: `orchestrator`, `oracle`, `librarian`, `explorer`, `fixer`, `designer`, `council`, `observer`. Alles andere (oder `omos_agent: custom`) erzeugt einen Custom Agent inklusive `prompt` und `orchestratorPrompt` aus dem `purpose`-Feld.

### Mapping-Formate

```yaml
model_classes:
  fast-research: ollama/qwen3.5:9b              # einfach
  high-reasoning:                               # erweitert
    model: ollama/qwen3.6:35b-a3b-q4_K_M
    variant: thinking
    temperature: 0.3
```

Alle Zusatzfelder werden 1:1 in den Agent-Eintrag des Presets übernommen.

## Was omos prüft

1. Team-Profil vorhanden, Schema bekannt, `id` und `roles` vorhanden
2. Jede `model_class` hat einen Mapping-Eintrag (sonst Fehler mit Lösungshinweis)
3. MCPs gegen `~/.config/opencode/opencode.json(c)` abgleichen (**Warnung**, kein Abbruch)
4. Rollen ohne MCPs/Skills → Hinweis

`omos` nimmt keine Verfügbarkeit an und wählt keine Modelle automatisch aus. Fehlt ein Mapping, bricht das Rendern mit konkreter Ursache ab.

## Walkthrough mit dem Beispiel-Package

```bash
cd omos/examples

# Trockenlauf: was würde generiert?
python3 ../omos.py check --package package --mapping model-mapping.yaml

# Rendern in das Beispiel-Projekt
python3 ../omos.py render --package package \
  --mapping model-mapping.yaml \
  --output package/.opencode/oh-my-opencode-slim.json
```

Erwartetes Ergebnis: Preset `acme-job-applications` mit fünf Agenten – `orchestrator`, `librarian` (Alias `researcher`), Custom Agent `writer`, `oracle` (Alias `checker`), Custom Agent `notifier`. Der Researcher erhält keinen LaTeX-Zugang, der Writer keine Job-Suchtools, der Notifier gar keine externen Zugriffe.

Danach:

```bash
cd package && opencode
/preset acme-job-applications
```

## Troubleshooting

| Problem | Ursache/Lösung |
|---|---|
| `Modellklasse X ist nicht gemappt` | Mapping ergänzen, erneut rendern |
| `Warnung: MCP ... nicht konfiguriert` | MCP in `opencode.jsonc` einrichten oder aus dem Profil entfernen |
| `/preset` zeigt nichts Neues | OpenCode nach dem Render neu laden; Preset greift nicht mid-session |
| Preset weg nach manuellem Editieren | Datei ist generiert – Änderungen gehören ins Mapping oder Team-Profil |
| YAML-Fehler | Zeilenangabe aus der Fehlermeldung folgen |

## Grenzen (bewusst)

- `omos` startet keine Agenten und orchestriert nichts zur Laufzeit – das macht oh-my-opencode-slim.
- MCP-/Skill-Allowlists sind Capability Scoping, keine Sandbox. Irreversible Aktionen brauchen serverseitige Autorisierung + Human Approval.
- Die Modellverfügbarkeit wird gegen die opencode.jsonc-Namen geprüft, nicht per API-Healthcheck.