project-tracking

トリガー: /track-init、/plan-epic <description>、/plan-migrate、/track <description>、/backlog、「何が保留になっていますか？」、「何が保留中ですか？」、「〜するのを忘れないで」、「〜することを覚えておいて」、「計画を立てましょう」、「エピックを作りましょう」、実装中に見つかったバグ、sdd-tasks によって生成された SDD タスク。

---

階層モデル — Epic / Story / Task / Bug

このスキルは、GitHub Issue Types（ネイティブ）とサブイシュー（ネイティブ）を使用して、 3 階層の階層構造（および独立したタイプとしての Bug）を適用します。 ラベルは後方互換性のために維持されますが、Issue Types が優先されます。

レベル	GitHub Issue Type	期間	親サブイシュー	サブイシューを持つ
Epic	Epic	数週間	なし	Stories
Story	Feature	数日	Epic	Tasks
Task	Task	数時間	Story（または緊急修正の場合は Epic）	なし
Bug	Bug	数時間〜数日	Epic（安定性対応）または影響を受ける Story	なし

判断の目安:

• 1 つの Task は Claude の 1 セッションに相当します。収まらない場合は、Task を装った Story です。分割してください。
• サブイシューのない Story は、受け入れ条件がすでにタスクリストとして機能する場合に限り許容されます（本当に小規模な場合）。
• サブイシューのない Epic は望ましくありません。実際には Story である可能性があります。
• 計画済みの Epic に属さない Bug は、親なしで単独にできます。

Issue Types とラベル

このスキルは、Issue Type が有効な組織では Issue Type と、それに対応する従来のラベル（type/epic、type/feature、type/task、type/bug）の両方を設定します。これにより、新しい階層への段階的な移行中も、古いビューやフィルター、既存の /track のフローを引き続き使用できます。

Issue Type が利用可能かどうかは、COMMANDS.md の Issue-Type detection ブロックを通じて、セッションごとに 1 回検出します。応答が空、またはフィールドがサポートされていない場合は、ラベルのみのモードに切り替え、セッションごとに 1 回ユーザーに警告します。

"この組織では Issue Types が有効になっていません。ラベルに切り替えます — type/epic、 type/feature、type/task、type/bug。ネイティブタイプを有効にするには、 組織の設定 → Issue Types に移動してください。"

gh / GraphQL のコマンドブロックはすべて COMMANDS.md に記載されています。 以下ではステップ ID（例: [track-init §1]）を参照します。このファイルには判断ロジックを、 COMMANDS.md には正確なコマンドを記載しています。

プロセス

事前確認: リポジトリと設定の検出

どのフローを実行する場合も、最初にオーナー／リポジトリを解決します（COMMANDS.md の Pre-flight — detect repo を実行）。 次に、engram でプロジェクト設定を検索します。

• クエリ tracking/{repo-name}/config で mem_search を実行します
• 見つかった場合は mem_get_observation を呼び出し、プロジェクト番号とフィールド ID を取得します
• 見つからず、フローでプロジェクト操作が必要な場合は、先に /track-init を実行するようユーザーに警告します

---

フロー 1: 初期設定 — /track-init

リポジトリごとに 1 回実行します。冪等性があるため、再実行しても安全です。

ステップ 0 — トークンの機能を検出する

[track-init §0] を実行します。失敗した場合は、そこにある表を使って原因を分類してください。すべての失敗がトークンに起因すると決めつけてはいけません。原因ごとに対応が異なります。gh-not-authenticated（§0-auth）、fine-grained PAT（§0-manual）、project スコープの不足（gh auth refresh -s project）、一時的な GitHub／ネットワークエラー（停止して後で再試行し、トークンには触れないでください）、または REST は動作するものの Projects／GraphQL が FORBIDDEN を返す場合は、トークン環境変数の設定ミス（§0-token-env。トークンの種類が違う、または正しいトークンが gh の参照しない名前で設定されている）です。

最もよくあるケース（あなたの場合）: fine-grained PAT は個人アカウントの Projects V2 をサポートしていません（組織のみサポートします）。[track-init §0-manual] では、2 つの方法を案内します。トークンを修正する（推奨: Classic PAT と gh auth を使う。すべてのリポジトリで自動作成が可能になります）か、ボードを手動で作成する（迅速な代替策）です。トークンの修正を推奨してください。ユーザーがトークンを修正したら、ステップ 0 を再実行してからステップ 1 に進みます。手動で作成した場合は、プロジェクト番号を記録し、ステップ 2（ラベル）に進みます。

ステップ 1 — GitHub プロジェクトボードを作成する（自動パス）

ステップ 0 で Projects V2 のサポートが確認された場合のみ、[track-init §1] を実行します（プロジェクトと、Status／Priority／Type の単一選択フィールドを作成します）。

ステップ 2 — ラベルを作成する

[track-init §2] を実行します（type／priority／status ラベル）。冪等です。すでに存在するラベルがあると gh label create は失敗するため、エラーを捕捉して処理を続けます。

ステップ 3 — フィールド ID とオプション ID を取得する

ボードを自動作成した場合（ステップ 1）も、手動作成した場合（ステップ 0）も、[track-init §3] を実行して status_field_id、priority_field_id、type_field_id と各値のオプション ID を取得します。gh project item-edit で必要です。

ステップ 4 — 設定を engram に保存する

以下を指定して mem_save を呼び出します。

• title：「{repo-name} のプロジェクト追跡設定を初期化」
• type：config
• topic_key：tracking/{repo-name}/config
• content：project_number、owner、repo、およびすべてのフィールド ID とオプション ID を構造化マップとして保存

ユーザーに次のように伝えます：「ボードをリンクしました。{owner}/{repo} のプロジェクト #{project_number} です。設定を engram に保存しました。」

---

フロー 2：エピックを計画する — /plan-epic <description>

大規模な機能や取り組みをエンドツーエンドで計画するために使用します。1 つのエピック、そのストーリー、および各ストーリーのタスクを計画します。ユーザーが明示的に確認するまで、GitHub には何も書き込まれません。

このリポジトリの engram 設定が存在しない場合は、最初に /track-init を実行します。

ステップ 1 — テンプレートを読み込む

このスキルディレクトリから本文テンプレートを読み込みます。

• templates/epic.md
• templates/story.md
• templates/task.md

これらが規約となります。このフローで作成するすべての Issue は、これらのテンプレートに従います。

ステップ 2 — Issue Type のサポートを検出する

COMMANDS.md の Issue-Type detection を実行します。結果をセッション中はキャッシュします。 ネイティブの Issue Types モードとラベルフォールバックモードのどちらを使用するか判断します。

ステップ 3 — チャットで階層の提案を Markdown として提示する

次の形式で、1 つのチャットメッセージを作成します。

# Epic: {Title}

Type: Epic | Priority: {P0..P3}
[Epic body following templates/epic.md]

---

## Story 1: {Title}

Type: Feature | Priority: {P0..P3} | Parent: Epic above
[Story body following templates/story.md]

### Task 1.1: {Title}
Type: Task | Parent: Story 1
[Task body following templates/task.md]

### Task 1.2: {Title}
...

---

## Story 2: {Title}
...

提案全体を 1 つのメッセージにまとめて提示します。まだ GitHub API は呼び出さないでください。

ステップ 4 — 確認を待つ

提案メッセージの最後に、次のプロンプトを正確に記載します。

Review the plan above. Reply:
  - "dale" / "go" / "create" → I create all N issues + sub-issue links
  - "edit <X>" / "no <X>"     → tell me what to change, I revise the plan
  - "abort"                   → drop the plan, nothing is created

ユーザーが確認キーワード以外の内容を返信した場合は、編集指示として扱い、修正版の提案を作成します。再度確認を求めます。このリストの確認キーワードが明示されない限り、Issue を作成してはいけません。

ステップ 5 — 順番に作成する

エピック → ストーリー 1 → タスク 1.1 → タスク 1.2 → ストーリー 2 → … の順に Issue を作成します。

各 Issue について：

1. タイトル、本文、ラベル、およびサポートされている場合は Issue Type を指定して、mcp__github__create_issue を呼び出します。
2. 返された Issue 番号を取得します。
3. 提案に親 Issue がある場合は、[sub-issue link] を使ってサブ Issue としてリンクします。
4. [track §3] を使って Issue をプロジェクトボードに追加します。
5. [track §4] を使ってプロジェクトのフィールドを設定します。Status=Backlog、Priority=提案どおり、Type=提案どおり。

ステップ 6 — 結果を報告する

次の形式の要約ブロックを 1 つ表示します。

## Created

Epic #N: {title}
├── Story #N+1: {title}
│   ├── Task #N+2: {title}
│   ├── Task #N+3: {title}
│   └── Task #N+4: {title}
└── Story #N+5: {title}
    ├── Task #N+6: {title}
    └── Task #N+7: {title}

Total: 1 epic, 2 stories, 5 tasks. All added to project board as Backlog.

engram の観察記録を保存します。

• type: architecture、topic_key: tracking/{repo}/epic-{N} を指定して mem_save を呼び出します。content には、エピックのタイトル、子ストーリーとタスクの番号、計画の出典（ユーザーのリクエスト、SDD 仕様の参照など）を記録します。

---

フロー 3：移行を計画する — /plan-migrate

既存のリポジトリに親子関係のない Issue が並ぶフラットなボードがあり、エピック／ストーリー／タスクの階層に再編成する必要がある場合に使用します。

ステップ 1 — 現在の状態を取得する

[migrate-fetch] を実行します。次のヒューリスティックを使って、Issue をレベルごとに分類します。

シグナル	想定されるレベル
タイトルが epic: で始まる、またはラベルが type/epic、または Type=Epic	エピック
タイトルが feat: で始まる、またはラベルが type/feature、または Type=Feature	ストーリー
タイトルが bug: で始まる、またはラベルが type/bug、または Type=Bug	バグ
タイトルが chore:／task: で始まる、またはプレフィックスがない	タスク

ステップ 2 — チャットで階層を提案する

メッセージを 1 つ作成します。

# Migration proposal — {N} open issues

## Epics
- #10 epic: Payments & Monetization
  Will own:
    - #28 feat: Stripe integration for guide bookings
    - {other feats that thematically belong}

- #14 epic: Push Notifications & Engagement
  Will own:
    - #30 feat: push notifications (Expo / Firebase)

## Bugs (orphan — no epic owner)
- #18, #19, #20, ...
  Recommended: create epic "Stability & Bugfixes" to own all of these.
  OR leave as standalone (no parent). Pick one.

## Unclassified
- #X, #Y — could not infer parent confidently. Please tell me.

/plan-epic のステップ 4 と同じ確認プロンプトで締めくくります。

ステップ 3 — 確認後に適用

各親 → 子のペアに対して、[sub-issue link] を実行します。Issue Type をさかのぼって設定する必要がある課題には、[set-issue-type] を実行します。Issue Types がサポートされていない場合は、代わりに従来の type/* ラベルが付いていることを確認します。

ステップ 4 — 報告

/plan-epic のステップ 6 と同じツリー概要を出力します。Engram の観察を保存します。type: architecture、topic_key: tracking/{repo}/migration-{date}。

---

フロー 4：追跡 — 課題を作成してボードに追加

トリガーモデル（ハイブリッド）

状況	動作
/track <description>	確認なしで課題をすぐに作成
複数の項目がある場合、またはバックログセッション中に /track を実行	すべて作成し、一覧を表示して、実行前に確認を求める
sdd-tasks がタスクを生成	タスクごとに課題を 1 件作成することを提案し、確認を求める
ユーザーが将来の作業に言及（「habría que...」、「falta...」、「después hay que...」）	内部で収集します。セッション終了時に「追跡可能な項目を N 件検出しました：[list]。課題として作成しますか？」と提案
「acordate que hay que...」／「remember to...」	課題をすぐに作成することを提案
実装中にバグを発見	type/bug ラベル付きの課題をすぐに作成することを提案

課題の作成手順

ステップ 1 — 重複を確認

[track §1] を実行します。類似する課題がある場合は、それを表示して「課題 #N はすでに存在します：'{title}'。それでも新しく作成しますか？」と尋ねます。

ステップ 2 — MCP 経由で課題を作成

[track §2] を実行します — owner、repo、規約に沿った title（type: description）、本文のテンプレート、および該当する labels を指定して mcp__github__create_issue を呼び出します。本文のテンプレートは [track §2] にあります。

ステップ 3 — プロジェクトボードに追加

[track §3] を実行します（item_id を取得します）。

ステップ 4 — プロジェクトのフィールドを設定

[track §4] を実行します — Engram の設定（tracking/{repo-name}/config）からフィールド／オプション ID を読み込み、Status／Priority／Type を設定します。

ステップ 5 — ユーザーに確認

Created #14: feat: add OAuth with Google — added to board as Backlog/P1-High [Feature]

---

フロー 5：クエリ — /backlog とステータスに関する質問

デフォルト：ボード全体の概要

[backlog §default] を実行し、Status フィールドの値ごとに項目をグループ化します。次を出力します。

## Project Board: {project-name}

### In Progress (2)
- #14 feat: OAuth with Google [P1-High]
- #12 fix: Email validation [P0-Critical]

### Review (1)
- #13 feat: User profile page [P1-High]

### Backlog (3)
- #15 feat: Dashboard redesign [P2-Medium]
- #16 chore: Update dependencies [P3-Low]
- #17 feat: Export to PDF [P2-Medium]

### Done (last 5)
- #11 fix: Login redirect loop [P1-High]

ステータスは次の順に表示します：In Progress → Review → Todo → Backlog → Done（ノイズを避けるため、最後の 5 件のみ）。

絞り込みクエリ

コマンド	適用されるフィルター
/backlog bugs	Type = Bug の項目のみ
/backlog high	Priority = P0-Critical または P1-High の項目のみ
/backlog in-progress	Status = In Progress の項目のみ
/backlog todo	Status = Todo の項目のみ
/backlog review	Status = Review の項目のみ

---

ステータス遷移

手動トリガー：/track move #14 in-progress、/track move #14 review、/track move #14 done。基盤となるコマンド：[status-move]。

自動統合ポイント：

• Claude が課題への対応を開始 → 「In Progress」に移動
• Claude が課題の PR を作成 → 「Review」に移動（branch-pr スキルと統合）
• PR がマージされる／課題がクローズされる → 「Done」に移動

---

ルール

• GitHub Issues + Projects が、何をする必要があるかを示す信頼できる情報源です。バックログ、タスク、ストーリー、バグが対象です。
• Engram は、決定事項、発見事項、技術的なコンテキストに関する信頼できる情報源であり続けます。両者は相互補完的であり、競合するものではありません。
• イシューを重複して作成しないでください。作成前に必ず gh issue list --search を実行してください。
• イシューのタイトルは慣例的な形式に従います：type: description（例：feat: add OAuth、fix: email validation）
• ラベルは小文字を使い、区切り文字に / を使用します：type/feature、priority/high、status/backlog
• 各イシューには、プロジェクトボードで少なくとも Type フィールドを設定する必要があります。
• /track-init は冪等です。2 回実行してもラベルやプロジェクトが重複して作成されないようにしてください。また、gh label create のエラーは適切に処理してください。
• ブートストラップ後、プロジェクト設定（ID）を topic_key: tracking/{repo-name}/config として engram に保存する必要があります。
• gh project item-edit を呼び出す前に、必ず engram からフィールド ID を読み込んでください。見つからない場合は、gh project field-list で再取得してください。
• 一括作成には確認が必要です。複数のイシューを一度に提案するときは、全件を表示し、ユーザーの承認を得てから作成してください。
• タイプや優先度を決めつけず、提案してください。会話から追跡対象の項目を自動検出する場合は、妥当なデフォルトを推定したうえで、作成前にユーザーに確認してください。
• イシューの作成には MCP を優先して使用し（mcp__github__create_issue）、プロジェクトボードの操作にはすべて gh CLI を使用してください。
• /track-init が実行されていない場合（engram の設定がなく、プロジェクトもリンクされていない場合）は、それを検出し、ボードを操作する前に実行するよう提案してください。
• 細粒度 PAT は個人アカウントの Projects V2 をサポートしていません。使用できるのは Classic PAT または組織スコープのトークンのみです。これを検出した場合は、2 つの解決策（§0-manual）を提示してください。トークンを修正する方法（Classic PAT + gh auth。すべてのリポジトリで利用可能になります）を、手動ボードへのフォールバックよりも推奨してください。手動作成だけを唯一の選択肢として提示してはいけません。
• gh がトークンを読み取るのは GH_TOKEN、次に GITHUB_TOKEN の順のみで、環境変数のトークンは gh auth login の設定を上書きします。正しいトークンが別の名前（例：GITHUB_CLASSIC_TOKEN）で設定されていても、無視されます。REST は動作するのに Projects／GraphQL が FORBIDDEN を返す場合は、環境変数の設定ミスを疑ってください（§0-token-env）。Classic PAT を GH_TOKEN に設定し、1 行の GraphQL viewer.projectsV2 クエリで確認してください。このルールでは、トークンの種類、変数名、確認方法を記録し、シークレットの値は記録しないでください。
• 自動作成と手動作成のどちらの経路でも、ステップ 3（ID の取得）で合流します。ボードの作成方法にかかわらず、それ以降のワークフローは同じです。
• /plan-epic は確認を最優先します。完全な階層（Epic + Stories + Tasks）を Markdown でチャットに提案し、ユーザーが確認のキーワード（dale、go、create）を明示的に返信するまで、create_issue を呼び出してはいけません。それ以外の返信は承認ではなく、編集指示として扱います。
• Issue Types が利用できる場合は、それを正式な情報源とします。後方互換性のため、従来の type/* ラベルも併せて設定します。GraphQL の issueTypes クエリでサポート状況を検出し、セッション中は結果をキャッシュしてください。Issue Types がサポートされていない場合は、1 回だけ警告を表示し、ラベルのみのモードに切り替えてください。
• サブイシューのリンクには addSubIssue GraphQL ミューテーションを使用してください。本文にテキスト（「parent: #N」だけではリンクは作成されません）を書いて階層を表現してはいけません。
• 1 つのタスクは Claude の 1 セッションで完了できる範囲にしてください。1 セッションに収まらないタスクは、タスクに見せかけたストーリーです。作成前に分割を提案してください。
• /plan-migrate は、確認なしにイシューを変更しません。/plan-epic と同じく、確認を最優先する方針に従います。分類されていないイシューはユーザーに提示し、自動で割り当ててはいけません。
• バグのイシューは単独でも作成できます（親エピックなし）。または「Stability & Bugfixes」エピックの配下に置くこともできます。リポジトリごとにいずれか一方を選び、一貫性を保ってください。選択した方針は、tracking/{repo}/config の engram 設定に保存します。
• 本文テンプレートは skills/project-tracking/templates/（epic.md、story.md、task.md、bug.md）にあり、イシュー本文の構成に関する唯一の信頼できる情報源です。別の形式を独自に作らないでください。