taiga-stories

Stories Taiga

Il n'y a pas de contrôle de navigateur. Les téléchargements passent par l'API REST Taiga avec scripts/taiga_stories.py, qui n'utilise que la bibliothèque standard Python. Le même outillage fonctionne pour tout projet Taiga, configuré dans .env.

Configuration (une fois par dépôt)

1. Copier .env.example vers .env à la racine du dépôt et définir TAIGA_PROJECT_URL sur le lien du projet, ex. https://taiga.example.com/project/mon-projet.
2. Optionnellement définir STORIES_DIR (par défaut stories).

.env ne contient aucun secret et est ignoré par git. Le jeton ne va jamais dedans.

Écrire des stories

Chaque story est un fichier .md dans stories/, suivant story-template.md.

• Nom de fichier : minuscules, sans accents, mots avec des traits d'union (slug-automatique.md).

• Première ligne : # Histoire : <titre>. Le texte après « Histoire : » devient le titre Taiga. Pour les corrections de bugs, utiliser Correction — <ce qui se passait>.

• En-tête : **Projet :**, **Branche :**, **Version :**, **Date :** et **Points :**, un par ligne.

• Points : il n'y a pas de valeur par défaut. Avant d'enregistrer une nouvelle story dans stories/, estimer ses points avec la compétence story-points (historique des commits de CODE_REPO_PATH) et faire confirmer par l'utilisateur. Écrire la valeur dans **Points :** (**Pontos :** en portugais). Ce doit être un nom dans l'échelle de points du projet (1, 2, 3, 5, 8, 13, 21).

• Sections, dans cet ordre : ## Histoire d'utilisateur (En tant que / Je veux / afin de, chaque mot en gras sur sa propre ligne), ## Description (texte pour le product owner, pas de jargon technique), ## Critères d'acceptation (- [ ] liste à cocher, [x] pour ce qui est fait et testé), ## Tâches et ## Notes de déploiement (ou ## Notes quand ce n'est pas lié au déploiement).

• Tâches : les regrouper sous ### Backend, ### Frontend, ### Tests et ### Documentation, dans cet ordre, en omettant les groupes vides. Chaque tâche est N. **Titre** avec sa description indentée sur la ligne suivante. La numérotation est continue entre les groupes.

• Langue : écrire toute la story, titres compris, dans la langue de la demande de l'utilisateur. Une demande en portugais donne une story en portugais. Les deux jeux d'en-têtes sont analysés :

  Français	Anglais	Portugais
  # Histoire :	# Story:	# História:
  **Projet :** / **Branche :** / **Version :** / **Date :** / **Points :**	**Project:** / **Branch:** / **Version:** / **Date:** / **Points:**	**Projeto:** / **Branch:** / **Versão:** / **Período:** / **Pontos:**
  ## Histoire d'utilisateur (En tant que / Je veux / afin de)	## User story (As / I want / so that)	## História de usuário (Como / quero / para)
  ## Description	## Description	## Descrição
  ## Critères d'acceptation	## Acceptance criteria	## Critérios de aceite
  ## Tâches (### Backend, ### Frontend, ### Tests, ### Documentation)	## Tasks (### Backend, ### Frontend, ### Tests, ### Documentation)	## Tarefas (### Backend, ### Frontend, ### Testes, ### Documentação)
  ## Notes de déploiement / ## Notes	## Deployment notes / ## Notes	## Observações para implantação / ## Observações
  Correction — ...	Fix — ...	Correção — ...

• Texte compatible pare-feu : dans les descriptions, éviter un ; juste avant code (utiliser un point final), les balises littérales comme <script> (écrire « la balise script »), et les chaînes Classe::méthode à côté de routes. Le script contourne ces problèmes, mais le texte en est moins bon.

Vérifier le format (sans réseau, sans jeton) :

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

Corriger les erreurs. Une tâche sans description est un avertissement acceptable. Un **Points :** manquant n'est qu'un avertissement ici, mais il bloque le téléchargement.

Téléchargement vers Taiga

Toujours demander d'abord, dans le chat, à chaque fois

Utiliser AskUserQuestion, ou une simple question si elle est indisponible. Ne pas réutiliser les réponses précédentes :

1. Destination : quel sprint (nom exact, ex. Sprint 34) ou backlog.
2. Jeton de session : dans l'onglet Taiga ouvert, F12 > Console > localStorage.getItem("token"). L'utiliser uniquement comme variable d'environnement en ligne pour la commande. Ne jamais l'écrire dans .env ou dans un fichier.
3. Points manquants : si une story à télécharger n'a pas de **Points :** (le --dry-run affiche MANQUANT), estimer ceux-ci avec la compétence story-points et faire confirmer par l'utilisateur, en les listant par titre. Écrire chaque valeur dans la ligne **Points :** de la story (**Pontos :** en portugais), juste après **Date :** / **Período :**. Les stories qui ont déjà des points ne sont pas estimées à nouveau. Le téléchargement s'arrête avant de créer quoi que ce soit tant qu'une story n'a pas de valeur valide.

Si .env est manquant, demander aussi le lien du projet Taiga et créer .env à partir de .env.example.

Étapes

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

Passer les noms de fichiers à la fin pour télécharger uniquement certaines stories. Ensuite, rapporter à l'utilisateur combien de stories et de tâches ont été créées, plus les textes que le script a réécrits (et toute tâche dont la description a été supprimée).

Valeurs par défaut : le propriétaire du jeton est l'assigné des stories et des tâches, les statuts sont ceux par défaut du projet, et les points proviennent du champ **Points :** de chaque story, sur le rôle calculable du projet.

Le script :

• ignore les stories dont le titre existe déjà dans le projet. Utiliser --force seulement si l'utilisateur le demande ;
• reprend une exécution interrompue sans dupliquer (état dans stories/.taiga_state.json). S'il s'arrête, simplement l'exécuter à nouveau ;
• réécrit les textes bloqués par le pare-feu et les liste à la fin.

Ne pas enchaîner d'autres commandes de création avec ; après une étape qui peut échouer. Un échec à mi-parcours peut créer des doublons.

Leçons apprises

• Cloudflare 403 avec un corps HTML (« Just a moment... ») signifie que le WAF a bloqué le texte, pas un problème de permission. Le script réessaye avec des variantes plus simples. Si une tâche se retrouve sans description, la réécrire en texte simple (sans backticks, sans ::) et la PATCHer, en envoyant la version actuelle.
• 403 avec JSON PermissionDenied est une vraie erreur de permission. Les membres réguliers peuvent ne pas pouvoir supprimer des user stories (les tâches vont bien), donc éviter les doublons. Si cela arrive, réutiliser la story avec PATCH (sujet, description, points, jalon, assigned_to, version) au lieu de la supprimer.
• Les points vont dans points: {"<id du rôle calculable>": <id du point>}, et l'id du point est recherché par son nom dans l'échelle du projet.
• Sur Windows, Python ne voit pas le /tmp de Git Bash. Utiliser des chemins Windows, et exécuter Python avec -X utf8 pour que les accents s'affichent correctement.