AGENTS.mdMarkdown
# Projektleitlinie für MACHWEIS
Diese Regeln gelten für jede Arbeit im gesamten Repository.
## Pflichtlektüre vor jeder Aufgabe
Vor Analyse, Planung, Änderungen oder Tests müssen diese Dateien vollständig gelesen werden:
1. `README.md`
2. `docs/PRODUCT_BRIEF.md`
3. `docs/AI_INTEGRATION.md`
4. `docs/ROADMAP.md`
5. `docs/PROJECT_STATE.md`
`docs/PROJECT_STATE.md` ist die operative Quelle für den tatsächlich implementierten und live ausgerollten Stand. Zielbilder in älteren Dokumenten dürfen nicht als bereits implementiert ausgegeben werden.
## Arbeitsgrenzen
- Änderungen sind ausschließlich innerhalb eines vom Auftraggeber klar freigegebenen Blocks erlaubt.
- Keine angrenzenden Produktfunktionen, Refactorings, Migrationen oder Deployments ohne ausdrückliche Freigabe ergänzen.
- Diagnose- und Dokumentationsaufträge erlauben keine Implementierung.
- Bestehende uncommittete Änderungen gehören dem Auftraggeber. Insbesondere uncommittete Dateien unter `ios/` und eine vorhandene `ios/Podfile.lock` niemals verwerfen, zurücksetzen, überschreiben oder ungefragt committen.
- Keine Zugangsdaten, Tokens, personenbezogenen Daten oder produktiven Geheimnisse ausgeben oder protokollieren.
## Verbindlicher Arbeitsmodus für freigegebene Blöcke
- Vor Beginn jedes Blocks `docs/ROADMAP.md`, `docs/PROJECT_STATE.md`, den Git-Status und sämtliche vorhandenen uncommitteten Änderungen vollständig lesen. Die übrige Pflichtlektüre dieses Dokuments bleibt ebenfalls verbindlich.
- Bei einer klaren Freigabe den Block sofort und ohne vorgeschaltete Planungsrunde umsetzen. Nicht nach Teilschritten anhalten und nicht auf eine weitere Nachricht warten.
- Den nächsten Entwicklungsblock anhand von `docs/ROADMAP.md`, `docs/PROJECT_STATE.md`, technischen Abhängigkeiten und Risiken selbst bestimmen. Nicht nach der Reihenfolge oder nach bereits dokumentierten Architekturentscheidungen fragen. Rückfragen sind nur bei einer echten Produkt-, Preis-, Design- oder Sicherheitsentscheidung zulässig, die aus dem verbindlichen Projektkontext nicht belastbar hervorgeht.
- Roadmap-Entscheidungen, Architekturprinzipien und belegten Ist-Stand aus den Projektdokumenten anwenden, statt bereits entschiedene Fragen erneut zu stellen.
- Im selben ununterbrochenen Arbeitslauf implementieren, angemessen gezielt und vollständig testen, gefundene Fehler innerhalb des freigegebenen Blocks beheben, `git diff --check` ausführen, ausschließlich Blockdateien committen und nach `origin/main` pushen.
- Nur bei einem konkreten technischen oder Zugriffsblocker anhalten, der sich innerhalb des freigegebenen Umfangs nicht sicher beheben lässt. Dann Ursache, betroffene Datei beziehungsweise Schnittstelle und den kleinsten benötigten nächsten Schritt nennen.
- Nach erfolgreichem Funktionscommit `docs/PROJECT_STATE.md` noch im selben Arbeitslauf mit Ergebnis, Commit-ID, Tests, Push-/Live-Status, offenen Punkten und nächstem freizugebendem Block aktualisieren. Diese Statusaktualisierung ebenfalls committen und pushen; sie darf nicht als Anlass für eine weitere Freigaberunde verwendet werden.
- Nach jedem erfolgreichen Commit automatisch und ohne weitere Aufforderung eine kompakte ALL-INKL-Deployment-Checkliste erzeugen. Wenn der Commit kein Backend-Deployment benötigt, ausdrücklich „kein ALL-INKL-Deployment erforderlich“ melden.
- Vorhandene uncommittete Dateien unter `ios/` einschließlich `ios/Podfile.lock` niemals ändern, zurücksetzen, überschreiben, stagen oder committen.
- Ein Produktions-Deployment niemals selbstständig ausführen. Erst beginnen, wenn der Auftraggeber nach der Deployment-Checkliste eindeutig „Deployen“ schreibt. Freigaben für Implementierung, Commit, Push, Fortfahren oder den nächsten Block gelten nicht als Deployment-Freigabe.
## ALL-INKL-Deployments
Vor jedem Backend-Deployment ist [`docs/DEPLOYMENT.md`](docs/DEPLOYMENT.md) vollständig zu lesen und verbindlich anzuwenden. Insbesondere vor jedem Deployment zuerst eine kompakte Liste der hochzuladenden Dateien, des Migrationsbedarfs und der serverseitigen Testbefehle ausgeben. Die serverseitige `.env` darf niemals überschrieben oder ausgegeben werden; die öffentliche API-`.htaccess` liegt im Subdomain-Stammordner eine Ebene oberhalb von `machweis-backend`.
## Abschluss jedes freigegebenen Blocks
Für jeden Implementierungs- oder Dokumentationsblock gilt:
1. Angemessene gezielte Tests sowie die für den betroffenen Bereich relevante Gesamtsuite ausführen und Fehler innerhalb des Blocks beheben.
2. `git diff --check` ausführen und nur die zum Block gehörenden Dateien committen.
3. `docs/PROJECT_STATE.md` nach erfolgreichem Funktionscommit mit Ergebnis, Commit-ID, neuem Ist-Stand, offenen Punkten und nächstem freizugebendem Block aktualisieren und diese Abschlussdokumentation ebenfalls committen.
4. Alle zum Block gehörenden Commits nach erfolgreicher Prüfung zu `origin/main` pushen, sofern der Auftrag Commit und Push freigibt.
5. Commit-IDs, Testergebnisse, Push-Status, kompakte ALL-INKL-Deployment-Checkliste und bewusst unangetastete Arbeitskopieänderungen melden.
Wenn Tests fehlschlagen, ein Deployment nicht verifiziert ist oder ein sicherer Abschluss nicht möglich ist, darf der Stand nicht als fertig oder live bezeichnet werden. Der Blocker ist stattdessen in `docs/PROJECT_STATE.md` festzuhalten.