taiga-stories

Taiga ストーリー

ブラウザ操作は不要です。アップロードはscripts/taiga_stories.pyを介してTaiga REST APIで行われ、Python標準ライブラリのみを使用します。このツールはすべてのTaigaプロジェクトで動作し、設定は.envで行います。

セットアップ（リポジトリごとに1回）

1. .env.exampleをリポジトリルートに.envとしてコピーし、TAIGA_PROJECT_URLにプロジェクトのリンク（例：https://taiga.example.com/project/my-project）を設定します。
2. 必要に応じてSTORIES_DIRを設定します（デフォルトはstories）。

.envには秘密情報は含まれず、gitの管理対象外です。トークンは決して.envには入れません。

ストーリーの作成

各ストーリーはstories/内の1つの.mdファイルで、story-template.mdに従います。

• ファイル名: 小文字、アクセントなし、単語はハイフンで区切る（automatic-slug.md）。

• 最初の行: # Story: <タイトル>。「Story:」の後のテキストがTaigaのタイトルになります。バグ修正の場合はFix — <発生していた現象>を使用します。

• ヘッダー: **Project:**、**Branch:**、**Version:**、**Date:**、**Points:**を1行ずつ記述します。

• ポイント: デフォルト値はありません。新しいストーリーをstories/に保存する前に、story-pointsスキル（CODE_REPO_PATHのコミット履歴）を使ってポイントを見積もり、ユーザーに確認してもらいます。値を**Points:**（ポルトガル語では**Pontos:**）に記述します。プロジェクトのポイントスケール（1, 2, 3, 5, 8, 13, 21）に含まれる名前である必要があります。

• セクション（この順序で）: ## User story（As / I want / so that、それぞれ太字で独立した行）、## Description（プロダクトオーナー向けの説明文、コード用語は避ける）、## Acceptance criteria（- [ ] チェックリスト、完了・テスト済みは[x]）、## Tasks、## Deployment notes（デプロイに関するものでない場合は## Notes）。

• タスク: ### Backend、### Frontend、### Tests、### Documentationの順にグループ化し、空のグループは省略します。各タスクはN. **タイトル**の形式で、説明は次の行にインデントして記述します。番号はグループを跨いで連続します。

• 言語: ストーリー全体（見出しを含む）をユーザーのリクエスト言語で記述します。ポルトガル語のリクエストにはポルトガル語のストーリーを作成します。両方の見出しセットが解析されます：

  English	Portuguese
  # Story:	# História:
  **Project:** / **Branch:** / **Version:** / **Date:** / **Points:**	**Projeto:** / **Branch:** / **Versão:** / **Período:** / **Pontos:**
  ## User story (As / I want / so that)	## História de usuário (Como / quero / para)
  ## Description	## Descrição
  ## Acceptance criteria	## Critérios de aceite
  ## Tasks (### Backend, ### Frontend, ### Tests, ### Documentation)	## Tarefas (### Backend, ### Frontend, ### Testes, ### Documentação)
  ## Deployment notes / ## Notes	## Observações para implantação / ## Observações
  Fix — ...	Correção — ...

• ファイアウォール対策テキスト: 説明文では、codeの直前に;を置かない（ピリオドを使用）、リテラルタグ<script>（「scriptタグ」と記述）、ルートの隣にあるClass::methodの連鎖を避けます。スクリプトはこれらを回避しようとしますが、テキストの品質が低下します。

フォーマットを確認する（ネットワーク・トークン不要）：

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

エラーを修正します。説明のないタスクは許容される警告です。**Points:**の欠落はここでは警告に留まりますが、アップロードをブロックします。

Taigaへのアップロード

毎回、まずチャットで確認する

AskUserQuestion（使用できない場合は平文の質問）を使用します。以前の回答を再利用しないでください：

1. 宛先: スプリント（正確な名前、例：Sprint 34）またはバックログ。
2. セッショントークン: 開いているTaigaタブで、F12 > コンソール > localStorage.getItem("token")。コマンドのインライン環境変数としてのみ使用します。.envやファイルに決して書き込まないでください。
3. 不足しているポイント: アップロードするストーリーに**Points:**がない場合（--dry-runでMISSINGと表示される）、story-pointsスキルで見積もり、タイトルごとに列挙してユーザーに確認してもらいます。各値をストーリーの**Points:**行（ポルトガル語では**Pontos:**）に、**Date:** / **Período:**の直後に書き込みます。既にポイントがあるストーリーは再見積もりしません。有効な値がないストーリーがある場合、アップロードは何も作成せずに停止します。

.envがない場合は、Taigaプロジェクトのリンクも尋ね、.env.exampleから.envを作成します。

手順

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

末尾にファイル名を指定すると、一部のストーリーのみアップロードできます。その後、作成されたストーリーとタスクの数、スクリプトが書き換えたテキスト（および説明が削除されたタスク）をユーザーに報告します。

デフォルトでは、トークン所有者がストーリーとタスクの担当者になり、ステータスはプロジェクトのデフォルト、ポイントは各ストーリーの**Points:**フィールド（プロジェクトの計算対象ロール）から取得されます。

スクリプトの動作：

• タイトルがプロジェクトに既に存在するストーリーはスキップします。--forceはユーザーが要求した場合のみ使用します。
• 中断された実行を重複なしで再開します（状態はstories/.taiga_state.jsonに保存）。停止した場合は、もう一度実行するだけです。
• ファイアウォールでブロックされたテキストを書き換え、最後にリスト表示します。

失敗する可能性のあるステップの後に;で他の作成コマンドを連鎖させないでください。途中で失敗すると重複が発生する可能性があります。

学んだ教訓

• Cloudflare 403（HTML本文「Just a moment...」） はWAFがテキストをブロックしたことを意味し、権限の問題ではありません。スクリプトはよりプレーンなバリアントで再試行します。タスクの説明が空になった場合は、プレーンな散文（バッククォートや::なし）で書き直し、PATCHで現在のversionを送信します。
• 403 JSON PermissionDenied は実際の権限エラーです。通常のメンバーはユーザーストーリーの削除ができない場合があります（タスクは問題ありません）。そのため重複を避けてください。重複が発生した場合は、削除する代わりにPATCH（subject、description、points、milestone、assigned_to、version）でストーリーを再利用します。
• ポイントはpoints: {"<計算対象ロールID>": <ポイントID>}で指定し、ポイントIDはプロジェクトのスケールで名前から検索されます。
• Windowsでは、PythonはGit Bashの/tmpを認識しません。Windowsパスを使用し、アクセントが正しく出力されるように-X utf8を付けてPythonを実行します。