shirokuma-docs 0.1.0-alpha.1

package/plugin/shirokuma-skills-ja/skills/managing-github-items/SKILL.md

@@ -0,0 +1,50 @@
+---
+name: managing-github-items
+description: GitHubプロジェクトアイテム（Issue / Discussion）を作成・管理します。「アイテム作成」「Issue 作成」「Issue にして」「仕様作成」「create item」「create spec」「フォローアップ Issue」で使用。
+allowed-tools: Bash, AskUserQuestion, Read, Write
+---
+
+# GitHub アイテムの管理
+
+Issue / Discussion の作成と仕様 Discussion の管理を行う。
+
+## コマンドルーティング
+
+| コマンド | 用途 | リファレンス |
+|---------|------|------------|
+| `/create-item` | Issue / DraftIssue 作成 | [reference/create-item.md](reference/create-item.md) |
+| `/create-spec` | 仕様 Discussion 作成 | [reference/create-spec.md](reference/create-spec.md) |
+
+## パターン判定
+
+| ユーザー発話 | ルート先 |
+|-------------|---------|
+| 「Issue にして」「Issue 作って」「フォローアップ Issue」 | `/create-item` |
+| 引数なしで呼び出された場合 | `/create-item`（コンテキスト自動推定） |
+| 「仕様を書いて」「Spec 作成」「Discussion で提案」 | `/create-spec` |
+
+## 共通リファレンス
+
+| ドキュメント | 内容 | 読み込みタイミング |
+|-------------|------|-------------------|
+| [reference/github-operations.md](reference/github-operations.md) | GitHub CLI コマンド・ステータスワークフロー | 全コマンド共通 |
+| [reference/create-item.md](reference/create-item.md) | Issue 作成ワークフロー・コンテキスト推定 | `/create-item` 実行時 |
+| [reference/create-spec.md](reference/create-spec.md) | 仕様 Discussion 作成ワークフロー | `/create-spec` 実行時 |
+
+## エラーハンドリング
+
+| エラー | 対処 |
+|--------|------|
+| プロジェクト未作成 | "`/project-setup` でプロジェクトを作成してください" |
+| gh 未認証 | "`gh auth login` を実行してください" |
+| フィールド未発見 | デフォルト値を使用、ユーザーに警告 |
+| Issue 未発見 | "Issue #{n} が見つかりません。番号を確認してください" |
+| Ideas カテゴリなし | General に作成、Ideas 追加を提案 |
+| Discussions 無効 | `.claude/specs/` に保存 |
+| 必須フィールド空 | ユーザーに入力を求める |
+
+## 注意事項
+
+- 新規アイテムには必ず必須フィールド（Status, Priority, Type）を設定
+- XL アイテムは分割を検討するようユーザーに提案
+- 仕様タイトルには "[Spec]" プレフィックスを付与（フィルタリング用）

package/plugin/shirokuma-skills-ja/skills/managing-github-items/reference/create-item.md

@@ -0,0 +1,82 @@
+# /create-item ワークフロー
+
+Issue または DraftIssue を作成する。引数なしの場合、会話コンテキストから自動推定する。
+
+```
+/create-item                    # コンテキスト自動推定モード
+/create-item "タイトル"          # タイトル指定
+/create-item --type feature     # タイプ指定
+```
+
+## ステップ 1: 詳細収集
+
+引数あり: 指定されたタイトルを使用。
+引数なし: 会話コンテキストから以下を推定する。
+
+| 推定対象 | 情報源 | 推定方法 |
+|---------|--------|---------|
+| タイトル | 直前のユーザー発話 | 「Issue にして」の前に述べられた問題・機能の要約 |
+| Type | 会話コンテキスト | バグ報告 → Bug、機能要望 → Feature、技術的負債 → Chore |
+| Priority | 会話コンテキスト | 緊急性の表現（「すぐ」→ High、通常 → Medium） |
+| 本文 | 会話コンテキスト全体 | 概要・背景・タスクを構造化 |
+| Size | タスク推定 | タスク数・影響範囲から推定（デフォルト S） |
+
+推定結果を AskUserQuestion で確認してから作成する。
+
+タイプ一覧:
+
+| タイプ | ラベル |
+|--------|--------|
+| Feature | `feature` |
+| Bug | `bug` |
+| Chore | `chore` |
+| Docs | `docs` |
+| Research | `research` |
+
+## ステップ 2: 本文生成
+
+```markdown
+## 概要
+{何を、なぜ行うか}
+
+## 背景
+{この Issue が存在する理由、現状の問題、関連する技術的制約や依存関係}
+
+## タスク
+- [ ] タスク 1
+
+## 成果物
+{"完了" の定義}
+```
+
+> **背景セクション**: 計画レビュー（`planning-on-issue` ステップ 4）で、Issue 本文だけから計画を評価する。背景・制約・依存関係が不足していると、レビュアーが NEEDS_REVISION を返す。軽量な Issue（タイポ修正等）では 1 行で十分。
+
+## ステップ 3: フィールド設定
+
+| フィールド | 選択肢 | デフォルト |
+|-----------|--------|----------|
+| Priority | Critical / High / Medium / Low | Medium |
+| Size | XS / S / M / L / XL | S |
+| Status | Backlog / Ready | Backlog |
+
+## ステップ 4: 作成
+
+```bash
+# Issue（推奨 — #番号をサポート）
+shirokuma-docs issues create \
+  --title "Title" --body "Body" \
+  --labels feature \
+  --field-status "Backlog" --priority "Medium" --type "Feature" --size "M"
+
+# DraftIssue（軽量）
+shirokuma-docs projects create \
+  --title "Title" --body "Body" \
+  --field-status "Backlog" --priority "Medium"
+```
+
+## ステップ 5: 結果表示
+
+```markdown
+## アイテム作成完了
+**Issue:** #123 | **タイプ:** Feature | **優先度:** Medium | **ステータス:** Backlog
+```

package/plugin/shirokuma-skills-ja/skills/managing-github-items/reference/create-spec.md

@@ -0,0 +1,68 @@
+# /create-spec ワークフロー
+
+Ideas カテゴリに仕様 Discussion を作成する。
+
+```
+/create-spec "機能名"
+/create-spec                    # インタラクティブモード
+```
+
+## ステップ 1: カテゴリ ID 取得
+
+```bash
+OWNER=$(gh repo view --json owner -q '.owner.login')
+REPO=$(gh repo view --json name -q '.name')
+CATEGORY_ID=$(gh api graphql -f query='{
+  repository(owner: "'$OWNER'", name: "'$REPO'") {
+    discussionCategories(first: 10) { nodes { id name } }
+  }
+}' | jq -r '.data.repository.discussionCategories.nodes[] | select(.name == "Ideas") | .id')
+```
+
+## ステップ 2: 詳細収集
+
+ユーザーに確認: タイトル、概要、課題、提案、代替案（任意）
+
+## ステップ 3: 本文生成
+
+```markdown
+## 概要
+{概要}
+
+## 課題
+{問題}
+
+## 提案する解決策
+{提案}
+
+## 検討した代替案
+{代替案 or "なし"}
+
+## オープンクエスチョン
+- [ ] {質問}
+
+---
+ステータス: ドラフト
+```
+
+## ステップ 4: Discussion 作成
+
+```bash
+gh api graphql \
+  -f query='mutation($repoId: ID!, $catId: ID!, $title: String!, $body: String!) {
+    createDiscussion(input: {repositoryId: $repoId, categoryId: $catId, title: $title, body: $body}) {
+      discussion { url number }
+    }
+  }' \
+  -f repoId="$REPO_ID" -f catId="$CATEGORY_ID" \
+  -f title="[Spec] $TITLE" -f body="$BODY"
+```
+
+## ローカルフォールバック
+
+Discussions が利用不可の場合:
+
+```bash
+mkdir -p .claude/specs
+echo "$BODY" > .claude/specs/$(date +%Y-%m-%d)-{slug}.md
+```

package/plugin/shirokuma-skills-ja/skills/managing-github-items/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/managing-output-styles/SKILL.md

@@ -0,0 +1,233 @@
+---
+name: managing-output-styles
+description: Claude Codeの出力スタイルを管理。デフォルト/説明的/学習モードの切り替えやカスタムスタイルの作成を行います。「output style」「explanatory mode」「learning mode」「change style」「create custom style」、「explanatory modeに切り替えて」「スタイル変更」「カスタムスタイル作成」がトリガー。
+allowed-tools: Read, Write, Edit, Glob, Grep
+---
+
+# 出力スタイルの管理
+
+ビルトインスタイルの切り替えやカスタムスタイルの作成で Claude Code の動作を設定する。
+
+## いつ使うか
+
+- 「スタイル変更」「change output style」「switch to explanatory mode」
+- 「学習モード」「learning mode」「default mode」
+- 「カスタムスタイル作成」「create custom output style」
+- 「現在のスタイルは?」「what output style am I using」
+- 「スタイル一覧」「show available styles」「list output styles」
+
+## 概要
+
+出力スタイルは Claude Code のシステムプロンプトを変更し、ユースケースに応じた動作を実現する:
+
+- **default**: 標準エンジニアリングモード（効率的、プロダクション重視）
+- **explanatory**: 判断を説明する「Insights」セクション追加
+- **learning**: `TODO(human)` マーカー付き協調モード（ハンズオン練習用）
+
+カスタムスタイルで無制限のパーソナライズが可能。
+
+## ワークフロー
+
+### ステップ 1: 現在のスタイル確認
+
+ローカル設定ファイルを確認:
+
+```bash
+cat .claude/settings.local.json
+```
+
+`outputStyle` フィールドを確認。存在しなければ "default" がアクティブ。
+
+### ステップ 2: ビルトインスタイルに切り替え
+
+スラッシュコマンドを使用:
+
+```bash
+/output-style [style-name]
+```
+
+例:
+- `/output-style default` - 標準エンジニアリングモード
+- `/output-style explanatory` - 教育的インサイト
+- `/output-style learning` - ハンズオン練習モード
+
+インタラクティブメニューを開く:
+
+```bash
+/output-style
+```
+
+### ステップ 3: カスタムスタイル作成
+
+#### インタラクティブ作成:
+
+```bash
+/output-style:new [望む動作の説明]
+```
+
+例:
+```bash
+/output-style:new Focus on security best practices and include threat modeling
+```
+
+#### 手動作成:
+
+1. 保存場所を選択:
+   - ユーザーレベル: `~/.claude/output-styles/style-name.md`
+   - プロジェクトレベル: `.claude/output-styles/style-name.md`
+
+2. フロントマター付き Markdown ファイルを作成:
+
+```markdown
+---
+name: security-focused
+description: Emphasize security best practices
+---
+
+# Security-Focused Development
+
+When writing code:
+- Always consider OWASP Top 10 vulnerabilities
+- Include security comments for sensitive operations
+- Suggest security testing approaches
+- Flag potential security risks
+
+[追加の指示...]
+```
+
+3. 有効化:
+
+```bash
+/output-style security-focused
+```
+
+### ステップ 4: カスタムスタイル編集
+
+1. スタイルファイルを探す:
+
+```bash
+# ユーザーレベル
+ls ~/.claude/output-styles/
+
+# プロジェクトレベル
+ls .claude/output-styles/
+```
+
+2. 現在の内容を確認:
+
+```bash
+cat ~/.claude/output-styles/style-name.md
+```
+
+3. Edit ツールでファイルを編集
+
+4. Claude Code 再起動またはスタイル再適用:
+
+```bash
+/output-style style-name
+```
+
+## よくあるパターン
+
+### パターン 1: クイックスタイル切り替え
+
+頻繁な切り替え用に `.claude/commands/` にショートカットを作成:
+
+```bash
+# .claude/commands/explain.md
+Switch to explanatory output style with /output-style explanatory
+```
+
+使用: `/explain`
+
+### パターン 2: チーム共有スタイル
+
+カスタムスタイルを `.claude/output-styles/` に配置して git にコミット:
+
+```bash
+git add .claude/output-styles/team-style.md
+git commit -m "Add team output style"
+```
+
+チームメンバーは以下で有効化:
+
+```bash
+/output-style team-style
+```
+
+### パターン 3: タスク特化スタイル
+
+特定ワークフロー用のスタイルを作成:
+- `refactoring-focused.md` - コード品質とテスト重視
+- `documentation-first.md` - インラインドキュメントと README 更新優先
+- `performance-optimized.md` - ベンチマークと最適化重視
+
+[examples.md](examples.md) に完全な例あり。
+
+## 関連機能との違い
+
+| 機能 | 目的 | スコープ |
+|------|------|---------|
+| 出力スタイル | システムプロンプトを変更 | Claude の基本動作を変更 |
+| CLAUDE.md | コンテキスト追加 | ユーザーメッセージとして付加 |
+| --append-system-prompt | プロンプト拡張 | システムプロンプトに追加（置換ではない） |
+| エージェント | 特化タスク | 専用モデルと特定ツール |
+
+出力スタイルはシステムプロンプトを**置換**するが、コア機能は保持される。
+
+## エラーハンドリング
+
+### カスタムスタイルが見つからない
+
+```
+Error: Output style 'my-style' not found
+```
+
+**解決策**: ファイルの存在と名前の一致を確認:
+
+```bash
+# ファイル存在確認
+ls ~/.claude/output-styles/my-style.md
+ls .claude/output-styles/my-style.md
+
+# フロントマターの name 確認
+cat ~/.claude/output-styles/my-style.md
+```
+
+### スタイル変更が反映されない
+
+**解決策**: スタイルファイル編集後に Claude Code を再起動、または `/output-style style-name` を再実行。
+
+### 無効な YAML フロントマター
+
+```
+Error: Invalid frontmatter in output style
+```
+
+**解決策**: YAML 構文を検証（タブではなくスペース使用）:
+
+```yaml
+---
+name: my-style        # シンプルな名前には引用符不要
+description: Brief description
+---
+```
+
+## 関連リソース
+
+- [reference.md](reference.md) - 完全なフロントマター仕様、設定ファイル形式
+- [examples.md](examples.md) - よくあるユースケースのカスタムスタイル例
+
+## 注意事項
+
+- 設定は `.claude/settings.local.json` に保存（プロジェクトレベル）
+- カスタムスタイルは `~/.claude/output-styles/`（ユーザー）または `.claude/output-styles/`（プロジェクト）
+- ユーザーレベルスタイルは全プロジェクトで利用可能
+- プロジェクトレベルは同名のユーザーレベルをオーバーライド
+- パスは常にスラッシュを使用（クロスプラットフォーム）
+- フロントマターはタブではなくスペースを使用
+- `/output-style` コマンド使用時はスタイル変更が即座に反映
+- コア機能（Read, Write, Bash 等）は全スタイルで保持
+- カスタムスタイルの方向性は AskUserQuestion で確認してから作成
+- 複数スタイル作成時は TodoWrite で管理
+- ビルトインスタイル名（default, explanatory, learning）と衝突する名前を使わない