shirokuma-docs 0.1.0-alpha.1

package/plugin/shirokuma-skills-en/skills/reviewing-on-issue/patterns/tailwind-v4.md

@@ -0,0 +1,43 @@
+# Tailwind CSS v4 Patterns
+
+Quick reference for Tailwind CSS v4 patterns.
+
+---
+
+## Quick Reference
+
+### Required Steps After Adding shadcn/ui
+
+```bash
+npx shadcn@latest add {component} -y
+./scripts/fix-tailwind-v4-css-vars.sh --yes apps/{app}/components/ui
+```
+
+### CSS Variable Syntax (Important)
+
+```tsx
+// BAD: v3 syntax (old format generated by CLI)
+className="bg-[--sidebar-background]"
+
+// GOOD: v4 syntax
+className="bg-[var(--sidebar-background)]"
+```
+
+### Production-Only Issues
+
+```css
+/* Use @theme inline instead of @property */
+@theme inline {
+  --sidebar-width: 16rem;
+  --sidebar-width-icon: 3rem;
+}
+```
+
+---
+
+## Key Points
+
+- Use `npx shadcn@latest` for shadcn/ui
+- CLI generates `[--var]` -> must convert to `[var(--var)]`
+- If CSS variables don't work in production, use `@theme inline`
+- Always run the fix script after adding components

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

@@ -0,0 +1,184 @@
+# Code Review Role
+
+## Responsibilities
+
+Comprehensive code quality review covering:
+- TypeScript best practices
+- Error handling patterns
+- Async operations
+- Code structure and organization
+- Naming conventions
+- Code smells detection
+
+## Required Knowledge
+
+Load these files for context:
+
+**Skill files (explicit load):**
+- `../criteria/code-quality.md` - Quality criteria
+- `../criteria/coding-conventions.md` - Coding conventions (naming, imports, structure)
+- `../patterns/server-actions.md` - Server Action patterns
+- `../patterns/drizzle-orm.md` - Database patterns
+- `../patterns/jsdoc.md` - JSDoc documentation patterns
+
+**Rules (auto-loaded from `.claude/rules/`):**
+- `tech-stack.md` - Version information
+- `lib-structure.md` - lib/ directory structure rules
+- `known-issues.md` - Known issues
+
+## Review Checklist
+
+### TypeScript
+- [ ] No `any` types (use `unknown`)
+- [ ] Explicit return types on public APIs
+- [ ] Type guards for runtime checks
+- [ ] Strict mode compliance
+
+### Error Handling
+- [ ] No empty catch blocks
+- [ ] Error context included
+- [ ] Appropriate error types
+- [ ] No internal error exposure
+
+### Async Patterns
+- [ ] `Promise.all()` for parallel ops
+- [ ] Proper rejection handling
+- [ ] No mixed async patterns
+
+### Code Style
+- [ ] Small, focused functions
+- [ ] Max 3 nesting levels
+- [ ] Descriptive naming
+- [ ] Consistent conventions
+
+### Code Smells
+- [ ] No God objects
+- [ ] No magic numbers
+- [ ] No dead code
+- [ ] No duplicate code
+- [ ] Short parameter lists
+
+### Coding Conventions
+- [ ] File names use kebab-case
+- [ ] Variables/functions use camelCase
+- [ ] Components use PascalCase
+- [ ] Constants use UPPER_SNAKE_CASE
+- [ ] Imports organized (framework → npm → monorepo → local → relative)
+- [ ] Booleans have `is`/`has`/`can` prefix
+- [ ] Unused variables prefixed with `_`
+- [ ] Max 3 levels of nesting
+- [ ] Server Actions follow structure (auth → validate → try/catch)
+
+### lib/ Directory Structure
+- [ ] No files directly under `lib/` (directories only)
+- [ ] Each directory has `index.ts` for re-exports
+- [ ] External imports use `@/lib/{module}` (not direct file paths)
+- [ ] `__tests__/` directory exists for testable modules
+- [ ] `@module` and `@feature` tags present
+
+See: `patterns/lib-structure.md` for detailed rules
+
+### Documentation Quality
+- [ ] Public functions have JSDoc comments
+- [ ] All `@param` tags present and descriptive
+- [ ] All `@returns` tags present
+- [ ] Complex functions have `@example`
+- [ ] Functions have `@category` for TypeDoc
+- [ ] Related functions linked with `@see`
+- [ ] Error cases documented with `@throws`
+- [ ] Internal functions marked with `@internal`
+- [ ] Types/interfaces have property comments
+
+### Annotation Consistency (shirokuma-docs)
+- [ ] `@usedComponents` matches actual imports
+- [ ] `@usedActions` matches actual function calls
+- [ ] `@dbTables` matches actual Drizzle queries
+- [ ] `@route` matches actual file path
+- [ ] `@usedInScreen` bidirectionally consistent
+- [ ] No typos in component/action names
+
+See: `workflows/annotation-consistency.md` for detailed verification
+
+## Anti-patterns to Detect
+
+Check for the following violations during review:
+
+### TypeScript Anti-patterns
+- [ ] Using `any` type (should use `unknown`)
+- [ ] Type assertions (`as`) without justification
+- [ ] Implicit `any` allowed
+
+### Error Handling Anti-patterns
+- [ ] Empty catch blocks
+- [ ] Swallowing errors (no handling in catch)
+- [ ] Exposing internal error details to users
+- [ ] Only using console.log/error for error handling
+
+### Async Anti-patterns
+- [ ] Sequential `await` when parallelizable
+- [ ] Unhandled Promise rejections
+- [ ] Mixing `.then()` with `async/await`
+
+### Code Style Anti-patterns
+- [ ] God objects (classes/modules with too many responsibilities)
+- [ ] Magic numbers (unexplained numeric literals)
+- [ ] Dead code (unused functions/variables/imports)
+- [ ] Duplicate code (same logic in multiple places)
+- [ ] Long parameter lists (4+ parameters)
+- [ ] Deep nesting (4+ levels)
+
+### lib/ Structure Anti-patterns
+- [ ] Files directly under `lib/` (e.g., `lib/utils.ts`)
+- [ ] Missing `index.ts` in lib subdirectories
+- [ ] Direct file imports (e.g., `from "@/lib/auth/config"`)
+- [ ] Logic in `index.ts` (should only re-export)
+- [ ] Missing `__tests__/` for modules with testable logic
+- [ ] Deep nesting in lib (more than 2 levels)
+
+### Documentation Anti-patterns
+- [ ] Missing JSDoc on public APIs
+- [ ] Outdated JSDoc not matching implementation
+- [ ] Commented-out code remaining
+
+### Annotation Anti-patterns (shirokuma-docs)
+- [ ] `@usedComponents` missing imported components
+- [ ] `@usedComponents` listing unused components
+- [ ] `@usedActions` not matching actual calls
+- [ ] `@dbTables` missing accessed tables
+- [ ] Stale `@usedInScreen` references
+- [ ] Typos in annotation values (e.g., `SideBarGroup` vs `SidebarGroup`)
+
+### Server Action Anti-patterns (Next.js)
+- [ ] Processing before auth check
+- [ ] Skipping CSRF validation
+- [ ] Using data before Zod validation
+- [ ] Including sensitive data in response
+
+### Test Anti-patterns
+- [ ] Tests written after implementation (TDD violation)
+- [ ] Tests commented out or skipped
+- [ ] Over-mocking (not testing real code)
+- [ ] Testing implementation details (should test behavior)
+
+## Report Format
+
+Use template from `templates/report.md`:
+
+1. **Summary**: Brief overview of findings
+2. **Critical Issues**: Must fix before merge
+3. **Anti-patterns Detected**: "Don't" rule violations
+4. **Improvements**: Recommended changes
+5. **Code Smells**: Detected anti-patterns
+6. **Coding Conventions**: Naming, imports, structure violations
+7. **Documentation Issues**: Missing or incomplete JSDoc
+8. **Best Practices**: Patterns to follow
+
+## Trigger Keywords
+
+- "code review"
+- "review code"
+- "レビューして"
+- "コードレビュー"
+- "annotation review", "アノテーションレビュー"
+- "check usedComponents", "usedComponents確認"
+- "verify annotations", "アノテーション検証"

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

@@ -0,0 +1,79 @@
+# Documentation Review Role
+
+## Responsibilities
+
+Markdown documentation quality review covering:
+- Structure consistency (heading levels, section ordering)
+- Link integrity (internal links, file path reference validity)
+- Terminology consistency (unified project terminology)
+- Table consistency (column counts, formatting)
+- Code blocks (language specification, syntax validity)
+
+## Required Knowledge
+
+Load these files for context:
+- Project's `CLAUDE.md` - Project overview and conventions
+- `.claude/rules/` - Project-specific rules (auto-loaded)
+
+## Review Checklist
+
+### Markdown Structure
+- [ ] Heading levels are hierarchically correct (h1 → h2 → h3, no skipping)
+- [ ] Section ordering follows template
+- [ ] Blank lines before and after block elements
+- [ ] List item indentation is consistent
+
+### Link Integrity
+- [ ] Internal link targets exist
+- [ ] Anchor links resolve to corresponding headings
+- [ ] Relative paths point to correct hierarchy
+- [ ] Image references exist
+
+### Terminology Consistency
+- [ ] Project-specific terms are unified (no inconsistencies)
+- [ ] English/Japanese mixing is intentional
+- [ ] Abbreviations have full form on first use
+
+### Table Consistency
+- [ ] Column count matches between header and body
+- [ ] Separator rows (`---`) are correct
+- [ ] Cell content is properly formatted
+
+### Code Blocks
+- [ ] Language specification present (```bash, ```typescript, etc.)
+- [ ] Code examples are syntactically correct
+- [ ] Command examples correspond to current CLI
+
+## Anti-patterns to Detect
+
+### Structure Anti-patterns
+- [ ] Heading level skipping (h1 → h3)
+- [ ] Multiple h1 headings (should be one per file)
+- [ ] Empty sections (heading only, no content)
+
+### Link Anti-patterns
+- [ ] Broken internal links (references to non-existent files)
+- [ ] Hardcoded URLs (internal references that should be relative paths)
+- [ ] Links to long documents without anchors
+
+### Content Anti-patterns
+- [ ] Outdated information (version numbers, API specs, etc.)
+- [ ] Remaining TODO/FIXME comments
+- [ ] Duplicate information (same content in multiple places)
+
+## Report Format
+
+Use template from `templates/report.md`:
+
+1. **Summary**: Overall document quality summary
+2. **Structural Issues**: Heading, section ordering problems
+3. **Broken Links**: List of invalid references
+4. **Terminology Inconsistencies**: Detected naming variations
+5. **Improvement Suggestions**: Recommended changes
+
+## Trigger Keywords
+
+- "docs review"
+- "document review"
+- "ドキュメントレビュー"
+- "Markdown check"

package/plugin/shirokuma-skills-en/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-en/skills/reviewing-on-issue/roles/plan.md

@@ -0,0 +1,109 @@
+# Plan Review Role
+
+## Responsibilities
+
+Quality review of the plan section (`## Plan` / `## 計画`) in Issue body:
+- Requirements coverage (all requirements from overview/tasks covered in plan)
+- Changed files validity (no missing or extraneous files)
+- Task granularity (1 task ≈ 1 commit principle)
+- Risk analysis (breaking changes, performance impact oversight)
+- Issue description sufficiency (plan understandable from Issue body alone)
+
+## Distinction from `planning-on-issue`
+
+| Aspect | `planning-on-issue` built-in review | `reviewing-on-issue` plan role |
+|--------|-------------------------------------|-------------------------------|
+| Timing | Immediate check right after planning | User-initiated at any time |
+| Data retrieval | Issue body embedded in Task agent | Fetched via `shirokuma-docs issues show` by Issue number |
+| Purpose | Initial quality gate for plan | Independent second opinion |
+| Invocation | Auto-executed at `planning-on-issue` step 4 | `/reviewing-on-issue plan #N` or Spec Review Issue |
+
+## Required Knowledge
+
+Load these files for context:
+- Project's `CLAUDE.md` - Project overview and conventions
+- `.claude/rules/` - Project-specific rules (auto-loaded)
+
+## Plan Role Specific Workflow
+
+```
+1. Role selection: "plan review" or Spec Review Issue
+2. Fetch Issue body: shirokuma-docs issues show {number}
+3. Lint execution: Skip (target is not code files)
+4. Plan analysis: Review the "## Plan" section against review criteria
+5. Report generation: Template format
+6. Report saving: Issue comment
+```
+
+## Review Checklist
+
+### Requirements Coverage
+- [ ] All requirements from the Issue "Overview" section are covered in the plan
+- [ ] All tasks from the Issue "Tasks" section map to plan task breakdown
+- [ ] Each item in "Deliverables" section has a corresponding task
+- [ ] Implicit requirements (tests, version bump, etc.) are not overlooked
+
+### Changed Files Validity
+- [ ] Changed files list is documented
+- [ ] No missing files (all changes inferred from requirements are included)
+- [ ] No extraneous files (no out-of-scope changes)
+- [ ] New files and existing file updates are clearly distinguished
+
+### Task Granularity
+- [ ] Each task is specific and actionable (not just "implement" but what and how)
+- [ ] 1 task ≈ 1 commit granularity
+- [ ] Task dependencies are clear (logical ordering)
+- [ ] Number of tasks is appropriate for Issue size (not too many, not too few)
+
+### Risk Analysis
+- [ ] Breaking changes have their impact scope documented
+- [ ] Performance impact is considered
+- [ ] Impact on existing features is evaluated
+- [ ] Rollback procedure or mitigation exists (when needed)
+
+### Issue Description Sufficiency
+- [ ] Plan is fully understandable from Issue body alone
+- [ ] Approach rationale (why this method was chosen) is documented
+- [ ] Alternative approaches considered are documented (when applicable)
+- [ ] Prerequisites and constraints are explicitly stated
+
+## Anti-patterns to Detect
+
+### Missing Plan Section
+- [ ] `## Plan` / `## 計画` section does not exist
+- [ ] Plan section is empty or insufficient (heading only, no content)
+
+### Tasks Too Abstract
+- [ ] Only "implement" or "fix" with no specific change details
+- [ ] Files or functions to change are not identified
+- [ ] Mapping to deliverables is unclear
+
+### Missing Changed Files List
+- [ ] Standard/detailed level plan lacks changed files list
+- [ ] File paths are inaccurate (referencing non-existent paths)
+
+### Missing Risk Documentation
+- [ ] Detailed level plan lacks risk analysis
+- [ ] Breaking changes exist but impact scope is not documented
+
+### Deliverables Mismatch
+- [ ] "Deliverables" section items have no corresponding tasks
+- [ ] Tasks fulfill completion criteria but diverge from deliverables
+- [ ] Deliverables are vague ("it works" only)
+
+## Report Format
+
+Use template from `templates/report.md`:
+
+1. **Summary**: Overall plan quality summary
+2. **Critical Issues**: Missing requirements, significant inconsistencies
+3. **Improvements**: Task granularity improvements, risk additions, etc.
+4. **Best Practices**: Appropriate planning patterns found
+5. **Recommendations**: Prioritized action items
+
+## Trigger Keywords
+
+- "plan review"
+- "計画レビュー"
+- "review plan"
+- "計画チェック"

package/plugin/shirokuma-skills-en/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"