bollwerk/docs/genome-engine.md

Genome Engine – Konzept

Ziel

Automatische Erkennung evolutionärer Verbesserungen an Copilot-Customization-Dateien (Skills, Agents, Prompts, Instructions) über Git-History hinweg. Die erkannten Verbesserungen werden destilliert, bewertet und als Propagation-Vorschläge für andere Projekte bereitgestellt.

---

Begriffe

Begriff	Bedeutung
Trait	Ein Skill, Agent, Prompt(-Verbund) oder Instructions-File inkl. aller zugehörigen Dateien
Genome	Die Gesamtheit aller Traits eines Projekts
Mutation	Ein Git-Commit-Delta an einem Trait (siehe Mutation-Typen)
Growth Vector	Destillierte, bewertete Mutation (bereinigt, klassifiziert, gescored)
Propagation	Konkreter Änderungsvorschlag für ein Ziel-Genome

---

Scope

Folgende Pfade bilden das Genome:

• .github/skills/**
• .github/agents/**
• .github/prompts/**
• .github/copilot-instructions.md

---

Trait-Erkennung

Traits werden aus dem Dateipfad abgeleitet. Die Granularität hängt vom Trait-Typ ab:

Skills

Ein Skill besteht aus einem Ordner mit mehreren zusammengehörigen Dateien (SKILL.md, Scripte, Templates). Der Ordnername ist der Trait-Schlüssel.

.github/skills/gh-tickets/SKILL.md        → trait: skill/gh-tickets
.github/skills/gh-tickets/queries.graphql  → trait: skill/gh-tickets
.github/skills/android-build/SKILL.md      → trait: skill/android-build
.github/skills/android-build/android-dev.ps1 → trait: skill/android-build

Regel: skill/<ordnername> – alle Dateien im Ordner gehören zum selben Trait.

Agents

Ein Agent besteht aus genau einer Datei. Der vollständige Dateiname (ohne Pfad, ohne Extension) ist der Trait-Schlüssel.

.github/agents/android-implementer.agent.md → trait: agent/android-implementer
.github/agents/code-reviewer.agent.md       → trait: agent/code-reviewer

Regel: agent/<dateiname-ohne-extension> – 1:1-Zuordnung Datei → Trait.

Prompts

Prompts unterscheiden zwei Varianten: Standalone und Verbund.

Standalone-Prompts

Einzeldateien ohne Router-Beziehung. Der Dateiname ist der Trait-Schlüssel.

.github/prompts/commit.prompt.md  → trait: prompt/commit
.github/prompts/ship.prompt.md    → trait: prompt/ship
.github/prompts/publish.prompt.md → trait: prompt/publish
.github/prompts/clean.prompt.md   → trait: prompt/clean

Regel: prompt/<dateiname-ohne-extension> – 1:1-Zuordnung Datei → Trait.

Verbund-Prompts (Router + Sub-Workflows)

Wenn eine Prompt-Datei eine Routing-Tabelle mit Verweisen auf andere .prompt.md-Dateien enthält, bilden Router + referenzierte Dateien einen Trait. Der Router-Name ist der Trait-Schlüssel.

.github/prompts/nextstep.prompt.md                → trait: prompt/nextstep
.github/prompts/nextstep-implementation.prompt.md  → trait: prompt/nextstep
.github/prompts/nextstep-infrastructure.prompt.md  → trait: prompt/nextstep
.github/prompts/nextstep-planning.prompt.md        → trait: prompt/nextstep
.github/prompts/nextstep-block-planning.prompt.md  → trait: prompt/nextstep
.github/prompts/nextstep-tech-decision.prompt.md   → trait: prompt/nextstep
.github/prompts/nextstep-test.prompt.md            → trait: prompt/nextstep

Regel: prompt/<router-name> – Router (<name>.prompt.md) + alle <name>-*.prompt.md-Dateien gehören zum selben Trait.

Begründung: Der gesamte Workflow (Router + Sub-Prompts) ist semantisch eine Einheit (~300 Zeilen). Ein neuer Sub-Workflow ist nur im Kontext des Routers sinnvoll. Bei Propagation muss der Agent immer Router + Sub-Prompts zusammen betrachten.

Verbund-Erkennung (Namenskonvention): Eine Datei <name>.prompt.md ist ein Router, wenn Dateien <name>-*.prompt.md im selben Verzeichnis existieren. Alle <name>-*.prompt.md-Dateien gehören zum selben Verbund-Trait.

Instructions

Instructions-Dateien sind Einzeldateien. Der Dateiname ist der Trait-Schlüssel.

.github/copilot-instructions.md → trait: instructions/copilot-instructions

Regel: instructions/<dateiname-ohne-extension> – 1:1-Zuordnung Datei → Trait.

---

Mutation-Typen

Jede Mutation wird mit einem Typ klassifiziert:

Typ	Bedeutung	Beispiel
content-change	Inhalt einer Datei im Trait geändert	nextstep-implementation.prompt.md optimiert
member-added	Neue Datei zum Trait hinzugefügt	Neuer nextstep-migration.prompt.md + Router-Eintrag
member-removed	Datei aus dem Trait entfernt	nextstep-test.prompt.md gelöscht + Router-Eintrag entfernt

Bei Verbund-Traits umfasst member-added/member-removed immer die betroffene Sub-Datei und die Router-Anpassung als zusammenhängende Mutation. Bei Standalone-Traits und Skills entspricht member-added dem Anlegen einer neuen Datei im Trait-Ordner.

---

Pipeline

Phase 1: Extraction (Script)

Input: Repo-Pfad + Zeitspanne (z.B. --since "4 days ago") Output: raw-mutations.md

• Scannt git log für Änderungen im Genome-Scope
• Gruppiert Diffs nach Trait (siehe Trait-Erkennung oben)
• Gibt pro Trait alle Commits mit Diff, Message und Autor aus

Tool: genome-extract.ps1

Phase 2: Distillation (Agent)

Input: raw-mutations.md Output: distilled-mutations.md

• Klassifiziert jede Mutation:
  • 🔴 Critical – Bugfixes, die andere auch treffen
  • 🟡 Evolution – Generelle Verbesserungen (bessere Prompts, neue Patterns)
  • ⚪ Specialized – Projektspezifisch, nicht übertragbar
• Scored jede Mutation (1–10)
• Filtert sensitive Daten (Usernames, Maschinenpfade, Tokens, projektspezifische IDs)
• Specialized Mutations werden komplett entfernt

Tool: genome-distill.prompt.md

Phase 3: Propagation (Agent)

Input: distilled-mutations.md + Ziel-Genome (.github/ des Ziel-Repos) Output: propagation-proposals.md

• Matched Traits zwischen Quell- und Ziel-Genome
• Erstellt konkrete Änderungsvorschläge pro Trait
• Formatiert als Checkliste:
  • [x] Critical (default an)
  • [x] Evolution mit Score ≥ 7 (default an)
  • [ ] Evolution mit Score < 7 (default aus)
  • Specialized taucht nicht auf (bereits gefiltert)
• User wählt aus, Agent wendet ausgewählte Patches an

Tool: genome-propagate.prompt.md

---

Zeitbasierte Transferlogik

Die Zeitspanne bestimmt, welche Mutations extrahiert werden:

1. Letzter .github/-Commit im Ziel-Repo ermitteln → T_target
2. Alle .github/-Commits im Quell-Repo seit T_target extrahieren
3. Das Delta zwischen T_target und jetzt ist der Evolutionszeitraum

Beispiel: bollwerk hat .github/ zuletzt vor 4 Tagen von hva übernommen. Seitdem gab es 12 Commits an .github/ in bollwerk. Diese 12 Commits sind die Mutations.

---

Deliverables

#	Datei	Typ	Ort
1	genome-extract.ps1	PowerShell Script	.github/genome/
2	genome-distill.prompt.md	Prompt	.github/genome/
3	genome-propagate.prompt.md	Prompt	.github/genome/
4	raw-mutations.md	Generiert	.github/genome/output/
5	distilled-mutations.md	Generiert	.github/genome/output/
6	propagation-proposals.md	Generiert	.github/genome/output/

---

Zukünftige Erweiterungen

• Multi-Repo-Registry: Zentrale Sammlung von Growth Vectors aus vielen Projekten
• Automatische Erkennung des Evolutionszeitraums über Repo-Vergleich
• CI-Integration: Propagation-Check bei jedem Push
• Community-Sharing: Öffentliche Growth Vectors als "Trait Packages"