shirokuma-docs 0.1.0-alpha.1

package/plugin/shirokuma-skills-ja/skills/showing-github/reference/github-operations.md

@@ -0,0 +1,163 @@
+# GitHub 操作リファレンス
+
+セッション/GitHub スキル共通リファレンス。CLI コマンド、ワークフロー、規約の単一情報源。
+
+## アーキテクチャ: Issues + Projects ハイブリッド
+
+| コンポーネント | 用途 |
+|-------------|------|
+| **Issues** | タスク管理、`#123` 参照、履歴 |
+| **Projects** | Status/Priority/Type/Size フィールド管理 |
+| **Labels** | タイプ識別のみ（`feature`, `bug`, `chore`） |
+| **Discussions** | 引き継ぎ、仕様、決定事項、Q&A |
+
+**ステータスは Projects フィールドで管理**（ラベルではない）。
+
+Project 命名規約: Project 名 = リポジトリ名（例: `blogcms` リポ → `blogcms` プロジェクト）。
+
+## 前提条件
+
+- `gh` CLI インストール・認証済み
+- GitHub Project 設定済み（未設定なら `/project-setup` を実行）
+- Discussions 有効化（カテゴリ: Handovers, Ideas, Q&A）（任意）
+
+## DraftIssue vs Issue
+
+| 機能 | DraftIssue | Issue |
+|------|-----------|-------|
+| `#number` | なし | あり（`#123`） |
+| 外部参照 | 不可 | 可 |
+| コメント | 不可 | 可 |
+| 作成コマンド | `projects create` | `issues create` |
+| ユースケース | 軽量メモ | 完全なタスク |
+
+**推奨**: `#number` サポートのため `issues create` をデフォルトで使用。
+
+## shirokuma-docs CLI リファレンス
+
+直接の `gh` コマンドより shirokuma-docs CLI を優先。設定は `shirokuma-docs.config.yaml`。
+
+### Issues（主要インターフェース）
+
+```bash
+shirokuma-docs issues list                          # オープン Issue 一覧
+shirokuma-docs issues list --all                    # クローズ含む
+shirokuma-docs issues list --status "In Progress"   # ステータスフィルタ
+shirokuma-docs issues show {number}                  # 詳細
+shirokuma-docs issues create \
+  --title "Title" --body "Body" \
+  --labels feature \
+  --field-status "Backlog" --priority "Medium" --type "Feature" --size "M"
+shirokuma-docs issues update {number} --field-status "In Progress"
+shirokuma-docs issues comment {number} --body "..."
+shirokuma-docs issues close {number}
+shirokuma-docs issues reopen {number}
+```
+
+### Projects（低レベルアクセス）
+
+```bash
+shirokuma-docs projects list                        # プロジェクトアイテム一覧
+shirokuma-docs projects fields                      # フィールドオプション表示
+shirokuma-docs projects add-issue {number}          # Issue をプロジェクトに追加
+shirokuma-docs projects create \
+  --title "Title" --body "Body" \
+  --field-status "Backlog" --priority "Medium"               # DraftIssue
+shirokuma-docs projects get PVTI_xxx                # アイテム ID で取得
+shirokuma-docs projects update {number} --field-status "Done"
+```
+
+### Discussions
+
+```bash
+shirokuma-docs discussions list --category Handovers --limit 5
+shirokuma-docs discussions get {number}
+shirokuma-docs discussions create \
+  --category Handovers \
+  --title "$(date +%Y-%m-%d) - Summary" \
+  --body "Content"
+```
+
+### Repository
+
+```bash
+shirokuma-docs repo info
+shirokuma-docs repo labels
+```
+
+### クロスリポジトリ操作
+
+```bash
+shirokuma-docs issues list --repo docs
+shirokuma-docs issues create --repo docs --title "Title" --body "Body"
+```
+
+### gh フォールバック（CLI 未対応の操作のみ）
+
+```bash
+# ラベル
+gh issue edit {number} --add-label "label"
+gh issue edit {number} --remove-label "label"
+gh label list
+gh label create "name" --color "0E8A16" --description "Desc"
+
+# Pull Requests
+gh pr list --state open
+gh pr view {number}
+gh pr comment {number} --body "..."
+
+# リポジトリ情報
+gh repo view --json nameWithOwner -q '.nameWithOwner'
+
+# 認証
+gh auth login
+gh auth status
+```
+
+## ステータスワークフロー
+
+```mermaid
+graph LR
+  Icebox --> Backlog --> SpecReview[Spec Review] --> Ready --> InProgress[In Progress]
+  InProgress --> Review --> Testing --> Done --> Released
+  InProgress <--> Pending["Pending（ブロック中）"]
+```
+
+| ステータス | 説明 |
+|-----------|------|
+| Icebox | 低優先度、未計画 |
+| Backlog | 将来の作業として計画済み |
+| Spec Review | 要件レビュー中 |
+| Ready | 開始可能 |
+| In Progress | 作業中 |
+| Pending | ブロック中（理由を記録） |
+| Review | コードレビュー中 |
+| Testing | QA テスト中 |
+| Done | 完了 |
+| Released | 本番デプロイ済み |
+
+## ラベル規約
+
+ラベルは**タイプ識別のみ**に使用（ステータスは Projects フィールドで管理）:
+
+| ラベル | 用途 |
+|-------|------|
+| `feature` | 新機能 |
+| `bug` | バグ修正 |
+| `chore` | メンテナンス |
+| `docs` | ドキュメント |
+| `research` | 調査 |
+
+任意の優先度ラベル: `priority:critical`, `priority:high`
+
+## よくあるエラー対処
+
+| エラー | 対処 |
+|-------|------|
+| `shirokuma-docs: command not found` | インストール: `npm i -g @shirokuma-library/shirokuma-docs` |
+| `gh: command not found` | インストール: `brew install gh` or `sudo apt install gh` |
+| `not logged in` / `not authenticated` | 実行: `gh auth login` |
+| No project found | `/project-setup` を実行してプロジェクト作成 |
+| Discussions disabled/category not found | ローカルファイルにフォールバック |
+| `HTTP 404` | リポジトリ名と権限を確認 |
+| API rate limit | キャッシュ済み/部分データを表示 |

package/plugin/shirokuma-skills-ja/skills/starting-session/SKILL.md

@@ -0,0 +1,93 @@
+---
+name: starting-session
+description: 作業セッションを開始し、プロジェクトの状態と前回の引き継ぎを表示します。「セッション開始」「作業開始」「start session」「begin work」で起動。
+allowed-tools: Bash, Read, Grep, AskUserQuestion
+---
+
+# セッション開始
+
+新しい作業セッションを開始し、プロジェクトのコンテキストを表示する。
+
+## ワークフロー
+
+### ステップ 1: セッションコンテキスト取得
+
+```bash
+shirokuma-docs session start
+```
+
+返される JSON: `repository`, `git`（ブランチ、未コミット変更）, `lastHandover`, `backups`（PreCompact バックアップ）, `issues`（アクティブ Issue + フィールド）, `total_issues`
+
+### ステップ 1b: バックアップ検出
+
+`backups` フィールドが存在する場合、前回のセッションが中断された可能性がある。
+バックアップ内容（ブランチ、未コミット変更、直近のコミット）をユーザーに通知し、コンテキスト復元の参考にする。
+
+### ステップ 2: コンテキスト表示
+
+```markdown
+## セッション開始
+
+**リポジトリ:** {repository}
+**時刻:** {current time}
+**ブランチ:** {currentBranch} {hasUncommittedChanges ? "(未コミットあり)" : "(クリーン)"}
+
+### 前回の引き継ぎ
+{lastHandover.title or "なし"}
+- サマリー: {Summary セクション}
+- 次のステップ: {Next Steps セクション}
+
+### アクティブな Issue
+{ステータスでグループ化: 作業中 → 準備完了 → バックログ → アイスボックス}
+```
+
+未コミット変更がある場合、ユーザーに通知。
+
+### ステップ 3: 方向性の確認
+
+AskUserQuestion で上位アイテムを選択肢として提示（作業中 > 準備完了 > バックログ、最大4オプション）。
+
+## アイテム選択時
+
+Issue のステータスに基づいて適切なスキルにルーティングする。
+
+### ステータスベースルーティング
+
+| Issue ステータス | 委任先 | 理由 |
+|-----------------|--------|------|
+| Backlog | `planning-on-issue` | 計画が必要 |
+| Planning | `planning-on-issue` | 計画策定中 |
+| Spec Review | `working-on-issue` | 暗黙承認で実装開始 |
+| In Progress | `working-on-issue` | 作業再開 |
+| Review / Pending | `working-on-issue` | 作業続行 |
+| (その他 / ステータスなし) | `working-on-issue` | デフォルト |
+
+### スキル起動
+
+```
+Skill: {ルーティングテーブルに基づくスキル名}
+Args: #{number}
+```
+
+`working-on-issue` がステータス更新、ブランチ作成、計画確認、スキル選択・実行、作業後フローを一貫して処理する。
+`planning-on-issue` が計画策定とステータス遷移を処理する。
+`starting-session` ではステータス更新やブランチ作成を行わない。
+
+## エッジケース
+
+| 状況 | 対応 |
+|------|------|
+| `shirokuma-docs` 未インストール | `pnpm install` を案内 |
+| `gh` 未インストール | `brew install gh` または `sudo apt install gh` を案内 |
+| GitHub 未ログイン | `gh auth login` を案内 |
+| Issue がゼロ | 「アクティブな Issue なし」と表示 |
+| 引き継ぎがない | 「前回の引き継ぎ: なし」と表示 |
+| git pull 失敗 | 警告して続行（ローカルのベースブランチを使用） |
+
+## 注意事項
+
+- セッションヘッダーに現在時刻を表示
+- 引き継ぎから Summary / Next Steps をパース
+- 優先度順に表示
+- アイテム選択後はステータスベースルーティングに従い `working-on-issue` または `planning-on-issue` に委任（ステータス更新・ブランチ作成を重複しない）
+- 直接 `gh` コマンドを使わない（`shirokuma-docs session start` を使用）

package/plugin/shirokuma-skills-ja/skills/working-on-issue/SKILL.md

@@ -0,0 +1,208 @@
+---
+name: working-on-issue
+description: Issue番号またはタスク説明を受け取り、適切なスキルを選択してワークフローを統括するワークディスパッチャー。「これやって」「work on」「取り組む」「着手して」「#42 やって」で使用。
+allowed-tools: Bash, Read, Grep, Glob, AskUserQuestion, TodoWrite
+---
+
+# Issue に取り組む
+
+Issue の種類やタスク説明に基づいて、適切なスキルに作業をディスパッチする。
+
+**注意**: セッションセットアップには `starting-session` を使用。このスキルは特定タスクの作業開始用。
+
+## コンセプト
+
+このスキルは**全作業のエントリーポイント**。何をすべきか分析し、適切なスキルに委任した後、ワークフローを順次実行する。
+
+```
+/working-on-issue #42 → 分析 → スキル選択 → 実行 → Commit → PR → Review
+```
+
+ワークフローは**常に順次実行**される。ステップ間でユーザーに確認しない。
+
+### TodoWrite 登録（必須）
+
+**作業開始前**にチェーン全ステップを TodoWrite に登録する。
+
+**実装 / デザイン / バグ修正:**
+
+| # | content | activeForm | スキル |
+|---|---------|------------|--------|
+| 1 | 実装する | 実装中 | `nextjs-vibe-coding` / `frontend-designing` |
+| 2 | 変更をコミット・プッシュする | コミット・プッシュ中 | `committing-on-issue` |
+| 3 | プルリクエストを作成する | プルリクエストを作成中 | `creating-pr-on-issue` |
+| 4 | セルフレビューを実行し結果を PR に投稿する | セルフレビュー・結果投稿中 | `creating-pr-on-issue` ステップ 6 で実行（個別呼び出し不要） |
+
+**リファクタリング / Chore:**
+
+| # | content | activeForm | スキル |
+|---|---------|------------|--------|
+| 1 | 変更を実施する | 変更を実施中 | 直接編集 |
+| 2 | 変更をコミット・プッシュする | コミット・プッシュ中 | `committing-on-issue` |
+| 3 | プルリクエストを作成する | プルリクエストを作成中 | `creating-pr-on-issue` |
+| 4 | セルフレビューを実行し結果を PR に投稿する | セルフレビュー・結果投稿中 | `creating-pr-on-issue` ステップ 6 で実行（個別呼び出し不要） |
+
+**調査:**
+
+| # | content | activeForm | スキル |
+|---|---------|------------|--------|
+| 1 | 調査を実施する | 調査を実施中 | `best-practices-researching` |
+| 2 | Discussion に調査結果を保存する | Discussion を作成中 | `shirokuma-docs discussions create` |
+
+各ステップの実行開始時に `in_progress`、完了時に `completed` に更新する。
+`creating-pr-on-issue` 完了時（セルフレビュー含む）にステップ 3 と 4 を同時に `completed` にする。
+
+## ワークフロー
+
+### ステップ 1: 作業の分析
+
+**Issue 番号あり**: `shirokuma-docs issues show {number}` で取得し、title/body/type/status/priority/size を抽出。
+
+#### 計画済み判定（Issue 番号ありの場合）
+
+Issue 本文に `## 計画` セクション（`^## 計画` で前方一致検出）があるか確認する。
+
+| 計画状態 | アクション |
+|---------|----------|
+| 計画なし | → `planning-on-issue` に委任して計画を策定（全 Issue 共通） |
+| 計画あり | → 計画を `## 計画` セクションからコンテキストとして実装スキルに渡す |
+
+- 計画の深さは `planning-on-issue` が Issue 内容に応じて自動判定する（軽量/標準/詳細）
+
+#### Planning ステータスからの遷移
+
+Issue のステータスが Planning の場合:
+
+| 計画状態 | アクション |
+|---------|----------|
+| Planning + 計画なし | → `planning-on-issue` に委任（計画を継続） |
+| Planning + 計画あり | → Spec Review に遷移し、ユーザーに承認を求める（暗黙承認にしない） |
+
+Planning + 計画ありのケース（セッション中断等）では、計画のサマリーを表示して承認を確認する。
+
+**テキスト説明のみ**: キーワードから分類:
+
+| キーワード | 作業タイプ |
+|-----------|-----------|
+| implement, create, add, 実装, 作成, 追加 | 実装 |
+| design, UI, デザイン, 印象的 | デザイン |
+| fix, bug, 修正, バグ | バグ修正 |
+| refactor, リファクタ | リファクタリング |
+| research, 調査 | 調査 |
+| review, レビュー | レビュー |
+| config, setup, 設定 | Chore |
+
+### ステップ 2: ステータス更新
+
+Issue が In Progress でなければ: `shirokuma-docs issues update {number} --field-status "In Progress"`
+
+**Spec Review からの遷移（暗黙承認モデル）**: Issue の Status が Spec Review の場合、ユーザーが `/working-on-issue` を呼び出した行為自体が計画の承認を意味する。追加の確認なしに In Progress に遷移する。
+
+**Planning からの遷移**: 上記「Planning ステータスからの遷移」の判定結果に従う。計画なしの場合は `planning-on-issue` に委任（ステータス更新はスキルが処理）。計画ありの場合は Spec Review に遷移して承認を待つ。
+
+### ステップ 3: フィーチャーブランチの確保
+
+`develop` にいる場合、`branch-workflow` ルールに従いブランチを作成:
+
+```bash
+git checkout develop && git pull origin develop
+git checkout -b {type}/{number}-{slug}
+```
+
+ブランチタイプ: Feature→`feat`, Bug→`fix`, Chore/Research→`chore`, Docs→`docs`
+
+### ステップ 3b: ADR 提案（Feature M+ のみ）
+
+Feature タイプでサイズ M 以上の場合、ADR 作成を提案（AskUserQuestion）。
+
+### ステップ 4: スキルの選択と実行
+
+| 作業タイプ | スキル | 呼び出し |
+|-----------|-------|---------|
+| 実装 / バグ修正 | `nextjs-vibe-coding` | Skill |
+| デザイン | `frontend-designing` | Skill |
+| 調査 | `best-practices-researching` | Skill (`context: fork`) |
+| レビュー | `reviewing-on-issue` | Skill (`context: fork`) |
+| リファクタリング / Chore | 直接編集 | — |
+
+### ステップ 5: ワークフロー順次実行
+
+作業完了後、ワークフローチェーンを**自動的に順次実行**する。ステップ間でユーザーに確認しない。
+
+**前提**: TodoWrite 登録（上記セクション参照）でチェーン全ステップが登録済み。
+各ステップの実行開始時に `in_progress`、完了時に `completed` に更新する。
+
+| 作業タイプ | チェーン |
+|-----------|---------|
+| 実装 / デザイン / バグ修正 | Work → Commit → PR → Review |
+| リファクタリング / Chore | Work → Commit → PR → Review |
+| 調査 | Research → Discussion |
+
+- ステップ間で確認しない、進捗を1行で報告
+- **セルフレビューループ**: PR 作成後に `reviewing-on-issue` を実行。`creating-pr-on-issue` のセルフレビューチェーン（ステップ 6）として実行される
+  - FAIL + Auto-fixable → 自動修正 → コミット・プッシュ（PR自動更新）→ 再レビュー
+  - 最大3イテレーション（初回レビュー + 最大2回の修正・再レビュー）
+  - イテレーション間で issue 数が増加した場合はループ停止
+- レビューステップはデフォルトで `reviewing-on-issue` を使用。プロジェクト固有のレビューチェックリストやスキル（`.claude/skills/` 等）がある場合は併用する
+- **ステップ 4 の完了条件**: `reviewing-on-issue` がレポートを保存し、PR コメントの投稿が確認された時点で `completed` にする。Self-Review Result の返却のみでは完了としない
+- **フィードバック蓄積**: セルフレビューの検出パターンを Discussion (Reports) に記録。頻出パターン（3回以上）はルール化提案を生成
+- 失敗時: チェーン停止、状況報告、ユーザーに制御を返す
+
+## 引数
+
+| 形式 | 例 | 動作 |
+|------|---|------|
+| Issue 番号 | `#42` | Issue 取得、タイプ分析 |
+| 説明文 | `implement dashboard` | テキスト分類 |
+| 引数なし | — | AskUserQuestion で確認 |
+
+## 表示フォーマット
+
+```markdown
+## 作業対象: #{number} {title}
+
+**タイプ:** {type} → **スキル:** {skill-name}
+**ブランチ:** {branch-name}
+**優先度:** {priority}
+```
+
+## エッジケース
+
+| 状況 | アクション |
+|------|----------|
+| Issue が見つからない | AskUserQuestion で番号確認 |
+| Issue が Done/Released | 警告、再オープン確認 |
+| 既に In Progress | ステータス変更なしで続行 |
+| 誤ったブランチ | AskUserQuestion: 切り替え or 続行 |
+| チェーン失敗 | 完了/残りステップ報告、制御を返す |
+
+## ルール参照
+
+このスキルは以下のルールに依存する（`.claude/rules/` から自動読み込み）：
+
+| ルール | 用途 |
+|--------|------|
+| `branch-workflow` | ブランチ命名、`develop` からの作成、PR ターゲット |
+| `project-items` | ステータスワークフロー、フィールド要件、本文メンテナンス |
+| `git-commit-style` | コミットメッセージ形式（`committing-on-issue` スキルに委任） |
+
+## ツール使用
+
+| ツール | タイミング |
+|--------|-----------|
+| AskUserQuestion | 要件確認、アプローチ選択、エッジケース判断（作業タイプ不明、Issue 未発見、ブランチ不一致等） |
+| TodoWrite | チェーンステップ登録（全作業で必須）、複数 Issue セッションの進捗トラッキング |
+| Bash | Git 操作、`shirokuma-docs issues` コマンド |
+
+**AskUserQuestion**: ユーザー入力が必要な場面（要件確認、アプローチ選択、エッジケース判断）で使用する。ワークフローステップ遷移（Commit → PR → Review）の確認には使用しない。
+
+**TodoWrite**: 全作業で使用。チェーン全ステップを事前登録し、各ステップの進捗を `in_progress` → `completed` で更新する。
+
+## 注意事項
+
+- このスキルは作業の**プライマリエントリーポイント**
+- 作業開始前に Issue ステータスを更新
+- 正しいフィーチャーブランチを確保
+- ワークフローは常に順次実行（Commit → PR → Review）
+- チェーン実行はエラー発生時に停止し、ユーザーに制御を返す
+- 直接作業（リファクタリング/Chore）ではスキル委任不要