# Projektwissen AG_Prozesse – Anweisungen für KI-Agenten und Mitwirkende Kanonische, werkzeugneutrale Anweisungsdatei. Claude Code liest sie über `CLAUDE.md`. Sie bleibt bewusst kurz: Details liegen in `docs/` und werden nur bei Bedarf gelesen. ## Worum es geht - Arbeitsgruppe der sächsischen Flurbereinigungsbehörden („LNO Sachsen") zur **Modellierung von Verwaltungsprozessen in BPMN 2.0**. Zielwerkzeug für den Import ist **PICTURE**. - Kernwerkzeug ist der Skill `sn-bpmn`: Prozessbeschreibung (Rohtext, Stichpunkte, Word/PDF) → strukturierte Arbeitsschritt-`.md` → BPMN-2.0-Datei (`.agents/skills/sn-bpmn/md_to_bpmn.py`). - Dieser Ordner ist der Klon des Repositories **`AG_Prozesse/Projektwissen`**. Weitere Repositories der Gruppe liegen als eigenständige Git-Klone in Unterordnern und stehen in `workspace.toml`: derzeit **`Prozessbibliothek`** mit den versionierten Prozessmodellen (ADR 0004). - Die Arbeitsweise (Skripte, Skills, Git-Regeln) stammt aus `AG_QGIS/Projektwissen`, siehe `docs/entscheidungen/0001-uebernahme-aus-ag-qgis.md`. ## Zuerst lesen – nur was die Aufgabe braucht 1. `docs/status/STATUS.md` – aktueller Stand, offene Baustellen, wer woran arbeitet. 2. `docs/wissen/fallstricke.md` – bekannte Stolperfallen (BPMN-Layout, PICTURE-Import, Werkzeuge). 3. Für Modellierungsaufgaben: `.agents/skills/sn-bpmn/SKILL.md` und die dort genannten Dateien. 4. Fachbegriffe: `docs/wissen/glossar.md`. Übersicht aller Dokumente: `docs/README.md`. ## Harte Regeln ### Git und Server – der Mensch drückt ab - **Nie pushen, mergen, taggen oder etwas auf Gitea verändern.** Agenten bereiten vor, eine Person sendet ab. `.claude/settings.json` sperrt `git push`, `git merge`, `git rebase`, `git tag` technisch. - Hauptbranch ist `main`. Nie direkt auf `main` committen: eigener Branch `feature/-` bzw. `bugfix/-`, dann Pull Request. Vollständig: `docs/leitfaden/05_git_arbeitsweise.md`. - Sitzungsbeginn: `python scripts/hallo.py` (bzw. `/hallo`), bevor irgendetwas geändert wird. ### Tests - Vor jedem Commit: `python -m pytest -q` – alle Tests grün. - **Neue Funktionalität ohne Test wird nicht gemergt** – im Konverter wie in den Skripten. Mindestens ein Test je neuem beobachtbarem Verhalten, ohne Netzwerk. Bei einer Fehlerbehebung zuerst der Test, der den Fehler zeigt. - **Jeder neue oder geänderte Test bekommt einen deutschen Docstring**, erste Zeile in der Form `"""Prüft, dass …"""`. - Tests werden nicht gelöscht, nicht mit `skip` stillgelegt und nicht in ihrer Erwartung angepasst, um grün zu werden – außer das Verhalten wurde bewusst geändert und der Pull Request begründet es. - **Einzige Ausnahme:** ein bekannter, per Issue erfasster Konverterfehler an einem Modell unter `.agents/skills/sn-bpmn/beispiele/` (Referenzmodell oder Syntaxbeispiel) darf als `xfail(strict=True)` mit Issue-Nummer im Grund eingetragen werden, und zwar je Fehler einzeln, nie für ein ganzes Modell (`BEKANNTE_KREUZUNGEN` in `tests/test_referenzmodelle.py`). Nie für Fehler, die die eigene Änderung verursacht. - **Referenzmodelle** unter `.agents/skills/sn-bpmn/beispiele/referenz_*.md` sind echte, größere Prozesse zum Testen von Konverteränderungen. Ändert sich deren `.bpmn`, im Pull Request mit Vorschau begründen. ### Inhalte - **Keine personenbezogenen Daten, keine Zugangsdaten, keine internen Originalunterlagen** im Repository, in der Doku oder in Prompts. Quelldokumente (Word/PDF) bleiben lokal unter `referenz/` (nicht versioniert); ins Repository kommen nur die daraus abgeleiteten, bereinigten Arbeitsschritt-`.md` und BPMN-Dateien. Dasselbe gilt für den Eingangsordner `input/` (Skill `sn-einlesen`): Dateien dort nie löschen, verschieben oder umbenennen; einziger Eingriff ist der Einlese-Vermerk über `scripts/einlesen.py`. - **Prozessmodelle liegen im eigenen Repository `Prozessbibliothek`**, geklont nach `Prozessbibliothek//` (ADR 0004, Regeln in `docs/leitfaden/08_prozessbibliothek.md`). Issues, Branches und Pull Requests zu Modellen laufen dort. Die `.md` ist maßgeblich, die `.bpmn` wird nie von Hand bearbeitet, sondern mit `python scripts/pruefe_prozesse.py --erzeugen` neu erzeugt. Den Status `abgenommen` setzt der Agent nie von sich aus. - Rollen und Verantwortliche in Prozessmodellen als Funktion benennen („Sachbearbeitung Flurbereinigung"), nie als Person. - Keine Python-Abhängigkeiten außer der Standardbibliothek und `pytest` ohne Issue-Absprache und Eintrag in `fallstricke.md`. Eingebettete Fremdbibliotheken sind nur bpmn-js (`werkzeuge/vorschau/bpmn-js/`) und Bootstrap mit Bootstrap Icons (`werkzeuge/bootstrap/`) – nicht von Hand ändern, Aktualisierung nach der jeweiligen `README.md`. Eigene Gestaltung gehört nach `werkzeuge/stil/ag_prozesse.css`. Weitere nur per Issue. - **Die Markdown-Syntax und das Ablageformat der Prozessbibliothek sind Verträge.** Wer sie ändert, prüft vorher alle Modelle der Bibliothek, zieht `Anleitung.md` bzw. `docs/leitfaden/08_prozessbibliothek.md` nach und nennt die Änderung im Pull Request unter „Änderungen an Syntax und Ablageformat“. - Kein Umbau „nebenbei". Strukturänderungen nur über eigenes Issue. ### Allgemein - Sprache: Doku, Kommentare, Docstrings, Commit-Nachrichten, Issues und PRs auf Deutsch, mit echten Umlauten (Prüfung: `python scripts/pruefe_umlaute.py`). Bezeichner nach dem Stil der jeweiligen Datei. ## Arbeitsablauf in Kurzform (Details: Skill `sn-aufgabe-bearbeiten`) 1. `python scripts/hallo.py` – Stand holen. 2. Gitea-Issue lesen (Skill `sn-ticket`, `python scripts/gitea.py ticket Projektwissen `) oder als Entwurf vorbereiten. Ziel und Abnahmekriterien klären, bevor etwas geändert wird. 3. Branch `feature/-` bzw. `bugfix/-` von `main`. Ohne Issue kein solcher Branch: erst den Entwurf, dann legt der Mensch das Issue an (Ausnahme: `doku/…`). 4. In kleinen Schritten umsetzen; nur betroffene Dateien und Abschnitte lesen. 5. `python -m pytest -q` (enthält `pruefe_prozesse.py`) und `python scripts/pruefe_umlaute.py`. Erzeugte BPMN-Dateien zusätzlich in PICTURE importieren und das Ergebnis im PR nennen. 6. Pull-Request-Text vollständig nach `docs/vorlagen/pull_request.md` vorbereiten – alle Abschnitte einschließlich Checkliste –, mit Übergabenotiz (Skill `sn-uebergabe`). **Push und Pull Request macht der Mensch.** 7. Neue Erkenntnisse in `docs/wissen/` oder `docs/entscheidungen/` festhalten, nicht nur im lokalen Gedächtnis des Werkzeugs. ## Tokensparend arbeiten - Gezielt `grep`, dann nur die nötigen Abschnitte lesen. `md_to_bpmn.py` (über 1000 Zeilen) nie komplett laden. - Keine Dateien oder Testausgaben in den Chat kopieren; Pfade mit Zeilennummern nennen. - Am Ende jeder Aufgabe eine Übergabenotiz, damit die nächste Sitzung nicht neu erkunden muss. - Breite Suchen an einen Unteragenten delegieren, wenn das Werkzeug das kann; Hauptkontext schlank halten. ## Befehle - Sitzungsbeginn: `python scripts/hallo.py` (Claude Code: `/hallo`) - Tickets: `python scripts/gitea.py tickets` | `python scripts/gitea.py ticket Projektwissen 12` | `… suche ""` - Tests: `python -m pytest -q` - Umlaute prüfen: `python scripts/pruefe_umlaute.py` - Prozessmodelle prüfen bzw. alle `.bpmn` neu erzeugen: `python scripts/pruefe_prozesse.py [--erzeugen]` - Diagramm im Browser ansehen (offline): `python scripts/vorschau.py ` - Eingangsordner prüfen bzw. Einlese-Vermerk setzen: `python scripts/einlesen.py [--json]` | `python scripts/einlesen.py vermerk input/.md --ergebnis neu|aktualisiert --ziel ` - Workspace einrichten oder aktualisieren: `python scripts/setup_workspace.py` (mit `--pull` für fast-forward) - Entwurf umwandeln: `python .agents/skills/sn-bpmn/md_to_bpmn.py entwuerfe/.md entwuerfe/.bpmn` ## Skills Liegen in `.agents/skills/` (Agent-Skills-Standard) und werden nach `.claude/skills/` gespiegelt: `sn-bpmn`, `sn-einlesen`, `sn-aufgabe-bearbeiten`, `sn-ticket`, `sn-uebergabe`.