Create UI Design

UI実装Issue $0 に対して、実装に先立って Pencil のデザイン（.pen）を作成・更新し、デザインのみの独立したPRを作るスキル。各フェーズの「完了条件」を満たさないまま次のフェーズに進まないこと。

このスキルはコードを実装しない。差分は .pen とスナップショット PNG のみ。実装は本デザインPRのマージ後に exec-issue が担当する。

Instructions

GitHub アクセス

本スキルの GitHub 参照/更新は gh コマンドを優先し、gh が使えない場合に GitHub MCP へフォールバックする（本文中の gh コマンド例はそのまま第一手段として読む）。クラウド実行時のみ優先順位が逆転して GitHub MCP が第一手段になるが、その指示は起動プロンプトで渡されるので、指示が無ければローカル実行として扱う。判定手順・gh ↔ MCP の対応表・MCP に代替が無い操作は ${CLAUDE_PLUGIN_ROOT}/references/github-access.md を参照する。

実行モードの制約

本スキル固有のリスク: 本スキルは claude-task-worker の create-ui-design ワーカー（cc-create-ui-design ラベル）から自動起動され、ワーカーはスキルプロセスの同期完了を根拠にラベル遷移（cc-ui-design-pr-created の付与、デザインPRへの cc-ui-design 付与と、uiDesign.yolo が true の場合の cc-triage-scope 付与）を進める。処理が未完のままターンを終えると、デザインPR未作成のままトリガーラベルが外れてIssueが停滞したり、デザインなしで実装フェーズへ流れたりする状態壊れが起きる。

プリアンブル（! インライン実行）に失敗しうるコマンドを置かないこと: プリアンブルのコマンドが失敗すると、セッションはモデル未起動のまま何も出力せず exit 0 で終了し、ワーカーが空振り実行を延々と繰り返す。pencil の疎通確認はフェーズ0の本文で行う。

スコープと出力の規律

• Issueが要求している画面・状態だけをデザインする: 「あると良さそう」で画面・セクション・状態バリエーションを足さない（デザインの膨張はそのまま実装スコープの膨張になる）。気づいた提案は .pen に入れず、デザインPRの本文に1行で挙げるだけにする
• 成果物は .pen とスナップショットPNGのみ
• PR本文・Issueコメント・最終報告は必要な実質だけ: 各セクション1〜3行を目安にし、言い換え・埋め草を書かない。該当がない項目は「なし」の1語で済ませる
• 委譲は pencil-design-updater 1体。検証目的で別のサブエージェントを起動せず、成果物の確認は git status --short とスナップショットの確認でメインが自分で行う

フェーズ0: 事前チェック

0-1. 作業ディレクトリとIssueの確認

• pwd で .claude/worktrees/ 配下にいることを確認する。worktree外なら 中断（デフォルトブランチで作業してはならない）。ただし起動プロンプトに「このセッションはクラウド実行のため worktree を持たず、cwd はリポジトリルートである」旨の指示がある場合はこの確認をスキップする — クラウド実行ではワーカーが worktree を作らないため常に worktree 外になる。ガードの目的である「デフォルトブランチで作業しない」は次の確認で担保する。指示が無く worktree 外でもある場合は従来どおり 中断 する（クラウドかもしれないという推測で続行しない）
• bash ${CLAUDE_PLUGIN_ROOT}/scripts/gh-compat.sh default-branch でデフォルトブランチ名を取得し、git rev-parse --abbrev-ref HEAD の現在ブランチと比較する。一致する場合は 中断。デフォルトブランチ名の取得に失敗した場合も 中断 する（fail-safe）
• gh issue view $0 --json number,title,body,state,labels,comments でIssueが OPEN であることを確認する（GitHub MCP が使える場合は issue_read（method: get。コメント取得は get_comments）を使う。以下はフォールバック）。CLOSEDなら 中断
• git status --short で未コミット変更があれば git stash push -u -m "create-ui-design auto-stash $0" で自動退避し、その旨を最終報告に明記する

0-2. Pencil の疎通確認

pencil version
pencil status

いずれかが失敗する（未インストール・未認証など）場合は、デザインを作らずに以下を実行して終了する。この場合デザインPRは作らない。

1. Issue に理由（実行したコマンドとエラー出力の要約）をコメントする

   gh issue comment $0 --body-file - <<'EOF'
   ## Pencil を利用できないためデザインを作成できません（要人手確認）
   
   `create-ui-design` は Pencil CLI が必要ですが、実行環境で利用できませんでした。
   
   ## 実行したコマンドとエラー
   
   ~~~text
   <コマンドとエラー出力の要約>
   ~~~
   
   ## 対応後の進め方
   
   - Pencil をインストール・認証したうえで、`cc-need-human-check` ラベルを外し `cc-create-ui-design` ラベルを付け直してください
   - デザインなしで実装へ進める場合は、`cc-need-human-check` ラベルを外し `cc-ui-design-ready` と `cc-exec-issue` ラベルを付けてください
   EOF
   

2. gh issue edit $0 --add-label "cc-need-human-check" を実行する
3. 最終報告に「Pencil 利用不可・cc-need-human-check 付与済み」と原因を明記して終了する

0-3. デザイン配置先の解決

リポジトリ直下の claude-task-worker.json の uiDesign.designDir を読む。既定値 designs を使ってよいのは「ファイルが存在しない」場合、または「ファイルは存在するがキー未設定（jq が null を返す）」場合のみ。jq がexit code非0で終わる場合（JSON構文エラー・権限エラーなど）は、意図した designDir と異なる場所へ成果物を作る危険があるため、既定値へフォールバックせず安全側に倒す。

if [ ! -f claude-task-worker.json ]; then
  DESIGN_DIR="designs"
elif DESIGN_DIR=$(jq -r '.uiDesign.designDir // "designs"' claude-task-worker.json); then
  :
else
  JQ_EXIT=$?
  echo "failed to read claude-task-worker.json (jq exit ${JQ_EXIT})" >&2
  DESIGN_DIR=""
fi

DESIGN_DIR が空文字列のまま（=上記の jq 失敗）の場合は、デザインを作らずフェーズ0-2と同じ手順（Issueへの理由コメント + cc-need-human-check 付与。デザインPRは作らない）でスキルを終了する。以降「フェーズ0-2と同じ手順」はこの手順を指す。

完了条件: worktree内・Issue OPEN・pencil 疎通OK・DESIGN_DIR が空文字列でなく確定していること。

フェーズ1: デザイン要件の抽出

フェーズ0-1で取得したdescriptionとコメント履歴から、以下を抽出する。

• 対象画面・コンポーネント（何を作る/変えるのか）
• 構成要素（要素の一覧と階層・配置）
• 状態バリエーション（空・ローディング・エラー・選択中・権限差など、Issueが要求するもの）
• 既存デザイン・既存実装との関係（既存画面の改修なのか新規なのか）

デザイン不要と判明した場合

「このIssueはUI変更を伴わない」と判断した場合（サーバーサイドのみ、文言差し替えのみ、レイアウトに影響しない微修正など）は、デザインを作らずに以下を実行して終了する。

1. description に「デザイン不要」マーカーを書き込む。この書き込みを省略してはならない（マーカーが無いと、後続の再トリアージで同じIssueが再びデザイン先行フローへ振り分けられ、判定が無限に繰り返される）。

   既存本文は必ず保持し、## UIデザイン セクションが既にある場合は重複追記せず置換する。無ければ本文末尾に追記する。フォーマットは以下の固定形式にする（UIデザインは不要 の行は triage-created-issue / exec-issue が文字列一致で検出するため、文言を変えない）。

   ## UIデザイン
   
   UIデザインは不要（`create-ui-design` が判定）。参照すべき `.pen` は無く、コードのみを実装する。
   
   - 判断理由: <UI変更を伴わないと判断した根拠を1-2行で>
   

   GitHub MCP が使える場合は本文取得に issue_read（method: get）を使う。以下は MCP 利用不可時のフォールバック。

   BODY_FILE="$(mktemp -t issue-$0-body-XXXXXX.md)"
   trap 'rm -f "$BODY_FILE"' EXIT
   ORIGINAL_BODY="$(gh issue view $0 --json body --jq .body)"
   # 既存の ## UIデザイン セクションを除去した本文 + 上記セクション を BODY_FILE に書き出す
   <組み立て処理>
   gh issue edit $0 --body-file "$BODY_FILE"
   gh issue view $0 --json body --jq .body | grep -F 'UIデザインは不要'
   

   grep がヒットしない場合はもう一度だけ書き込みを試し、それでも反映されなければフェーズ0-2と同じ手順（cc-need-human-check 付与）で終了する（マーカー無しで実装へ戻すとトリアージのループになるため）。

2. Issue に判断理由をコメントする

   gh issue comment $0 --body-file - <<'EOF'
   ## UIデザインは不要と判断しました
   
   ## 判断理由
   <UI変更を伴わないと判断した根拠を具体的に>
   
   description の `## UIデザイン` セクションにも同じ判断を記録しました。デザインPRは作成せず、そのまま実装フェーズへ進めます。
   EOF
   

3. 実装トリガーを付与する（cc-ui-design-ready は付けない。exec-issue のフェーズ0ガードは同ラベルがあると .pen の実パス行を要求するため、デザイン不要経路では付与せず cc-exec-issue のみで実装へ戻す）

   gh issue edit $0 --add-label "cc-exec-issue"
   

   cc-exec-issue の付与は create-ui-design ワーカーが「デザイン不要で正常終了した」と判定する根拠でもある。付け忘れるとデザインPR不在として cc-need-human-check が付き、Issueが不要に停止する。

4. 最終報告に「デザイン不要・実装フェーズへ復帰」と理由を明記して終了する

完了条件: 対象画面・構成要素・状態バリエーションが列挙できているか、デザイン不要として終了していること。

フェーズ2: 既存デザインの調査

既存の .pen が1つでもあれば、それを更新する。新規ファイルを作るのは、リポジトリに .pen が1つも無い場合だけ。新しい画面・状態も、既存 .pen の中へフレーム（ページ）として追加する。Issue 番号や画面名を付けた別ファイルを並べると、デザインが複数ファイルに分散して同じ画面・コンポーネントが二重管理になり、後続のデザイン・DESIGN.md 更新がどれを正とすべきか判断できなくなるため。

リポジトリで管理されている .pen を列挙する（DESIGN_DIR 直下に限らない。配下のサブディレクトリや DESIGN_DIR 外に置かれた既存ファイルも更新対象の候補にする）。

git ls-files '*.pen'

• 1件以上ある場合 → 更新。更新するファイルを次の順で1つに決める

  1. Issue の description（## UIデザイン セクション等）やコメントで参照されている .pen
  2. 対象画面・機能を収録している .pen（inspect-pencil-node スキルで各ファイルのトップレベル Node を見て判断する）
  3. どれにも当てはまらなければ、最も多くの画面を収録している（＝主たる）.pen。判断が割れたら DESIGN_DIR 直下のものを優先する

  決めたファイルは inspect-pencil-node スキルで現状の構造・スタイルを取得してからフェーズ3へ渡す

• 0件の場合のみ → 新規作成

.pen は平文JSON（.pen は平文JSONで、構造は ${CLAUDE_PLUGIN_ROOT}/references/pen-format.md が定義する）なので Read / jq で読めるが、レイアウト解決後のサイズやスクリーンショットが必要な構造の把握は inspect-pencil-node スキル経由で行う。編集は手でJSONを書き換えず edit-pencil-design の execute で行う。

完了条件: 「更新する既存パス」または「新規作成するパス」のいずれかが確定していること。

• 更新: 既存パスをそのまま上書き（git ls-files '*.pen' が1件以上なら必ずこちら）
• 新規: <DESIGN_DIR>/<kebab-slug>.pen（<kebab-slug> はプロダクト・アプリ全体を表す短い英小文字ケバブケース。後続のIssueもこのファイルを更新していくため、Issue番号や個別画面名をファイル名に含めない）

フェーズ3: デザインの作成・更新

pencil-design-updater エージェントに委譲する（.pen の編集は edit-pencil-design スキル経由でのみ行う。直接編集は禁止）。

ブリーフィングには以下をすべて含める（サブエージェントは会話履歴を持たないため）:

【背景】Issue #$0「<title>」: <要約 1-2行>

【対象ファイル】
<新規作成なら作成先パス / 更新なら既存パス>（新規/更新の別を明記）

【デザインする内容】
- 対象画面・コンポーネント: <フェーズ1の抽出結果>
- 構成要素と配置: <要素の一覧と階層>
- 状態バリエーション: <空・ローディング・エラー等。無ければ「なし」>

【既存デザインとの関係】
<更新の場合は inspect-pencil-node で把握した現状構造の要約。新規なら「新規作成」>

【完了条件】
- `edit-pencil-design` スキル経由で `.pen` を作成/更新すること（直接編集は禁止）
- 編集・作成したNodeのスクリーンショットを `<DESIGN_DIR>/snapshots/` に PNG 出力すること
- `.pen` とスナップショット PNG 以外のファイルを変更しないこと
- 更新の場合は対象ファイルを `--in` / `--out` 同パスで上書きし、別名の `.pen` を新規作成しないこと（新しい画面は対象ファイル内のフレームとして追加する）

【作業ディレクトリ】
<worktreeの絶対パス>

サブエージェントの完了報告を鵜呑みにせず、git status --short で .pen とスナップショット PNG が実際に生成・更新されていることを検証する。更新の場合は、対象の既存 .pen が変更（M）になっていること、未追跡（??）の .pen が増えていないことも確認し、別ファイルが作られていたらそのファイルを削除して（本スキルが作った未追跡ファイルなので破棄してよい）既存ファイルの更新として再委譲する。生成されていなければ再委譲する（最大2回）。2回試行しても生成できない場合は、失敗ログを含めフェーズ0-2と同じ手順で終了する。

完了条件: .pen とスナップショット PNG が git status --short に現れており、他のファイルに差分がないこと。更新の場合は、変更された .pen がフェーズ2で決めた既存ファイルだけであること。

フェーズ4: デザインブランチの作成とpush

再実行時に既存ブランチが残っていても失敗しないよう、先に存在確認してから作成/切り替えを分岐する。

BRANCH="cc-ui-design-$0"
git fetch origin "${BRANCH}" 2>/dev/null || true
if git rev-parse --verify --quiet "refs/remotes/origin/${BRANCH}" >/dev/null; then
  git switch -C "${BRANCH}" "origin/${BRANCH}"
elif git rev-parse --verify --quiet "refs/heads/${BRANCH}" >/dev/null; then
  git switch "${BRANCH}"
else
  git switch -c "${BRANCH}"
fi
git status --short | awk '{print $2}' | grep -E '\.pen$|/snapshots/.+\.png$' | xargs -r git add --
git status --short

ステージするのは .pen ファイルと snapshots/ 配下のPNGファイルのallowlistのみとし、git add "${DESIGN_DIR}" のようなディレクトリ丸ごとaddは行わない。ステージ後、git status --short を再確認し、allowlist外のファイル（ステージされずに残っている変更・元々trackedな変更として存在していたもの、いずれも含む）が1件でも残っている場合は、それらを git restore --staged / git checkout -- で破棄してはならない（ユーザーの意図しないtracked変更まで巻き込んで消し去る危険があるため）。破棄せず以下を実行して終了する。

NON_ALLOWED=$(git status --short | awk '{print $2}' | grep -vE '\.pen$|/snapshots/.+\.png$' || true)

NON_ALLOWED が空でない場合は、フェーズ0-2と同じ手順でスキルを終了する。空の場合のみコミット・pushへ進む。

cc-ui-design-$0 は本スキルの実行だけが書き込むブランチのため、リモートに同名ブランチが残っていても --force-with-lease で上書きして安全に収束させる。

git commit -m "design: Issue #$0 のUIデザインを追加"
if git ls-remote --exit-code origin "${BRANCH}" >/dev/null 2>&1; then
  git fetch origin "${BRANCH}"
  git push --force-with-lease -u origin "${BRANCH}"
else
  LS_REMOTE_STATUS=$?
  if [ "${LS_REMOTE_STATUS}" -eq 2 ]; then
    git push -u origin "${BRANCH}"
  else
    echo "failed to check remote branch existence (exit ${LS_REMOTE_STATUS}), possibly auth/network error" >&2
    exit 1
  fi
fi

git ls-remote --exit-code は「リモートに一致する参照がない」場合のみ exit code 2 を返す（認証・ネットワーク失敗など他の異常は 2 以外）。exit 2 ならリモート未存在と確定できるため素の push -u に進み、それ以外は原因不明のエラーとして即座に失敗させる。

push（またはリモート存在確認）に失敗した場合はエラー出力を最終報告に含め、フェーズ0-2と同じ手順で終了する。

完了条件: cc-ui-design-$0 ブランチが remote に存在すること。

フェーズ5: デザインPRの作成

ベースブランチは実装PRと揃える（Epic配下のIssueでは、デザインが実装ブランチに存在しない事態を防ぐため）。

parent の取得は Issue Dependencies（sub-issue）系のフィールドであり、MCP 側の対応が不定のため gh-compat.sh issue-parent（REST優先・失敗時のみ gh へフォールバック）を使う。ログインユーザー取得（gh api user）は GitHub MCP が使える場合は get_me を使う。

BASE_BRANCH=""
if ! PARENT=$(bash ${CLAUDE_PLUGIN_ROOT}/scripts/gh-compat.sh issue-parent "$0"); then
  echo "failed to resolve issue parent" >&2
  exit 1
fi
if [ -n "${PARENT}" ] && git rev-parse --verify --quiet "refs/remotes/origin/cc-epic-${PARENT}" >/dev/null; then
  BASE_BRANCH="cc-epic-${PARENT}"
else
  BASE_BRANCH=$(git symbolic-ref --short refs/remotes/origin/HEAD | sed 's@^origin/@@')
fi

PR の作成は gh-compat.sh create-pr だけで行う（gh pr create は GraphQL 経由でクラウドでは 403 になり、GitHub MCP の create_pull_request は assignees の引数を持たない）。PR本文は --body-file - + heredoc（<<'EOF' クォート版）で渡す。プレースホルダは heredoc に渡す前に実値へ置換しておくこと。

bash ${CLAUDE_PLUGIN_ROOT}/scripts/gh-compat.sh create-pr \
  --title "design: <Issueタイトル>" \
  --base "${BASE_BRANCH}" \
  --assignee "@me" \
  --body-file - <<'EOF'
## 概要
Issue #$0「<Issueタイトル>」のUIデザインです。実装は含まず、`.pen` とスナップショットPNGのみを変更しています。

## デザインの意図
<なぜこの画面構成にしたのかを1-3行で>

## 主要な構成
- <要素・レイアウトの説明>

## 状態バリエーション
- <空・ローディング・エラー等。無ければ「なし」>

## スナップショット
- `<DESIGN_DIR>/snapshots/<node>.png`

Refs #$0
EOF

Closes #$0 / Fixes #$0 などの closing keyword は絶対に使わない。 デザインPRのマージで実装Issueが閉じてしまい、実装フェーズへ進めなくなるため。参照は必ず Refs #$0 にする。

ラベルは付与しない（cc-ui-design はワーカーが onCompleted で付与する。cc-triage-scope も同様にワーカー側の担当で、claude-task-worker.json の uiDesign.yolo が true の場合のみ付与される）。

PR作成の検証

GitHub MCP が使える場合は list_pull_requests を使う。以下は MCP 利用不可時のフォールバック。

gh pr list --head "cc-ui-design-$0" --state open --json number,url

• PRが実在する場合: そのURLを最終報告に含めて正常終了する
• PRが実在しない場合: フェーズ0-2と同じ手順（コメントにはPR未作成の旨と原因を書く）で終了する

完了条件: cc-ui-design-$0 を head とするOpen PRの実在が確認できていること。

フェーズ6: 最終報告

以下を1-5行で報告して終了する。

• 作成/更新した .pen のパス（新規/更新の別）
• 出力したスナップショット PNG のパス
• デザインPRのURLとベースブランチ
• （該当時）デザイン不要と判断した理由、または cc-need-human-check を付与した理由

中断条件

以下のいずれかに該当する場合のみ、理由を1-2行で出力して即中断する。

• 引数が空、または Issue 番号として解釈できない
• worktree外で実行されている
• gh issue view でIssueが見つからない、または CLOSED

注意事項

• コードを実装しない: 差分は .pen とスナップショット PNG のみ
• .pen を直接編集しない: 編集は pencil-design-updater エージェント（edit-pencil-design スキル）経由、読み取りは inspect-pencil-node スキルに限る
• closing keyword を使わない: PR本文の Issue 参照は Refs #$0 のみ
• 未完の処理を残したまま完了報告してターンを終えない: ワーカーがデザインPR未作成のまま完了扱いでラベル遷移を進めてしまう
• ユーザーに判断を求めない: 中断条件以外はすべて本スキル内のルールで自動決定し、曖昧な場合は安全側（デザインを作らず cc-need-human-check に落とす側）を選んで根拠を最終報告に明記する