shirokuma-docs 0.1.0-alpha.1

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

@@ -0,0 +1,227 @@
+---
+name: committing-on-issue
+description: 変更をステージ、コミット、プッシュし、オプションでPR作成チェーンを実行します。PRマージと関連Issueのステータス自動更新にも対応。「コミットして」「commit」「push」「変更をコミット」「コミットしてPR作って」「マージして」「merge」で起動。
+allowed-tools: Bash, Read, Grep, Glob, AskUserQuestion
+---
+
+# コミット
+
+変更をステージし、コミットし、オプションでリモートにプッシュします。
+
+## ワークフロー
+
+### ステップ 1: 変更の確認
+
+```bash
+git status --short
+git diff --stat
+git branch --show-current
+```
+
+変更のサマリーをユーザーに表示。
+
+### ステップ 2: ファイルのステージング
+
+関連ファイルを個別にステージ。`git add -A` より明示的パスを優先。
+
+```bash
+git add {file1} {file2} ...
+```
+
+**ステージ禁止**:
+- `.env`、認証情報、シークレット
+- 大きなバイナリファイル
+- 他の作業による無関係な変更
+
+不明な場合は AskUserQuestion でファイルリストをオプションとして提示。
+
+### ステップ 2.5: plugin/ 変更時のバージョンバンプ確認
+
+ステージされたファイルに `plugin/` 配下が含まれるか確認（`.gitkeep` は除外）:
+
+```bash
+git diff --cached --name-only | grep '^plugin/' | grep -v '\.gitkeep$'
+```
+
+該当する場合:
+1. `package.json` のバージョンが適切にバンプされているか確認
+2. 未バンプの場合: `plugin-version-bump` ルールに従いバンプ + `node scripts/sync-versions.mjs` を実行
+3. バンプ済みの場合: 全 `plugin.json` が `package.json` と一致するか確認
+
+### ステップ 3: コミットメッセージ作成
+
+Conventional Commits 形式:
+
+```
+{type}: {description} (#{issue-number})
+
+{任意の本文}
+```
+
+| タイプ | 用途 |
+|--------|------|
+| `feat` | 新機能・機能強化 |
+| `fix` | バグ修正 |
+| `refactor` | リファクタリング |
+| `docs` | ドキュメント |
+| `test` | テスト |
+| `chore` | 設定・ツール |
+
+**ルール**（詳細は `git-commit-style` ルール参照）:
+- 1 行目は 72 文字以内
+- 該当する場合は Issue 番号を参照
+- 本文は複雑な変更の場合のみ
+- `Co-Authored-By` 署名は付けない
+
+### ステップ 4: コミット
+
+```bash
+git commit -m "$(cat <<'EOF'
+{type}: {description} (#{issue-number})
+
+{任意の本文}
+EOF
+)"
+```
+
+### ステップ 5: プッシュ（フィーチャーブランチの場合）
+
+フィーチャーブランチ（`develop` や `main` 以外）にいる場合、自動プッシュ:
+
+```bash
+git push -u origin {branch-name}
+```
+
+`develop` や `main` にいる場合はプッシュしない。保護ブランチへの直接プッシュは `branch-workflow` ルールに従い避けるべきことをユーザーに通知。
+
+### ステップ 6: 確認表示
+
+```markdown
+## コミット完了
+
+**ブランチ:** {branch-name}
+**コミット:** {hash} {message}
+**ファイル:** {count} ファイル変更
+**プッシュ:** {yes/no}
+```
+
+### ステップ 7: PR チェーン（プッシュ後）
+
+プッシュ成功後、PR 作成へのチェーンが必要か判定。
+
+**PR キーワード検出**: ユーザーの**最初のメッセージ**（`/committing-on-issue` 起動時のテキスト）から PR 関連キーワードを検出:
+
+| 言語 | キーワード |
+|------|-----------|
+| 日本語 | "PR作って", "PR作成", "プルリクエスト", "PRも作って", "PRも" |
+| 英語 | "pull request", "create PR", "open PR" |
+
+**PR 提案前の事前チェック**:
+
+```bash
+gh pr list --head {branch-name} --json number,url --jq '.[0]'
+```
+
+このブランチに既に PR がある場合、既存 URL を表示してスキップ:
+
+```markdown
+PR already exists: {url}
+```
+
+**PR キーワード検出 AND 既存 PR なし:**
+
+Skill ツールで `creating-pr-on-issue` スキルを自動起動。現在のブランチと関連 Issue 番号をコンテキストとして渡す。
+
+**PR キーワードなし AND 既存 PR なし:**
+
+自動実行せず、次のステップを提案:
+
+```markdown
+ブランチをプッシュしました。PR を作成しますか？
+→ `/creating-pr-on-issue` で develop へのプルリクエストを作成
+```
+
+**フィーチャーブランチでない場合（プッシュがスキップされた場合）:**
+
+このステップ全体をスキップ。
+
+### ステップ 8: マージチェーン
+
+PR マージと関連 Issue のステータス自動更新を処理する。マージキーワード検出時、または `working-on-issue` からの起動時に有効化。
+
+**マージキーワード検出**: ユーザーメッセージから以下を検出:
+
+| 言語 | キーワード |
+|------|-----------|
+| 日本語 | "マージして", "マージ", "merge" |
+| 英語 | "merge PR", "merge this", "merge it" |
+
+**マージキーワード検出時（コミットフローとは独立）:**
+
+1. **PR をマージし関連 Issue を更新**:
+
+```bash
+shirokuma-docs issues merge --head {current-branch}
+```
+
+この 1 コマンドでブランチから PR 特定、squash マージ、PR 本文から関連 Issue 抽出（`Closes/Fixes/Resolves #N`）、Project Status を "Done" に更新、ブランチ削除を処理する。
+
+**Status 更新の冪等性**: `issues merge` CLI が関連 Issue の Project Status を自動で Done に更新する。`ending-session --done` が同じ Issue に対して実行されても冪等に動作する（既に Done なら no-op）。
+
+ブランチに PR が見つからない場合は CLI がエラーを報告。ユーザーに通知して停止。
+
+※ 内部で `gh pr merge` を呼び出すため PreToolUse フックで保護。ユーザーに確認が求められる。
+
+2. **develop に切り替え**:
+
+```bash
+git checkout develop && git pull origin develop
+```
+
+3. **確認表示**:
+
+```markdown
+## マージ完了
+
+**PR:** （CLI 出力に基づく） → {base-branch}
+**Issue 更新:** （CLI 出力に基づく）
+**ブランチ:** 削除済み、develop に切り替え
+```
+
+**コミットフローとの連携**（例: "コミットしてマージして"）:
+
+ステップ 1-6 → ステップ 7（PR チェーン）→ ステップ 8（マージチェーン）を順次実行。
+
+## 引数
+
+メッセージ引数付きで起動された場合（例: `/committing-on-issue fix typo in config`）:
+- 提供されたテキストをコミットメッセージのベースとして使用
+- コミット前の変更確認は引き続き実行
+- 引数内の PR キーワードは PR チェーンをトリガー（例: `/committing-on-issue fix typo PRも作って`）
+- マージキーワードはマージチェーンをトリガー（例: `/committing-on-issue コミットしてマージして`）
+
+## エッジケース
+
+| 状況 | 対応 |
+|------|------|
+| 変更なし | 通知して終了 |
+| develop/main にいる | コミットするがプッシュ警告、フィーチャーブランチ作成を提案 |
+| マージコンフリクト | ユーザーに通知、自動解決しない |
+| pre-commit フック失敗 | 修正して新規コミット（amend 禁止） |
+| 複数 Issue 混在 | AskUserQuestion でファイル選択 |
+| ブランチに PR が既に存在 | 既存 PR URL を表示してチェーンをスキップ |
+| `gh` CLI 利用不可 | PR チェーンをスキップ、ユーザーに通知 |
+| 現ブランチに PR がない（マージ時） | ユーザーに通知してスキップ |
+| 未解決レビューあり | 警告してユーザーに確認 |
+| PR 本文に Issue 参照なし | ステータス更新をスキップ、通知 |
+
+## 注意事項
+
+- コミット前に必ず変更を確認
+- `git add -A` や `git add .` はレビューなしで使わない
+- 明示的に求められない限り前のコミットを amend しない
+- force push 禁止
+- フィーチャーブランチではプッシュ自動、`develop` と `main` ではスキップ
+- PR チェーンは直接起動 + キーワード時のみ（`working-on-issue` オーケストレーションには干渉しない）
+- マージチェーンは単独起動（"マージして"）またはコミット/PR との連携が可能
+- マージ後は `shirokuma-docs issues merge` が関連 Issue ステータスを自動で Done に更新

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

@@ -0,0 +1,187 @@
+---
+name: creating-pr-on-issue
+description: 現在のブランチから GitHub プルリクエストを作成する。「PR作成」「プルリクエスト作成」「create pull request」で使用。
+allowed-tools: Bash, Read, Grep, Glob, AskUserQuestion
+---
+
+# プルリクエスト作成
+
+フィーチャーブランチから `develop` への PR を作成する。
+
+## ワークフロー
+
+### ステップ 1: ブランチ状態確認
+
+```bash
+git branch --show-current
+git status --short
+git log --oneline develop..HEAD
+```
+
+**事前チェック:**
+- フィーチャーブランチにいること（`develop` や `main` ではない）
+- 変更がコミット済み
+- `develop` より先にコミットあり
+
+`develop` または `main` にいる場合、先にフィーチャーブランチを作成するよう案内する。
+
+### ステップ 2: プッシュ
+
+```bash
+git push -u origin {branch-name}
+```
+
+### ステップ 3: 変更分析
+
+```bash
+git log --oneline develop..HEAD
+git diff --stat develop..HEAD
+```
+
+最新コミットだけでなく全コミットを把握。
+
+### ステップ 4: PR作成
+
+```bash
+gh pr create --base develop --title "{title}" --body "$(cat <<'EOF'
+## 概要
+- {箇条書き}
+
+## 関連 Issue
+{Closes #N or Refs #N}
+
+## テスト計画
+- [ ] {テスト項目}
+EOF
+)"
+```
+
+**タイトルルール**: 70文字以内、プレフィックス(`feat:` 等)は英語、**それ以降は日本語**で記述する。Issue番号はタイトルに入れない。
+
+### ステップ 4b: Status 更新
+
+Issue 番号ありで起動された場合（例: `/creating-pr-on-issue 39`）、PR 作成直後に Status を Review に更新する:
+
+```bash
+shirokuma-docs issues update {number} --field-status "Review"
+```
+
+Issue 番号なしの場合はこのステップをスキップ（`ending-session` のセーフティネットでカバー）。
+
+### ステップ 5: 確認表示
+
+PR URL、ブランチ、コミット数、概要、リンクされた Issue を表示。
+
+### ステップ 6: セルフレビューチェーン
+
+PR 作成後、セルフレビューを**常に自動実行**する。
+
+#### 6a. ファイルカテゴリ検出
+
+`git diff --name-only develop..HEAD` で変更ファイルを取得し、カテゴリを判定：
+
+| カテゴリ | 判定条件 |
+|---------|---------|
+| config | `.claude/skills/`, `.claude/rules/`, `.claude/agents/`, `.claude/output-styles/`, `.claude/commands/`, `plugin/` 配下 |
+| code | `.ts`, `.tsx`, `.js`, `.jsx` ファイル |
+| docs | `.md` ファイル（上記 config パス配下を除く） |
+
+**ルーティング:**
+
+| ファイル構成 | レビュー方法 |
+|-------------|-------------|
+| config のみ | `claude-config-reviewing` のみ起動 |
+| code/docs のみ（config なし） | `reviewing-on-issue` のみ起動（従来通り） |
+| 混在（config + code/docs） | `reviewing-on-issue` → `claude-config-reviewing` 順次起動 → 結果統合 |
+
+**混在時の結果統合ルール:**
+- Status: いずれかが FAIL → FAIL
+- Critical/Warning: 両方の合計
+- Files with issues: マージ
+- Auto-fixable: いずれかが no → no
+
+#### 6b. セルフレビューループ
+
+```mermaid
+graph LR
+  A[PR作成] --> B[カテゴリ検出] --> C[ルーティング] --> D[レビュー実行] --> E{指摘あり?}
+  E -->|FAIL + Auto-fixable| F[自動修正] --> G[コミット] --> H[プッシュ] --> D
+  E -->|FAIL + Not auto-fixable| I[ループ停止、ユーザーに報告]
+  E -->|PASS| J[完了]
+```
+
+**ループ上限**: 最大3イテレーション（初回レビュー + 最大2回の修正・再レビュー）
+
+**手順:**
+
+1. カテゴリ検出して適切なスキルを起動（PR 番号をコンテキストとして渡す）
+2. レビュー結果の Self-Review Result を確認：
+   - **PASS**: ループ終了、完了報告
+   - **FAIL + Auto-fixable: yes**: 指摘に基づき自動修正 → `git add` → `git commit` → `git push` → 再レビュー
+   - **FAIL + Auto-fixable: no**: ループ停止、手動対応が必要な指摘を報告
+3. 3イテレーションでも FAIL の場合はループ停止、残りの指摘を報告
+
+**安全策:**
+- イテレーション間で issue 数が増加した場合（修正が新たな問題を生んだ場合）、ループを停止して報告
+- 各イテレーションのフィードバックを蓄積（`reviewing-on-issue` のフィードバック蓄積機能）
+
+**進捗報告:**
+
+```text
+セルフレビュー [1/3]: カテゴリ検出 → config + code（混在）
+  reviewing-on-issue 実行中...
+  claude-config-reviewing 実行中...
+  → 統合結果: 2 件の critical issue 検出、自動修正中...
+  → 修正完了、コミット・プッシュ
+
+セルフレビュー [2/3]: 再レビュー実行中...
+  → 問題なし。セルフレビュー完了。
+```
+
+## 引数
+
+Issue 番号付きで起動された場合（例: `/creating-pr-on-issue 39`）：
+- PR 本文に `Closes #39` を含める
+- Issue のコンテキストから PR タイトルを生成
+
+## 言語
+
+PR のタイトルと本文は日本語で記述する。Conventional commit プレフィックス (`feat:`, `fix:` 等) は常に英語。
+
+**NGタイトル例（日本語設定なのに英語）:**
+
+```
+feat: add branch workflow rules          ← 日本語設定では不正
+docs: update CLAUDE.md command table     ← 日本語設定では不正
+```
+
+## エッジケース
+
+| 状況 | アクション |
+|------|----------|
+| develop/main にいる | フィーチャーブランチ必要 |
+| 未コミット変更あり | 先にコミットを提案 |
+| コミットなし | PR作成不可 |
+| 既存PRあり | URL表示 |
+| プッシュ失敗 | エラー表示、`git pull --rebase` を提案 |
+
+## 次のステップ（スタンドアロン起動時のみ）
+
+`working-on-issue` チェーンから呼ばれた場合はセルフレビュー完了後にチェーンが自動続行するため、このセクションは適用されない。スタンドアロンで起動された場合のみ、次のワークフローステップを提案：
+
+```
+PR を作成しました。次のステップ:
+→ `/ending-session` で引き継ぎを保存し Issue ステータスを更新
+```
+
+## 注意事項
+
+- PR作成前に必ずプッシュ
+- `develop` や `main` から PR を作成しない
+- 日常作業は `develop` ターゲット（`main` はホットフィックスのみ）
+- `main` への直接 PR 禁止（ホットフィックスのみ例外）
+- ブランチ未作成・未コミット時は AskUserQuestion でコミットまたはブランチ作成を提案
+- Issue 参照を含めて自動リンクを有効にする
+- PR 本文は簡潔かつ情報量を確保
+- セルフレビューは常に自動実行
+- PR 本文に AI 署名（`🤖 Generated with Claude Code` 等）を含めない

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

@@ -0,0 +1,230 @@
+---
+name: ending-session
+description: 作業セッションを終了し、引き継ぎ情報を保存してプロジェクトアイテムを更新します。「セッション終了」「作業終了」「end session」「引き継ぎ保存」で起動。
+allowed-tools: Bash, Read, Write, Grep, Glob, AskUserQuestion
+---
+
+# セッション終了
+
+セッションを終了し、引き継ぎを自動保存する。
+
+## 引き継ぎは必須
+
+すべてのセッションは引き継ぎ Discussion で終了する**必要がある**（オプションではない）。短いセッションでも将来のセッションに有用なコンテキストを提供する。
+
+- 重要な作業がなくても、議論や調査の簡潔なサマリーを記載
+- ユーザーが引き継ぎをスキップしようとした場合、重要性を説明して作成を続行
+- Summary や Next Steps セクションを空にしない — 各セクション最低 1 行は記載
+
+## ワークフロー
+
+### ステップ 1: セッションサマリー収集
+
+会話を分析して以下を抽出:
+1. **サマリー**: 達成したこと（1-2文）
+2. **関連アイテム**: 作業したプロジェクトアイテム
+3. **主な決定事項**: 重要な決定とその根拠
+4. **ブロッカー**: 遭遇した障害
+5. **次のステップ**: 次回セッションの実行可能なタスク
+6. **変更ファイル**: `git status --short` から取得
+7. **コミット**: `git log --oneline` から取得（今回セッション分）
+
+### ステップ 2: 変更情報取得
+
+```bash
+git status --short | head -20
+git log --oneline -10
+git branch --show-current
+```
+
+### ステップ 3: プッシュ・PR 作成（フィーチャーブランチの場合）
+
+フィーチャーブランチ（ベースブランチ以外）にいる場合:
+
+#### 3a. 未コミット変更の確認
+
+```bash
+git status --short
+```
+
+未コミット変更がある場合、AskUserQuestion でコミットするか確認。
+`committing-on-issue` スキルのワークフローに従い、特定ファイルをステージ、Conventional Commits メッセージを作成（Co-Authored-By なし）、コミット。
+
+#### 3b. ブランチプッシュ
+
+```bash
+git push -u origin {branch-name}
+```
+
+#### 3c. PR 作成
+
+`creating-pr-on-issue` スキルのワークフローに従い、`develop` ターゲットで PR を作成（`branch-workflow` ルール参照）:
+
+```bash
+gh pr create --base develop --title "{タイトル}" --body "$(cat <<'EOF'
+## Summary
+{達成内容の箇条書き 1-3 点}
+
+## Related Issues
+{完了: Closes #N / 継続中: Refs #N}
+
+## Test plan
+- [ ] {テストチェックリスト}
+EOF
+)"
+```
+
+**PR タイトル**: 70 文字以内の簡潔なサマリー。
+**PR 本文**: 完了アイテムは `Closes #{number}`、継続中は `Refs #{number}`。
+**PR ベース**: 日常作業は常に `develop`。ホットフィックスのみ `main`。
+
+#### 3d. PR URL の記録
+
+引き継ぎ本文に含めるため PR URL を記録。
+
+ベースブランチにいる場合（フィーチャーブランチなし）、このステップ全体をスキップ。
+
+### ステップ 4: 引き継ぎ保存 + ステータス更新（単一コマンド）
+
+下記テンプレートで引き継ぎ本文を構築し、実行:
+
+```bash
+shirokuma-docs session end \
+  --title "$(date +%Y-%m-%d) - {サマリー}" \
+  --body "$HANDOVER_BODY" \
+  --done {完了issue番号} \
+  --review {レビュー中issue番号}
+```
+
+この単一コマンドで:
+- 引き継ぎ Discussion を作成（Handovers カテゴリ）
+- 指定した Issue を "Done" または "Review" ステータスに更新
+
+**オプション**:
+- `--title`（必須）- 引き継ぎタイトル、通常は日付 + サマリー
+- `--body`（必須）- Markdown 形式の引き継ぎ本文
+- `--done <numbers...>` - Done にする Issue 番号
+- `--review <numbers...>` - Review にする Issue 番号
+
+**--done vs --review の選択**:
+- `--done`: 作業完了、PR 不要（またはマージ済み）
+- `--review`: PR 作成済み、ユーザーレビュー待ち（PR がマージ済みなら自動で Done に昇格）
+
+**判定アルゴリズム**（各 Issue について）:
+
+| 優先度 | 条件 | アクション |
+|--------|------|----------|
+| 0 | ステータスが Planning または Spec Review | ステータス更新しない（pre-work ステータス、計画途中） |
+| 1 | Issue に関連するマージ済み PR がある | `--done` |
+| 2 | Issue に関連するオープン PR がある | `--review` |
+| 3 | PR 不要で作業完了 | `--done` |
+| 4 | 作業継続中（未完了） | ステータス更新しない |
+
+判定に必要な情報は `shirokuma-docs issues show {number}` で PR 状態を確認する。
+
+**冪等性**: `creating-pr-on-issue` が PR 作成時に既に Review に更新済みの場合、`--review` は no-op。`committing-on-issue` のマージチェーンが Done に更新済みの場合、`--done` は no-op。`ending-session` はセーフティネットとして機能し、スキルが更新し損ねた Status を補完する。
+
+**出力**:
+```json
+{
+  "handover": {
+    "number": 31,
+    "title": "2026-02-02 - Feature implementation",
+    "url": "https://github.com/..."
+  },
+  "updatedIssues": [
+    { "number": 27, "status": "Done" },
+    { "number": 26, "status": "Review" }
+  ]
+}
+```
+
+**ローカルフォールバック**（`session end` 失敗時）:
+
+```bash
+mkdir -p .claude/sessions
+echo "$HANDOVER_BODY" > .claude/sessions/$(date +%Y-%m-%d-%H%M%S)-handover.md
+```
+
+成功時、`session end` は `.claude/sessions/` 内の PreCompact バックアップを自動クリーンアップする。
+
+### ステップ 5: サマリー表示
+
+```markdown
+## セッション終了
+
+**保存先:** {handover.url or ローカルパス}
+**ブランチ:** {ブランチ名}
+**PR:** {PR URL or "N/A"}
+
+### 成果
+{サマリー}
+
+### 完了アイテム
+- #{number} → Done
+
+### レビュー中アイテム
+- #{number} → Review (PR #{pr_number})
+
+### 次のステップ
+- [ ] {タスク 1}
+- [ ] {タスク 2}
+```
+
+## 引き継ぎ本文テンプレート
+
+```markdown
+## サマリー
+{達成内容}
+
+## 関連アイテム
+- #{number} - {title} - {status}
+
+## 主な決定事項
+- {決定と根拠}
+
+## ブロッカー
+- {ブロッカー or なし}
+
+## 次のステップ
+- [ ] {次のタスク}
+
+## コミット（今回のセッション）
+| ハッシュ | 説明 |
+|---------|------|
+| {hash} | {message} |
+
+## プルリクエスト
+- {PR URL or "PR 未作成（ベースブランチで作業）"}
+
+## 変更ファイル
+- `path/file.ts` - {変更内容}
+
+## メモ
+{追加情報}
+```
+
+## エラーハンドリング
+
+| エラー | 対処 |
+|--------|------|
+| `session end` 失敗 | ローカルファイルに保存 |
+| "Handovers" カテゴリなし | ローカルファイルに保存 |
+| gh 未認証 | ローカルファイルに保存 |
+| セッション中に変更なし | 簡潔でも引き継ぎを保存 |
+| Issue がプロジェクトにない | 警告して続行 |
+| `git push` 失敗 | ユーザーに警告、PR なしで引き継ぎ保存 |
+| `gh pr create` 失敗 | ユーザーに警告、ブランチ名を引き継ぎに含める |
+| ベースブランチにいる（フィーチャーブランチなし） | プッシュ/PR ステップをスキップ、引き継ぎのみ保存 |
+
+## 注意事項
+
+- 確認なしで自動保存（高速ワークフローのため）
+- 短くても必ずサマリーを生成
+- ローカルフォールバックにより引き継ぎの喪失を防止
+- `session end` で引き継ぎ作成 + ステータス更新を 1 回で処理
+- PR 作成済みアイテムには `--review`、レビュー不要の完了アイテムには `--done`
+- トレーサビリティのため引き継ぎ本文に PR URL を含める
+- Summary / Next Steps を空にしない（最低 1 行ずつ記載）
+- PR 作成済みアイテムには `--review` を使用（`--done` ではない）
+- 複数アイテム更新時は TodoWrite で進捗管理