shirokuma-docs 0.1.0-alpha.1

package/plugin/shirokuma-skills-ja/skills/github-project-setup/SKILL.md

@@ -0,0 +1,206 @@
+---
+name: github-project-setup
+description: GitHub ProjectのStatus、Priority、Type、Sizeフィールド初期設定を自動化します。「project setup」「プロジェクト作成」「GitHub Project初期設定」、カンバンワークフローで新規プロジェクト開始時に使用。
+allowed-tools: Bash, Read, Glob
+---
+
+# GitHub プロジェクトセットアップ
+
+GitHub Project の初期設定を自動化。Status ワークフロー、Priority、Type、Size カスタムフィールドを含む。
+
+## いつ使うか
+
+- 新しい GitHub Project を作成する場合
+- カンバンワークフローをセットアップする場合
+- 「project setup」「プロジェクト作成」「GitHub Project 初期設定」
+
+## ワークフロー
+
+### ステップ 1: 権限確認
+
+```bash
+gh auth status
+```
+
+権限が不足している場合、以下を実行するよう案内:
+
+```bash
+gh auth refresh -s project,read:project
+```
+
+### ステップ 2: リポジトリ情報取得
+
+```bash
+OWNER=$(gh repo view --json owner -q '.owner.login' 2>/dev/null)
+REPO=$(gh repo view --json name -q '.name' 2>/dev/null)
+```
+
+### ステップ 3: プロジェクト作成
+
+```bash
+PROJECT_NAME="${1:-$REPO}"
+gh project create --owner $OWNER --title "$PROJECT_NAME" --format json
+```
+
+### ステップ 4: リポジトリにリンク
+
+```bash
+gh project link $PROJECT_NUMBER --owner $OWNER --repo $OWNER/$REPO
+```
+
+リポジトリの Projects タブからアクセス可能になる。
+
+### ステップ 5: フィールド ID 取得
+
+```bash
+PROJECT_NUMBER=$(gh project list --owner $OWNER --format json | jq -r '.projects[0].number')
+FIELD_ID=$(gh project field-list $PROJECT_NUMBER --owner $OWNER --format json | jq -r '.fields[] | select(.name=="Status") | .id')
+PROJECT_ID=$(gh project view $PROJECT_NUMBER --owner $OWNER --format json | jq -r '.id')
+```
+
+### ステップ 6: 全フィールド設定
+
+会話から言語を自動検出してセットアップスクリプトを使用:
+
+```bash
+python scripts/setup-project.py \
+  --lang={en|ja} \
+  --field-id=$FIELD_ID \
+  --project-id=$PROJECT_ID
+```
+
+**作成されるフィールド**:
+
+| フィールド | オプション |
+|-----------|-----------|
+| Status | Icebox → Backlog → Spec Review → Ready → In Progress ⇄ Pending → Review → Testing → Done / Not Planned → Released |
+| Priority | Critical / High / Medium / Low |
+| Type | Feature / Bug / Chore / Docs / Research |
+| Size | XS / S / M / L / XL |
+
+[scripts/setup-project.py](scripts/setup-project.py) に言語辞書あり。
+
+### ステップ 7: Issue Types セットアップ
+
+GitHub Issue Types は組織レベルの設定（プロジェクトレベルではない）。GitHub UI で組織オーナーが設定。
+
+**注意**: Issue Types は組織リポジトリでのみ利用可能。個人リポジトリでは不可。
+
+**既に設定済みか確認:**
+
+ユーザーに確認: 「組織で Issue Types は設定済みですか?（Settings → Issue Types）」
+
+**未設定の場合、ガイド:**
+
+1. `https://github.com/organizations/{org}/settings/issue-types` に移動
+2. デフォルトタイプ（既存）: Task, Bug, Feature
+3. カスタムタイプを追加:
+
+| タイプ | 説明 | 色 |
+|--------|------|----|
+| Chore | メンテナンス、設定、ツール、リファクタリング | Gray |
+| Docs | ドキュメント改善・追加 | Blue |
+| Research | 調査、スパイク、探索 | Purple |
+
+**重要**: Issue Types は組織全体の設定。組織内の全リポジトリで共有される。このステップは組織ごとに1回のみ必要。
+
+詳細は [reference/issue-types.md](reference/issue-types.md) 参照。
+
+### ステップ 8: ラベルセットアップ（任意）
+
+デフォルトラベルを整理し、プロジェクト構造に合わせたエリアラベルを作成。
+
+1. **重複ラベルを削除**: Type フィールドと重複するもの（bug, enhancement, documentation）
+2. **該当しないラベルを削除**: good first issue, help wanted, question
+3. **エリアラベルを作成**: プロジェクトのモジュール構造に合わせて
+
+```bash
+gh label create "area:{module}" --color "{color}" --description "{description}"
+```
+
+**運用ラベルは保持**: `duplicate`, `invalid`, `wontfix`（ライフサイクル/トリアージ用）。
+
+詳細は [reference/labels.md](reference/labels.md) 参照。
+
+### ステップ 9: ビルトイン自動化の有効化
+
+プロジェクトの推奨自動化を有効化。API では設定不可 — GitHub UI をガイド。
+
+**推奨ワークフロー:**
+
+| ワークフロー | ターゲットステータス | 用途 |
+|-------------|-------------------|------|
+| Item closed | Done | Issue クローズ時に自動 Done |
+| Pull request merged | Done | PR マージ時に自動 Done |
+
+**現在の状態を確認:**
+
+```bash
+shirokuma-docs projects workflows
+```
+
+**ユーザーをガイド:**
+
+1. `https://github.com/orgs/{owner}/projects/{number}/settings/workflows` に移動
+2. "Item closed" を有効化 → ターゲットを **Done** に設定
+3. "Pull request merged" を有効化 → ターゲットを **Done** に設定
+
+**注意**: `session end --review` CLI コマンドとこれらの自動化は冪等に協調動作。両方有効でも競合しない。
+
+### ステップ 10: 結果報告
+
+完了後に表示:
+
+- プロジェクト名と URL
+- 設定された Status 一覧
+- 追加されたカスタムフィールド
+- ラベルサマリー（削除/作成件数）
+
+## ステータスワークフロー
+
+**通常フロー**:
+
+Icebox → Backlog → Spec Review → Ready → In Progress → Review → Testing → Done / Not Planned → Released
+
+**例外フロー**:
+
+| パターン | フロー | 説明 |
+|---------|--------|------|
+| 要件不明確 | Spec Review → Backlog | 再検討が必要 |
+| ブロック | Any → Pending → 元のステータス | 一時保留（理由必須） |
+| レビューフィードバック | Review → In Progress | 修正が要求された |
+| テスト失敗 | Testing → In Progress | バグ修正が必要 |
+| シンプルなタスク | Backlog → Ready | 要件が明確なら Spec Review をスキップ |
+
+**運用ルール**:
+
+1. 1人あたり In Progress は1つ（WIP 制限）
+2. Pending に移動する際は理由を必ず記録
+3. 1週間以上同じステータスのタスクをレビュー
+4. Ready キューにアクション可能なタスクを補充
+
+## エラーハンドリング
+
+| エラー | 対処 |
+|--------|------|
+| `missing scopes [project]` | `gh auth refresh -s project,read:project` を実行 |
+| `Project already exists` | 既存プロジェクトの URL を表示 |
+| `Owner not found` | `--owner` オプションを明示的に使用 |
+
+## 注意事項
+
+- **プロジェクト名規約**: プロジェクト名 = リポジトリ名（例: repo `shirokuma-docs` → project `shirokuma-docs`）。CLI の `getProjectId()` がリポジトリ名で検索するため
+- 10ステップのため `TodoWrite` で進捗管理
+- 既存プロジェクトがある場合は `AskUserQuestion` で上書き確認
+- 権限リフレッシュにはインタラクティブモードが必要（ユーザーが手動実行）
+- 言語は会話から自動検出（日本語または英語）
+- AI 開発では、時間見積もりより Size（工数）が有用
+- XL タスクはより小さなタスクに分割すべき
+
+## 関連リソース
+
+- [scripts/setup-project.py](scripts/setup-project.py) - 言語辞書付きセットアップスクリプト
+- [reference/status-options.md](reference/status-options.md) - ステータスワークフローと定義
+- [reference/custom-fields.md](reference/custom-fields.md) - カスタムフィールド定義
+- [reference/issue-types.md](reference/issue-types.md) - Issue Types セットアップとマイグレーションガイド
+- [reference/labels.md](reference/labels.md) - ラベル分類体系とセットアップガイド

package/plugin/shirokuma-skills-ja/skills/github-project-setup/reference/custom-fields.md

@@ -0,0 +1,42 @@
+# カスタムフィールドリファレンス
+
+## 概要
+
+| フィールド | 目的 | AI 開発での用途 |
+|-----------|------|---------------|
+| Priority | 緊急度・重要度 | タスク優先順位付け |
+| Type | タスクカテゴリ | 作業分類 |
+| Size | 工数見積 | 時間見積の代替 |
+
+## Priority
+
+| 値 | 色 | 用途 |
+|---|-----|------|
+| Critical | Red | 緊急、即時対応が必要 |
+| High | Orange | 重要だが緊急ではない |
+| Medium | Yellow | 通常の優先度 |
+| Low | Gray | 時間がある時に対応 |
+
+## Type
+
+| 値 | 色 | 用途 |
+|---|-----|------|
+| Feature | Green | 新機能 |
+| Bug | Red | バグ修正 |
+| Chore | Gray | リファクタリング、設定変更 |
+| Docs | Blue | ドキュメント |
+| Research | Purple | 調査、PoC |
+
+## Size（AI 開発向け）
+
+AI 支援開発では従来の時間見積が適さないため、Size で工数・複雑さを示す。
+
+| 値 | 色 | 目安 |
+|---|-----|------|
+| XS | Gray | 数分で完了 |
+| S | Green | 1セッション |
+| M | Yellow | 複数セッション |
+| L | Orange | 丸1日以上 |
+| XL | Red | 分割が必要 |
+
+**ルール**: XL タスクは必ず小さなタスクに分割すること。

package/plugin/shirokuma-skills-ja/skills/github-project-setup/reference/issue-types.md

@@ -0,0 +1,84 @@
+# Issue Types リファレンス
+
+## 概要
+
+GitHub Issue Types は**組織レベル**の設定で、全リポジトリの Issue を分類する。Projects のカスタム "Type" フィールドの代替。
+
+**設定 URL**: `https://github.com/organizations/{org}/settings/issue-types`
+
+**要件**: 組織オーナーロール（UI 設定時）。API 操作には `admin:org` OAuth スコープが必要。
+
+## 推奨タイプ
+
+### デフォルトタイプ（事前設定済み）
+
+| タイプ | 説明 | 色 |
+|-------|------|-----|
+| Task | 具体的な作業項目 | Default |
+| Bug | 予期しない問題や動作 | Default |
+| Feature | リクエスト、アイデア、新機能 | Default |
+
+### カスタムタイプ（手動追加）
+
+| タイプ | 説明 | 色 |
+|-------|------|-----|
+| Chore | メンテナンス、設定、ツール、リファクタリング | Gray |
+| Docs | ドキュメントの改善・追加 | Blue |
+| Research | 調査、スパイク、探索 | Purple |
+
+## 移行: Project Type フィールド → Issue Types
+
+Project で "Type" single-select フィールドを使用している場合、ビルトイン Issue Types に移行する。
+
+### Step 1: Issue Types の作成
+
+1. `https://github.com/organizations/{org}/settings/issue-types` にアクセス
+2. Chore、Docs、Research タイプを追加（Bug、Feature、Task は既存）
+
+### Step 2: 既存 Issue にタイプを割り当て
+
+各オープン Issue について、現在の Project Type フィールド値に合わせて Issue Type を設定:
+
+```bash
+shirokuma-docs issues list
+```
+
+GitHub UI（Issue サイドバー → Type ドロップダウン）または API で設定:
+
+```bash
+gh api graphql \
+  -H 'GraphQL-Features: issue_types' \
+  -f query='
+    mutation($issueId: ID!, $typeId: ID!) {
+      updateIssue(input: {id: $issueId, issueTypeId: $typeId}) {
+        issue { number title }
+      }
+    }
+  ' -f issueId="$ISSUE_NODE_ID" -f typeId="$TYPE_ID"
+```
+
+### Step 3: Project Type フィールドの削除
+
+全 Issue の移行完了後:
+
+1. Project Settings → Custom Fields
+2. "Type" single-select フィールドを削除
+3. `shirokuma-docs issues` コマンドが Project Type フィールドを参照している場合は更新
+
+### Step 4: ワークフローの更新
+
+Project "Type" フィールドを参照しているファイルを更新:
+
+- `.claude/rules/shirokuma/github/project-items.md` — Type フィールド定義
+- `plugin/shirokuma-skills-ja/skills/github-project-setup/reference/custom-fields.md` — Type フィールドリファレンス
+- `plugin/shirokuma-skills-ja/skills/github-project-setup/scripts/setup-project.py` — Type フィールド作成
+- `plugin/shirokuma-skills-ja/skills/github-project-setup/SKILL.md` — Step 6 Type フィールド一覧
+
+## 注意事項
+
+- Issue Types は**組織**リポジトリでのみ利用可能（個人リポジトリは対象外）
+- Issue Types は組織内の全リポジトリで共有
+- 組織オーナーのみが Issue Types を作成・変更可能
+- Issue Types は Issue サイドバーに表示（Project ボードのフィールドではない）
+- Project "Type" カスタムフィールドと Issue Types は別システム — 移行中は一時的に共存可能
+- 組織あたり最大25のカスタム Issue Types が作成可能

package/plugin/shirokuma-skills-ja/skills/github-project-setup/reference/labels.md

@@ -0,0 +1,85 @@
+# ラベルリファレンス
+
+## 設計原則
+
+ラベルと Type フィールドは異なる目的を持つ:
+
+| 仕組み | 役割 | 軸 | 例 |
+|--------|------|-----|-----|
+| Type（Project フィールド / Issue Types） | 作業の**種類** | カテゴリ | Bug, Feature, Chore |
+| Labels | 作業の**影響範囲** | 横断的属性 | area:cli, area:plugin |
+
+ラベルは Type と重複させないこと。ラベルが Type 値と1:1対応する場合、ラベルを削除して Type を使用する。
+
+## 推奨ラベル分類
+
+### エリアラベル（必須）
+
+プロジェクトのモジュール構造に基づいてエリアを定義。`area:` プレフィックスを使用。
+
+| ラベル | 色 | 説明 |
+|-------|-----|------|
+| `area:cli` | `#0e8a16` | コア CLI とコマンド |
+| `area:plugin` | `#5319e7` | プラグインシステム（skills, rules, agents） |
+| `area:github` | `#1d76db` | GitHub 連携コマンド |
+| `area:lint` | `#fbca04` | Lint・バリデーションコマンド |
+
+**プロジェクトに合わせてカスタマイズ**: コードベース構造に合ったエリアに置き換える（例: `area:api`, `area:web`, `area:database`）。
+
+### 運用ラベル（デフォルトから保持）
+
+| ラベル | 色 | 説明 |
+|-------|-----|------|
+| `duplicate` | `#cfd3d7` | この Issue または PR は既に存在 |
+| `invalid` | `#e4e669` | 正しくないと思われる |
+| `wontfix` | `#ffffff` | 対応しない |
+
+これらはライフサイクル・トリアージ目的であり、Type ではカバーできない。
+
+## 削除すべきデフォルトラベル
+
+以下の GitHub デフォルトラベルは Type と重複するか、適用外:
+
+| ラベル | 削除理由 |
+|-------|---------|
+| `bug` | Type: Bug と重複 |
+| `enhancement` | Type: Feature と重複 |
+| `documentation` | Type: Docs と重複 |
+| `good first issue` | 非該当（プライベートリポ / AI 支援） |
+| `help wanted` | 非該当（プライベートリポ / AI 支援） |
+| `question` | Discussions を使用 |
+
+## ラベル割り当てルール
+
+1. **エリアラベルは任意** - 全ての Issue にエリアラベルが必要なわけではない。タイトルから影響範囲が明らかでない場合に使用
+2. **複数エリアラベル可** - 横断的な Issue は複数エリアを持てる（例: `area:cli` + `area:github`）
+3. **運用ラベルはトリアージ時に適用** - `duplicate`, `invalid`, `wontfix` はクローズやリダイレクト時に設定
+4. **AI はエリアラベルを提案すべき** - Issue 作成時、スコープが明確ならエリアラベルを提案
+
+## セットアップ
+
+**注意**: 以下のコマンドは `gh label` を直接使用。`shirokuma-docs` CLI がインストール済みの場合は `shirokuma-docs repo labels --create` を使用して他の GitHub 操作との一貫性を保つ。
+
+### 重複ラベルの削除
+
+```bash
+for label in bug enhancement documentation "good first issue" "help wanted" question; do
+  gh label delete "$label" --yes
+done
+```
+
+### エリアラベルの作成
+
+```bash
+gh label create "area:cli" --color "0e8a16" --description "Core CLI and commands"
+gh label create "area:plugin" --color "5319e7" --description "Plugin system (skills, rules, agents)"
+gh label create "area:github" --color "1d76db" --description "GitHub integration commands"
+gh label create "area:lint" --color "fbca04" --description "Lint and validation commands"
+```
+
+## 注意事項
+
+- ラベルはリポジトリレベルの設定（Issue Types は組織レベル）
+- ラベルは Issue 一覧に表示され、視覚的なフィルタリングに有用
+- `gh label` コマンドは特別な OAuth スコープ不要（標準の `repo` スコープで十分）
+- Type 重複ラベルから移行する場合、ラベル定義を削除する前に既存 Issue からラベルを外す

package/plugin/shirokuma-skills-ja/skills/github-project-setup/reference/status-options.md

@@ -0,0 +1,69 @@
+# ステータスオプションリファレンス
+
+## ワークフロー図
+
+```mermaid
+graph LR
+    Icebox[Icebox] --> Backlog[Backlog]
+    Backlog --> SpecReview[Spec Review]
+    SpecReview --> Ready[Ready]
+    SpecReview -.->|不明確| Backlog
+    Ready --> InProgress[In Progress]
+    InProgress --> Pending[Pending]
+    Pending -.->|解消| InProgress
+    InProgress --> Review[Review]
+    Review --> Testing[Testing]
+    Review -.->|変更要求| InProgress
+    Testing --> Done[Done]
+    Testing -.->|バグ発見| InProgress
+    Done --> Released[Released]
+    Backlog -.->|見送り| NotPlanned[Not Planned]
+    InProgress -.->|見送り| NotPlanned
+    Pending -.->|見送り| NotPlanned
+```
+
+## ステータス定義
+
+| ステータス | 色 | 用途 | 次のステータス |
+|-----------|-----|------|--------------|
+| Icebox | Gray | 将来検討するアイデア | Backlog |
+| Backlog | Blue | 優先順位付き作業項目 | Spec Review |
+| Spec Review | Pink | 要件・仕様レビュー中 | Ready / Backlog |
+| Ready | Green | 開始可能、依存関係解決済み | In Progress |
+| In Progress | Yellow | 作業中（1人1つまで） | Review / Pending |
+| Pending | Red | 一時的にブロック中（理由必須） | 元のステータス |
+| Review | Purple | PR レビュー待ち | Testing / In Progress |
+| Testing | Orange | QA・テスト中 | Done / In Progress |
+| Done | Green | 完了・マージ済み | Released |
+| Released | Green | 本番デプロイ済み | - |
+| Not Planned | Gray | 見送り・対応不要。Issue close 時に stateReason=NOT_PLANNED で自動設定。 | - |
+
+## 使用例
+
+### Icebox
+
+| 使用タイミング | 例 |
+|-------------|-----|
+| アイデアを思いついた | 「ダークモード対応したい」 |
+| 将来検討 | 「v2.0 で検討」 |
+| 低優先度 | 「あれば良い機能」 |
+
+### Pending
+
+| 使用タイミング | 例 |
+|-------------|-----|
+| 他タスク/PR 待ち | 「#123 のマージ待ち」 |
+| 外部レスポンス待ち | 「クライアント確認待ち」 |
+| 技術的ブロッカー | 「ライブラリのバグを報告済み」 |
+
+**重要**: ブロック理由は必ずコメントに記録すること。
+
+### Not Planned
+
+| 使用タイミング | 例 |
+|-------------|-----|
+| 要件が不要になった | 「仕様変更により対応不要」 |
+| 別 Issue で対応済み | 「#456 で解決済み」 |
+| 見送り判断 | 「ROI が合わないため見送り」 |
+
+**重要**: Issue を close する際に `stateReason=NOT_PLANNED` を指定すると自動設定される。

package/plugin/shirokuma-skills-ja/skills/github-project-setup/scripts/locales/en.json

@@ -0,0 +1,35 @@
+{
+  "status": {
+    "Icebox": "Ideas for future",
+    "Backlog": "To do list",
+    "Spec Review": "Requirements review",
+    "Ready": "Ready to start",
+    "In Progress": "Working on it",
+    "Pending": "Blocked",
+    "Review": "Awaiting review",
+    "Testing": "Testing",
+    "Done": "Completed",
+    "Not Planned": "Explicitly not planned",
+    "Released": "Released"
+  },
+  "priority": {
+    "Critical": "Urgent",
+    "High": "High priority",
+    "Medium": "Normal",
+    "Low": "Low priority"
+  },
+  "type": {
+    "Feature": "New feature",
+    "Bug": "Bug fix",
+    "Chore": "Maintenance",
+    "Docs": "Documentation",
+    "Research": "Research"
+  },
+  "size": {
+    "XS": "Minutes",
+    "S": "Single session",
+    "M": "Multiple sessions",
+    "L": "Full day+",
+    "XL": "Split needed"
+  }
+}

package/plugin/shirokuma-skills-ja/skills/github-project-setup/scripts/locales/ja.json

@@ -0,0 +1,35 @@
+{
+  "status": {
+    "Icebox": "アイデア・将来検討",
+    "Backlog": "やることリスト",
+    "Spec Review": "要件・仕様確認中",
+    "Ready": "着手可能",
+    "In Progress": "作業中",
+    "Pending": "一時保留・ブロック中",
+    "Review": "レビュー待ち",
+    "Testing": "テスト中",
+    "Done": "完了",
+    "Not Planned": "見送り・対応不要",
+    "Released": "リリース済み"
+  },
+  "priority": {
+    "Critical": "緊急・最優先",
+    "High": "高優先度",
+    "Medium": "通常",
+    "Low": "低優先度"
+  },
+  "type": {
+    "Feature": "新機能",
+    "Bug": "バグ修正",
+    "Chore": "雑務・リファクタ",
+    "Docs": "ドキュメント",
+    "Research": "調査・検証"
+  },
+  "size": {
+    "XS": "数分で完了",
+    "S": "1セッションで完了",
+    "M": "複数セッション",
+    "L": "1日以上",
+    "XL": "分割が必要"
+  }
+}