290 lines
10 KiB
Markdown
290 lines
10 KiB
Markdown
# 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] --> 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 - Score 8/10]
|
||
M2 -->|destilliert| GV2[Insight - Score 9/10]
|
||
GV1 --> PR[Transfer - 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 TD
|
||
GIT[(Git-History)] --> SCRIPT[kc-extract.py]
|
||
SCRIPT --> RAW[raw-improvements.md]
|
||
RAW --> AGENT1[KI-Agent: Distillation]
|
||
AGENT1 -->|Klassifizieren + Scoren + Sanitizen| DIST[distilled-insights.md]
|
||
DIST --> AGENT2[KI-Agent: Transfer]
|
||
ZIEL[Ziel-Repo] --> AGENT2
|
||
AGENT2 --> PATCHES[transfer-proposals.md]
|
||
|
||
style SCRIPT fill:#2d4a2d,stroke:#4a7c4a
|
||
style AGENT1 fill:#4a3d2d,stroke:#7c6a4a
|
||
style AGENT2 fill:#2d3d4a,stroke:#4a6a7c
|
||
```
|
||
|
||
### 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 fuer 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]
|
||
SAN -->|Score ge 4| OUT[distilled-insights.md]
|
||
SAN -->|Score lt 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 skills [skills/knowledge-conduit/]
|
||
SK[SKILL.md]
|
||
EX[kc-extract.py]
|
||
end
|
||
subgraph prompts [prompts/]
|
||
OR[knowledge-conduit.prompt.md]
|
||
DI[kc-distill.prompt.md]
|
||
PR[kc-transfer.prompt.md]
|
||
end
|
||
subgraph output [knowledge-conduit/output/]
|
||
RM[raw-improvements.md]
|
||
DM[distilled-insights.md]
|
||
PP[transfer-proposals.md]
|
||
end
|
||
subgraph concept [knowledge-conduit/]
|
||
CO[Concept.md]
|
||
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"
|