apache/magpie

setup

Dieses Skill ist das einzige Framework-Artefakt, das ein übernehmendes Projekt committet. Jedes andere Apache-Magpie-Skill (Sicherheit, PR-Verwaltung, Issue) ist ein gitignorierter Symlink in das gitignorierte Snapshot unter <snapshot-dir>, das von diesem Skill verwaltet wird.

Das Übernahmemodell ist Snapshot + agentische Überschreibungen + drift- bewusste Aktualisierungen (kein Submodul, kein Marktplatz, keine vendorisierte Kopie):

• Das Framework wird in <snapshot-dir> heruntergeladen und im übernehmenden Repository gitignoriert. Das Snapshot ist ein Build- Artefakt, kein Quellcode.
• Drei Installationsmethoden werden unterstützt (siehe docs/setup/install-recipes.md für wörtliche, kopierbare Rezepte):
  • svn-zip – veröffentlichtes, signiertes Zip von der ASF-Distribution (empfohlen für die Produktion, sobald Releases verfügbar sind).
  • git-tag – auf einen bestimmten Git-Tag festgelegt.
  • git-branch – folgt einer Branch-Spitze (Standard: main, der WIP-Pfad).
• Zwei Lockdateien zeichnen die Framework-Version auf. Die committete gibt an, worauf das Projekt setzt; die lokale zeichnet auf, was jede Maschine tatsächlich geladen hat. Abweichungen zwischen ihnen werden von /magpie-setup upgrade erkannt und behoben.
• Symlinks machen die Skills des Frameworks aufrufbar, als ob sie im übernehmenden Repository lägen. Jeder Symlink heißt magpie-<framework-skill> – jedes Framework-Skill wird unter einem magpie--Präfix installiert, sodass es namensräumlich ist und niemals mit den eigenen Skills des Übernehmers kollidiert (z. B. wird das Snapshot-skills/pr-management-triage/ zu magpie-pr-management-triage, aufgerufen als /magpie-pr-management-triage). .agents/skills/ ist der einzige kanonische Ort: seine magpie-*-Einträge verlinken in <snapshot-dir>/skills/<framework-skill>/. Jedes andere Agenten-Ziel (.claude/skills/, .github/skills/, …) erhält einen dünnen Relay-Symlink pro Skill, der auf den kanonischen Eintrag zurückzeigt (.claude/skills/magpie-<n> → ../../.agents/skills/magpie-<n>) – unabhängig davon, welches Layout das übernehmende Projekt zuvor verwendet hat (siehe agents.md). Die Symlinks sind gitignoriert, weil ihre Ziele bei einem frischen Klon vor dem Ausführen von /magpie-setup verschwinden.
• Übernehmerspezifische Änderungen an Framework-Workflows liegen als agentenlesbare Anweisungen unter .apache-magpie-overrides/<skill-name>.md (committet). Sie invalidieren oder ändern Schritte, die das Skill des Frameworks andernfalls ausführen würde. Siehe overrides.md für den Vertrag und docs/setup/agentic-overrides.md für die Design-Grundlage.

Lokale Selbstübernahme (nur Framework-Checkout). Das einzige Repository, das nicht mit dem Snapshot-Mechanismus übernommen werden kann, ist Apache Magpie Framework Checkout selbst – ein Remote-Snapshot des Frameworks in sich selbst wäre zirkulär. Stattdessen übernimmt es sich selbst mit method:local: jeder kanonische magpie-<skill> in .agents/skills/ ist ein committeter Symlink in das In-Repo ../../skills/<skill>/-Quellverzeichnis, und jedes andere aktive Agenten-Ziel (agents.md) – .claude/skills/ (Claude Code), .github/skills/ (GitHubs Skill-Loader) und jeder vorhandene Holdout – erhält einen committeten Relay-Symlink (magpie-<skill> → ../../.agents/skills/magpie-<skill>) – ohne Snapshot, ohne Remote-Abruf und ohne Kopie. Dadurch werden die eigenen Skills des Frameworks aufrufbar, während das Framework entwickelt wird, und jeder Mitwirkende erhält sie bei einem frischen Klon ohne Einrichtungsschritt aktiv. adopt erkennt das Framework-Checkout strukturell und leitet dorthin automatisch weiter (siehe adopt.md → Lokale Selbstübernahme).

Die zwei Lockdateien

Das Lockdatei-Modell des Frameworks trennt worauf das Projekt setzt (committet) von was diese Maschine tatsächlich abgerufen hat (lokal). Diese Trennung ist die Grundlage für die Drifterkennung und die Unterstützung mehrerer Installateure.

<committed-lock> – .apache-magpie.lock

Im Wurzelverzeichnis des übernehmenden Repositorys committet. Der Pin des Projekts. Nur von /magpie-setup bearbeitet; nicht von Hand ändern.

# .apache-magpie.lock – committet; der Pin des Projekts.

method: <git-branch | git-tag | svn-zip>
url:    <siehe pro-METHODEN-Format unten>

# Für method=git-branch:
ref:    main

# Für method=git-tag:
ref:    v1.0.0          # der Tag-Name
commit: <SHA>           # der Commit, auf den der Tag beim Committen zeigte

# Für method=svn-zip:
ref:    1.0.0           # die Versionsnummer
sha512: <hash>          # die SHA-512 des veröffentlichten Zips (zur Überprüfung beim erneuten Abruf)

Der nächste Übernehmer, der /magpie-setup adopt ausführt, liest diese Datei und installiert die gleiche Version neu, die das Projekt deklariert hat. Dies ist der Kern des Versprechens "Einmal übernommen, alle nachfolgenden Benutzer erhalten dasselbe".

<local-lock> – .apache-magpie.local.lock

Im Wurzelverzeichnis des übernehmenden Repositorys gitignoriert. Der Fingerabdruck des lokalen Snapshots. Zeichnet auf, was diese Maschine abgerufen hat und wann.

# .apache-magpie.local.lock – gitignoriert; pro Maschine.

source_method:    <git-branch | git-tag | svn-zip>
source_url:       <URL, von der der Snapshot tatsächlich abgerufen wurde>
source_ref:       <tatsächlich abgerufener Branch / Tag / Version>
fetched_commit:   <aktueller Commit-SHA auf der Festplatte>
fetched_at:       <ISO-8601-Zeitstempel>

Die Driftprüfung bei jedem Framework-Skill-Aufruf vergleicht diese mit <committed-lock> und zeigt jede Abweichung als einen vorgeschlagenen /magpie-setup upgrade an.

Detaildateien in diesem Verzeichnis

Datei	Zweck
adopt.md	Erste Übernahme – erkennen, ob Snapshot vorhanden oder Bootstrap nötig, die zwei Lockdateien schreiben, den Benutzer fragen, welche Skill-Familien verkabelt werden sollen, die gitignorierten Symlinks erstellen, .apache-magpie-overrides/ einrichten, den Post-Checkout-Hook installieren, Projektdokumentation aktualisieren. Die Standard-Unteraktion.
upgrade.md	Das gitignorierte Snapshot gemäß dem committeten Lock aktualisieren, alle agentischen Überschreibungen + Symlinks mit der neuen Framework-Struktur abgleichen, Konflikte sichtbar machen. Treibt den Drift-Behebungs-Workflow an.
verify.md	Schreibgeschützter Gesundheitscheck – Snapshot vorhanden + intakt, beide Lockdateien synchron, Symlinks zeigen auf lebende Ziele, .gitignore korrekt, .apache-magpie-overrides/ vorhanden, Drift-Status (committet vs. lokal), das setup-Skill selbst ist aktuell.
agents.md	Das Agenten-Ziel-Register – welche Verzeichnisse Framework-Skill-Symlinks bei verschiedenen Anbietern landen, und das kanonisch-plus-Relay-Modell: .agents/skills/ ist der eine kanonische Ort (Links in das Snapshot/Quellverzeichnis); jedes andere Ziel (claude-code, github, Holdout-Natives wie Windsurf / Goose) erhält einen pro Skill Relay-Symlink in .agents/skills/. Definiert die aktive Zielauswahl, SKILL.md-Formatportabilität und den Claude-Code-only-Layer (Sandbox/Hooks). Die Quelle der Wahrheit, die jede Unteraktion für die Zielmenge konsultiert.
overrides.md	Verwaltung agentischer Überschreibungsdateien – eine Überschreibung für ein Framework-Skill öffnen / erstellen, vorhandene Überschreibungen auflisten, Hilfe beim Abgleichen, wenn das Framework die zugrunde liegende Skill-Struktur bei einem Upgrade ändert.
unadopt.md	Die Übernahme rückgängig machen – Snapshot, Locks, Symlinks, Post-Checkout-Hook, .gitignore-Einträge, die Übernahmeabschnitte in README.md / AGENTS.md / CONTRIBUTING.md und das committete setup-Skill selbst entfernen. Behält .apache-magpie-overrides/ standardmäßig bei; --purge-overrides entfernt es ebenfalls. Zeigt den vollständigen Entfernungsplan vor jedem Schreibvorgang an.

Goldene Regeln

Goldene Regel 1 – niemals das Snapshot ändern. Das <snapshot-dir> ist ein Build-Artefakt, gitignoriert und aus Sicht des Übernehmers schreibgeschützt. Jede Änderung, die ein Übernehmer wünscht, muss in .apache-magpie-overrides/ erfolgen (wo sie committet wird und das nächste upgrade überlebt). Das Skill sowie jedes andere Framework-Skill, das zur Laufzeit Überschreibungen konsultiert, schreibt niemals in <snapshot-dir>.

Goldene Regel 2 – <committed-lock> ist der Pin des Projekts; <local-lock> ist die maschinenbezogene Wahrheit. Sie dienen unterschiedlichen Zwecken und leben an unterschiedlichen Orten:

• <committed-lock> deklariert, welche Version das Projekt verwendet. Bearbeitet von dem Übernehmer, der zuerst /magpie-setup adopt ausführt (oder später /magpie-setup upgrade ausführt und den neuen Pin akzeptiert). Das Erhöhen ist eine bewusste Aktion auf Projektebene; die Erhöhung zeigt sich im git diff des PRs, der sie vorgeschlagen hat.
• <local-lock> zeichnet auf, was diese Maschine installiert hat. Wird stillschweigend von /magpie-setup adopt und /magpie-setup upgrade aktualisiert. Pro Entwickler, pro Checkout, pro Worktree.

Goldene Regel 3 – Abweichung wird sichtbar, Abweichung wird behoben. Jedes Framework-Skill (und /magpie-setup verify) prüft <committed-lock> gegen <local-lock> zu Beginn seiner Ausführung. Bei einer Abweichung zeigt das Skill die Lücke an und schlägt /magpie-setup upgrade vor. Der Benutzer akzeptiert oder verschiebt; falls er akzeptiert, führt upgrade Folgendes aus:

1. Löscht <snapshot-dir> vollständig.
2. Installiert gemäß dem committeten Lock neu (die neue Version, die das Projekt gewählt hat).
3. Aktualisiert die gitignorierten Framework-Skill-Symlinks – fügt alle neuen Framework-Skills hinzu, die die Familienauswahl des Benutzers abdeckt, entfernt alle Framework-Skills, die umbenannt oder entfernt wurden.
4. Gleicht agentische Überschreibungen mit der neuen Framework-Struktur ab (zeigt Konflikte an; überschreibt niemals automatisch).
5. Aktualisiert <local-lock> auf den neuen Abruf.

Goldene Regel 4 – .gitignore hält das übernehmende Repository sauber. Drei Dinge werden im übernehmenden Repository gitignoriert:

• <snapshot-dir> (das gesamte Framework-Snapshot – möglicherweise Gigabyte groß).
• <local-lock> (maschinenbezogener Zustand).
• Die magpie-*-Symlinks, die setup adopt in jedem aktiven Ziel- Verzeichnis erstellt – die kanonischen in .agents/skills/ (sie zielen auf das gitignorierte Snapshot) und die Relays in .claude/skills/ / .github/skills/ / Holdouts (sie zielen auf die kanonischen Einträge) – beide würden in einem frischen Klon baumeln. Die einzige Ausnahme, die in jedem Verzeichnis nicht ignoriert wird, ist magpie-setup.

Committet: Dieses Skill (setup, als kanonisches .agents/skills/magpie-setup/ plus seine Relays), das <committed-lock>, das Verzeichnis .apache-magpie-overrides/, die .gitignore-Einträge selbst, alle Projekt-Dokumentations- aktualisierungen, die die Sub-Aktion adopt vornimmt.

Goldene Regel 5 – .agents/skills/ ist kanonisch; alles andere leitet nur hinein. Unabhängig davon, wie ein übernehmendes Projekt zuvor sein .claude/skills/ oder .github/skills/ organisiert hat, verkabelt adopt das Framework immer auf die gleiche Weise: die kanonischen magpie-*-Links leben in .agents/skills/, und jedes andere aktive Ziel (.claude, .github, Holdouts) erhält pro Skill Relay-Symlinks, die auf die kanonischen Einträge zurückzeigen (.claude/skills/magpie-<n> → ../../.agents/skills/magpie-<n>). Die eigenen nativen (nicht-magpie-) Skills des Übernehmers in diesen Verzeichnissen bleiben unberührt. Siehe agents.md.

Goldene Regel 6 – dieses Skill kopieren, den Rest verlinken; alle unter dem magpie--Präfix. Dieses Skill (Quelle skills/setup/) ist das einzige Framework-Skill, das kopiert in ein übernehmendes Repository wird – committet als das kanonische .agents/skills/magpie-setup/, mit committeten Relay-Symlinks zu ihm von .claude/skills/magpie-setup und .github/skills/magpie-setup. Alle anderen Framework-Skills sind verlinkt (kanonischer Link in das gitignorierte Snapshot, plus Relays), jeweils benannt magpie-<framework-skill> (z. B. magpie-security-issue-import → <snapshot-dir>/skills/security-issue-import/). Das magpie--Präfix namensräumt jedes Framework-Skill, sodass es niemals mit den eigenen Skills des Übernehmers kollidiert. Das Mischen von Kopie und Symlink – z. B. das Kopieren eines Sicherheits-Skills – erzeugt ein Wartungsrisiko: Kopien driften von der Quelle der Wahrheit des Frameworks ab, und der Drifterkennungsmechanismus (der annimmt, dass die Framework-Version diejenige in <snapshot-dir> ist) wird stillschweigend falsch angewendet.

Goldene Regel 7 – agentische Überschreibungen werden zur Laufzeit gelesen. Jedes Framework-Skill, das Überschreibungen unterstützt, beginnt seine Ausführung mit der Prüfung von .apache-magpie-overrides/<dieses-skill>.md auf übernehmerspezifische Anweisungen und wendet diese an, bevor es das Standardverhalten ausführt. Die Überschreibungsdatei ist reines Markdown, das der Agent interpretiert – keine Template-Engine, kein Patch-Tool. Siehe docs/setup/agentic-overrides.md für den Vertrag.

Goldene Regel 8 – zwei Familien werden immer installiert; die übrigen sind Opt-In. Zwei Skill-Familien werden bei jeder Übernahme / Aktualisierung / Worktree-Initialisierung bedingungslos verkabelt, und der Benutzer wird nie danach gefragt:

• setup-* – jedes Framework-Skill, dessen Quellname mit setup- beginnt, mit Ausnahme des Bootstraps setup selbst (das gemäß Regel 6 als magpie-setup kopiert wird, nicht verlinkt). Konkret: setup-isolated-setup-install, setup-isolated-setup-update, setup-isolated-setup-verify, setup-override-upstream, setup-shared-config-sync, plus jedes neue setup-*-Skill, das das Framework in Zukunft entwickeln wird – jeweils verlinkt als magpie-setup-*.
• list-* – die Entdeckungsfamilie; jedes Framework-Skill, dessen Quellname mit list- beginnt. Heute ist dies nur list-skills (verlinkt als magpie-list-skills); das Präfix ermöglicht es dem Framework, ein di

…

[gekürzt für die Übersetzung]