Projektwissen/README.md

Projektwissen — AG Prozesse Sachsen

Hier fängst du an. Dieses Repository ist das gemeinsame Gedächtnis der Arbeitsgruppe, die Verwaltungsprozesse der sächsischen Flurbereinigungsbehörden („LNO Sachsen") in BPMN 2.0 modelliert und in PICTURE importiert. Es enthält die Regeln, die Wissensbasis, die Anweisungen für KI-Agenten, die Skripte und den Skill sn-bpmn, der aus einer Prozessbeschreibung eine importierbare BPMN-Datei macht.

flowchart LR
    Q["Prozessbeschreibung<br/><i>Rohtext, Word, PDF</i>"] --> E["Arbeitsschritt-.md<br/><i>Entwurf, Skill sn-bpmn</i>"]
    E -->|"fachlich prüfen<br/>und anpassen"| E
    E -->|"md_to_bpmn.py"| B["BPMN 2.0<br/><i>.bpmn</i>"]
    B --> P(["Import in PICTURE"])

    style E fill:#e8f6ec,stroke:#2f9e44

Ordnername ≠ Reponame. Das Repository heißt Projektwissen, der lokale Ordner heißt AG_Prozesse — damit weitere Repositories der Gruppe später daneben geklont werden können. Der Klon-Befehl unten setzt das richtig.

In 15 Minuten startklar

Vorher da sein muss: Git, Python ≥ 3.11 mit pytest, ein Gitea-Konto mit Schreibrecht in der Organisation AG_Prozesse. Details und Windows-Besonderheiten: docs/leitfaden/04_werkzeuge_einrichten.md.

# 1. Projektwissen holen — Zielordner AG_Prozesse nicht vergessen
git clone https://entwicklung.flurneuordnung-sachsen.de/AG_Prozesse/Projektwissen.git AG_Prozesse
cd AG_Prozesse

# 2. Skills für Claude Code bereitstellen (und ggf. weitere Repositories holen)
python scripts/setup_workspace.py

# 3. Prüfen, dass alles läuft (Sekunden)
python -m pytest -q

# 4. Claude Code installieren (Windows/PowerShell; macOS/Linux siehe Leitfaden 04)
irm https://claude.ai/install.ps1 | iex

# 5. KI-Werkzeug starten — im Ordner AG_Prozesse
claude

Zum Warmwerden diese Frage stellen:

„Fasse docs/status/STATUS.md zusammen und nenne die drei wichtigsten Regeln aus AGENTS.md."

Kommt eine brauchbare Antwort, ist die Einrichtung fertig. Kommt keine, wurde das Werkzeug im falschen Ordner gestartet.

Einen Prozess modellieren

Am einfachsten über den Eingangsordner: Beschreibung als .md nach input/ legen und „Lies den Ordner input ein“ sagen. Der Agent prüft, ob es den Prozess schon gibt, fragt dich, wie es weitergeht, und vermerkt das Einlesen in der Datei. Schritt für Schritt für Einsteiger: docs/leitfaden/07_prozesse_einlesen.md.

Oder direkt:

Im Ordner AG_Prozesse Claude Code starten und zum Beispiel sagen:

„Modelliere den Prozess aus referenz/antragspruefung.docx als BPMN."

Der Skill sn-bpmn erzeugt daraus einen Entwurf entwuerfe/<name>.md, nennt die getroffenen Annahmen und wartet. Du prüfst und änderst den Entwurf fachlich — als Diagramm ansehen geht jederzeit mit python scripts/vorschau.py entwuerfe/<name>.md (offline im Browser) —, dann: „passt so, wandle um". Heraus kommt <name>.bpmn für den Import in PICTURE. Syntax des Entwurfs: .agents/skills/sn-bpmn/Anleitung.md.

input/, referenz/ und entwuerfe/ werden nicht versioniert — Quelldokumente bleiben auf deinem Rechner. Soll das Modell für alle verfügbar sein, legt der Agent es auf Wunsch in der Prozessbibliothek ab, einem eigenen Repository, mit Steckbrief und Status Entwurf, per Pull Request. Dort liegen auch die fertigen .bpmn zum Herunterladen.

Am Werkzeug mitarbeiten

#	Schritt	Womit
1	Stand holen — immer zuerst	/hallo bzw. python scripts/hallo.py
2	Offene Tickets ansehen	python scripts/gitea.py tickets
3	Ein Ticket im Detail lesen	python scripts/gitea.py ticket Projektwissen 12
4	Aufgabe an den Agenten geben	Skill sn-aufgabe-bearbeiten, Muster in 03_arbeitsweise.md
5	Nachweis erbringen	python -m pytest -q
6	Pull Request	Vorlage docs/vorlagen/pull_request.md

Die Regeln, die immer gelten

Die vollständige, für Agenten verbindliche Fassung steht in AGENTS.md. Das Wichtigste in Kurzform:

1. Der Mensch drückt ab. Agenten bereiten alles vor — Push, Merge, Tag und alles auf dem Gitea-Server macht eine Person mit ihrem eigenen Zugang. → 05_git_arbeitsweise.md
2. Nie direkt auf main committen. Immer Arbeitsbranch feature/… oder bugfix/… und Pull Request.
3. Neues Verhalten des Konverters ohne Test wird nicht gemergt.
4. Keine personenbezogenen Daten und keine internen Originalunterlagen im Repository oder in Prompts. Rollen im Modell als Funktion, nie als Person.
5. Kein Umbau nebenbei. Strukturänderungen brauchen ein eigenes Issue.
6. Deutsch mit echten Umlauten in Doku, Kommentaren, Commits, Issues und Pull Requests.
7. Wissen gehört in docs/, nicht in das Gedächtnis des KI-Werkzeugs — das ist lokal und teilt sich nicht.

Wegweiser

Pfad	Inhalt
AGENTS.md / CLAUDE.md	Anweisungen für Agenten (kanonisch ist AGENTS.md)
workspace.toml	Gitea-Organisation und Verzeichnis weiterer Repositories
Prozessbibliothek/	Klon des eigenen Repositorys mit den versionierten Prozessmodellen (ADR 0004, Regeln)
scripts/	hallo.py, setup_workspace.py, gitea.py, pruefe_umlaute.py, pruefe_prozesse.py, vorschau.py, einlesen.py
input/	Eingangsordner für Prozessbeschreibungen (.md), lokal, nicht versioniert – Skill sn-einlesen
werkzeuge/vorschau/	BPMN-Vorschau im Browser (bpmn-js, offline); vorschau.html auch ohne Python
.agents/skills/	Skills, gespiegelt nach .claude/skills/; sn-bpmn enthält den Konverter
.claude/commands/	Slash-Befehle für Claude Code (/hallo)
docs/status/	Aktueller Stand — immer zuerst lesen
docs/leitfaden/	Arbeitsweise, Werkzeuge, Git
docs/wissen/	Fallstricke, Glossar — das gemeinsame Gedächtnis
docs/entscheidungen/	Warum etwas so ist (ADR, append-only)
docs/vorlagen/	Issue, Pull Request, Übergabe, Repo-AGENTS.md

Wenn etwas nicht geht

Symptom	Ursache und Abhilfe
git clone meldet „Repository not found"	Zugang zur Organisation AG_Prozesse fehlt — Maintainer fragen
No module named pytest	python -m pip install pytest im selben Python
Der Agent kennt die Regeln oder den Skill nicht	Falscher Startordner, oder python scripts/setup_workspace.py --nur-skills fehlt
PICTURE lehnt die BPMN-Datei ab oder zeichnet sie falsch	docs/wissen/fallstricke.md, Abschnitt BPMN
Konflikte beim Pullen	/hallo vor der Arbeit vergessen — siehe 05_git_arbeitsweise.md

Mitmachen

Auch dieses Repository wird per Pull Request geändert — Regeln, Wissensbasis und Skripte sind genauso versioniert wie Code. Wer eine Regel für falsch hält, macht ein Issue auf. Wer etwas gelernt hat, das andere Zeit kostet, trägt es in docs/wissen/fallstricke.md ein.