# 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"