shirokuma-docs 0.1.0-alpha.1

package/plugin/shirokuma-skills-en/rules/nextjs/tailwind-v4.md

@@ -0,0 +1,43 @@
+---
+paths:
+  - "**/*.css"
+  - "components/ui/**/*.tsx"
+  - "**/components/ui/**/*.tsx"
+---
+
+# Tailwind CSS v4 + shadcn/ui
+
+## CSS Variable Syntax
+
+```tsx
+// NG: Tailwind v3 syntax (broken in v4)
+className="bg-[--sidebar-background]"
+
+// OK: Tailwind v4 syntax
+className="bg-[var(--sidebar-background)]"
+```
+
+After adding shadcn/ui components:
+```bash
+npx shadcn@canary add <component> -y
+# Fix CSS variable syntax: [--var] → [var(--var)]
+```
+
+## Production-Only Issues
+
+CSS variables may work in dev but break in production build.
+
+Fix: Use `@theme inline` instead of `@property` or `:root`:
+```css
+@theme inline {
+  --sidebar-width: 16rem;
+  --sidebar-background: 0 0% 100%;
+}
+```
+
+## Verification
+
+```bash
+grep -r "\[--" components/ui/  # Find v3 syntax
+pnpm build  # Test production build
+```

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

@@ -0,0 +1,43 @@
+# Tech Stack Reference
+
+## Recommended Stack
+
+| Category | Technology |
+|----------|------------|
+| Frontend | Next.js 16 / React 19 / TypeScript 5 |
+| Database | PostgreSQL 16 + Drizzle ORM |
+| Auth | Better Auth (DB sessions) |
+| i18n | next-intl (ja/en) |
+| Styling | Tailwind CSS v4 + shadcn/ui |
+| Testing | Jest + Playwright |
+
+> Update versions to match your project's `package.json`.
+
+## Key Patterns
+
+| Pattern | Summary |
+|---------|---------|
+| Async Params | `params: Promise<...>` → `await params` |
+| Server Actions | Auth → CSRF → Validation → DB → Redirect |
+| CSRF Protection | Queries: read-only check, Mutations: CSRF token |
+| Rate Limiting | `checkRateLimit()` for destructive ops |
+| Ownership Check | Verify `authorId === userId` before mutation |
+
+## Radix UI Hydration (CRITICAL)
+
+```typescript
+const [mounted, setMounted] = useState(false)
+useEffect(() => { setMounted(true) }, [])
+
+if (!mounted) return <PlaceholderWithoutRadixUI />
+return <ComponentWithRadixUI />
+```
+
+## Known Issues Quick Reference
+
+| Issue | Fix |
+|-------|-----|
+| Hydration mismatch | Use `mounted` state pattern |
+| CSS variable broken in prod | Use `@theme inline` |
+| Login redirect loop | Use `window.location.href` |
+| CSP: inline style blocked | Add `'unsafe-inline'` |

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

@@ -0,0 +1,66 @@
+---
+paths:
+  - "**/*.test.ts"
+  - "**/*.test.tsx"
+  - "__tests__/**/*"
+  - "tests/**/*"
+---
+
+# Testing Conventions
+
+## Test Structure
+
+```typescript
+describe("FeatureName", () => {
+  beforeEach(() => {
+    jest.clearAllMocks()
+  })
+
+  it("should create with valid data", async () => {
+    // Arrange
+    // Act
+    // Assert
+  })
+})
+```
+
+## Mock Patterns
+
+### Server Action Mocks
+
+```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 Mocks
+
+```typescript
+jest.mock("@/lib/auth", () => ({
+  auth: jest.fn(() => Promise.resolve({
+    user: { id: "user-1", email: "test@example.com" }
+  }))
+}))
+```
+
+## Skip Tests
+
+Add `@skip-reason` when using `.skip`:
+
+```typescript
+/**
+ * @skip-reason External API dependency, mock not implemented
+ */
+it.skip("should do X", () => { })
+```
+
+## Verification
+
+```bash
+pnpm test
+```

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

@@ -0,0 +1,112 @@
+---
+paths:
+  - ".claude/skills/**/*.md"
+---
+
+# Output Destinations Rule
+
+## Overview
+
+Claude Code skills produce two types of output. Route each to the appropriate destination.
+
+## Output Types
+
+| Type | Purpose | Destination | Lifetime |
+|------|---------|-------------|----------|
+| **Working reports** | Human review during work | GitHub Discussions (Reports) | Temporary |
+| **Final documentation** | Project-wide records | shirokuma-docs portal | Permanent |
+
+## Working Reports
+
+**Use for**: Review reports, implementation progress, lint results
+
+**Destination**: GitHub Discussions → Reports category
+
+```bash
+# Create via shirokuma-docs CLI
+shirokuma-docs discussions create \
+  --category Reports \
+  --title "Review: {target}" \
+  --body "report content"
+```
+
+**Characteristics**:
+- Created during active work sessions
+- For human confirmation and feedback
+- Can be periodically cleaned up
+- Viewable in GitHub browser UI
+
+## Final Documentation
+
+**Use for**: Complete feature docs, API references, architecture diagrams
+
+**Destination**: shirokuma-docs portal
+
+```bash
+# Build portal
+shirokuma-docs portal -p . -o docs/portal
+
+# Or via skill
+/shirokuma-md build
+```
+
+**Characteristics**:
+- Created after work completion
+- Permanent project documentation
+- Auto-generated from code annotations
+- Viewable at docs portal URL
+
+## Migration from Local Logs
+
+**Old pattern** (deprecated):
+```
+logs/reports/YYYY-MM-DD-*.md
+logs/reviews/YYYY-MM-DD-*.md
+```
+
+**New pattern**:
+```
+Working → GitHub Discussions (Reports)
+Final   → shirokuma-docs portal
+```
+
+## Skill Updates
+
+When updating skills, replace local log references:
+
+| Old | New |
+|-----|-----|
+| `Save to logs/reports/` | `Create Discussion in Reports category` |
+| `Save to logs/reviews/` | `Create Discussion in Reports category` |
+| Report file path output | Discussion URL output |
+
+## PR Reviews → PR Comments
+
+Review results targeting a PR should be posted directly as PR comments.
+
+```bash
+shirokuma-docs issues comment {PR#} --body "Review summary"
+```
+
+| Condition | Destination |
+|-----------|-------------|
+| PR review (normal) | PR comment (summary) |
+| PR review (5+ errors) | PR comment + Discussion (detailed) |
+| File/directory review | Discussion (Reports) |
+
+## Reports Category Usage
+
+| Purpose | Example |
+|---------|---------|
+| Comprehensive review reports | Project-wide security audit |
+| Research results | Best practice research, technology comparisons |
+| Self-review feedback | Pattern accumulation from automated review loops |
+
+**Do NOT save to Reports**: PR-specific review results (→ post as PR comment instead)
+
+## Notes
+
+- **No local files**: Avoid storing reports in repository
+- **Browser-friendly**: GitHub Discussions for easy human review
+- **Clean separation**: Temporary (Discussions) vs Permanent (Portal)
+- **PR reviews → PR comments**: Post PR-targeted reviews directly on the PR

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

@@ -0,0 +1,15 @@
+# shirokuma-docs CLI Invocation
+
+## Direct Call (No npx)
+
+`shirokuma-docs` is installed globally. Always call it directly:
+
+```bash
+# Correct
+shirokuma-docs session start
+shirokuma-docs issues list
+shirokuma-docs lint-tests -p .
+
+# Wrong - unnecessary overhead
+npx shirokuma-docs session start
+```

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

@@ -0,0 +1,54 @@
+# Plugin Cache Management
+
+## Architecture
+
+Claude Code loads skills from the **global cache**, not the project-local `.claude/plugins/` directory.
+
+```
+plugin/ (bundled source)
+    ↓ shirokuma-docs update (= update-skills --sync)
+.claude/plugins/shirokuma-skills-en/   (project-local copy)
+    ↓ claude plugin install/update
+~/.claude/plugins/cache/...         (global cache — Claude Code reads from here)
+```
+
+## Recommended: `shirokuma-docs update`
+
+`shirokuma-docs update` is a shortcut for `update-skills --sync`. It updates skills, rules, and syncs the global cache in one command.
+
+```bash
+# Recommended (shortcut)
+shirokuma-docs update
+
+# Equivalent (full command)
+shirokuma-docs update-skills --sync
+```
+
+## After `update` Adds New Skills
+
+When `shirokuma-docs update` reports new skills added, the global cache must also be updated:
+
+```bash
+# If plugin version changed
+claude plugin update shirokuma-skills-en@shirokuma-library --scope project
+
+# If plugin version is the same (update reports "already at latest")
+claude plugin uninstall shirokuma-skills-en@shirokuma-library --scope project
+claude plugin install shirokuma-skills-en@shirokuma-library --scope project
+```
+
+A new session is required after cache update for skills to appear.
+
+## When to Guide the User
+
+| Symptom | Cause | Action |
+|---------|-------|--------|
+| New skill not in skill list | Cache not updated | `claude plugin uninstall` + `install` |
+| `plugin update` says "already at latest" | Same version number | Use uninstall + install instead |
+| Skill works in one project but not another | Plugin scope mismatch | Check `--scope` (user vs project) |
+
+## Rules
+
+1. **Never write directly to the global cache** — use `claude plugin` commands
+2. **Use `shirokuma-docs update`** — shortcut for `update-skills --sync`. Always remind about cache sync when new skills are added
+3. **Version-same updates require uninstall + install** — `plugin update` skips when version unchanged

package/plugin/shirokuma-skills-en/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 Annotations
+
+## Required by File Type
+
+| File Type | Required Tags |
+|-----------|---------------|
+| Test (`*.test.ts`) | `@testdoc` on each `it()` |
+| Server Action | `@serverAction`, `@feature`, `@dbTables` |
+| Page component | `@screen`, `@route` |
+| Component | `@component` |
+| Type-only file | `@skip-test` |
+
+## Test Annotation (REQUIRED)
+
+```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
+});
+```
+
+## Screen Annotation
+
+```typescript
+/**
+ * Dashboard screen
+ *
+ * @screen DashboardScreen
+ * @route /dashboard
+ * @usedComponents ProjectList, ActivityFeed
+ * @usedActions getProjects, getActivities
+ */
+export default function DashboardPage() { }
+```
+
+## Server Action Annotation
+
+```typescript
+/**
+ * Get project list
+ *
+ * @serverAction
+ * @feature ProjectManagement
+ * @dbTables projects
+ * @authLevel member
+ */
+export async function getProjects(orgId: string) { }
+```
+
+## Skip Test Annotation
+
+```typescript
+/**
+ * @skip-test Type definitions only - no runtime logic
+ */
+export type Project = typeof projects.$inferSelect
+```
+
+## Verification
+
+```bash
+shirokuma-docs lint-tests -p . -f terminal
+shirokuma-docs lint-coverage -p . -f summary
+```

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

@@ -0,0 +1,168 @@
+---
+paths:
+  - ".claude/skills/**/*.md"
+  - ".claude/agents/**/*.md"
+  - ".claude/output-styles/**/*.md"
+  - ".claude/commands/**/*.md"
+---
+
+# Claude Config Authoring Rules
+
+## Naming Convention
+
+**Format**: `gerund-form` (verb + -ing), lowercase, hyphens, max 64 chars
+
+```yaml
+# Good
+name: processing-pdfs
+name: managing-agents
+
+# Bad
+name: PDF-Processor    # Not gerund, uppercase
+name: helper           # Too vague
+```
+
+## Description (CRITICAL)
+
+**Template**: `[What it does]. Use when [triggers].`
+
+**Requirements**:
+- Max 1024 characters
+- Third person voice
+- Include WHAT (capability) and WHEN (triggers)
+- NO angle brackets (`<example>` forbidden)
+
+```yaml
+# Good
+description: Extract text from PDF files. Use when working with PDFs or user mentions "PDF", "PDF処理".
+
+# Bad
+description: Helps with documents  # Too vague, no triggers
+```
+
+## File Size Limits
+
+- `SKILL.md` / `AGENT.md`: Under 500 lines
+- Challenge every sentence for necessity
+- Move detailed content to reference files
+
+## Language Guidelines
+
+| File Type | Language |
+|-----------|----------|
+| SKILL.md / AGENT.md | English |
+| rules/*.md | English |
+| output-styles/*.md | English |
+| CLAUDE.md | English |
+| description (SKILL.md frontmatter) | English keywords only (see below) |
+
+- **Avoid**: Heavy table formatting (token-inefficient)
+- **EN plugin description**: English keywords only (no Japanese triggers)
+- **JA plugin description**: Japanese + English technical terms that Japanese users actually type (e.g., "コミット" + "commit")
+- **No fake slash commands**: Only reference `/skill-name` if the command actually exists. Use plain quoted keywords instead (e.g., "commit" not "/commit")
+
+## File Structure
+
+```
+skill-name/
+├── SKILL.md        # Required, <500 lines
+├── reference.md    # Optional, detailed specs
+├── examples.md     # Optional, I/O examples
+└── scripts/        # Optional, automation
+```
+
+## Context Efficiency Principles
+
+More constraints = lower LLM compliance. Adjust density by role.
+
+### Role-Based Density
+
+| Role | Constraint Density | Reason |
+|------|-------------------|--------|
+| **Reviewer** (`context: fork`) | High is OK | Observation tasks have high compliance |
+| **Coder** | Minimal | Code generation + constraint compliance compound |
+
+### Writing Principles
+
+- **Name it, don't explain it**: Reference known concepts by name (e.g., "Follow Conventional Commits" is enough)
+- **Detail only project-specific**: Only elaborate on project-specific rules
+- **Consolidate, don't scatter**: Define rules in one place, reference elsewhere
+- **Compress, don't expand**: Convert verbose tables to bullet points or inline
+
+### Safe to Omit (LLM Already Knows)
+
+- Known concept explanations (Git Flow, TDD, Conventional Commits, etc.)
+- General best practices
+- Language/framework basic syntax
+
+## SKILL.md Required Content
+
+These must **never be removed** during compression.
+
+### 1. Workflow (Required)
+
+Step-by-step workflow must not be omitted. LLM can guess flows, but project-specific ordering, branching, and gates must be explicit.
+
+### 2. Tool Usage Timing (Required)
+
+Specify when to use which tools within the skill:
+- **TodoWrite**: 3+ step tasks, multi-issue work
+- **AskUserQuestion**: Decision points, multiple approaches
+- **Task**: Parallel investigation, fork execution
+- **EnterPlanMode**: Not needed in skill workflows (plans are written to Issue body, approval is managed via Spec Review. `plansDirectory` is configured as a safety net)
+
+Without tool instructions, LLM may skip using them.
+
+### 3. NG Cases / Checklists (Required)
+
+Skill-specific "must not do" items:
+- Not general NG — **project-specific NG** cases
+- Example: committing-on-issue → no `--no-verify`, no `Co-Authored-By`
+- Example: creating-pr-on-issue → no direct push to base branch
+
+Include completion criteria and quality gates as checklists.
+
+### 4. Output Template Embedding (Recommended)
+
+When a skill is invoked via Task or fork, the output format should be owned by the skill itself. Avoid designs where the caller embeds output templates in the prompt.
+
+```
+# NG: Caller defines output format
+Task(prompt: "Review this. Output in this format: ## Result\n| Item | Verdict |...")
+
+# OK: Skill owns the output format
+Skill("reviewing-on-issue")  # Output format defined inside the skill
+```
+
+**Principles**:
+- Skills should hold their output templates in SKILL.md or reference files
+- Callers pass only input data (issue number, target files, etc.)
+- Output format changes require editing only one place (the skill)
+
+**Good examples**: reviewing-on-issue (Self-Review Result template embedded), claude-config-reviewing (quality checklist embedded)
+
+## Anti-Patterns
+
+- Deep reference chains (keep ONE level from SKILL.md)
+- Windows backslashes (use forward slashes only)
+- Too many options without defaults
+- Vague naming without specific triggers
+- Long explanations of LLM-known concepts
+- Motivational/philosophy sections ("why" over "what")
+- **Omitting workflows** (flows must not be left to LLM inference)
+- **Omitting tool usage instructions** (TodoWrite, AskUserQuestion, etc.)
+- **Omitting NG cases** (without prohibitions, LLM defaults to its own behavior)
+
+## Validation Checklist
+
+Before committing:
+- [ ] Name: gerund form, lowercase
+- [ ] Description: triggers, third person, no `<>`
+- [ ] SKILL.md: under 500 lines
+- [ ] Frontmatter: valid YAML (spaces, not tabs)
+- [ ] Paths: forward slashes only
+- [ ] **Workflow**: Step-by-step flow documented
+- [ ] **Tool usage**: TodoWrite / AskUserQuestion / Task usage points specified
+- [ ] **NG cases**: Skill-specific prohibitions and checklists present
+- [ ] Coder skills: Known concept explanations removed, reference only
+- [ ] Reviewer skills: Checklist coverage is sufficient