ADR-005: Repository Strategy — Eigenes Standalone-Repo + Referenz im Semantic-Anchors-Repo

Status

Proposed

Context

Das Plugin ist als Contribution zum LLM-Coding/Semantic-Anchors Repository vorgesehen (analog zum Claude Code Plugin unter plugins/semantic-anchors/). Allerdings gibt es mehrere Faktoren, die diese einfache Annahme infrage stellen:

  1. Release-Zyklus: Das Semantic-Anchors-Repo hat einen eigenen Release-Rhythmus. Unser Plugin bräuchte eventuell schnellere Releases (Bugfixes, Security).

  2. npm publish: Ein Plugin im Subtree eines Fremd-Repos zu publishen ist kompliziert (CI/CD, Versionsmanagement).

  3. opencode Ecosystem: opencode hat eine eigene Plugin-Liste (https://opencode.ai/docs/ecosystem#plugins). Ein Standalone-Repo kann dort gelistet werden.

  4. Issues/PRs: Eigene Issues und PRs sind einfacher zu managen als Issues in einem Fremd-Repo.

  5. CI/CD: Eigene GitHub Actions sind unabhängig vom Semantic-Anchors-Workflow.

Die Entscheidung betrifft: Wo lebt der Code? Wo wird entwickelt? Wie wird released? Wie wird contributed?

Alternatives Considered

Option A: Nur Semantic-Anchors-Repo

Der gesamte Code lebt ausschliesslich als plugins/opencode-semantic-anchors/ im LLM-Coding/Semantic-Anchors Repository.

LLM-Coding/Semantic-Anchors/
├── plugins/
│   └── opencode-semantic-anchors/   ← Hier lebt der Code
├── docs/
└── ...

Vorteile: - Ein Ort für alles (Single Source of Truth) - Analog zum Claude Code Plugin (existierender Präzedenzfall) - Maximale Sichtbarkeit in der Semantic-Anchors-Community - Kein Sync-Aufwand zwischen Repos - Contribution ist "nur ein PR"

Nachteile: - Kein eigenes npm-Paket (oder sehr umständlich) - Release-Zyklus gekoppelt an Semantic-Anchors-Maintainer - Eigene CI/CD nur via Semantic-Anchors-Workflow - Issues/PRs teilen sich den Pool mit dem gesamten Repo - npm publish müsste durch Semantic-Anchors-Maintainer erfolgen - Kein Eintrag im opencode Ecosystem (dort werden npm-Pakete gelistet)

Option B: Eigenes Standalone-Repo (gewählt)

Der Code lebt in einem eigenen GitHub-Repository, unabhängig vom Semantic-Anchors-Repo.

github.com/JensGrote/opencode-semantic-anchors/
├── src/
├── package.json
├── dist/
└── ...

Vorteile: - Eigenes npm-Paket (publish jederzeit) - Eigener CI/CD (Tests, Build, Publish) - Eigene Issues/PRs (fokussiert auf das Plugin) - opencode Ecosystem kann das Paket listen - Unabhängiger Release-Zyklus (Bugfixes sofort) - Volle Kontrolle über Branch-Strategie und Releases

Nachteile: - Weniger Sichtbarkeit in der Semantic-Anchors-Community - Contribution ins Semantic-Anchors-Repo erfordert separate Referenz - Eigenes Repository = eigene Maintenance (Issues, Security, Dependencies) - Kein "Auto-Discovery" durch Semantic-Anchors-Leser

Option C: Beide — Standalone-Repo + Subtree/Submodule im Semantic-Anchors-Repo

Der Code lebt im Standalone-Repo, wird aber per git subtree oder git submodule in das Semantic-Anchors-Repo eingebunden.

LLM-Coding/Semantic-Anchors/
├── plugins/
│   └── opencode-semantic-anchors/   ← subtree von eigenem Repo

Vorteile: - Beste aus beiden Welten (eigenes Repo + Sichtbarkeit im Semantic-Anchors) - Contribution = Update des Subtrees - npm publish vom eigenen Repo

Nachteile: - Höchster Sync-Aufwand — zwei Repos müssen konsistent bleiben - Subtree-Merges sind fehleranfällig - Submodule sind UX-technisch problematisch ("forgot to update submodule") - Zwei verschiedene Contribution-Pfade (direct vs subtree) verwirren Contributor - Zusätzlicher Aufwand für Semantic-Anchors-Maintainer

Option D: Fork + Upstream PR

Plugin im eigenen Repo entwickeln, dann per Fork+PR ins Semantic-Anchors-Repo bringen, danach nur noch im Semantic-Anchors-Repo pflegen.

Nachteile: - Einmaliger Aufwand — nach Contribution ist das eigene Repo obsolet - Fork-Chain ist verwirrend (upstream vs origin) - Nach Contribution kein eigener Release-Zyklus mehr - GitHub Forks sind als dauerhafte Entwicklungsumgebung suboptimal

Evaluation Criteria

Kriterium Gewicht Beschreibung

Release-Unabhängigkeit

Hoch

Eigener Release-Zyklus (Bugfixes, Security)

npm-Publish-Fähigkeit

Hoch

Muss als npm-Paket veröffentlicht werden können

Sichtbarkeit

Mittel

Auffindbarkeit für opencode-User und Semantic-Anchors-Community

Wartbarkeit

Hoch

Issues, PRs, CI/CD ohne Abhängigkeit von Fremd-Maintainern

Sync-Aufwand

Niedrig

Kein manueller Sync zwischen Repos

Contribution-Pfad

Mittel

Einfacher Weg ins Semantic-Anchors-Repo

Decision

Option B: Eigenes Standalone-Repo mit Cross-Links wurde gewählt.

Begründung: - Pragmatismus: Ein eigenes Repo gibt uns volle Kontrolle über Releases, CI/CD, Issues und npm publish - opencode Ecosystem: Der Eintrag in der Plugin-Liste erfordert ein npm-Paket — das geht sauber nur mit eigenem Repo - Semantic Anchors Ecosystem: Sichtbarkeit wird durch Cross-Links in beide Richtungen hergestellt (nicht durch Subtree) - Release-Geschwindigkeit: Bugfixes und Security-Patches können sofort released werden, ohne auf Semantic-Anchors-Maintainer zu warten - Geringer Sync-Aufwand: Im Gegensatz zu Option C (Subtree) entsteht kein regelmässiger Sync-Aufwand - Präzedenzfall: agentcontract/spec ist ebenfalls ein eigenes Repo (kein Subdir von Semantic-Anchors) — das etablierte Muster ist Standalone

Cross-Linking Strategic

Die Verbindung zu beiden Ökosystemen wird durch aktive Cross-Links hergestellt, nicht durch Repository-Struktur:

┌──────────────────────────┐       ┌──────────────────────────┐
│  opencode Ecosystem       │       │  Semantic Anchors        │
│  (opencode.ai/docs)       │       │  (GitHub Repo)           │
│                           │       │                          │
│  Plugin-Liste ────────────┼───────┼─► README.md / CLAUDE.md  │
│  "see also"               │       │  "see also"              │
└──────────────────────┼───┘       └─────────────────┼────────┘
                       │                             │
                       ▼                             ▼
              ┌──────────────────────────────────────────┐
              │  Standalone-Repo                         │
              │  github.com/JensGrote/                    │
              │    opencode-semantic-anchors              │
              │                                           │
              │  - README: "Built for opencode"           │
              │  - README: "Part of Semantic Anchors"     │
              │  - opencode.jsonc example                 │
              │  - Anchor-basierte Presets               │
              └──────────────────────────────────────────┘

Konkret: 1. Unser README.md verlinkt auf opencode Plugin Docs + Semantic-Anchors Repository 2. opencode Ecosystem (https://opencode.ai/docs/ecosystem#plugins) listet unser Plugin 3. Semantic-Anchors README/CLAUDE.md verlinkt auf unser Plugin als opencode-Integration 4. npm-Paket hat opencode und semantic-anchors als Keywords

Consequences

  • Positiv: Volle Kontrolle über Releases, CI/CD, Issues und npm publish

  • Positiv: Unabhängigkeit von Semantic-Anchors-Maintainer für Bugfix-Releases

  • Positiv: Eintrag im opencode Ecosystem möglich (npm-Paket-Voraussetzung)

  • Positiv: Sichtbarkeit in beiden Ökosystemen durch Cross-Links

  • Positiv: Eigene Issues/PRs ohne "Rauschen" des Semantic-Anchors-Repos

  • Negativ: Cross-Links müssen aktiv gepflegt werden (kein "Auto-Discovery")

  • Negativ: Eigenes Repo = eigene Öffentlichkeitsarbeit (README, Doku, Sichtbarkeit)

  • Negativ: Kein automatischer Eintrag im Semantic-Anchors-Repo (erfordert PR)

  • Trade-off: Eigenständigkeit gegen Sichtbarkeit — wird durch Cross-Links adressiert

Related

  • ADR-004: Take before Buy before Make (Repository ist Konsequenz der Make-Entscheidung)

  • PLAN.md (muss aktualisiert werden: Contribution nicht als Subdir, sondern als Referenz)

  • MASTER-TODO.md Phase 5 (PR + npm publish)

  • opencode Ecosystem: https://opencode.ai/docs/ecosystem#plugins

  • Semantic-Anchors Claude Code Plugin (Präzedenzfall für Subdir-Ansatz unter plugins/)

Sources