Create Issue Tree

create-issue-tree

要件・タスク一覧から Phase 分割された GitHub Issue ツリーを新規作成する。 ルート（トラッキング issue）→ Phase 親 issue → issue → sub-issue の 4 階層を構築し、implement-issue-tree が post-order DFS で消化できる構造を維持する。

ルート issue 本文の運用ルール「実行順は sub-issues リスト順が正」は既定では post-order の優先度に留まり、並列実行時に後続 Phase が前 Phase を追い越す余地がある。Phase 完了を厳密に順序保証したい場合は implement-issue-tree 実行時に phaseGate: true を指定する（Issue #494。implement-issue-tree の SKILL.md 参照）。

使い方

引数としてタスク要件テキストまたはファイルパスを渡す。 --phase オプションで特定 Phase のみ起票することもできる（大規模ツリーを段階的に起票する場合）。 2 回目以降の部分起票では --root で既存ルート issue 番号を渡し、同じツリーに継ぎ足す （指定しないと新しいルート issue が重複作成される）。 --milestone オプションで起票する issue 全件に割り当てる GitHub Milestone を指定できる （--root 指定時は省略可。既存ルートの milestone を自動継承する）。 --granularity オプションで 1 issue に収める実装時間の上限を指定できる。 2h・4h・1h のように正整数+時間単位（h）で指定する。優先順位は `--granularity` 明示 > `--root` 指定時の既存ルート issue 本文マーカー > 既定 `2h` の順 （Step 1 で確定）。決定した値はルート issue 本文へ <!-- granularity: Nh --> として 永続化され、同じルートに対する update-issue-tree 実行時に継承される。

create-issue-tree "ユーザー認証機能を実装する"
create-issue-tree requirements.md
create-issue-tree requirements.md --phase 2 --root 123
create-issue-tree requirements.md --milestone "v2.0"
create-issue-tree requirements.md --granularity 4h

前提条件

• gh CLI がインストールされ、認証済みであること（gh auth status で確認）
• 対象リポジトリへの Issue 書き込み権限があること

フロー

Step 1: 要件を分析してタスクを分解する

入力テキストまたはファイルから要件を読み込み、以下の観点でタスクを分解する。

• 粒度基準: 1 issue は実装 `${GRANULARITY}`（既定 2h・`--granularity` で変更可）程度に収める。 超えると判断した場合は sub-issue に再分解する

--granularity の値は代入前に Claude 側でも同じ正規表現（^[1-9][0-9]*h$）で検証し、 不一致ならこのフェンスを実行せずユーザーに再指定を求める（未信頼値を生成済みシェルへ 埋め込まない）。優先順位は使い方節のとおり、`--granularity` > ルートのマーカー > 既定 2h の順。

# --granularity で渡された時間を実際の値で代入する（実行時に Claude が置き換える）
# 例: --granularity 4h が指定された場合 → GRANULARITY_ARG="4h" / 未指定の場合は空文字
GRANULARITY_ARG="<--granularity で渡された時間（未指定なら空文字）>"
# --root で渡された Issue 番号（未指定なら空文字）。Step 2.5 で ROOT_NUMBER として
# OPEN 検証込みで正式に確定する前に、粒度継承の参照のためここでも読む
ROOT_ARG="<--root で渡された Issue 番号（未指定なら空文字）>"

if [[ -n "${GRANULARITY_ARG}" ]]; then
  GRANULARITY="${GRANULARITY_ARG}"
  GRANULARITY_SOURCE="--granularity 引数"
elif [[ -n "${ROOT_ARG}" ]]; then
  # ルート本文の取得失敗とマーカー不在は分離する。取得失敗は「粒度を既定へ倒さず中止」する
  # （gh issue view 自体の失敗を || true で握り潰すと、権限エラー・issue 不在等を
  # 「マーカーなし」と誤読して既定 2h へサイレントに倒れてしまうため）
  ROOT_BODY=$(gh issue view "${ROOT_ARG}" --json body --jq '.body') \
    || { echo "エラー: ルート issue #${ROOT_ARG} の本文を取得できません。粒度を既定へ倒さず中止します。"; exit 1; }
  # 既存ルート本文の <!-- granularity: Nh --> マーカーから継承する。マーカーが無ければ既定 2h
  # （|| true は grep のマーカー不在にのみ掛かる。gh issue view 自体の失敗は上で既に処理済み）
  ROOT_GRANULARITY=$(printf '%s\n' "${ROOT_BODY}" \
    | grep -oE '<!-- granularity: [1-9][0-9]*h -->' | head -1 | grep -oE '[1-9][0-9]*h' || true)
  if [[ -n "${ROOT_GRANULARITY}" ]]; then
    GRANULARITY="${ROOT_GRANULARITY}"
    GRANULARITY_SOURCE="ルート issue #${ROOT_ARG} のマーカー"
  else
    GRANULARITY="2h"
    GRANULARITY_SOURCE="既定値"
  fi
else
  GRANULARITY="2h"
  GRANULARITY_SOURCE="既定値"
fi

# 許可する構文は正整数 + h のみ（例: 1h / 2h / 4h）。引用符・空白・コマンド置換・0h・単位なしは
# ここで拒否する（ROOT_GRANULARITY はマーカー抽出時点で同じ正規表現を通しているが、
# GRANULARITY_ARG はユーザー入力の生値のため、代入元によらずこの検証を必ず通す）
if ! printf '%s' "${GRANULARITY}" | grep -qE '^[1-9][0-9]*h$'; then
  echo "エラー: --granularity の値 '${GRANULARITY}' は不正です（許可: 正整数+h、例 2h）。中止します。"
  exit 1
fi

# 確定値と由来を必ず出力する（既定 2h と読み替えないことをここで可視化する）
echo "粒度基準: ${GRANULARITY}（由来: ${GRANULARITY_SOURCE}）"

以降の Step は Step 1 で出力された GRANULARITY の値を使う（既定 2h と読み替えない）。

• 各タスクの依存関係・実行順を把握する
• タスク数を集計し、Phase 分割の要否を判断する（目安: 10 件超で Phase 分割を検討）

分解結果をユーザーに提示し、Phase 構成・issue 数について確認を取る。 --phase オプションが指定されている場合は該当 Phase のタスクのみ対象とする。

Step 2: Phase 構成を設計する

タスク数・依存関係をもとに Phase を設計する。

• Phase は独立して開発可能な単位で分割する（例: Phase 1 基盤・Phase 2 機能・Phase 3 改善）
• 各 Phase に親 issue タイトル（Conventional Commits 形式推奨）を割り当てる
• 全体をまとめるルート（トラッキング）issue のタイトルを決定する
• 例: chore(global): 全 open issue の Phase 別トラッキング (YYYY-MM-DD)

タスクが少数（Phase 分割不要）の場合はルート issue + 子 issue の 2 階層構成にする。

Step 2.5: milestone を決定する

このツリーに割り当てる GitHub Milestone を決定する。ルート・Phase 親・子・sub-issue の 全件に同一 milestone を適用する（ツリー単位で 1 milestone）。

--root が指定されている場合は、ここで先に ROOT_NUMBER を設定し、milestone の 継承・書き込みを行う前に OPEN 状態を検証する（closed なルートの milestone を 書き換えてから中断する事故を防ぐ。Step 3 側では再代入・再検証しない）。

# --root で渡された Issue 番号を実際の値で代入する（実行時に Claude が置き換える）
# 例: --root 123 が指定された場合 → ROOT_NUMBER="123" / --root 未指定の場合 → ROOT_NUMBER=""
ROOT_NUMBER="<--root で渡された Issue 番号（未指定なら空文字）>"

# --root 指定時のみ: OPEN でなければ milestone 操作より前に中止する
# （新規ツリー作成で ROOT_NUMBER が空の場合はこの検証をスキップする）
if [[ -n "${ROOT_NUMBER}" ]]; then
  ROOT_STATE=$(gh issue view "${ROOT_NUMBER}" --json state --jq '.state')
  if [[ "${ROOT_STATE}" != "OPEN" ]]; then
    echo "エラー: ルート issue #${ROOT_NUMBER} は OPEN ではありません (state: ${ROOT_STATE})。中止します。"
    exit 1
  fi
fi

milestone 非運用リポジトリのガード: --milestone が明示されていない場合、リポジトリに milestone が 1 件も存在しなければ（closed 含む）milestone 非運用リポジトリとみなし、 以降の確認をすべてスキップして MILESTONE は空のまま Step 3 へ進む （milestone を使わないリポジトリの起票フローに確認を増やさない）。

MILESTONE_COUNT=$(gh api "repos/{owner}/{repo}/milestones?state=all" --jq 'length')
# MILESTONE_COUNT が 0 かつ --milestone 未指定なら、このステップの残りをスキップする

優先順位は `--milestone` > `--root` からの継承 > ユーザーへの確認 の順。

• --milestone が指定されている場合: その値をそのまま MILESTONE として使用する （--root も同時指定されている場合、ルート側の milestone より --milestone を優先する。 ルート側と異なる値の場合は、ルートの milestone も合わせて更新してよいかユーザーに確認する。 更新しないと回答された場合はツリー内で milestone が混在する点を伝えたうえで続行する）
• --milestone 未指定かつ --root 指定時: 既存ルートの milestone を自動継承する （milestone が取得できた場合のみユーザーへの確認は不要）

  MILESTONE=$(gh issue view "${ROOT_NUMBER}" --json milestone --jq '.milestone.title // empty')

MILESTONE が空（既存ルートに milestone が未設定）の場合は自動継承とみなさず、 「どちらも未指定の場合」と同じユーザー確認フローへ進む（リポジトリに milestone が 存在するのにサイレントに milestone なしで進行しない。milestone が 1 件もない場合は 冒頭の非運用ガードが先に働くため、この確認には到達しない）。

• どちらも未指定の場合、または --root 指定時に継承すべき milestone が空だった場合: milestone を割り当てるかユーザーに確認する。 割り当てる場合はオープン中の milestone 一覧を提示して選ばせるか、新規 milestone 名の 入力を受け付けて MILESTONE に設定する。割り当てないと回答されたら MILESTONE は 空のまま Step 3 以降へ進む（issue は milestone なしで作成される）。

  gh api "repos/{owner}/{repo}/milestones" --jq '.[] | select(.state=="open") | .title'

ユーザーが一覧にない新規 milestone 名を入力した場合、gh issue create --milestone は 既存の milestone 名しか受け付けないため、使用前に milestone 自体を作成する。 同名の closed milestone が既に存在すると作成が 422（already_exists）で失敗するため、 その場合は reopen するか別名にするかをユーザーに確認する。

  gh api --method POST "repos/{owner}/{repo}/milestones" -f "title=${MILESTONE}"

--root 指定時に継承すべき milestone が空でこのフローに合流した場合、決定した MILESTONE を既存ルート issue にも反映する（子だけ milestone が付き、ルートが 未設定のまま残る不整合を防ぐ）。

  if [[ -n "${ROOT_NUMBER}" && -n "${MILESTONE}" ]]; then
    gh issue edit "${ROOT_NUMBER}" --milestone "${MILESTONE}"
  fi

Step 3: ルート（トラッキング）issue を作成する

ルート issue はツリー全体の進捗を管理するトラッキング issue として作成する。ルート issue 自体には phase ラベルは付与しない（Phase 親以下の issue にのみ付与する）。

`--root` 指定時は新規作成をスキップする。 --phase での 2 回目以降の部分起票で ルート issue を重複作成しないため、Step 2.5 で設定・OPEN 検証済みの ROOT_NUMBER を そのまま再利用する（ここで再代入・再検証しない）。

--root 未指定の場合のみ、以下でルート issue を新規作成する。

# MILESTONE が空でなければ --milestone を付与する（Step 2.5 で決定済み）
ROOT_ARGS=(--title "chore: 全 open issue の Phase 別トラッキング ($(date +%Y-%m-%d))")
if [[ -n "${MILESTONE}" ]]; then
  ROOT_ARGS+=(--milestone "${MILESTONE}")
fi

# gh issue create は issue URL を stdout に出力する（--json 非対応）。URL 末尾から番号を抽出する
ROOT_URL=$(gh issue create "${ROOT_ARGS[@]}" \
  --body "$(printf '<!-- granularity: %s -->\n' "${GRANULARITY}"; cat <<'EOF'
## 概要

全 open issue を Phase 別に 1 ツリーへ整理する。各 Phase 親 issue を sub-issues として紐付け。

## Phase 別実装計画

| Phase | 親 issue | 直下 | 総 open 件数 |
|-------|----------|------|-------------|
| (作成後に更新) | | | |

## 運用

- 新規 issue は起票時に Phase 親へ紐付ける
- 実行順は sub-issues リスト順が正
- closed 親の下に open issue を残置しない
- implement-issue-tree が post-order DFS で消化可能な構造を維持する
EOF
)")
ROOT_NUMBER=$(printf '%s' "${ROOT_URL}" | grep -oE '[0-9]+$')
echo "ルート issue: ${ROOT_NUMBER}"