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.

graph LR
    A[Repo A<br/>Verbesserungen] -->|Git-History| E[Extraction]
    E -->|raw-mutations| D[Distillation]
    D -->|Growth Vectors| P[Propagation]
    P -->|Patches| B[Repo B<br/>aktualisiert]

---

Begriffe

graph TD
    G[🧬 Genome<br/>Gesamtheit aller Traits] --> T1[Trait: Skill]
    G --> T2[Trait: Agent]
    G --> T3[Trait: Prompt]
    G --> T4[Trait: Instructions]
    T1 -->|Git-Delta| M1[Mutation]
    T3 -->|Git-Delta| M2[Mutation]
    M1 -->|destilliert| GV1[Growth Vector<br/>Score 8/10 🟡]
    M2 -->|destilliert| GV2[Growth Vector<br/>Score 9/10 🔴]
    GV1 --> PR[Propagation<br/>Konkrete Patches]
    GV2 --> PR

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
• .github/*.instructions.md

---

Trait-Erkennung

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

graph TD
    F[Dateipfad] --> S{Pfad-Pattern?}
    S -->|.github/skills/X/...| SK["skill/X"]
    S -->|.github/agents/X.agent.md| AG["agent/X"]
    S -->|.github/prompts/X.prompt.md| PM{Verbund?}
    S -->|.github/*.instructions.md| IN["instructions/X"]
    PM -->|"X-*.prompt.md existiert"| VB["prompt/X<br/>(Verbund)"]
    PM -->|Keine Sub-Prompts| SA["prompt/X<br/>(Standalone)"]

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

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-planning.prompt.md        → trait: prompt/nextstep
.github/prompts/nextstep-tech-decision.prompt.md   → trait: prompt/nextstep

Verbund-Erkennung: Eine Datei <name>.prompt.md ist ein Router, wenn Dateien <name>-*.prompt.md im selben Verzeichnis existieren. Alle 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
.github/kotlin-conventions.instructions.md → trait: instructions/kotlin-conventions

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

---

Mutation-Typen

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

---

Pipeline

flowchart LR
    subgraph "Phase 1: Extraction"
        direction TB
        GIT[(Git-History)] --> SCRIPT[genome-extract.py]
        SCRIPT --> RAW[raw-mutations.md]
    end
    subgraph "Phase 2: Distillation"
        direction TB
        RAW2[raw-mutations.md] --> AGENT1[KI-Agent]
        AGENT1 --> |"Klassifizieren\nScoren\nSanitizen"| DIST[distilled-mutations.md]
    end
    subgraph "Phase 3: Propagation"
        direction TB
        DIST2[distilled-mutations.md] --> AGENT2[KI-Agent]
        ZIEL[Ziel-Genome] --> AGENT2
        AGENT2 --> PATCHES[Konkrete Patches]
    end
    RAW --> RAW2
    DIST --> DIST2

Phase 1: Extraction (Script)

Input: Repo-Pfad + Zeitspanne (z.B. --since "7 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.py (Python)

Phase 2: Distillation (Agent)

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

flowchart TD
    M[Mutation] --> K{Klassifizierung}
    K -->|Bugfix für alle| C[🔴 Critical]
    K -->|Generelle Verbesserung| E[🟡 Evolution]
    K -->|Nur dieses Projekt| S[⚪ Specialized]
    C --> SC[Score 1–10]
    E --> SC
    S --> X[❌ Entfernt]
    SC --> SAN[Sanitization<br/>Pfade, Tokens, IDs ersetzen]
    SAN --> |Score ≥ 4| OUT[→ distilled-mutations.md]
    SAN --> |Score < 4| X

• Scored jede Mutation (1–10) nach Übertragungswert
• 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 Output: propagation-proposals.md

• Matched Traits zwischen Quell- und Ziel-Genome
• Erstellt konkrete Änderungsvorschläge pro Trait
• Formatiert als Checkliste mit Default-Auswahl:

Kategorie	Default	Bedingung
🔴 Critical	✅ an	immer
🟡 Evolution ≥ 7	✅ an	Score ≥ 7
🟡 Evolution < 7	❌ aus	Score < 7
⚪ Specialized	—	gefiltert

Tool: genome-propagate.prompt.md

---

Zeitbasierte Transferlogik

sequenceDiagram
    participant R as Quell-Repo
    participant T as Ziel-Repo
    Note over T: Letzter .github/-Commit = T_target
    R->>R: git log --since T_target
    R->>R: 12 Commits an .github/ gefunden
    R-->>T: Mutations extrahiert → Distillation → Propagation

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

---

Dateistruktur

graph TD
    subgraph ".github/skills/genome/"
        SK[SKILL.md<br/>Skill-Dokumentation]
        EX[genome-extract.py<br/>Phase 1 Script]
    end
    subgraph ".github/prompts/"
        OR[genome.prompt.md<br/>Orchestrator]
        DI[genome-distill.prompt.md<br/>Phase 2]
        PR[genome-propagate.prompt.md<br/>Phase 3]
    end
    subgraph ".github/genome/output/"
        RM[raw-mutations.md<br/>generiert]
        DM[distilled-mutations.md<br/>generiert]
        PP[propagation-proposals.md<br/>generiert]
    end
    subgraph "docs/"
        CO[genome-engine.md<br/>Dieses Konzept]
    end
    OR -->|"ruft auf"| EX
    OR -->|"delegiert an"| DI
    OR -->|"delegiert an"| PR
    EX -->|"schreibt"| RM
    DI -->|"liest"| RM
    DI -->|"schreibt"| DM
    PR -->|"liest"| DM
    PR -->|"schreibt"| PP

#	Datei	Typ	Ort
1	genome-extract.py	Python Script	.github/skills/genome/
2	genome.prompt.md	Orchestrator	.github/prompts/
3	genome-distill.prompt.md	Prompt	.github/prompts/
4	genome-propagate.prompt.md	Prompt	.github/prompts/
5	SKILL.md	Skill-Doku	.github/skills/genome/
6	genome-engine.md	Konzept	docs/
7	raw-mutations.md	Generiert	.github/genome/output/
8	distilled-mutations.md	Generiert	.github/genome/output/
9	propagation-proposals.md	Generiert	.github/genome/output/

Generierte Dateien (7–9) sind gitignored.

---

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"