toyin-software-factory/sync

Ausgabestil (einfache Worte, keine Bindestriche, keine Gedankenstriche)

Schreiben Sie alles, was dieser Skill produziert, Dateien und Nachrichten gleichermaßen, in einfacher, klarer Sprache. Sprechen Sie den Leser als „Sie“ an, warm und direkt wie ein Kollege, und präsentieren Sie jeden Schritt als Empfehlung, die er ausführen oder überspringen kann, niemals als Befehl. Behalten Sie Fachbegriffe bei, die eine echte Bedeutung haben; erklären Sie jeden in einfachen Worten. Verwenden Sie niemals einen Bindestrich oder Gedankenstrich als Satzzeichen: keinen langen Gedankenstrich, keinen kurzen Gedankenstrich und keine zusammengesetzten Wörter mit Bindestrich. Schreiben Sie „read only“, nicht „read-only“. Sagen Sie es in einfachen Worten oder formulieren Sie den Satz um. Code, Dateipfade, Befehlsflags und Werte, auf die andere Skills abstimmen, behalten ihre Bindestriche. Verwenden Sie kurze Sätze, Kommas oder Klammern. Klarheit ist besser als Cleverness.

Was dieser Skill tut

Schließt den Kreislauf einer abgeschlossenen Änderung: synchronisiert AGENTS.md-Dateien, den Umfang (Scope) und die damit verbundenen **Status**:-Zeilen von Spezifikationen mit dem, was das Repository jetzt zeigt, und kennzeichnet, was nicht bearbeitet werden darf (veraltete Spezifikationen, kuratierte Prosa). Die folgende Tabelle „Grenzen“ ist der genaue Vertrag.

agent-prompt.md ist die einzige Quelle der Wahrheit für die Wartungsregeln; SKILL.md deckt nur die Orchestrierung ab. Der Hauptthread liest sie und führt die Wartung selbst durch (siehe Schritt 3).

Kanonische Datei: dauerhafter Kontext lebt in der toolagnostischen AGENTS.md; CLAUDE.md ist nur ein Verweis darauf. /sync bearbeitet/erstellt beide, behandelt sie jedoch nur als Ziele, niemals als Quelle einer Änderung.

Grenzen

Aktion	/sync	Eigentümer
Vorhandene root/verschachtelte AGENTS.md bearbeiten	✅ pflegt	/sync
Die Zeile ## Build approach der root AGENTS.md mit dem Ansatz des Scope-Headers abgleichen (chirurgische Einzelzeilenbearbeitung, wie der Stack)	✅ pflegt; kennzeichnet eine kuratierte Abweichung	/sync
Eine einzeilige Verweiszeile auf design.md (das UI-Designsystem) in der nächsten AGENTS.md hinzufügen, wenn eine Änderung eines etabliert	✅ pflegt (nur Verweis)	/sync
Verschachtelte <bereich>/AGENTS.md für einen Bereich erstellen, der in dieser Änderung neu ist	✅ erstellt (Diff = voller Bereichskontext) + fügt root-Verweis hinzu	/sync
Verschachteltes Dokument für einen bereits vorhandenen undokumentierten Bereich erstellen (nur durch den Diff aufgeschnitten)	❌ kennzeichnet „/audit ausführen“	/audit
Die root AGENTS.md erstellen oder umstrukturieren	❌ kennzeichnet „/audit ausführen“	/audit
Die **Status**:-Zeile einer Spezifikation mit dem Scope-Status ihres Features abgleichen (planned→Proposed, in-progress→In Progress, done→Accepted; eine Assumed-Spezifikation ist die Ausnahme: belassen Sie sie als Assumed und zeigen Sie sie an, gleichen Sie sie niemals auf Accepted ab)	✅ Nur Statuszeile	/sync
Eine Assumed-Spezifikation löschen (aus Assumed entfernen)	❌ kennzeichnet als Entscheidungsschuld „/architect zur Ratifizierung ausführen“ (wird niemals auf den Feature-Status abgestimmt; nur die Ratifizierung löscht sie)	/architect
Inhalt einer Spezifikation bearbeiten / sie ersetzen	❌ kennzeichnet als veraltet	/architect
Den Umfang (Scope) für die relevante Arbeitsbereichs-Scope-Datei abgleichen (nicht alle docs/scope/), beliebige abgeschlossene Unteraufgabe aus Repository-Beweisen (Code, Tests, AGENTS.md) anhaken, Status vorrücken	✅ korrigiert	/sync
Features oder Unteraufgaben im Scope hinzufügen/neu anordnen	❌ unverändert lassen	/scope
Kuratierte AGENTS.md-Prosa überschreiben oder umschreiben	❌ kennzeichnet stattdessen einen Konflikt	Mensch

Die Trennlinie bei der Erstellung ist Kontext, nicht Richtlinie: erstellen Sie nur, wenn diese Änderung Ihnen den gesamten Bereich zeigt; delegieren Sie an /audit, wenn der Bereich vor der Änderung existiert und Sie nur einen Ausschnitt gesehen haben. Wenn Sie unsicher sind, kennzeichnen Sie es anstatt zu erstellen.

Bitten vs. Handlungen

Handlungen. Hält nur an, wenn es nichts zu synchronisieren gibt (leerer Änderungssatz). Jede Bearbeitung kuratierter Dateien wird im Bericht aufgelistet, damit Sie sie überprüfen oder rückgängig machen können.

Artefakt-Eigentum

Besitzt genau das, was die Tabelle „Grenzen“ gewährt, und schreibt nichts anderes. Als universeller Unteraufgaben-Abgleicher hakt es jede Scope-Unteraufgabe ab, die es aus Repository-Beweisen überprüfen kann (durchläuft die /test//audit//sync Unteraufgaben, die andere Skills nicht abhaken) und rückt den Feature-Status vor; genaue Regeln in agent-prompt.md.

Artefakt-Basis. Spezifikationen und der Scope befinden sich standardmäßig unter docs/ oder .workflow/, wenn docs/ eine veröffentlichte Dokumentationsseite ist; verwenden Sie die Basis, die im Repository existiert (Pfade hier gehen von docs/ aus).

---

Portabilität (jedes Betriebssystem, jeder Agent)

• Befehle: git ist das einzige erforderliche CLI und verhält sich auf jedem Betriebssystem gleich; führen Sie die git-Zeilen wie gezeigt aus. Andere Shell-Ausschnitte sind POSIX-Referenzen, keine wörtlichen Skripte: gehen Sie nicht davon aus, dass find, grep, sed, cat, test/[ ], ls oder xargs existieren; verwenden Sie die plattformübergreifenden Dateiwerkzeuge Ihres Agenten und wenden Sie Verzweigungslogik selbst an, anstatt Shell-if/Variablen/Umleitungen.
• Mitgelieferte Dateien: werden durch Pfade relativ zum Ordner dieses Skills referenziert. Lösen Sie den Ordner in einen absoluten Pfad auf (Sie lösen diese relativen Pfade bereits auf) und lesen Sie agent-prompt.md zum Schreibzeitpunkt selbst (Schritt 3), nicht während der früheren Schritte.
• Die gesamte Wartung erfolgt inline auf dem Hauptthread, wobei die genauen Regeln in agent-prompt.md (maßgeblich) befolgt werden.

Ausführung

1. Änderungssatz eingrenzen (günstig, mit Dateistatus pro Datei)

Aktualität zuerst (Teams): git fetch --quiet; wenn git rev-list --count HEAD..origin/$BASE > 0 sind Sie hinter origin/$BASE zurück, warnen Sie den Entwickler, zuerst zu pullen, ein Teammitglied hat diese Dokumente möglicherweise bereits synchronisiert.

Basis: main, wenn git rev-parse --verify main erfolgreich ist, sonst master. Aktueller Branch: git rev-parse --abbrev-ref HEAD. Verwenden Sie --name-status (nicht --name-only); die Logik für neue Bereiche und Bereinigung verwaister Dateien benötigt pro Datei den Status Hinzugefügt vs. Geändert vs. Gelöscht.

• Der aktuelle Branch ist die Basis, Modus uncommitted: git diff --name-status HEAD.
• Andernfalls, Modus branch: git merge-base "$BASE" HEAD, dann git diff --name-status <merge-base>.

Fügen Sie in beiden Fällen unverfolgte Dateien aus git ls-files --others --exclude-standard hinzu, jede mit einem vorangestellten A-Status (passend zum --name-status-Format). Notieren Sie sich den Modus, die Basis und die Merge-Basis für den Schreibschritt.

Entfernen Sie Duplikate, dann filtern Sie auf Quelldateien, um von ihnen zu synchronisieren:

• Dokumentation und Konfiguration entfernen (AGENTS.md auf jeder Ebene, docs/**, *.md, test-preferences.json, Sperrdateien, generierte Ausgaben); /sync liest diese als Ziele/Kontext, niemals als Änderungsquelle.
• Testdateien entfernen (*.test.*, *.spec.*, __tests__/, usw.); Tests sind keine dauerhaften Bereichskonventionen.
• Behalten Sie die D (gelöscht) Einträge in einer separaten Liste; sie treiben die Bereinigung verwaister Dateien an (Schritt 3), obwohl nicht von ihnen synchronisiert wird.
• Behalten Sie Änderungen an Abhängigkeitsmanifesten in einer separaten Liste für die Tool-Entdeckung, auch wenn es sich um Konfiguration und nicht um Quellcode handelt: package.json, pyproject.toml, requirements*.txt, go.mod, Cargo.toml, composer.json, Gemfile, pubspec.yaml, mix.exs, *.csproj und gleichwertige Paketmanifeste. Sperrdateien sind nur Signale; übergeben Sie keine Sperrdateiinhalte.

Wenn keine Quelldateien und keine Abhängigkeitsmanifeständerungen übrig bleiben (nur Dokumente/Tests/Sperrdateien/generierte Dateien geändert), anhalten, nichts zu synchronisieren. Nicht starten.

2. Kontextdateien und Spezifikationen lokalisieren (nur Pfade, sie hier NICHT lesen)

Verwenden Sie die Dateisuche/Glob-Werkzeuge Ihres Agenten:

• Notieren Sie, ob eine root AGENTS.md existiert.
• Finden Sie jede AGENTS.md (root + verschachtelt), unter Ausschluss von node_modules/ und .git/.
• Finden Sie alle Spezifikationen unter docs/specs/, deren Namen mit einer Ziffer beginnen, sortiert.
• Finden Sie die Scope-Datei(en), deren Arbeitsbereich/Features der Diff tatsächlich berührt (in einem Monorepo wählt der Arbeitsbereich einer geänderten Datei apps/<x>/… den Pfad docs/scope/<x>/); lesen oder übergeben Sie niemals alle docs/scope/.

Notieren Sie die Pfade sowie die geänderte Dateiliste und den Diff-Befehl; lesen Sie die Dateien zum Schreibzeitpunkt. Lesen Sie den Inhalt der root AGENTS.md jetzt (kurz und nützlich zur Orientierung). Notieren Sie für jede geänderte Datei das nächstgelegene umschließende Verzeichnis mit einer AGENTS.md (root oder verschachtelt); das ist die Kontextdatei, die höchstwahrscheinlich aktualisiert werden muss.

2.5 Agent Skills und optionale MCPs für neu hinzugefügte Tools entdecken

Nur ausführen, wenn sich Abhängigkeitsmanifeste geändert haben oder der Diff eindeutig ein bedeutendes externes Tool hinzufügt. Überspringen Sie gewöhnliche Hilfsbibliotheken, es sei denn, sie definieren einen dauerhaften Workflow oder eine Integration.

• Identifizieren Sie neu hinzugefügte bedeutende Pakete/Tools aus dem Manifest-Diff, nicht aus der vollständigen Sperrdatei: Framework, Router, Styling-/UI-Kit, Datenbank, ORM/Abfrageschicht, Authentifizierung/Session, Zahlungen, E-Mail/Benachrichtigungen, Speicher/Uploads, Suche, Warteschlange/Hintergrundjobs, KI-Anbieter/Vektor-DB, Browser/Laufzeit-Tests, Observability, Hosting/Deploy. Fügen Sie Paketnamen und gebräuchliche Aliasnamen aus Manifesten hinzu. Hören Sie nicht nach der ersten Technologie auf.

• Filtern Sie alles heraus, was bereits durch installierte Skills, verbundene MCPs oder abgelehnte Einträge in AGENTS.md abgedeckt ist.

• Fragen Sie vor der Suche.

  Das Fragen ist obligatorisch. Das Suchen nicht. Es wird nichts gesucht, geholt, installiert oder gestartet für die Agent Skill- und MCP-Entdeckung, bis der Entwickler eine Auswahl getroffen hat. Bieten Sie vier Optionen an: Suche sie für mich, ich nenne die gewünschten, nein und die Ablehnung aufzeichnen, oder jetzt nicht. Nur die erste Option darf einen Suchbefehl ausführen. Überspringen Sie das Angebot niemals stillschweigend und führen Sie niemals eine Suche durch, bevor der Entwickler einer zugestimmt hat.

  Nennen Sie die Tools, die diese Änderung hinzugefügt hat, sagen Sie in einem Satz, dass ein Agent Skill dem Agenten die tatsächlichen Konventionen dieses Tools gibt und ein MCP-Server ihm Live-Zugriff auf das reale System verschafft, und fragen Sie dann: „Soll ich Agent Skills und MCP-Server für die Tools suchen, die diese Änderung hinzugefügt hat?“ (Überschrift Agent skills), mit Ja, suche sie für mich (empfohlen) · Ich nenne die gewünschten · Nein, überspringen · Jetzt nicht, später. Bei Ja fahren Sie unten fort. Bei Ich nenne die gewünschten nehmen Sie die Liste und gehen Sie direkt zum Installationsschritt, ohne etwas zu suchen. Bei Nein, überspringen führen Sie nichts aus und zeichnen die Ablehnung auf. Bei Jetzt nicht, später führen Sie nichts aus und notieren die Kandidaten-Tools im Bericht.

• Isolieren Sie die Suchen in einem schreibgeschützten Unter-Agenten (Funktionalität zuerst, nur nach Ja). Übergeben Sie den verbleibenden Satz an einen Entdeckungs-Unter-Agenten, anstatt auf dem Hauptthread zu suchen: starten Sie ihn im Hintergrund (er blockiert nicht), wenn Ihr Agent das unterstützt, sonst blockierend; setzen Sie sein Modell explizit auf eine schnelle, kostengünstige Stufe (übernehmen Sie nicht das Sitzungsmodell; starten Sie ihn bei Claude Code als Unter-Agent-Typ researcher, der das Modell festlegt); er gibt nur die kompakte Kandidatenliste zurück. Dies hält die Suchausgabe aus dem begrenzten Kontext von /sync heraus. Kein Unter-Agent → Suche inline; keine Suchmöglichkeit → überspringen und notieren. Das Auswahlfeld bleibt auf dem Hauptthread.

• Führen Sie für jedes verbleibende Element npx skills find <tool-or-package> aus; wenn schwach, wiederholen Sie Aliasnamen aus Paket-/Organisationsnamen. Sammeln Sie jeden glaubwürdigen Agent Skill-Kandidaten und bestätigen Sie mit npx skills add <inhaber>/<repo> --list, wenn praktikabel. Wenn die CLI interaktiv/nicht verfügbar ist, suchen Sie "<tool>" "agent skill" und bestätigen Sie vor dem Angebot.

• Die MCP-Suche ist optional: zuerst die Connector-Liste, sonst "<tool>" "MCP server" pro Element. MCP ist empfohlene Verbesserung, nicht erforderlich.

• Halten Sie die Entdeckung gedeckelt und cachefähig: maximal 5 Websuchen und 8 abgerufene Seiten insgesamt, zuerst offizielle Dokumentation/Dokumente. Verwenden Sie docs/.agent-cache/tool-discovery/<slug>.md wieder, wenn es jünger als 30 Tage ist, nachdem installierte/abgelehnte Elemente herausgefiltert wurden.

• Bieten Sie alle Agent Skill-Treffer in einem Multi-Auswahl-Panel an, gruppiert nach Technologie: „Relevante Agent Skills für neu hinzugefügte Tools installieren?“ plus überspringen/ablehnen. Bieten Sie dann MCPs separat an: „Optionale MCP-Server, die diesen Tools helfen könnten“ plus überspringen/ablehnen. Niemals automatisch installieren oder verbinden.

• Installieren Sie ausgewählte Skills mit npx skills add <inhaber>/<repo> -y. Für MCPs verweisen Sie auf die Connector/MCP-Einstellungen des Benutzers; sobald verbunden, werden die Tools automatisch verwendet.

• Tragen Sie das Ergebnis als INSTALLED_SKILLS_OR_NONE, MCP_SERVERS_OR_NONE und DECLINED_TOOLS_OR_NONE und zeichnen Sie dauerhafte Zeilen in der richtigen AGENTS.md Datei auf, wenn Sie schreiben. Wenn nichts gefunden wurde oder keine Fähigkeit existiert, behandeln Sie als none.

3. Wartung durchführen (Hauptthread)

Der Hauptthread führt die Wartung selbst durch; er übergibt die AGENTS.md-/Scope-/Spezifikationsstatus-Bearbeitungen niemals an einen Unter-Agenten. Lesen Sie agent-prompt.md jetzt (erst jetzt, zum Schreibzeitpunkt) und befolgen Sie es genau; es ist maßgeblich für die Wartungsregeln. Das Lesen des Diffs ist die einzige Sache, die Sie auslagern dürfen, und nur für einen großen Änderungssatz, an einen schreibgeschützten scout-Unter-Agenten mit dem günstigsten Modell (Claude Code: haiku), der eine kompakte Zuordnung zurückgibt. Bleiben Sie innerhalb derselben Grenzen, die die alte Tool-Berechtigung ausdrückte: Edit vorhandene Docs, Scope und Spezifikations-**Status**:-Zeilen; Write streng für eine neue Bereichs-verschachtelte AGENTS.md; keine root-Erstellung, keine Spezifikations-Inhalts-Bearbeitungen (nur Statuszeile), keine flachen verschachtelten Docs für etablierte Bereiche (dies sind Regeln in agent-prompt.md).

Die anzuwendenden Eingaben:

1. MODE, BASE, MERGE_BASE, CHANGED_FILES (Namensstatus geänderte Quellliste), DIFF_COMMAND (exakter git diff Befehl)
2. DELETED_PATHS (gelöschte Pfade, zur Bereinigung verwaister Dateien)
3. ROOT_AGENTS_MD (Inhalt der root AGENTS.md), NESTED_PATHS (Pfade verschachtelter AGENTS.md)
4. SPEC_PATHS (alle Spezifikationspfade, zur Abgleichung der Statuszeile und Kennzeichnung von Veraltetem)
5. FILE_TO_CONTEXT_MAP (geänderte Datei → nächste Kontextdatei)
6. SCOPE_PATH_OR_NONE (relevante Arbeitsbereichs-Scope-Pfade, nicht alle docs/scope/; auch die Quelle des Status jedes verknüpften Features zur Abgleichung der Spezifikationsstatuszeile)
7. INSTALLED_SKILLS_OR_NONE, MCP_SERVERS_OR_NONE, DECLINED_TOOLS_OR_NONE aus Schritt 2.5

4. Das Ergebnis übermitteln

Wenn die Wartung fehlgeschlagen ist oder keine auswertbare Zusammenfassung erstellt hat, melden Sie dies und führen Sie sie erneut aus, erfinden Sie kein Ergebnis (ein echtes NOTHING_TO_SYNC ist ein gültiger Erfolg; ein Absturz oder eine leere Ausgabe nicht). Übermitteln Sie andernfalls die kompakte Zusammenfassung:

Beginnen Sie mit dem, was es in einer Zeile abgeglichen hat; listen Sie dann nur das auf, was den Entwickler benötigt (gemäß docs/conventions.md). Die Bearbeitungen selbst befinden sich in den Dateien. Vorlage:

## /sync abgeschlossen · <N> geänderte Dateien abgeglichen

**<AGENTS.md-Dateien · Scope-Features · Spezifikationsstatus> aktualisiert, um sie an den Diff anzupassen.**   (oder „alles bereits aktuell, nichts zu synchronisieren“)
Hinweise (Sie sind gefragt):
- Veraltete Spezifikation → /architect: `<datei>` (<warum, oder eine Statusabweichung, die /sync nicht sicher beheben konnte)
- …

**Installierte Skills verwenden:** … (wenn neue Skills/MCPs installiert/verbunden wurden, oder „keine“)

Nur die Dateien im Diff und die Spezifikationen im Status, die /sync aktualisiert hat, sind hier aufgelistet. Listen Sie keinen Inhalt auf, den /sync nicht angerührt hat, und listen Sie nichts auf, das die ausgegebenen Dateien verdoppelt.

5. Entdeckte Skills/MCPs anwenden (Schritt 2.5 Ergebnis)

Zeichnen Sie INSTALLED_SKILLS_OR_NONE, MCP_SERVERS_OR_NONE und DECLINED_TOOLS_OR_NONE im Abschnitt ## Agents & tools der root AGENTS.md auf. Wenn nichts gefunden wurde, kein Eintrag. Wenn abgelehnt wurde, fügen Sie unter ## Agents & tools - <tool> → declined (als nicht relevant beschlossen) hinzu.

Die Skills-Installation selbst hat bereits stattgefunden (durch die Skripte in node_modules/.bin/), und MCPs wurden vom Benutzer verbunden.