shirokuma-docs 0.1.0-alpha.1

package/plugin/shirokuma-skills-ja/rules/nextjs/tech-stack.md

@@ -0,0 +1,43 @@
+# 技術スタックリファレンス
+
+## 推奨スタック
+
+| カテゴリ | テクノロジー |
+|----------|-------------|
+| フロントエンド | Next.js 16 / React 19 / TypeScript 5 |
+| データベース | PostgreSQL 16 + Drizzle ORM |
+| 認証 | Better Auth（DB セッション） |
+| i18n | next-intl (ja/en) |
+| スタイリング | Tailwind CSS v4 + shadcn/ui |
+| テスト | Jest + Playwright |
+
+> プロジェクトの `package.json` に合わせてバージョンを更新してください。
+
+## 主要パターン
+
+| パターン | 概要 |
+|----------|------|
+| Async Params | `params: Promise<...>` → `await params` |
+| Server Actions | Auth → CSRF → Validation → DB → Redirect |
+| CSRF 保護 | クエリ: 読み取り専用チェック、ミューテーション: CSRF トークン |
+| レート制限 | 破壊的操作に `checkRateLimit()` |
+| 所有権チェック | ミューテーション前に `authorId === userId` を検証 |
+
+## Radix UI ハイドレーション（重要）
+
+```typescript
+const [mounted, setMounted] = useState(false)
+useEffect(() => { setMounted(true) }, [])
+
+if (!mounted) return <PlaceholderWithoutRadixUI />
+return <ComponentWithRadixUI />
+```
+
+## 既知の問題クイックリファレンス
+
+| 問題 | 修正 |
+|------|------|
+| ハイドレーション不一致 | `mounted` ステートパターンを使用 |
+| 本番で CSS 変数が壊れる | `@theme inline` を使用 |
+| ログインリダイレクトループ | `window.location.href` を使用 |
+| CSP: インラインスタイルがブロック | `'unsafe-inline'` を追加 |

package/plugin/shirokuma-skills-ja/rules/nextjs/testing.md

@@ -0,0 +1,66 @@
+---
+paths:
+  - "**/*.test.ts"
+  - "**/*.test.tsx"
+  - "__tests__/**/*"
+  - "tests/**/*"
+---
+
+# テスト規約
+
+## テスト構造
+
+```typescript
+describe("FeatureName", () => {
+  beforeEach(() => {
+    jest.clearAllMocks()
+  })
+
+  it("should create with valid data", async () => {
+    // Arrange
+    // Act
+    // Assert
+  })
+})
+```
+
+## モックパターン
+
+### Server Action モック
+
+```typescript
+jest.mock("@/lib/actions/crud/projects", () => ({
+  getProjects: jest.fn(),
+  createProject: jest.fn(),
+}))
+
+const mockGetProjects = getProjects as jest.MockedFunction<typeof getProjects>
+mockGetProjects.mockResolvedValue([{ id: "1", name: "Test" }])
+```
+
+### Auth モック
+
+```typescript
+jest.mock("@/lib/auth", () => ({
+  auth: jest.fn(() => Promise.resolve({
+    user: { id: "user-1", email: "test@example.com" }
+  }))
+}))
+```
+
+## テストのスキップ
+
+`.skip` 使用時は `@skip-reason` を追加：
+
+```typescript
+/**
+ * @skip-reason External API dependency, mock not implemented
+ */
+it.skip("should do X", () => { })
+```
+
+## 検証
+
+```bash
+pnpm test
+```

package/plugin/shirokuma-skills-ja/rules/output-destinations.md

@@ -0,0 +1,95 @@
+---
+paths:
+  - ".claude/skills/**/*.md"
+---
+
+# 出力先ルール
+
+## 概要
+
+Claude Code のスキルは2種類の出力を生成する。それぞれを適切な出力先にルーティングする。
+
+## 出力タイプ
+
+| タイプ | 出力先 | 寿命 |
+|--------|--------|------|
+| **作業レポート**（レビュー、lint結果） | GitHub Discussions (Reports) | 一時的 |
+| **最終ドキュメント**（API、アーキテクチャ） | shirokuma-docs ポータル | 永続的 |
+
+## 作業レポート → Discussions
+
+**用途**: レビューレポート、実装進捗、lint 結果
+
+```bash
+shirokuma-docs discussions create \
+  --category Reports \
+  --title "Review: {target}" \
+  --body "report content"
+```
+
+**特徴**: 作業セッション中に作成、人間の確認用、定期的にクリーンアップ可能
+
+## 最終ドキュメント → ポータル
+
+**用途**: 完成した機能ドキュメント、API リファレンス、アーキテクチャ図
+
+```bash
+shirokuma-docs portal -p . -o docs/portal
+```
+
+**特徴**: 作業完了後に作成、永続的なプロジェクトドキュメント、コードアノテーションから自動生成
+
+## ローカルログからの移行
+
+**旧パターン**（非推奨）:
+```
+logs/reports/YYYY-MM-DD-*.md
+logs/reviews/YYYY-MM-DD-*.md
+```
+
+**新パターン**:
+```
+作業レポート → GitHub Discussions (Reports)
+最終ドキュメント → shirokuma-docs ポータル
+```
+
+## スキル更新時の対応
+
+スキルを更新する際、ローカルログ参照を置換：
+
+| 旧 | 新 |
+|----|-----|
+| `logs/reports/ に保存` | `Reports カテゴリに Discussion を作成` |
+| `logs/reviews/ に保存` | `Reports カテゴリに Discussion を作成` |
+| レポートファイルパス出力 | Discussion URL 出力 |
+
+## PR レビュー → PR コメント
+
+PR を対象としたレビュー結果は、PR コメントに直接投稿する。
+
+```bash
+shirokuma-docs issues comment {PR#} --body "レビュー結果サマリー"
+```
+
+| 条件 | 出力先 |
+|------|--------|
+| PR レビュー（通常） | PR コメント（サマリー） |
+| PR レビュー（error 5件以上） | PR コメント + Discussion（詳細） |
+| ファイル/ディレクトリレビュー | Discussion (Reports) |
+
+## Reports カテゴリの用途
+
+| 用途 | 例 |
+|------|-----|
+| 包括的レビューレポート | プロジェクト全体のセキュリティ監査 |
+| 調査・リサーチ結果 | ベストプラクティス調査、技術比較 |
+| セルフレビューフィードバック | 自動レビューループの検出パターン蓄積 |
+
+**Reports カテゴリに保存しないもの**: PR 固有のレビュー結果（→ PR コメントに投稿）
+
+## ルール
+
+- **ローカルファイルなし**: レポートをリポジトリに保存しない
+- **ブラウザフレンドリー**: GitHub Discussions で人間が簡単にレビュー
+- **明確な分離**: 一時的（Discussions）vs 永続的（ポータル）
+- **PR レビュー → PR コメント**: PR 対象のレビューは PR に直接投稿

package/plugin/shirokuma-skills-ja/rules/shirokuma-docs/cli-invocation.md

@@ -0,0 +1,15 @@
+# shirokuma-docs CLI の呼び出し
+
+## 直接呼び出し（npx 不要）
+
+`shirokuma-docs` はグローバルにインストール済み。常に直接呼び出す：
+
+```bash
+# 正しい
+shirokuma-docs session start
+shirokuma-docs issues list
+shirokuma-docs lint-tests -p .
+
+# 間違い - 不要なオーバーヘッド
+npx shirokuma-docs session start
+```

package/plugin/shirokuma-skills-ja/rules/shirokuma-docs/plugin-cache.md

@@ -0,0 +1,54 @@
+# プラグインキャッシュ管理
+
+## アーキテクチャ
+
+Claude Code はスキルを**グローバルキャッシュ**から読み込む。プロジェクトローカルの `.claude/plugins/` ディレクトリからではない。
+
+```
+plugin/ (バンドルソース)
+    ↓ shirokuma-docs update（= update-skills --sync）
+.claude/plugins/shirokuma-skills-ja/   (プロジェクトローカルコピー)
+    ↓ claude plugin install/update
+~/.claude/plugins/cache/...         (グローバルキャッシュ — Claude Code はここから読み込む)
+```
+
+## 推奨: `shirokuma-docs update`
+
+`shirokuma-docs update` は `update-skills --sync` の短縮コマンド。スキル・ルール更新+キャッシュ同期を一発で実行する。
+
+```bash
+# 推奨（短縮コマンド）
+shirokuma-docs update
+
+# 同等（フルコマンド）
+shirokuma-docs update-skills --sync
+```
+
+## `update` で新しいスキルが追加された後
+
+`shirokuma-docs update` が新しいスキルの追加を報告した場合、グローバルキャッシュも更新が必要：
+
+```bash
+# プラグインバージョンが変更された場合
+claude plugin update shirokuma-skills-ja@shirokuma-library --scope project
+
+# プラグインバージョンが同じ場合（update が「already at latest」と報告）
+claude plugin uninstall shirokuma-skills-ja@shirokuma-library --scope project
+claude plugin install shirokuma-skills-ja@shirokuma-library --scope project
+```
+
+キャッシュ更新後、スキルが表示されるには新しいセッションが必要。
+
+## ユーザーへのガイダンスが必要な場合
+
+| 症状 | 原因 | アクション |
+|------|------|----------|
+| 新しいスキルがスキルリストにない | キャッシュ未更新 | `claude plugin uninstall` + `install` |
+| `plugin update` が「already at latest」と表示 | バージョン番号が同じ | uninstall + install を使用 |
+| あるプロジェクトでスキルが動くが別では動かない | プラグインスコープの不一致 | `--scope`（user vs project）を確認 |
+
+## ルール
+
+1. **グローバルキャッシュに直接書き込まない** — `claude plugin` コマンドを使用
+2. **`shirokuma-docs update` を推奨** — `update-skills --sync` の短縮形。新スキル追加時はキャッシュ同期について必ずリマインド
+3. **バージョンが同じ場合の更新は uninstall + install** — `plugin update` はバージョン未変更時にスキップする

package/plugin/shirokuma-skills-ja/rules/shirokuma-docs/shirokuma-annotations.md

@@ -0,0 +1,78 @@
+---
+paths:
+  - "**/*.test.ts"
+  - "**/*.test.tsx"
+  - "lib/actions/**/*.ts"
+  - "**/app/**/page.tsx"
+  - "components/**/*.tsx"
+---
+
+# shirokuma-docs アノテーション
+
+## ファイルタイプ別の必須タグ
+
+| ファイルタイプ | 必須タグ |
+|---------------|---------|
+| テスト (`*.test.ts`) | 各 `it()` に `@testdoc` |
+| Server Action | `@serverAction`, `@feature`, `@dbTables` |
+| ページコンポーネント | `@screen`, `@route` |
+| コンポーネント | `@component` |
+| 型定義のみのファイル | `@skip-test` |
+
+## テストアノテーション（必須）
+
+```typescript
+/**
+ * @testdoc Creates a new user with valid data
+ * @purpose Verify user creation happy path
+ * @precondition Valid email and password
+ * @expected User is created and ID is returned
+ */
+it("should create user with valid data", async () => {
+  // test
+});
+```
+
+## スクリーンアノテーション
+
+```typescript
+/**
+ * Dashboard screen
+ *
+ * @screen DashboardScreen
+ * @route /dashboard
+ * @usedComponents ProjectList, ActivityFeed
+ * @usedActions getProjects, getActivities
+ */
+export default function DashboardPage() { }
+```
+
+## Server Action アノテーション
+
+```typescript
+/**
+ * Get project list
+ *
+ * @serverAction
+ * @feature ProjectManagement
+ * @dbTables projects
+ * @authLevel member
+ */
+export async function getProjects(orgId: string) { }
+```
+
+## テストスキップアノテーション
+
+```typescript
+/**
+ * @skip-test Type definitions only - no runtime logic
+ */
+export type Project = typeof projects.$inferSelect
+```
+
+## 検証
+
+```bash
+shirokuma-docs lint-tests -p . -f terminal
+shirokuma-docs lint-coverage -p . -f summary
+```

package/plugin/shirokuma-skills-ja/rules/skill-authoring.md

@@ -0,0 +1,184 @@
+---
+paths:
+  - ".claude/skills/**/*.md"
+  - ".claude/agents/**/*.md"
+  - ".claude/output-styles/**/*.md"
+  - ".claude/commands/**/*.md"
+---
+
+# Claude 設定ファイル作成ルール
+
+## 命名規約
+
+**形式**: `動名詞形`（動詞 + -ing）、小文字、ハイフン、最大64文字
+
+```yaml
+# 良い例
+name: processing-pdfs
+name: managing-agents
+
+# 悪い例
+name: PDF-Processor    # 動名詞でない、大文字
+name: helper           # 曖昧すぎる
+```
+
+## description（重要）
+
+**テンプレート**: `[機能の説明]. Use when [トリガー].`
+
+**要件**:
+- 最大1024文字
+- 三人称
+- WHAT（機能）と WHEN（トリガー）を含む
+- 山括弧禁止（`<example>` は不可）
+
+```yaml
+# 良い例
+description: PDFファイルからテキストを抽出します。PDFを扱う場合や「PDF」「PDF処理」に言及された場合に使用。
+
+# 悪い例
+description: Helps with documents  # 曖昧、トリガーなし
+```
+
+## ファイルサイズ制限
+
+- `SKILL.md` / `AGENT.md`: 500行以下
+- すべての文の必要性を精査
+- 詳細な内容はリファレンスファイルに移動
+
+## 言語ガイドライン
+
+| ファイルタイプ | 言語 |
+|---------------|------|
+| SKILL.md / AGENT.md | 日本語 |
+| rules/*.md | 日本語 |
+| output-styles/*.md | 日本語 |
+| CLAUDE.md | 日本語 |
+| description (SKILL.md frontmatter) | 日本語 + 英語技術用語（下記参照） |
+
+- **避ける**: 重いテーブルフォーマット（トークン非効率）
+- **EN版 description**: 英語キーワードのみ（日本語トリガー不要）
+- **JA版 description**: 日本語 + 日本語ユーザーが実際に使う英語技術用語（例: 「コミット」+「commit」）
+- **存在しないスラッシュコマンド禁止**: `/skill-name` は実在するコマンドのみ参照可。引用符付きキーワードを使用（例: 「commit」であって「/commit」ではない）
+
+## ファイル構造
+
+```
+skill-name/
+├── SKILL.md        # 必須、500行以下
+├── reference.md    # オプション、詳細仕様
+├── examples.md     # オプション、I/O 例
+└── scripts/        # オプション、自動化
+```
+
+## コンテキスト効率原則
+
+制約が多いほど LLM の遵守率が低下する。ロール別に密度を調整すること。
+
+### ロール別密度方針
+
+| ロール | 制約密度 | 理由 |
+|--------|---------|------|
+| **レビュアー** (`context: fork`) | 多くてOK | 観察・報告タスクは遵守率が高い |
+| **コーダー** | 最小限に | コード生成 + 制約遵守の複合タスク |
+
+### 執筆原則
+
+- **Name it, don't explain it**: 既知概念は名前で参照（例: "Conventional Commits に従う" で十分）
+- **Detail only project-specific**: プロジェクト固有ルールのみ詳述
+- **Consolidate, don't scatter**: 同じルールを複数ファイルに分散させない
+- **Compress, don't expand**: 冗長なテーブルは箇条書きやインラインに圧縮
+
+### LLM に任せてよいもの
+
+- 既知概念の説明（Git Flow, TDD, Conventional Commits 等）
+- 一般的なベストプラクティス
+- 言語・フレームワークの基本構文
+
+## SKILL.md 必須コンテンツ
+
+圧縮時でも以下は**削除してはならない**。
+
+### 1. ワークフロー（必須）
+
+ステップバイステップの作業フローは省略不可。LLM はフローを推測できるが、プロジェクト固有の順序・条件分岐・ゲートは明記が必要。
+
+```markdown
+## ワークフロー
+### Step 1: 準備
+...
+### Step 2: 実行
+...
+### Step 3: 検証
+...
+```
+
+### 2. ツール使用タイミング（必須）
+
+スキル内でいつどのツールを使うかを明記:
+- **TodoWrite**: 3ステップ以上の作業、マルチ Issue 時
+- **AskUserQuestion**: 判断が必要な分岐点、複数アプローチの選択
+- **Task**: 並行調査、フォーク実行
+- **EnterPlanMode**: スキルワークフローでは不要（計画は Issue 本文に書き出し、Spec Review で承認を管理するため。`plansDirectory` は万が一の安全策として設定済み）
+
+ツール指示がないと LLM は自己判断で使用をスキップする。
+
+### 3. NGケース / チェックリスト（必須）
+
+そのスキル固有の「やってはいけないこと」を明示:
+- 一般的な NG ではなく**プロジェクト固有の NG** を記載
+- 例: committing-on-issue → `--no-verify` 禁止、`Co-Authored-By` 不要
+- 例: creating-pr-on-issue → ベースブランチへの直接プッシュ禁止
+
+完了条件や品質ゲートもチェックリストで明示:
+
+```markdown
+## チェックリスト
+- [ ] ビルドが通ること
+- [ ] ユーザーに確認を取ったこと
+```
+
+### 4. 出力テンプレート内蔵（推奨）
+
+スキルが Task や fork で呼び出される場合、出力形式はスキル自身が保持すべき。呼び出し側が出力テンプレートを prompt に埋め込む設計は避ける。
+
+```
+# NG: 呼び出し側が出力形式を定義
+Task(prompt: "レビューして。出力は以下の形式で: ## 結果\n| 項目 | 判定 |...")
+
+# OK: スキル側が出力形式を保持
+Skill("reviewing-on-issue")  # 出力形式はスキル内に定義済み
+```
+
+**原則**:
+- スキルは自身の出力テンプレートを SKILL.md 内または reference ファイルに保持する
+- 呼び出し側は入力データ（Issue 番号、対象ファイル等）のみ渡す
+- 出力形式の変更はスキル側を1箇所修正するだけで済む
+
+**良い例**: reviewing-on-issue（Self-Review Result テンプレートを内蔵）、claude-config-reviewing（品質チェックリストを内蔵）
+
+## アンチパターン
+
+- 深い参照チェーン（SKILL.md から1レベルに保つ）
+- Windows のバックスラッシュ（フォワードスラッシュのみ）
+- デフォルトなしのオプション過多
+- 具体的なトリガーのない曖昧な命名
+- LLM が知っている概念の長い説明
+- 動機付け・哲学セクション（"なぜ" より "何を"）
+- **ワークフローの省略**（フローは LLM に推測させてはいけない）
+- **ツール使用指示の省略**（TodoWrite, AskUserQuestion 等の使い所）
+- **NGケースの省略**（禁止事項がないと LLM はデフォルト動作する）
+
+## バリデーションチェックリスト
+
+コミット前に確認：
+- [ ] 名前: 動名詞形、小文字
+- [ ] description: トリガー、三人称、`<>` なし
+- [ ] SKILL.md: 500行以下
+- [ ] フロントマター: 有効な YAML（タブではなくスペース）
+- [ ] パス: フォワードスラッシュのみ
+- [ ] **ワークフロー**: ステップバイステップのフローが記載されているか
+- [ ] **ツール使用**: TodoWrite / AskUserQuestion / Task の使い所が明記されているか
+- [ ] **NGケース**: スキル固有の禁止事項・チェックリストがあるか
+- [ ] コーダー系: 既知概念の説明を削除し参照のみにしたか
+- [ ] レビュアー系: チェックリストの網羅性は十分か

package/plugin/shirokuma-skills-ja/skills/best-practices-researching/SKILL.md

@@ -0,0 +1,144 @@
+---
+name: best-practices-researching
+description: 公式ドキュメントとプロジェクトパターンを調査してから実装する。新機能の開始時、ベストプラクティスが不明な場合、「Xのベストプラクティスを調べて」「Yの実装方法は？」などのリクエスト時に使用。トリガー: "ベストプラクティス調査", "実装方法を調べて", "Drizzleでソフトデリートってどう実装するのがベスト？", "research best practices", "how should I implement".
+context: fork
+agent: general-purpose
+model: opus
+allowed-tools: Read, Grep, Glob, WebSearch, WebFetch, Bash, AskUserQuestion, TodoWrite
+---
+
+# ベストプラクティス調査
+
+公式ドキュメントとプロジェクトパターンを調査し、実装ガイダンスを提供する。`context: fork` で隔離実行。
+
+## コア責務
+
+- 公式ドキュメントから推奨パターンを検索
+- 既存プロジェクトパターンとの一貫性を確認
+- 調査結果を実行可能な推奨事項として統合
+- 重要な調査結果を将来の参照用に保存
+
+## 技術スタック ドキュメントソース
+
+| 技術 | 公式ドキュメント |
+|------|----------------|
+| Next.js 16 | nextjs.org/docs |
+| React 19 | react.dev |
+| Drizzle ORM | orm.drizzle.team/docs |
+| Better Auth | better-auth.com/docs |
+| shadcn/ui | ui.shadcn.com |
+| Tailwind CSS v4 | tailwindcss.com/docs |
+| next-intl | next-intl.dev/docs |
+| Playwright | playwright.dev/docs |
+
+## ワークフロー
+
+### 1. リクエスト分析
+
+ユーザーが実装・理解したい内容を解析:
+- 機能の種類（CRUD、認証、UIコンポーネント等）
+- 関連技術
+- 特定の懸念事項や制約
+
+調査方向が不明確な場合は `AskUserQuestion` で確認。複数技術の調査時は `TodoWrite` で管理。
+
+### 2. プロジェクトパターン検索
+
+プロジェクト内の既存パターンを確認:
+
+```bash
+# プロジェクトコードを検索
+Grep: [関連パターン] in {project}/
+```
+
+**参考パターン**（`nextjs-vibe-coding` スキルのナレッジベースで提供）:
+- `code-patterns.md` - Server Actions、i18n、フォーム
+- `better-auth.md` - 認証パターン
+- `drizzle-orm.md` - データベースパターン
+- `tailwind-v4.md` - スタイリングパターン
+
+### 3. 公式ドキュメント検索
+
+WebSearch で公式推奨を検索:
+
+```
+WebSearch: "[技術] [機能] best practices 2026"
+WebSearch: "[技術] official documentation [トピック]"
+```
+
+**優先順位**:
+1. 公式ドキュメント
+2. GitHub issues/discussions
+3. コミュニティベストプラクティス
+
+### 4. 調査結果の統合
+
+公式推奨とプロジェクトパターンを比較:
+- ギャップや不一致を特定
+- プロジェクト固有の適応を記録
+- 矛盾がある場合はフラグ
+
+### 5. 保存（任意）
+
+重要な調査結果は Research カテゴリに Discussion を作成:
+
+```bash
+shirokuma-docs discussions create --category Research --title "[Research] {トピック}" --body "{調査結果}"
+```
+
+## 出力フォーマット
+
+```markdown
+# 調査: [トピック]
+
+## サマリー
+[調査結果の1-2行概要]
+
+## 公式推奨事項
+- **[ソース]**: [主要な推奨事項]
+- **[ソース]**: [主要な推奨事項]
+
+## プロジェクトパターン
+- **[ファイル]**: [プロジェクト内の既存パターン]
+- **[ファイル]**: [関連する実装]
+
+## 推奨事項
+
+### やるべき
+- [コード例付きの具体的な推奨事項]
+
+### 避けるべき
+- [避けるべきアンチパターン]
+
+## 実装メモ
+[このプロジェクト固有の考慮事項]
+
+## ソース
+- [URL 1]
+- [URL 2]
+```
+
+## 基本原則
+
+1. **公式優先**: 常に公式ドキュメントを最優先
+2. **プロジェクト一貫性**: 既存のプロジェクトパターンと整合
+3. **実行可能な出力**: 具体的で実装可能な推奨事項を提供
+4. **ソース帰属**: トレーサビリティのため常にソースを引用
+5. **簡潔さ**: 調査結果は簡潔でスキャンしやすい形に
+
+## アンチパターン
+
+- 未検証の情報を推奨事項に含めない
+- ソース URL を省略しない
+- 古いバージョンのドキュメントを参照しない
+
+## 完了チェックリスト
+
+- [ ] 公式ドキュメントを最低 1 つ参照した
+- [ ] すべての推奨事項にソースが付与されている
+- [ ] プロジェクトパターンとの比較を行った
+
+## 注意事項
+
+- 調査結果は `nextjs-vibe-coding` スキルに渡して実装可能
+- `context: fork` で隔離サブエージェントとして実行（メインコンテキストを汚染しない）