vlv-code/init-meta-project

Initialisierung und Upgrade der Agentenumgebung (Meta-Projekt-Init & Audit)

Autonomer Skill zur Vorbereitung eines Repositorys für Agenten-Workflows. Erkennt automatisch eine bestehende meta-project-Struktur, verhindert das Überschreiben gesammelter Daten und führt entweder ein sicheres Upgrade auf den neuesten Standard durch oder erstellt die Struktur von Grund auf neu.

Basiert auf dem Prinzip der kontinuierlichen/opportunistischen Aktualisierung: Beim Zugriff auf Meta-Wissensausschnitte muss der Agent Lücken schließen und eine kohärente Vision des Projekts aufrechterhalten.

---

Wann der Skill aufgerufen werden sollte

• Der Benutzer fordert: "Repository für Agenten vorbereiten", "Meta-Projekt initialisieren", "AGENTS.md prüfen", "Agentenstruktur aktualisieren", "Meta-Wissen aktualisieren".

---

Ausführungsschritte

Phase 0: Prüfung der bestehenden Meta-Projekt-Umgebung

Vor dem Durchführen von Schreiboperationen wird die Existenz von Meta-Projekt-Komponenten geprüft:

1. Prüfen auf AGENTS.md im Repository-Stammverzeichnis.
2. Prüfen auf die Verzeichnisse .agents/project_knowledge/ und .agents/skills/.

Szenario A: Struktur existiert bereits (Audit & sicheres Upgrade)

Wenn AGENTS.md oder der Ordner .agents/ bereits im Repository vorhanden sind:

1. Verbot von zerstörerischen Überschreibungen:
   • Es ist strengstens verboten, observations.md zu löschen oder zu überschreiben – alle gesammelten Beobachtungen müssen erhalten bleiben.
   • Es ist verboten, benutzerdefinierte Invarianten und Beschreibungen aus der vorhandenen AGENTS.md zu löschen.
2. Standards-Compliance-Audit:
   • Prüfen, ob AGENTS.md den Abschnitt "Prinzipien und Architekturausrichtungen (North Stars)" enthält. Wenn nicht, hinzufügen, ohne den Servicezweck und die Invarianten zu ändern.
   • Prüfen, ob AGENTS.md das Direktivprotokoll mit dem Link "Zugriff + opportunistische Aktualisierung" enthält. Wenn veraltet, den Abschnitt aktualisieren.
   • Prüfen, ob boundaries.md Glob-Muster, Datenschutzverzeichnisse (data/**, *.db), die Zuweisung von Formatierungs-/Rendering-Modulen zur Gelben Zone und die Default-Deny-Invariante (Schwarze Zone) enthält.
   • Prüfen, ob die Tabelle in observations.md die Spalte "Kategorie" enthält. Falls das alte 4-Spalten-Format verwendet wird, den Tabellenkopf aktualisieren, ohne Datenzeilen zu löschen.
   • Aktualität der SKILL.md-Dateien in .agents/skills/ prüfen (record-observation, sync-architecture, ground-meta-project).
3. Sichere Erweiterung:
   • Fehlende Wissensausschnitte erstellen (z. B. wenn weak_spots.md nicht vorhanden ist).
   • Das Skill-Register in AGENTS.md um neue spezialisierte Stack-Skills für das Repository ergänzen.
4. Upgrade-Bericht:
   • Den Benutzer informieren: "Vorhandenes Meta-Projekt erkannt. Geprüft und auf den neuesten Standard aktualisiert ohne Verlust gesammelter Daten."

---

Szenario B: Erstsetup (Sauberes Grundgerüst)

Wenn keine Struktur existiert, wird der standardmäßige Zwei-Pass-Algorithmus ausgeführt:

Pass 1: Express-Scan und Generierung des Skeletts (Schnell & High-Level)

1. Express-Inspektion des Repository-Stammverzeichnisses: Stammverzeichnis auflisten und identifizieren:

   • Manifeste: package.json, pyproject.toml, go.mod, Cargo.toml, requirements.txt, pom.xml, docker-compose.yml.
   • Kernverzeichnisse: src/, app/, tests/, migrations/, scripts/, data/.
   • Zero Unmapped Dirs Regel: Alle Quellverzeichnisse der obersten Ebene im Repository-Stammverzeichnis auflisten. Streng nach .gitignore-Pfaden, VCS-Metadaten und Standard-Build/Paket/Test-Caches (.git, node_modules, .venv, venv, dist, build, coverage, __pycache__, .pytest_cache, .idea, .vscode) filtern. Jedes verbleibende Quellverzeichnis der obersten Ebene MUSS explizit berücksichtigt und in boundaries.md der Grünen, Gelben oder Roten Zone zugeordnet werden (nicht zugeordnete Verzeichnisse fallen standardmäßig unter Default Deny / Rote Zone).
   • Projektname, Zweck und Kernkonzepte aus README.md (falls vorhanden).
   • Erforderliche Schlüssel und Abhängigkeiten aus .env.example (falls vorhanden).

2. Tech-Stack und Kernprinzipien identifizieren:

   • Prägnanten Stack-String formulieren (z. B. Python 3.12, FastAPI, uv, pytest, Docker).
   • 2–3 grundlegende Ausrichtungen hervorheben (z. B. architektonische Einfachheit, strenge Typisierung, Datenunveränderlichkeit, Offline-First).

3. Verzeichnisstruktur erstellen: Verzeichnisse erstellen:

   • .agents/project_knowledge/
   • .agents/project_knowledge/archive/
   • .agents/skills/record-observation/
   • .agents/skills/sync-architecture/
   • .agents/skills/ground-meta-project/
   • scripts/

4. Gebündelte Meta-Projekt-Skills und Laufzeitskripte bereitstellen: SKILL.md-Dateien aus den eingebetteten Vorlagen unten schreiben nach:

   • .agents/skills/record-observation/SKILL.md
   • .agents/skills/sync-architecture/SKILL.md
   • .agents/skills/ground-meta-project/SKILL.md Automatisierungsskripte ohne Abhängigkeiten für Grenzen und Komprimierung in das Repository-Skriptverzeichnis scripts/ bereitstellen:
   • scripts/check_boundaries.py (Boundary Gate CLI)
   • scripts/compact_memory.py (Context Rot Shield & Memory Compactor)

5. Erste Entwürfe von Wissensausschnitten erstellen: Dateien schreiben in .agents/project_knowledge/:

   • observations.md (5-Spalten-Tabelle mit der ersten Initialisierungszeile; plattformunabhängige Befehlsbeispiele verwenden, z. B.: python -m pytest).
   • boundaries.md (Zonen-Vorlage mit grundlegenden Glob-Mustern: Formatierung in Gelber Zone, Daten in Roter).
   • weak_spots.md (Risikoregister-Struktur auf Basisebene).
   • architecture.md (Architekturgerüst auf Basisebene).
   • tasks.md (Aktives Ziel, Team-Checkliste und Delegationsregister).

Pass 2: Tiefer Tauchgang ins Repository, Prinzipien & Shell-Skills

1. Obligatorische Kerninspektions-Checkliste: Es ist verboten, weak_spots.md und architecture.md mit Boilerplate-Vorlagen zu füllen, ohne den Quellcode der Schlüsselmodule zu lesen! Der Agent muss read_file-Aufrufe für die folgenden kritischen Bereiche ausführen:

   • Speicherung & Datenbank: Das primäre Datenzugriffsmodul lesen (storage.py, Repositories, Modelle). Monolithische Größe (LOC-Anzahl), Schema-Kopplung und Migrations-Setup bewerten.
   • Externe API & Service-Clients: Integrationsmodule lesen (KI-Modell-SDKs, externe Clients). Auf Wiederholungen, Timeouts, Fallbacks und globale Singletons prüfen.
   • Containerisierung & Laufzeit: Dockerfile, docker-compose.yml und CI-Workflows (.github/workflows/) lesen. Auf Systembinärabhängigkeiten (FFmpeg, Hilfsprogramme), Benutzerberechtigungen (UID) und Datenvolumen-Mounts prüfen.
   • Benutzeroberfläche & Eingabe: Tastatur-/Router-Module lesen. Auf Plattformbeschränkungen prüfen (z. B. 64-Byte-Limit für Telegram callback_data, FSM-Zustände, Bestätigung für zerstörerische Aktionen).

2. Interaktives Kalibrierungsinterview (Codiertes Zwei-Fragen-Protokoll): Automatisierte Scans identifizieren, was im Code vorhanden ist, können aber nicht ungeschriebenen historischen Kontext, Geschäftsinvarianten oder Produktionssensitivitäten erkennen. Der Agent führt ein kurzes, strukturiertes interaktives Interview durch (über das ask_question-Werkzeug oder eine direkte interaktive Aufforderung) und stellt genau 2 gezielte Fragen:

   • Frage 1 (North Stars & Kerninvarianten): "Welche zentralen architektonischen Invarianten, Geschäftsregeln und Produktionseinschränkungen (North Stars) dürfen bei keiner Nachbesserung verletzt werden?"
   • Frage 2 (Rote Zone & sensible Pfade): "Welche spezifischen Verzeichnisse oder Module (Abrechnung, Datenbank, Kryptografie, Schlüssel, Legacy) sind kritisch und müssen in der Roten Zone blockiert werden?"

   Verarbeitung der Antworten:

   • Benutzerantworten auf Frage 1 werden sofort in Abschnitt 1 von AGENTS.md integriert ("Prinzipien und Architekturausrichtungen (North Stars)").
   • Benutzerantworten auf Frage 2 werden vor dem einmaligen Schreibvorgang in die Rote Zone von boundaries.md eingetragen.
   • Wenn der Benutzer die Fragen überspringt oder eine leere Antwort gibt, wird elegant auf die aus der Kerninspektions-Checkliste abgeleiteten Ausrichtungen zurückgegriffen.

3. Projektkonzepte und -prinzipien kalibrieren: Die Ergebnisse der Checkliste und die Interviewantworten zu 2–3 prägnanten architektonischen Ausrichtungen (North Stars) synthetisieren, die widersprüchliche Agentenaktionen verhindern.

4. Stack-Skills aus der Agenten-Shell-Registrierung zuordnen: Den Repository-Stack den im Agentenumfeld verfügbaren spezialisierten Skills zuordnen (~/.gemini/config/skills/ und eingebaute):

   • Python / uv / ruff → python-pro
   • FastAPI → fastapi-pro
   • TypeScript / JavaScript → typescript-expert
   • Next.js → nextjs-best-practices
   • Docker / Dockerfile / Compose → docker-expert
   • PostgreSQL / SQL / Migrationen → postgresql-optimization, sql-pro
   • Kubernetes / Helm → kubernetes-architect
   • Telegram-Bot / aiogram → telegram-bot-builder
   • CI/CD-Pipelines → github-actions-creator
   • Sauberer Code & Review → clean-code, code-reviewer

5. Grenzen kalibrieren (boundaries.md): Glob-Muster in .agents/project_knowledge/boundaries.md für die tatsächlichen Projektverzeichnisse verfeinern:

   • Default Deny / 100% Pfadabdeckung (Zero Unmapped Dirs): Sicherstellen, dass jedes nicht ignorierte Quellverzeichnis der obersten Ebene explizit einer Zone zugewiesen ist. Die Default-Deny-Regel (Schwarze Zone) hinzufügen: Jeder nicht zugeordnete Pfad ist standardmäßig streng in der Roten Zone.
   • Test-Zonen-Differenzierung:
     • Erstellen neuer Tests für neue Funktionalität – Grüne Zone.
     • Vorhandene Regressionstestsuite (tests/**, *_test.*, *.spec.*) – streng Gelbe Zone mit der Invariante, die das Abschwächen von Behauptungen (assert/expect) verbietet.
     • Architekturintegrität, API-Verträge und Datenschema-Tests (*integrity*, *contract*, *schema*, E2E) – streng Rote Zone.
   • Formatierungs-/Escape-Module und Vorlagen-Engines – streng Gelbe Zone.
   • Datenbankdateien und -verzeichnisse (data/**, *.db, *.sqlite*) – streng Rote Zone.
   • Platzhalterpfade durch tatsächliche Migrationspfade ersetzen (alembic/versions/**, prisma/migrations/**, etc.).
   • Routen-/Controller-Pfade durch tatsächliche Subsystem-Standorte ersetzen.

6. Risiko- und Schwachstellenanalyse (weak_spots.md): Konkrete technische Schulden, die während der Kerninspektion identifiziert wurden (Monolithen, Singletons), externe Laufzeitabhängigkeiten (Redis, Postgres, Message Broker, Systemprogramme wie FFmpeg), Plattformbeschränkungen und obligatorische Variablen aus .env.example aufzeichnen.

7. Architektur-Ausschnitt befüllen (architecture.md): High-Level-Stack, Subsysteme, Hintergrundaufgaben/Scheduler und Datenflüsse basierend auf inspizierten Kernmodulen beschreiben.

   • Bedingte End-to-End-Datenflüsse: Das Schema "End-to-End-Datenflüsse (Pre-Flight Flow Tracing)" generieren, wenn mehrstufige, Client-Server-, API- oder UI-Komponenten erkannt werden (Mapping [Origin: UI/CLI/Event] ➔ [Transport: API Route / Message] ➔ [Domain / Storage: Persistence] ➔ [Assembly / Packager] ➔ [Consumer: Client / Daemon]). Für reine einlagige CLI- oder Stdlib-Bibliotheken ohne externe Kommunikations- oder Persistenzschichten diesen Abschnitt weglassen, um Kontextüberfrachtung zu vermeiden.

8. In-Memory-Synthese-Flush-Protokoll: Der Agent schreibt keine Zwischenentwürfe auf die Festplatte. Alle Invarianten werden während der Durchgänge 1 und 2 im Arbeitsspeicher synthetisiert, danach werden die Dateien in strenger Bottom-Up-Reihenfolge geschrieben:

   • Schritt A: Vorinstallierte Skills (.agents/skills/record-observation/, sync-architecture/ und ground-meta-project/) und Automatisierungsskripte (scripts/check_boundaries.py, scripts/compact_memory.py bei gemeinsamem Repository-Setup).
   • Schritt B: Wissensausschnitte (observations.md -> boundaries.md -> weak_spots.md -> architecture.md).
   • Schritt C: Stammdatei (AGENTS.md) – streng zuletzt, als Aggregator der Verweise auf Ausschnitte und Stack-Skills.

---

Abschluss und Verifikation

1. Erstellte/aktualisierte Dateien mit Get-ChildItem -Recurse .agents oder ls -R .agents verifizieren.
2. Lokale unsichtbare Overlay-Option: Wenn die Initialisierung in einem externen/Kunden-Projekt erfolgt oder ein persönlicher Modus ohne Git-Commits angefordert wird:
   • AGENTS.md und .agents/ zu .git/info/exclude im Ziel-Repository hinzufügen.
   • git status verifizieren: Meta-Projekt-Dateien dürfen nicht in "Unversionierte Dateien" auftauchen.
3. Prägnante Zusammenfassung für den Benutzer ausgeben:
   • Ausführungsmodus (Erstsetup vs. Audit mit Upgrade; geteilt vs. unsichtbares Overlay).
   • Erstellter/aktualisierter Dateibaum.
   • Erfasste Projektausrichtungen (North Stars).
   • Liste der verknüpften Stack-Skills.

---

Eingebettete Referenzvorlagen

Vorlage: record-observation/SKILL.md

---
name: record-observation
description: >-
  Verwenden Sie diesen Skill, um eine undokumentierte Fehler, Umgebungsbesonderheit, Laufzeitrandfall
  oder nicht offensichtliche Lösung in die Tabelle `.agents/project_knowledge/observations.md` des Repositorys aufzunehmen.
---

# Beobachtung in der Repository-Wissensdatenbank aufzeichnen

1. Sicherstellen, dass `.agents/project_knowledge/observations.md` existiert.
2. Die letzten 20 Zeilen auf Duplikate prüfen.
3. Eintrag streng als einzelne Markdown-Tabellenzeile anhängen:
   `| YYYY-MM-DD | [<Kategorie>] | <Pfad_oder_Komponente> | <Kurze Problemzusammenfassung/Fakt> | <Lösung oder Workaround> |`
   Kategorien: `[build]`, `[runtime]`, `[deps]`, `[db]`, `[api]`, `[test]`, `[env]`, `[ci]`, `[boundaries]`, `[orchestration]`, `[decommission]`, `[incident]`, `[init]` oder explizites Domain-Tag (z. B. `[theme]`).
4. Wenn Zeilenanzahl > 30–40, abgeschlossene Datensätze nach `.agents/project_knowledge/archive/observations-YYYY.md` verschieben.

Vorlage: sync-architecture/SKILL.md

---
name: sync-architecture
description: >-
  Verwenden Sie diesen Skill, um Repository-Module, Abhängigkeiten und Einstiegspunkte zu analysieren
  und `.agents/project_knowledge/architecture.md` zu generieren oder zu aktualisieren.
---

# Projektarchitektur-Ausschnitt synchronisieren

1. Abhängigkeits- und Build-Manifeste lesen.
2. Einstiegspunkte und Verzeichnisse der obersten Ebene identifizieren.
3. 3–5 Subsysteme, ihre Rollen und Datenflüsse identifizieren.
4. `.agents/project_knowledge/architecture.md` aktualisieren.
5. Eine kurze Zusammenfassung der Änderungen anzeigen.

Vorlage: ground-meta-project/SKILL.md

---
name: ground-meta-project
description: >-
  Notfall-Ausrichtungs- und Rekalibrierungs-Skill: Stoppt außer Kontrolle geratene Bearbeitungen,
  erzwingt einen Zoom-Out, liest AGENTS.md, das aktive Rollen-Passwort, boundaries.md und die Architektur-Karte erneut,
  diagnostiziert Kontextdrift und setzt das Alter zurück

…

[gekürzt für die Übersetzung]