bollwerk/.github/genome/Concept Genome Engine.md

Genome Engine – Konzept

Ziel

Automatische Erkennung von Verbesserungen an KI-Tooling-Dateien (Skills, Agents, Prompts, Instructions) über Git-History hinweg. Die erkannten Improvements werden destilliert, bewertet und als Transfer-Vorschläge für andere Projekte bereitgestellt.

graph LR
    A[Repo A<br/>Verbesserungen] -->|Git-History| E[Extraction]
    E -->|raw improvements| D[Distillation]
    D -->|Insights| T[Transfer]
    T -->|Patches| B[Repo B<br/>aktualisiert]

---

Begriffe

graph TD
    G[🧬 Genome<br/>Gesamtheit aller Capabilities] --> T1[Capability: Skill]
    G --> T2[Capability: Agent]
    G --> T3[Capability: Prompt]
    G --> T4[Capability: Instructions]
    T1 -->|Git-Delta| M1[Improvement]
    T3 -->|Git-Delta| M2[Improvement]
    M1 -->|destilliert| GV1[Insight<br/>Score 8/10 🟡]
    M2 -->|destilliert| GV2[Insight<br/>Score 9/10 🔴]
    GV1 --> PR[Transfer<br/>Konkrete Patches]
    GV2 --> PR

Begriff	Bedeutung
Capability	Ein Skill, Agent, Prompt(-Verbund) oder Instructions-File inkl. aller zugehörigen Dateien
Genome	Die Gesamtheit aller Capabilities eines Projekts – das "KI-Wissen" eines Repos
Improvement	Ein Git-Commit-Delta an einer Capability – eine konkrete Verbesserung am KI-Tooling
Insight	Destilliertes, bewertetes Improvement (bereinigt, klassifiziert, gescored, übertragbar)
Transfer	Konkreter Änderungsvorschlag, um ein Insight auf ein Ziel-Genome anzuwenden

---

Scope

Folgende Pfade bilden das Genome:

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

---

Capability-Erkennung

Capabilities werden aus dem Dateipfad abgeleitet. Die Granularität hängt vom Capability-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 Capability-Schlüssel.

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

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

Agents

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

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

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

Prompts

Prompts unterscheiden zwei Varianten: Standalone und Verbund.

Standalone-Prompts

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

.github/prompts/commit.prompt.md  → capability: prompt/commit
.github/prompts/ship.prompt.md    → capability: prompt/ship
.github/prompts/publish.prompt.md → capability: prompt/publish

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

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 eine Capability. Der Router-Name ist der Capability-Schlüssel.

.github/prompts/nextstep.prompt.md                → capability: prompt/nextstep
.github/prompts/nextstep-implementation.prompt.md  → capability: prompt/nextstep
.github/prompts/nextstep-planning.prompt.md        → capability: prompt/nextstep
.github/prompts/nextstep-tech-decision.prompt.md   → capability: prompt/nextstep

Verbund-Erkennung: Eine Datei <name>.prompt.md ist ein Router, wenn Dateien <name>-*.prompt.md im selben Verzeichnis existieren. Alle gehören zur selben Verbund-Capability.

Instructions

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

.github/copilot-instructions.md          → capability: instructions/copilot-instructions
.github/kotlin-conventions.instructions.md → capability: instructions/kotlin-conventions

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

---

Improvement-Typen

Typ	Bedeutung	Beispiel
content-change	Inhalt einer Datei in der Capability geändert	nextstep-implementation.prompt.md optimiert
member-added	Neue Datei zur Capability hinzugefügt	Neuer nextstep-migration.prompt.md + Router-Eintrag
member-removed	Datei aus der Capability 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-improvements.md]
    end
    subgraph "Phase 2: Distillation"
        direction TB
        RAW2[raw-improvements.md] --> AGENT1[KI-Agent]
        AGENT1 --> |"Klassifizieren\nScoren\nSanitizen"| DIST[distilled-insights.md]
    end
    subgraph "Phase 3: Transfer"
        direction TB
        DIST2[distilled-insights.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-improvements.md

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

Tool: genome-extract.py (Python)

Phase 2: Distillation (Agent)

Input: raw-improvements.md Output: distilled-insights.md

flowchart TD
    M[Improvement] --> 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-insights.md]
    SAN --> |Score < 4| X

• Scored jedes Improvement (1–10) nach Übertragungswert
• Filtert sensitive Daten (Usernames, Maschinenpfade, Tokens, projektspezifische IDs)
• Specialized Improvements werden komplett entfernt

Tool: genome-distill.prompt.md

Phase 3: Transfer (Agent)

Input: distilled-insights.md + Ziel-Genome Output: transfer-proposals.md

• Matched Capabilities zwischen Quell- und Ziel-Genome
• Erstellt konkrete Änderungsvorschläge pro Capability
• 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: Improvements extrahiert → Distillation → Transfer

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-improvements.md<br/>generiert]
        DM[distilled-insights.md<br/>generiert]
        PP[transfer-proposals.md<br/>generiert]
    end
    subgraph ".github/genome/"
        CO[Concept 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-improvements.md	Generiert	.github/genome/output/
8	distilled-insights.md	Generiert	.github/genome/output/
9	transfer-proposals.md	Generiert	.github/genome/output/

Generierte Dateien (7–9) sind gitignored.

---

Zukünftige Erweiterungen

• Multi-Repo-Registry: Zentrale Sammlung von Insights aus vielen Projekten
• Automatische Erkennung des Transfer-Zeitraums über Repo-Vergleich
• CI-Integration: Transfer-Check bei jedem Push
• Community-Sharing: Öffentliche Insights als "Capability Packages"