# Knowledge Conduit – 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 Dev+AI-Teams bereitgestellt.

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

---

## Begriffe

```mermaid
graph TD
    G[� Knowledge Conduit<br/>Kanal zwischen Dev+AI-Teams] --> 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 |
| **Conduit**     | Der Kanal, durch den Wissen zwischen Dev+AI-Teams fließt                                  |
| **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-Repo anzuwenden                 |

---

## Scope

Folgende Pfade bilden die KI-Tooling-Landschaft:

- `.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:

```mermaid
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

```mermaid
flowchart LR
    subgraph "Phase 1: Extraction"
        direction TB
        GIT[(Git-History)] --> SCRIPT[kc-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-Repo] --> 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 KI-Tooling-Scope
- Gruppiert Diffs nach Capability (siehe Capability-Erkennung oben)
- Gibt pro Capability alle Commits mit Diff, Message und Autor aus

**Tool:** `kc-extract.py` (Python)

### Phase 2: Distillation (Agent)

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

```mermaid
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:** `kc-distill.prompt.md`

### Phase 3: Transfer (Agent)

**Input:** `distilled-insights.md` + Ziel-Repo
**Output:** `transfer-proposals.md`

- Matched Capabilities zwischen Quell- und Ziel-Repo
- 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:** `kc-transfer.prompt.md`

---

## Zeitbasierte Transferlogik

```mermaid
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

```mermaid
graph TD
    subgraph ".github/skills/knowledge-conduit/"
        SK[SKILL.md<br/>Skill-Dokumentation]
        EX[kc-extract.py<br/>Phase 1 Script]
    end
    subgraph ".github/prompts/"
        OR[knowledge-conduit.prompt.md<br/>Orchestrator]
        DI[kc-distill.prompt.md<br/>Phase 2]
        PR[kc-transfer.prompt.md<br/>Phase 3]
    end
    subgraph ".github/knowledge-conduit/output/"
        RM[raw-improvements.md<br/>generiert]
        DM[distilled-insights.md<br/>generiert]
        PP[transfer-proposals.md<br/>generiert]
    end
    subgraph ".github/knowledge-conduit/"
        CO[Concept.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   | `kc-extract.py`                | Python Script | `.github/skills/knowledge-conduit/` |
| 2   | `knowledge-conduit.prompt.md`  | Orchestrator  | `.github/prompts/`                  |
| 3   | `kc-distill.prompt.md`         | Prompt        | `.github/prompts/`                  |
| 4   | `kc-transfer.prompt.md`        | Prompt        | `.github/prompts/`                  |
| 5   | `SKILL.md`                     | Skill-Doku    | `.github/skills/knowledge-conduit/` |
| 6   | `Concept.md`                   | Konzept       | `.github/knowledge-conduit/`        |
| 7   | `raw-improvements.md`          | Generiert     | `.github/knowledge-conduit/output/` |
| 8   | `distilled-insights.md`        | Generiert     | `.github/knowledge-conduit/output/` |
| 9   | `transfer-proposals.md`        | Generiert     | `.github/knowledge-conduit/output/` |

> Generierte Dateien (7–9) sind gitignored.

---

## Zukünftige Erweiterungen

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