sergeylopukhov/context-cartographer

Context Cartographer

Erstellen Sie ein kleines Dokumentationssystem, das es zukünftigen Agenten ermöglicht, nur den Kontext zu laden, den sie benötigen.

Geltungsbereich

• Verwenden Sie dieses Skill für die Einrichtung eines Dokumentationssystems, Audits, Migrationen, Bereinigungen, Umstrukturierungen oder bei unklarer Zuständigkeit.
• Verwenden Sie es nicht für eine routinemäßige Änderung, wenn die Ziel-Besitzerdatei bereits bekannt ist.
• Verwenden Sie es nicht für automatische dauerhafte Wartung, die bereits durch AGENTS.md, CLAUDE.md, Cursor-Regeln, docs/architecture.md oder docs/code_rules.md erforderlich ist. Wenden Sie diese lokalen Anweisungen direkt an.
• Verwenden Sie es immer, wenn der Benutzer explizit context-cartographer aufruft.

Kernregeln

• Ermitteln Sie das Projektstammverzeichnis und inventarisieren Sie die tatsächlichen Pfade, bevor Sie Projektdateien lesen. Raten Sie keine Pfade aus dem aktuellen Verzeichnis oder einem anderen Projekt.
• Verwenden Sie bereits während der Aufgabe gelesene Dateien wieder. Lesen Sie nur eine geänderte Datei, eine abgeschnittene Ausgabe oder einen bestimmten ungelesenen Bereich erneut.
• Halten Sie die Stamm-Anweisungsdateien für Agenten kurz. Platzieren Sie detaillierte Informationen zu dauerhaften Themen in Besitzerdateien unter docs/.
• Verwenden Sie AGENTS.md für Codex, CLAUDE.md für Claude Code, .cursor/rules/context-cartographer.mdc für Cursor oder dünne Adapter für ausgewählte Multi-Agenten-Ziele.
• Überprüfen Sie den Ist-Zustand schreibgeschützt, bevor Sie Änderungen vorschlagen.
• Bewahren Sie vorhandene projektspezifische Regeln und editieren Sie chirurgisch.
• Überschreiben, verschieben, zusammenführen oder löschen Sie niemals vorhandene Anweisungs- oder Dokumentationsdateien ohne Genehmigung.
• Erstellen Sie nur Dateien, die durch Projektevidenz und aktuelle Anforderungen gestützt werden.
• Markieren Sie unbekannte Fakten als TODO: clarify; erfinden Sie keine Projektfakten.
• Halten Sie projektgedächtnis-Dokumente standardmäßig lokal und fügen Sie sie zur Repository-Ignore-Datei hinzu, es sei denn, der Benutzer bittet explizit darum, sie zu verfolgen oder zu veröffentlichen.
• Überprüfen Sie nach Bearbeitungen Links, Besitzer-Routing, Ignore-Regeln und veraltete Referenzen.

Erforderliche Entscheidungen

Vor dem Erstellen oder Ersetzen von Stamm-Anweisungsdateien für Agenten sind zu klären:

• Agentenziel;
• Code-Regeln-Modus: docs/code_rules.md verwenden oder nicht verwenden;
• Dokumentationswartungsmodus: automatische dauerhafte Wartung oder nur auf Anfrage Wartung;
• Umgang mit vorhandenen Dokumenten: unverändert lassen, nur prüfen, nach Genehmigung migrieren oder dem Agenten die Entscheidung überlassen;
• ob projektgedächtnis-Dokumente lokal bleiben oder verfolgt werden.

Leiten Sie den Code-Regeln-Modus oder den Dokumentationswartungsmodus nicht ab. Wenn mehr als zwei Entscheidungen fehlen, verwenden Sie den beigefügten Fragebogen.

Generierte Stamm-Anweisungen müssen die routinemäßige Wartung von diesem Skill unabhängig halten:

• Unter automatischer dauerhafter Wartung aktualisieren Sie das passende Besitzerdokument in derselben Aufgabe, wann immer abgeschlossene Arbeit das dauerhafte Verhalten, die Architektur, das Setup, die Bereitstellung, das Staging, die Testdaten, den Zugriff, den Import/Export, öffentliche URLs, den Betreiber-Workflow, das Datenmodell, öffentliche Schnittstellen, den Agenten-Workflow oder die Dokumentationszuständigkeit ändert.
• Unter nur auf Anfrage Wartung aktualisieren Sie Dokumente nur, wenn explizit darum gebeten wird, und markieren Sie wahrscheinlich veraltete Dokumente.
• Halten Sie fest, dass die routinemäßige Wartung Stamm-Anweisungen und vorhandene Besitzerdokumente direkt ohne Aufruf von context-cartographer verwendet.
• Wenn keine vorhandene Besitzerdatei passt, rufen Sie dieses Skill auf und befolgen Sie das Protokoll für fehlende Besitzer. Unter automatischer dauerhafter Wartung klassifizieren und erstellen Sie den kleinsten gerechtfertigten Besitzer automatisch, ohne nur um Erlaubnis zum Erstellen einer Markdown-Datei zu bitten.
• Rufen Sie dieses Skill später nur für Einrichtung, Audit, Migration, Bereinigung, Umstrukturierung, explizite Verwendung oder wirklich unklare Zuständigkeit auf.

Referenz-Routing

• Für die Ersteinrichtung lesen Sie immer references/setup-workflow.md; es leitet zu den anderen erforderlichen Referenzen weiter.
• Für Audit, Migration, Bereinigung, Umstrukturierung oder unklare Zuständigkeit lesen Sie immer references/existing-docs-workflow.md; es leitet zu den anderen erforderlichen Referenzen weiter.
• Lesen Sie references/doc-map.md, bevor Sie Dateien oder Besitzer auswählen.
• Lesen Sie references/file-templates.md, bevor Sie Stamm-Anweisungen oder docs/*.md erstellen.
• Lesen Sie references/audit-checklist.md, bevor Sie ein vorhandenes Repository prüfen.
• Lesen Sie references/cleanup-rules.md, bevor Sie Dokumente aufteilen, zusammenführen, löschen oder umbenennen.
• Lesen Sie references/question_schema.md, bevor Sie Fragebogen-JSON erstellen.
• Lesen Sie references/questionnaire_usage_examples.md nur, wenn Sie den Fragebogenablauf anpassen.

Arbeitsablauf

1. Ermitteln Sie das Projektstammverzeichnis und inventarisieren Sie die Pfade mit rg --files.
2. Klassifizieren Sie das Projektprofil, das ausgewählte Agentenziel, vorhandene Dokumente, Besitzer, den Code-Regeln-Modus und den Wartungsmodus.
3. Zeigen Sie für vorhandene Dokumente eine kompakte Karte der aktuellen Dateien, Themenbesitzer und geplanten Aktionen zum Erstellen/Aktualisieren/Löschen vor der Bearbeitung an.
4. Wenden Sie die kleinste gerechtfertigte Änderung am Dokumentationssystem innerhalb des autorisierten Umfangs des Benutzers an.
5. Überprüfen Sie Links, veraltete Dateinamen, Besitzerabdeckung, lokale Ignore-Regeln und die unabhängigen routinemäßigen Wartungsanweisungen.

Befolgen Sie für ein neues System references/setup-workflow.md.

Für Audit, Bereinigung, Migration, Umstrukturierung oder unklare Zuständigkeit befolgen Sie references/existing-docs-workflow.md.

Fragebogen

Für umfassende Einrichtungsarbeiten mit mehr als zwei fehlenden Entscheidungen:

1. Erstellen Sie .project-questionnaire/questions.json aus references/question_schema.md.
2. Setzen Sie language auf die Sprache des Benutzers oder Projekts.
3. Validieren Sie mit python3 <this-skill>/scripts/questionnaire_server.py --input .project-questionnaire/questions.json --validate-only.
4. Starten Sie den Server auf 127.0.0.1 mit einem automatischen Port.
5. Nachdem der Benutzer gespeichert und gesagt hat, dass er fertig ist, lesen Sie beide Antwortdateien, bevor Sie fortfahren.

Der Code-Regeln-Modus und der Dokumentationswartungsmodus müssen erforderliche Auswahlmöglichkeiten ohne Standard- oder Empfehlungsoptionen sein.

Update-Prüfung

Führen Sie python3 <this-skill>/scripts/check_update.py --json höchstens einmal pro Tag aus. Fragen Sie vor der Installation eines verfügbaren Updates. Erhöhen Sie die VERSION, wenn Sie eine Änderung veröffentlichen, die installierte Benutzer erhalten sollen.

Ausstiegskriterien

Melden Sie:

• erstellte oder geänderte Dateien;
• überprüfte Links, Routing und veraltete Referenzen;
• überprüfte lokale Ignore-Richtlinie;
• überprüftes unabhängiges automatisches Wartungs-Routing;
• durchgeführte Validierung und alle nicht ausgeführten Prüfungen.