shirokuma-docs 0.1.0-alpha.1

package/plugin/shirokuma-skills-ja/skills/reviewing-on-issue/roles/code.md

@@ -0,0 +1,181 @@
+# コードレビューロール
+
+## 責務
+
+包括的なコード品質レビュー:
+- TypeScript ベストプラクティス
+- エラーハンドリングパターン
+- 非同期操作
+- コード構造と命名規則
+- コードスメル検出
+
+## 必要な知識
+
+以下のファイルをコンテキストとして読み込む:
+
+**スキルファイル（明示的に読み込む）:**
+- `../criteria/code-quality.md` - 品質基準
+- `../criteria/coding-conventions.md` - コーディング規約（命名、imports、構造）
+- `../patterns/server-actions.md` - Server Action パターン
+- `../patterns/drizzle-orm.md` - データベースパターン
+- `../patterns/jsdoc.md` - JSDoc ドキュメントパターン
+
+**ルール（`.claude/rules/` から自動読み込み）:**
+- `tech-stack.md` - バージョン情報
+- `lib-structure.md` - lib/ ディレクトリ構造ルール
+- `known-issues.md` - 既知の問題
+
+## レビューチェックリスト
+
+### TypeScript
+- [ ] `any` 型を使用していない（`unknown` を使用）
+- [ ] 公開 API に明示的な戻り値型
+- [ ] ランタイムチェックに型ガード使用
+- [ ] strict モード準拠
+
+### エラーハンドリング
+- [ ] 空の catch ブロックなし
+- [ ] エラーコンテキストを含む
+- [ ] 適切なエラー型
+- [ ] 内部エラーの露出なし
+
+### 非同期パターン
+- [ ] 並列操作に `Promise.all()`
+- [ ] 適切な rejection ハンドリング
+- [ ] 非同期パターンの混在なし
+
+### コードスタイル
+- [ ] 小さく焦点を絞った関数
+- [ ] ネスト最大3レベル
+- [ ] 説明的な命名
+- [ ] 一貫した規約
+
+### コードスメル
+- [ ] God オブジェクトなし
+- [ ] マジックナンバーなし
+- [ ] デッドコードなし
+- [ ] 重複コードなし
+- [ ] 短いパラメータリスト
+
+### コーディング規約
+- [ ] ファイル名は kebab-case
+- [ ] 変数/関数は camelCase
+- [ ] コンポーネントは PascalCase
+- [ ] 定数は UPPER_SNAKE_CASE
+- [ ] import は整理済み（framework → npm → monorepo → local → relative）
+- [ ] Boolean は `is`/`has`/`can` プレフィックス
+- [ ] 未使用変数は `_` プレフィックス
+- [ ] 最大3レベルのネスト
+- [ ] Server Actions は構造に従う（auth → validate → try/catch）
+
+### lib/ ディレクトリ構造
+- [ ] `lib/` 直下にファイルなし（ディレクトリのみ）
+- [ ] 各ディレクトリに `index.ts`（再エクスポート用）
+- [ ] 外部インポートは `@/lib/{module}` を使用（直接ファイルパスではない）
+- [ ] テスト可能なモジュールに `__tests__/` ディレクトリ
+- [ ] `@module` と `@feature` タグが存在
+
+参照: `patterns/lib-structure.md`
+
+### ドキュメント品質
+- [ ] 公開関数に JSDoc コメント
+- [ ] すべての `@param` タグが存在し説明的
+- [ ] すべての `@returns` タグが存在
+- [ ] 複雑な関数に `@example`
+- [ ] TypeDoc 用の `@category`
+- [ ] 関連関数に `@see` リンク
+- [ ] エラーケースに `@throws`
+- [ ] 内部関数に `@internal`
+- [ ] 型/インターフェースにプロパティコメント
+
+### アノテーション整合性（shirokuma-docs）
+- [ ] `@usedComponents` が実際の import と一致
+- [ ] `@usedActions` が実際の関数呼び出しと一致
+- [ ] `@dbTables` が実際の Drizzle クエリと一致
+- [ ] `@route` が実際のファイルパスと一致
+- [ ] `@usedInScreen` が双方向に一貫
+- [ ] コンポーネント/アクション名にタイポなし
+
+参照: `workflows/annotation-consistency.md`
+
+## 検出すべきアンチパターン
+
+### TypeScript アンチパターン
+- [ ] `any` 型の使用（`unknown` を使うべき）
+- [ ] 正当な理由のない型アサーション（`as`）
+- [ ] 暗黙的 `any` の許容
+
+### エラーハンドリング アンチパターン
+- [ ] 空の catch ブロック
+- [ ] エラーの握りつぶし（catch 内で処理なし）
+- [ ] 内部エラー詳細のユーザーへの露出
+- [ ] console.log/error のみのエラーハンドリング
+
+### 非同期アンチパターン
+- [ ] 並列化可能な逐次 `await`
+- [ ] 未処理の Promise rejection
+- [ ] `.then()` と `async/await` の混在
+
+### コードスタイル アンチパターン
+- [ ] God オブジェクト（責務過多のクラス/モジュール）
+- [ ] マジックナンバー（説明のない数値リテラル）
+- [ ] デッドコード（未使用の関数/変数/import）
+- [ ] 重複コード（複数箇所の同じロジック）
+- [ ] 長いパラメータリスト（4個以上）
+- [ ] 深いネスト（4レベル以上）
+
+### lib/ 構造アンチパターン
+- [ ] `lib/` 直下のファイル（例: `lib/utils.ts`）
+- [ ] lib サブディレクトリに `index.ts` がない
+- [ ] 直接ファイルインポート（例: `from "@/lib/auth/config"`）
+- [ ] `index.ts` 内のロジック（再エクスポートのみであるべき）
+- [ ] テスト可能なモジュールに `__tests__/` がない
+- [ ] lib 内の深いネスト（2レベル超）
+
+### ドキュメント アンチパターン
+- [ ] 公開 API に JSDoc がない
+- [ ] 実装と一致しない古い JSDoc
+- [ ] コメントアウトされたコードの残存
+
+### アノテーション アンチパターン（shirokuma-docs）
+- [ ] `@usedComponents` にインポートされたコンポーネントが欠落
+- [ ] `@usedComponents` に未使用コンポーネントが記載
+- [ ] `@usedActions` が実際の呼び出しと不一致
+- [ ] `@dbTables` にアクセスされたテーブルが欠落
+- [ ] 古い `@usedInScreen` 参照
+- [ ] アノテーション値のタイポ（例: `SideBarGroup` vs `SidebarGroup`）
+
+### Server Action アンチパターン（Next.js）
+- [ ] 認証チェック前の処理
+- [ ] CSRF バリデーションのスキップ
+- [ ] Zod バリデーション前のデータ使用
+- [ ] レスポンスへの機密データの含有
+
+### テスト アンチパターン
+- [ ] 実装後にテスト作成（TDD 違反）
+- [ ] コメントアウトまたはスキップされたテスト
+- [ ] 過度なモック（実コードのテストが不十分）
+- [ ] 実装詳細のテスト（振る舞いをテストすべき）
+
+## レポート形式
+
+`templates/report.md` のテンプレートを使用:
+
+1. **概要**: 発見事項の簡潔な概要
+2. **重大な問題**: マージ前に修正必須
+3. **検出されたアンチパターン**: 違反事項
+4. **改善提案**: 推奨される変更
+5. **コードスメル**: 検出されたアンチパターン
+6. **コーディング規約**: 命名、import、構造の違反
+7. **ドキュメントの問題**: 不足または不完全な JSDoc
+8. **ベストプラクティス**: 従うべきパターン
+
+## トリガーキーワード
+
+- "code review"
+- "review code"
+- "レビューして"
+- "コードレビュー"
+- "annotation review", "アノテーションレビュー"
+- "check usedComponents", "usedComponents確認"
+- "verify annotations", "アノテーション検証"

package/plugin/shirokuma-skills-ja/skills/reviewing-on-issue/roles/docs.md

@@ -0,0 +1,79 @@
+# ドキュメントレビューロール
+
+## 責務
+
+Markdown ドキュメントの品質レビュー:
+- 構造の一貫性（見出しレベル、セクション順序）
+- リンク整合性（内部リンク、ファイルパス参照の有効性）
+- 用語一貫性（プロジェクト用語の統一使用）
+- テーブル整合性（カラム数、整形）
+- コードブロック（言語指定、構文の妥当性）
+
+## 必要な知識
+
+以下のファイルをコンテキストとして読み込む:
+- プロジェクトの `CLAUDE.md` - プロジェクト概要と規約
+- `.claude/rules/` - プロジェクト固有のルール（自動読み込み）
+
+## レビューチェックリスト
+
+### Markdown 構造
+- [ ] 見出しレベルが階層的に正しい（h1 → h2 → h3、スキップなし）
+- [ ] セクション順序がテンプレートに準拠
+- [ ] 空行がブロック要素の前後にある
+- [ ] リスト項目のインデントが一貫
+
+### リンク整合性
+- [ ] 内部リンクの参照先ファイルが存在
+- [ ] アンカーリンクが対応する見出しに解決
+- [ ] 相対パスが正しい階層を指す
+- [ ] 画像参照のファイルが存在
+
+### 用語一貫性
+- [ ] プロジェクト固有の用語が統一されている（表記ゆれなし）
+- [ ] 英語/日本語の混在が意図的
+- [ ] 略語の初出に正式名称がある
+
+### テーブル整合性
+- [ ] カラム数がヘッダーと本体で一致
+- [ ] 区切り行（`---`）が正しい
+- [ ] セル内容が適切にフォーマット
+
+### コードブロック
+- [ ] 言語指定がある（```bash, ```typescript 等）
+- [ ] コード例が構文的に正しい
+- [ ] コマンド例が現在の CLI に対応
+
+## 検出すべきアンチパターン
+
+### 構造アンチパターン
+- [ ] 見出しレベルのスキップ（h1 → h3）
+- [ ] 複数の h1 見出し（1ファイルに1つであるべき）
+- [ ] 空のセクション（見出しのみで内容なし）
+
+### リンクアンチパターン
+- [ ] 壊れた内部リンク（存在しないファイルへの参照）
+- [ ] ハードコードされた URL（相対パスにすべき内部参照）
+- [ ] アンカーなしの長文ドキュメントへのリンク
+
+### 内容アンチパターン
+- [ ] 古い情報（バージョン番号、API 仕様等）
+- [ ] TODO/FIXME コメントの残存
+- [ ] 重複する情報（複数箇所で同じ内容）
+
+## レポート形式
+
+`templates/report.md` のテンプレートを使用:
+
+1. **概要**: ドキュメント品質の全体サマリー
+2. **構造の問題**: 見出し、セクション順序の問題
+3. **壊れたリンク**: 無効な参照の一覧
+4. **用語の不整合**: 表記ゆれの検出結果
+5. **改善提案**: 推奨される変更
+
+## トリガーキーワード
+
+- "docs review"
+- "document review"
+- "ドキュメントレビュー"
+- "Markdownチェック"

package/plugin/shirokuma-skills-ja/skills/reviewing-on-issue/roles/nextjs.md

@@ -0,0 +1,105 @@
+# Next.js Review Role
+
+## Responsibilities
+
+Next.js project-specific review covering:
+- App Router patterns
+- Server/Client component usage
+- Data fetching patterns
+- Tailwind CSS v4 compliance
+- shadcn/ui integration
+- next-intl configuration
+
+## Required Knowledge
+
+Load ALL knowledge files for comprehensive review:
+
+**Skill files (explicit load):**
+- `../criteria/code-quality.md` - Quality criteria
+- `../criteria/security.md` - Security criteria
+- `../criteria/testing.md` - Testing criteria
+- `../patterns/drizzle-orm.md` - Database patterns
+- `../patterns/better-auth.md` - Auth patterns
+- `../patterns/server-actions.md` - Server Action patterns
+- `../patterns/i18n.md` - i18n patterns
+- `../patterns/e2e-testing.md` - E2E testing patterns
+
+**Rules (auto-loaded from `.claude/rules/`):**
+- `tech-stack.md` - Version information
+- `known-issues.md` - Known issues
+
+## Review Checklist
+
+### Next.js 16
+- [ ] Async params handled (`await params`)
+- [ ] Node.js 20.9.0+ used
+- [ ] TypeScript 5.1.0+ used
+- [ ] Parallel routes have default.js
+
+### Server/Client Components
+- [ ] Data fetching in Server Components
+- [ ] `"use client"` only when needed
+- [ ] No hooks in Server Components
+- [ ] Proper component boundaries
+
+### Server Actions
+- [ ] `"use server"` directive
+- [ ] Auth check at start
+- [ ] Zod validation
+- [ ] revalidatePath/Tag used
+- [ ] Structured responses
+
+### Tailwind CSS v4
+- [ ] CSS-first config (no tailwind.config.ts)
+- [ ] var() syntax used correctly
+- [ ] Important modifier suffix (`h-10!`)
+- [ ] Migration script run after shadcn add
+
+### shadcn/ui
+- [ ] canary version used
+- [ ] Migration script run
+- [ ] components.json configured
+- [ ] No v3 CSS variable syntax
+
+### next-intl
+- [ ] setRequestLocale at top of pages
+- [ ] Japanese slugs decoded
+- [ ] Both locales have translations
+- [ ] Client/Server patterns correct
+
+### Better Auth
+- [ ] Role check via database
+- [ ] window.location.href for redirects
+- [ ] credentials: "include" on client
+- [ ] Secure cookie settings
+
+### E2E Considerations
+- [ ] Rate limiting relaxed for dev
+- [ ] Multi-step auth timeouts
+- [ ] i18n in test assertions
+
+## Framework-Specific Issues
+
+### Must Check
+
+1. **CVE-2025-29927**: Middleware bypass
+2. **Async params**: Breaking change in Next.js 16
+3. **CSS variables**: v4 syntax required
+4. **setRequestLocale**: Required for SSG
+
+## Report Format
+
+Use template from `templates/report.md`:
+
+1. **Framework Summary**: Next.js/React compliance
+2. **Version Issues**: Outdated or incompatible
+3. **Pattern Violations**: Anti-patterns found
+4. **Known Issues**: Matching CVEs/bugs
+5. **Migration Needs**: Updates required
+
+## Trigger Keywords
+
+- "Next.js review"
+- "プロジェクトレビュー"
+- "nextjs review"
+- "app router review"

package/plugin/shirokuma-skills-ja/skills/reviewing-on-issue/roles/plan.md

@@ -0,0 +1,109 @@
+# 計画レビューロール
+
+## 責務
+
+Issue 本文の計画セクション（`## 計画`）の品質レビュー:
+- 要件カバレッジ（概要・タスクの全要件が計画で漏れなくカバーされているか）
+- 変更ファイルの妥当性（漏れや余分なファイルはないか）
+- タスク粒度（1タスク ≈ 1コミットの原則）
+- リスク分析（破壊的変更、パフォーマンス影響の見落とし）
+- Issue 記述の十分性（Issue 本文だけで計画を理解・評価できるか）
+
+## `planning-on-issue` との使い分け
+
+| 観点 | `planning-on-issue` 内蔵レビュー | `reviewing-on-issue` plan ロール |
+|------|--------------------------------|--------------------------------|
+| タイミング | 計画策定直後の即時チェック | ユーザーが任意タイミングで依頼 |
+| データ取得 | Task エージェントに Issue 本文を埋め込み | Issue 番号から `shirokuma-docs issues show` で取得 |
+| 目的 | 計画の初期品質ゲート | 独立したセカンドオピニオン |
+| 起動方法 | `planning-on-issue` のステップ 4 で自動実行 | `/reviewing-on-issue plan #N` または Spec Review Issue 指定 |
+
+## 必要な知識
+
+以下のファイルをコンテキストとして読み込む:
+- プロジェクトの `CLAUDE.md` - プロジェクト概要と規約
+- `.claude/rules/` - プロジェクト固有のルール（自動読み込み）
+
+## plan ロール固有ワークフロー
+
+```
+1. ロール選択: "plan review" or Spec Review Issue
+2. Issue 本文取得: shirokuma-docs issues show {number}
+3. Lint 実行: スキップ（対象がコードファイルではないため）
+4. 計画分析: Issue 本文の「## 計画」セクションをレビュー観点で分析
+5. レポート生成: テンプレート形式
+6. レポート保存: Issue コメント
+```
+
+## レビューチェックリスト
+
+### 要件カバレッジ
+- [ ] Issue の「概要」セクションの全要件が計画でカバーされている
+- [ ] Issue の「タスク」セクションの全タスクが計画のタスク分解に対応している
+- [ ] 「成果物」セクションの各項目に対応するタスクが存在する
+- [ ] 暗黙の要件（テスト、バージョンバンプ等）が見落とされていない
+
+### 変更ファイルの妥当性
+- [ ] 変更対象ファイル一覧が記載されている
+- [ ] 漏れているファイルがない（要件から推測される変更対象が全て含まれている）
+- [ ] 余分なファイルが含まれていない（スコープ外の変更がない）
+- [ ] 新規作成と既存更新が明確に区別されている
+
+### タスク粒度
+- [ ] 各タスクが具体的で実行可能（「実装する」だけでなく、何をどう変更するか記載）
+- [ ] 1タスク ≈ 1コミットの粒度
+- [ ] タスク間の依存関係が明確（順序が論理的）
+- [ ] タスクが多すぎず少なすぎない（Issue のサイズに適切）
+
+### リスク分析
+- [ ] 破壊的変更がある場合、その影響範囲が記載されている
+- [ ] パフォーマンスへの影響が考慮されている
+- [ ] 既存機能への影響が評価されている
+- [ ] ロールバック手順または影響軽減策がある（必要な場合）
+
+### Issue 記述の十分性
+- [ ] Issue 本文だけで計画の全体像を理解できる
+- [ ] アプローチの根拠（なぜこの方法を選んだか）が記載されている
+- [ ] 代替案の検討結果が記載されている（該当する場合）
+- [ ] 前提条件や制約が明記されている
+
+## 検出すべきアンチパターン
+
+### 計画セクション不在
+- [ ] `## 計画` セクションが存在しない
+- [ ] 計画セクションが空または不十分（見出しのみで内容なし）
+
+### タスクが抽象的すぎる
+- [ ] 「実装する」「修正する」のみで具体的な変更内容なし
+- [ ] 変更するファイルや関数が特定されていない
+- [ ] 成果物との対応が不明確
+
+### 変更ファイル一覧の欠落
+- [ ] 標準/詳細レベルの計画なのに変更ファイル一覧がない
+- [ ] ファイルパスが不正確（存在しないパスを参照）
+
+### リスク記載の欠落
+- [ ] 詳細レベルの計画なのにリスク分析がない
+- [ ] 破壊的変更があるのに影響範囲の記載がない
+
+### 成果物との不整合
+- [ ] 「成果物」セクションに対応するタスクがない
+- [ ] タスクは完了条件を満たすのに成果物と乖離
+- [ ] 成果物が曖昧（「動作すること」のみ）
+
+## レポート形式
+
+`templates/report.md` のテンプレートを使用:
+
+1. **概要**: 計画品質の全体サマリー
+2. **重大な問題**: 要件漏れ、重大な不整合
+3. **改善提案**: タスク粒度の改善、リスク追記等
+4. **良い実践**: 適切な計画パターン
+5. **推奨事項**: 優先度順のアクション項目
+
+## トリガーキーワード
+
+- "plan review"
+- "計画レビュー"
+- "review plan"
+- "計画チェック"

package/plugin/shirokuma-skills-ja/skills/reviewing-on-issue/roles/security.md

@@ -0,0 +1,124 @@
+# Security Review Role
+
+## Responsibilities
+
+Security-focused code review covering:
+- OWASP Top 10 2025 vulnerabilities
+- Authentication and authorization
+- Input validation and injection prevention
+- Sensitive data handling
+- Security headers and configuration
+
+## Required Knowledge
+
+Load these files for context:
+
+**Skill files (explicit load):**
+- `../criteria/security.md` - Security criteria (OWASP Top 10)
+- `../patterns/better-auth.md` - Auth patterns
+- `../patterns/server-actions.md` - Server Action security
+
+**Rules (auto-loaded from `.claude/rules/`):**
+- `tech-stack.md` - Version information
+- `known-issues.md` - CVEs and vulnerabilities
+
+## Review Checklist
+
+### A01: Broken Access Control
+- [ ] Authorization on ALL operations
+- [ ] Ownership verification
+- [ ] No IDOR vulnerabilities
+- [ ] Server-side validation
+
+### A02: Security Misconfiguration
+- [ ] .env in .gitignore
+- [ ] No secrets in code
+- [ ] Security headers configured
+- [ ] CORS properly configured
+
+### A03: Supply Chain
+- [ ] Dependencies audited
+- [ ] No known CVEs
+- [ ] Lock file committed
+
+### A05: Injection
+- [ ] Parameterized queries
+- [ ] ILIKE wildcards escaped
+- [ ] No eval() or Function()
+- [ ] All input validated
+
+### A07: Authentication Failures
+- [ ] BETTER_AUTH_SECRET >= 32 chars
+- [ ] bcrypt rounds >= 12
+- [ ] Secure cookie settings
+- [ ] Rate limiting enabled
+
+### Server Actions
+- [ ] `"use server"` directive
+- [ ] Auth check at start
+- [ ] Zod validation
+- [ ] No sensitive data in errors
+
+### CVE Awareness
+- [ ] Next.js >= 15.2.3 (CVE-2025-29927)
+- [ ] Or x-middleware-subrequest blocked
+
+## Security Anti-patterns to Detect
+
+Check for the following security violations during review:
+
+### Authentication Anti-patterns
+- [ ] Storing passwords in plaintext
+- [ ] Using predictable session tokens
+- [ ] Not invalidating sessions on logout
+- [ ] Returning detailed error messages on auth failure (user enumeration)
+
+### Authorization Anti-patterns
+- [ ] Client-side only authorization checks
+- [ ] Accessing resources without ownership verification
+- [ ] Skipping role checks
+- [ ] Privilege escalation vulnerabilities
+
+### Data Handling Anti-patterns
+- [ ] Logging sensitive information
+- [ ] Including sensitive data in URL parameters
+- [ ] Storing sensitive data in localStorage/sessionStorage
+- [ ] Including unnecessary sensitive fields in API responses
+
+### Input Handling Anti-patterns
+- [ ] Directly embedding user input in SQL/HTML/JS
+- [ ] Insufficient file upload validation
+- [ ] Missing redirect URL validation (open redirect)
+- [ ] Processing files without Content-Type header validation
+
+### Configuration Anti-patterns
+- [ ] Hardcoded secrets
+- [ ] Debug mode enabled in production
+- [ ] CORS set to `*`
+- [ ] Not enforcing HTTPS
+
+## Severity Levels
+
+| Level | Description | Action |
+|-------|-------------|--------|
+| **Critical** | Exploitable vulnerability | Block merge |
+| **High** | Security gap, hard to exploit | Fix before merge |
+| **Medium** | Potential risk | Fix recommended |
+| **Low** | Best practice violation | Track for later |
+
+## Report Format
+
+Use template from `templates/report.md`:
+
+1. **Security Summary**: Overall security posture
+2. **Critical Vulnerabilities**: MUST fix
+3. **OWASP Coverage**: Which categories affected
+4. **CVE Check**: Known vulnerabilities
+5. **Recommendations**: Prioritized fixes
+
+## Trigger Keywords
+
+- "security review"
+- "セキュリティレビュー"
+- "check security"
+- "vulnerability scan"