taiga-stories

Taiga Stories

Es gibt keine Browsersteuerung. Der Upload erfolgt über die Taiga REST API mit scripts/taiga_stories.py, das nur die Python-Standardbibliothek verwendet. Das gleiche Tooling funktioniert für jedes Taiga-Projekt, das in .env konfiguriert wird.

Einrichtung (einmal pro Repository)

1. Kopiere .env.example zu .env im Repository-Stamm und setze TAIGA_PROJECT_URL auf den Projekt-Link, z. B. https://taiga.example.com/project/my-project.
2. Optional kann STORIES_DIR gesetzt werden (Standard: stories).

.env enthält keine Geheimnisse und wird von git ignoriert. Das Token kommt niemals hinein.

Stories schreiben

Jede Story ist eine .md-Datei in stories/, die der story-template.md folgt.

• Dateiname: Kleinbuchstaben, ohne Akzente, Wörter mit Bindestrichen (automatischer-slug.md).

• Erste Zeile: # Story: <Titel>. Der Text nach „Story:“ wird zum Taiga-Titel. Für Fehlerbehebungen verwende Fix — <was passiert ist>.

• Kopfzeile: **Projekt:**, **Branch:**, **Version:**, **Datum:** und **Punkte:**, jede in einer eigenen Zeile.

• Punkte: Es gibt keinen Standard. Bevor du eine neue Story in stories/ speicherst, schätze ihre Punkte mit dem story-points Skill (Commit-Verlauf von CODE_REPO_PATH) und lass sie vom Benutzer bestätigen. Schreibe den Wert in **Punkte:**. Es muss ein Name in der Punktskala des Projekts sein (1, 2, 3, 5, 8, 13, 21).

• Abschnitte, in dieser Reihenfolge: ## User story (Als / möchte ich / damit, jeweils fett in eigener Zeile), ## Beschreibung (Fließtext für den Product Owner, kein Code-Jargon), ## Abnahmekriterien (- [ ] Checkliste, [x] für Erledigtes und Getestetes), ## Aufgaben und ## Deployment-Hinweise (oder ## Hinweise, wenn es nicht um Deployment geht).

• Aufgaben: Gruppiere sie unter ### Backend, ### Frontend, ### Tests und ### Dokumentation, in dieser Reihenfolge, wobei leere Gruppen weggelassen werden. Jede Aufgabe ist N. **Titel** mit ihrer Beschreibung in der nächsten Zeile eingerückt. Die Nummerierung ist durchgehend über alle Gruppen hinweg.

• Sprache: Schreibe die gesamte Story, einschließlich Überschriften, in der Sprache der Benutzeranfrage. Eine Anfrage auf Deutsch erhält eine Story auf Deutsch. Beide Überschriftensets werden erkannt:

  Deutsch	Englisch
  # Story:	# Story:
  **Projekt:** / **Branch:** / **Version:** / **Datum:** / **Punkte:**	**Project:** / **Branch:** / **Version:** / **Date:** / **Points:**
  ## User story (Als / möchte ich / damit)	## User story (As / I want / so that)
  ## Beschreibung	## Description
  ## Abnahmekriterien	## Acceptance criteria
  ## Aufgaben (### Backend, ### Frontend, ### Tests, ### Dokumentation)	## Tasks (### Backend, ### Frontend, ### Tests, ### Documentation)
  ## Deployment-Hinweise / ## Hinweise	## Deployment notes / ## Notes
  Fix — ...	Fix — ...

• Firewall-freundlicher Text: Vermeide in Beschreibungen ein ; direkt vor code (verwende einen Punkt), wörtliche Tags wie <script> (schreibe „das script-Tag“) und Ketten von Klasse::Methode neben Routen. Das Skript arbeitet um diese herum, aber der Text wird schlechter.

Überprüfe das Format (kein Netzwerk, kein Token):

python -X utf8 .claude/skills/taiga-stories/scripts/taiga_stories.py validate [datei.md ...]

Behebe Fehler. Eine Aufgabe ohne Beschreibung ist eine akzeptable Warnung. Ein fehlendes **Punkte:** ist hier nur eine Warnung, blockiert aber den Upload.

Hochladen zu Taiga

Immer zuerst im Chat fragen, jedes Mal

Verwende AskUserQuestion oder eine einfache Frage, falls nicht verfügbar. Verwende keine früheren Antworten erneut:

1. Ziel: welcher Sprint (exakter Name, z. B. Sprint 34) oder Backlog.
2. Sitzungstoken: im geöffneten Taiga-Tab, F12 > Konsole > localStorage.getItem("token"). Verwende es nur als Inline-Umgebungsvariable für den Befehl. Schreibe es niemals in .env oder in eine Datei.
3. Fehlende Punkte: Wenn eine hochzuladende Story kein **Punkte:** hat (der --dry-run zeigt MISSING), schätze diese mit dem story-points Skill und lass sie vom Benutzer bestätigen, indem du sie nach Titel auflistest. Schreibe jeden Wert in die **Punkte:**-Zeile der Story direkt nach **Datum:**. Stories, die bereits Punkte haben, werden nicht erneut geschätzt. Der Upload stoppt vor der Erstellung von irgendetwas, solange einer Story ein gültiger Wert fehlt.

Wenn .env fehlt, frage auch nach dem Taiga-Projekt-Link und erstelle .env aus .env.example.

Schritte

S=.claude/skills/taiga-stories/scripts/taiga_stories.py
python -X utf8 $S validate
python -X utf8 $S upload --sprint "Sprint 34" --dry-run        # oder --backlog
TAIGA_TOKEN='<token>' python -X utf8 $S upload --sprint "Sprint 34"

Füge Dateinamen am Ende an, um nur einige Stories hochzuladen. Melde dann dem Benutzer, wie viele Stories und Aufgaben erstellt wurden, sowie alle Texte, die das Skript umgeschrieben hat (und alle Aufgaben, deren Beschreibung verworfen wurde).

Standardmäßig: Der Token-Inhaber ist der Bearbeiter von Stories und Aufgaben, die Status sind die Projekt-Standardwerte und die Punkte stammen aus dem **Punkte:**-Feld jeder Story, in der berechnenden Rolle des Projekts.

Das Skript:

• überspringt Stories, deren Titel bereits im Projekt existieren. Verwende --force nur, wenn der Benutzer darum bittet;
• setzt einen unterbrochenen Lauf fort, ohne Duplikate zu erzeugen (Zustand in stories/.taiga_state.json). Wenn es stoppt, führe es einfach erneut aus;
• schreibt firewall-blockierte Texte um und listet sie am Ende auf.

Verkette keine anderen erstellenden Befehle mit ; nach einem Schritt, der fehlschlagen kann. Ein Fehler auf halbem Weg kann Duplikate erzeugen.

Erkenntnisse

• Cloudflare 403 mit einem HTML-Text („Just a moment…“) bedeutet, dass die WAF den Text blockiert hat, kein Berechtigungsproblem. Das Skript wiederholt mit schlichteren Varianten. Wenn eine Aufgabe keine Beschreibung hat, schreibe sie als einfachen Fließtext (keine Backticks, kein ::) um und füge sie per PATCH ein, wobei die aktuelle version gesendet wird.
• 403 mit JSON PermissionDenied ist ein echter Berechtigungsfehler. Normale Mitglieder können möglicherweise keine User Stories löschen (Aufgaben sind in Ordnung), vermeide daher Duplikate. Wenn eines passiert, verwende die Story mit PATCH (subject, description, points, milestone, assigned_to, version) wieder, anstatt sie zu löschen.
• Punkte werden in points: {"<id der berechnenden Rolle>": <Punkt-ID>} gesetzt, und die Punkt-ID wird anhand ihres Namens in der Projekt-Skala nachgeschlagen.
• Unter Windows sieht Python das /tmp von Git Bash nicht. Verwende Windows-Pfade und führe Python mit -X utf8 aus, damit Akzente korrekt ausgegeben werden.