shirokuma-docs 0.1.0-alpha.1

package/plugin/shirokuma-skills-en/rules/github/discussions-usage.md

@@ -0,0 +1,129 @@
+# GitHub Discussions Usage
+
+## Purpose
+
+Discussions store human-readable knowledge; Rules store AI-readable extracts.
+
+| Layer | Audience | Language | Content |
+|-------|----------|----------|---------|
+| Discussions | Human | English | Context, rationale, details |
+| Rules/Skills | AI | English | Concise patterns, commands |
+
+## Categories
+
+| Category | When to Use |
+|----------|-------------|
+| Handovers | Session end - create via `/ending-session` |
+| ADR | Architecture decisions confirmed |
+| Knowledge | Patterns/solutions confirmed |
+| Research | Investigation needed |
+
+## Workflow
+
+```
+Research → ADR (if decision) → Knowledge → Rule extract
+```
+
+### Discussion → Issue Flow
+
+Ideas and proposals live in Discussions until a decision is made to implement them.
+
+```
+Discussion (idea) → Decision to implement → Issue (Backlog) → Ready → In Progress
+```
+
+| Action | When |
+|--------|------|
+| Create Discussion | New idea, proposal, or investigation topic |
+| Convert to Issue | Team decides to implement the idea |
+| Keep as Discussion | Idea is rejected, deferred, or purely informational |
+
+Do NOT create Issues for undecided ideas. Use Discussions for exploration and decision-making first.
+
+## Knowledge → Rule Extraction Workflow
+
+When a pattern or solution is confirmed through practice, extract it into a Rule for AI consumption.
+
+```
+1. Discovery: Pattern found during work (code review, debugging, implementation)
+2. Knowledge Discussion: Record in Knowledge category with context and rationale
+3. Validation: Pattern used successfully 2+ times across sessions
+4. Rule Proposal: Extract concise, actionable rule from Knowledge Discussion
+5. Rule Creation: Use managing-rules skill to create the rule file
+6. Cross-Reference: Add Discussion # link as comment in the rule
+```
+
+| Step | Action | Output |
+|------|--------|--------|
+| Discovery | Identify recurring pattern | Mental note or comment |
+| Record | Create Knowledge Discussion | Discussion #{N} |
+| Validate | Confirm pattern holds across contexts | Updated Discussion |
+| Extract | Distill into AI-readable rule | Rule `.md` file |
+| Link | Reference source Discussion in rule | `<!-- Source: Discussion #{N} -->` |
+
+**When to skip the Discussion step**: Only for trivial patterns that are self-evident (e.g., typo corrections, obvious naming conventions). If the "why" matters, write a Discussion first.
+
+## Searching Existing Discussions
+
+Before creating a new Discussion, search for existing ones to avoid duplicates and build on prior context.
+
+```bash
+# Search by keyword
+shirokuma-docs discussions search "{keyword}"
+
+# Filter by category
+shirokuma-docs discussions list --category Knowledge
+shirokuma-docs discussions list --category Research
+shirokuma-docs discussions list --category ADR
+
+# Recent handovers (for session context)
+shirokuma-docs discussions list --category Handovers --limit 5
+```
+
+**When to search**:
+- Starting a new session (check recent Handovers)
+- Before creating a Knowledge Discussion (check for existing coverage)
+- Before starting research (check Research category for prior work)
+- When investigating a pattern (search Knowledge for related findings)
+
+## Cross-Reference
+
+- Discussions share number space with Issues (#1, #2, ...)
+- Reference in commits: "See Discussion #30"
+- Add to Projects for tracking
+
+## Auto Memory Boundary
+
+Do not store detailed information in Claude Code's auto memory. Memory holds pointers only; store details in Discussions. See `memory-operations` rule.
+
+## AI Behavior
+
+1. **Search**: Check existing Discussions before creating new ones
+2. **Read**: Check Discussions for context when researching
+3. **Write**: Create Discussions for significant findings
+4. **Extract**: Propose Rule when pattern is confirmed (see Knowledge → Rule workflow)
+5. **Reference**: Link Discussion # in Rule comments
+
+## Body Maintenance
+
+Discussion body MUST always be the latest consolidated version (see "Item Body Maintenance" in `project-items` rule).
+
+- When adding findings, corrections, or new insights via comments, **update the body immediately** to reflect the latest state
+- Comments serve as historical record of the discussion
+- The body should be "read this alone to understand the current conclusion"
+
+```bash
+shirokuma-docs discussions update {number} --body "$(cat <<'EOF'
+{updated body content}
+EOF
+)"
+```
+
+## Title Formats
+
+| Category | Format |
+|----------|--------|
+| Handovers | `YYYY-MM-DD [{username}] - {summary}` (username auto-inserted by CLI) |
+| ADR | `ADR-{NNN}: {title}` |
+| Knowledge | `{Topic Name}` |
+| Research | `[Research] {topic}` |

package/plugin/shirokuma-skills-en/rules/github/output-language.md

@@ -0,0 +1,14 @@
+# GitHub Output Language
+
+## Rule
+
+All content written to GitHub (Issues, PRs, Discussions comments and bodies) MUST be in **English**.
+
+| Element | Language |
+|---------|----------|
+| Issue / PR / Discussion body and comments | English |
+| PR title (after prefix) | English |
+| Commit message (after prefix) | English |
+| Conventional commit prefixes (`feat:`, `fix:`, etc.) | English |
+| Code / Variable names | English |
+| Label names | English |

package/plugin/shirokuma-skills-en/rules/github/pr-review-response.md

@@ -0,0 +1,37 @@
+# PR Review Response
+
+## When Review Comments Are Received
+
+1. Fetch all review threads: `shirokuma-docs issues pr-comments <PR#>`
+2. For each **unresolved** thread, determine the response type:
+
+### Code Fix Required
+
+1. Fix the code
+2. Commit and push
+3. Reply referencing the commit: `shirokuma-docs issues pr-reply <PR#> --reply-to <database_id> --body "Fixed in <hash>"`
+4. Resolve: `shirokuma-docs issues resolve <PR#> --thread-id <PRRT_id>`
+
+### Question or Discussion
+
+1. Reply with explanation
+2. Resolve the thread
+
+### Disagreement
+
+1. Reply explaining the concern and trade-offs
+2. Do **not** resolve — let the reviewer decide
+
+## Rules
+
+1. **Reply and Resolve are paired** - Every reply should be followed by a resolve, unless waiting for reviewer input
+2. **Process all threads before reporting back** - Do not ask the user between threads
+3. **Use correct IDs** - `--reply-to` takes numeric `database_id`, `--thread-id` takes GraphQL `PRRT_` ID (both from `pr-comments` output)
+
+## Edge Cases
+
+| Situation | Action |
+|-----------|--------|
+| Thread already resolved | Skip |
+| Outdated comment (code changed) | Reply if feedback is still valid, reference the relevant commit |
+| Reviewer requests re-review | Reply but leave thread open |

package/plugin/shirokuma-skills-en/rules/github/project-items.md

@@ -0,0 +1,276 @@
+# Project Items Rule
+
+## Required Fields
+
+Every project item MUST have:
+
+| Field | Required | Options |
+|-------|----------|---------|
+| Status | Yes | See workflow below |
+| Priority | Yes | Critical / High / Medium / Low |
+| Type | Yes | Feature / Bug / Chore / Docs / Research |
+| Size | Recommended | XS / S / M / L / XL |
+
+## Status Workflow
+
+```mermaid
+graph LR
+  Icebox --> Backlog --> Planning --> SpecReview[Spec Review]
+  SpecReview --> InProgress[In Progress] --> Review --> Testing --> Done --> Released
+  InProgress <--> Pending
+  Review <--> Pending
+  Backlog <--> Pending
+  Done -.-> NotPlanned[Not Planned]
+```
+
+| Status | Description |
+|--------|-------------|
+| Icebox | Low priority, shelved. May be promoted to Backlog later |
+| Backlog | Planned work. Requirements may still need refinement |
+| Planning | Plan is being created by `planning-on-issue` (pre-work status) |
+| Spec Review | Gate for requirements review before work begins |
+| In Progress | Currently working on |
+| Pending | Blocked (document reason) |
+| Review | Code review |
+| Testing | QA testing |
+| Done | Completed |
+| Not Planned | Explicitly not planned (set by `issues cancel`) |
+| Released | Deployed to production |
+
+### Idea → Issue Flow
+
+Ideas and proposals start as **Discussions** (Research or Knowledge category), not Issues.
+
+| Stage | Location | When to Move |
+|-------|----------|--------------|
+| Idea / exploration | Discussion | When the idea is first raised |
+| Decided to do | Issue (Backlog) | When the team agrees to implement |
+| Requirements firm | Issue (Spec Review) | When requirements need formal review |
+
+- Backlog tolerates varying levels of requirement detail
+- Do NOT create Issues for ideas that have not been decided on
+- Spec Review is the approval gate before implementation starts
+
+## Size Estimation
+
+| Size | Time | Example |
+|------|------|---------|
+| XS | ~1h | Typo fix, config change |
+| S | ~4h | Small feature, bug fix |
+| M | ~1d | Medium feature |
+| L | ~3d | Large feature |
+| XL | 3d+ | Epic (should be split) |
+
+## Body Template
+
+```markdown
+## 概要
+{What this item does}
+
+## 背景
+{Why this is needed - optional}
+
+## タスク
+- [ ] Task 1
+- [ ] Task 2
+
+## Deliverable
+{What "done" looks like}
+
+## 優先度
+{Priority justification - optional}
+```
+
+## Status Update Triggers
+
+AI MUST update issue status at these points:
+
+| Trigger | Action | Owner | Command |
+|---------|--------|-------|---------|
+| Planning started | → Planning | `planning-on-issue` | `issues update {n} --field-status "Planning"` |
+| Plan created | → Spec Review | `planning-on-issue` | `issues update {n} --field-status "Spec Review"` |
+| User approves plan, starts work | → In Progress + branch | `working-on-issue` | `issues update {n} --field-status "In Progress"` |
+| PR created | → Review | `creating-pr-on-issue` | `issues update {n} --field-status "Review"` |
+| PR merged | → Done | `committing-on-issue` (via `issues merge`) | Automatic |
+| Blocked by dependency | → Pending | Manual | `issues update {n} --field-status "Pending"` + comment |
+| Complete (no PR needed) | → Done | `ending-session` | `session end --done {n}` |
+| Cancelled | → Not Planned | `issues cancel` | `issues cancel {n}` |
+| Session end | → Review or Done | `ending-session` (safety net) | `session end --review/--done {n}` |
+
+### Planning Usage
+
+The `planning-on-issue` skill transitions from Backlog → Planning when starting plan creation.
+
+- **Purpose**: Visibility that planning is in progress; records planning start timestamp
+- **Entry**: `planning-on-issue` sets this status after fetching the issue
+- **Exit**: Plan complete → Spec Review (set by `planning-on-issue`)
+- **Pre-work status**: Not included in `WORK_STARTED_STATUSES` (same treatment as Spec Review)
+
+### Spec Review Usage
+
+The `planning-on-issue` skill writes a plan to the issue body and transitions Planning → Spec Review.
+
+- **Purpose**: User approval gate before implementation
+- **Entry**: `planning-on-issue` appends `## Plan` section and sets this status
+- **Exit**: User approves → `working-on-issue` starts implementation → In Progress
+- **Applies to**: All issues (plan depth scales with content: lightweight/standard/detailed)
+
+### Rules
+
+1. **One In Progress at a time** - Move previous item out before starting new one
+2. **Branch per issue** - Create a feature branch when starting work (see `branch-workflow` rule)
+3. **Event-driven**: Status changes happen immediately when events occur (`creating-pr-on-issue` sets Review, `issues merge` sets Done)
+4. **Session end safety net** - `ending-session` catches any missed status updates
+5. **Pending requires reason** - Add a comment explaining the blocker
+6. **Idempotency** - If status is already correct, skip the update (no error)
+
+## Built-in Automations
+
+GitHub Projects V2 provides built-in automation workflows that complement the CLI-based status updates.
+
+### Recommended Automations
+
+| Workflow | Trigger | Action | Status |
+|----------|---------|--------|--------|
+| Item closed | Issue is closed | Set Status → Done | **Enable** |
+| Pull request merged | PR merged | Set Status → Done | **Enable** |
+
+### How to Enable
+
+Built-in automations are configured via the GitHub UI (not API):
+
+1. Navigate to your GitHub Project's **Settings > Workflows**
+2. Enable "Item closed" → set target status to **Done**
+3. Enable "Pull request merged" → set target status to **Done**
+
+### CLI Compatibility
+
+| CLI Feature | Behavior with Automations |
+|-------------|--------------------------|
+| `session end --review` | Sets Review. When PR merges, automation moves to Done |
+| `session end --review` (PR already merged) | Auto-promotes to Done via `findMergedPrForIssue()` — idempotent with automation |
+| `session end --done` | Sets Done directly — idempotent with automation |
+| `session check` | Reports disabled recommended automations as warnings |
+| `session check --fix` | Fixes inconsistencies — compatible with automation |
+| `issues cancel` | Sets Not Planned after close. May race with "Item closed → Done" automation — CLI update usually wins. Use `session check --fix` to detect/correct. |
+
+### Checking Automation Status
+
+```bash
+shirokuma-docs projects workflows
+```
+
+Reports all workflows with their enabled/disabled status and recommendations.
+
+## Labels
+
+Labels complement Type by indicating **where** work applies, not **what** kind of work it is.
+
+| Mechanism | Role | Example |
+|-----------|------|---------|
+| Type | Work category | Bug, Feature, Chore |
+| Labels | Cross-cutting attribute | area:cli, area:plugin |
+
+### Label Rules
+
+1. **Labels do NOT duplicate Type** - Never create labels that mirror Type values (e.g., no `bug` label when Type: Bug exists)
+2. **Area labels are optional** - Use when the affected area is not obvious from the title
+3. **Multiple area labels allowed** - Cross-cutting issues may have multiple areas
+4. **Operational labels for triage** - `duplicate`, `invalid`, `wontfix` are set when closing or redirecting
+
+### Label Categories
+
+| Prefix | Purpose | Examples |
+|--------|---------|---------|
+| `area:` | Codebase area affected | `area:cli`, `area:plugin`, `area:github` |
+| (none) | Operational / triage | `duplicate`, `invalid`, `wontfix` |
+
+See `github-project-setup/reference/labels.md` for full taxonomy and setup commands.
+
+## Item Body Maintenance (Issues / Discussions / PRs)
+
+**The body is the source of truth.** Comments serve as historical record of the discussion. The body MUST always be the latest consolidated version. Readers should be able to understand the current state by reading the body alone.
+
+### When to Update
+
+| Trigger | Action |
+|---------|--------|
+| New findings or corrections added via comments | Consolidate into body |
+| Investigation results posted as comments | Merge into body's relevant section |
+| Requirements changed via comments | Update body's Tasks/Deliverable sections |
+| Decision made in comment thread | Record in body |
+| 3+ comments accumulated since last body update | Consolidate into body |
+
+### How to Update
+
+```bash
+# Issues
+shirokuma-docs issues update {number} --body "$(cat <<'EOF'
+{updated body content}
+EOF
+)"
+
+# Discussions
+shirokuma-docs discussions update {number} --body "$(cat <<'EOF'
+{updated body content}
+EOF
+)"
+```
+
+### Workflow Order (Comment First)
+
+When updating a body, ALWAYS follow this order:
+
+1. **Post a comment** — Record the changes, findings, or corrections as a comment first
+2. **Consolidate into body** — Integrate the comment content into the relevant body section
+
+This order ensures the comment history preserves "what was changed and why", enabling detection and correction of AI judgment errors or hallucinations.
+
+**Prohibited**: Updating the body directly and then adding a comment after the fact (reverse order). Updating the body without any comment.
+
+### Substantive Compliance
+
+Merely following the comment→body order is not enough. Comments must have **independent value as primary records** of the work.
+
+**Heuristic**: If deleting a comment would not lose any information absent from the body, that comment is not substantive.
+
+| Bad (Formal compliance) | Good (Substantive compliance) |
+|------------------------|-------------------------------|
+| "Plan created. See body for details." | "Selected approach A. Also considered B (reason), rejected due to X." |
+| "Updated issue body." | "Investigation found module X is also affected. Added to tasks." |
+| "Reflected review results." | "Review detected N issues: {summary of specific findings}" |
+
+**Content that should be primary records in comments**:
+- Decision rationale and alternatives considered
+- Facts discovered during investigation
+- Summary of review findings
+- Reasons for requirement changes
+
+**When consolidating into body**: Structure and merge comment content into relevant sections. Comments remain as historical record.
+
+### Guidelines
+
+1. **Preserve structure** - Keep the original body template sections
+2. **Update task checkboxes** - Check completed items, add new tasks discovered
+3. **Summarize, don't duplicate** - Consolidate comment threads into concise body updates
+4. **Comment first** - Always post a comment before updating the body (see Workflow Order section above)
+
+## Creating Items
+
+When creating new items:
+
+1. Set all required fields immediately
+2. Use the body template
+3. XL items should be split into smaller items
+4. Link related items in body if applicable
+
+### Initial Status Guidelines
+
+`issues create` automatically sets Status to **Backlog** by default. Override with `--field-status` when needed:
+
+| Scenario | Status |
+|----------|--------|
+| Default (planned work) | Backlog |
+| Starting immediately | In Progress |
+| Low priority / future idea | Icebox |
+| Needs requirements review | Spec Review |

package/plugin/shirokuma-skills-en/rules/memory-operations.md

@@ -0,0 +1,38 @@
+# Memory Operations
+
+## Principle
+
+**Memory is for pointers and working context only.**
+
+## What to Store in Memory
+
+| Type | Example |
+|------|---------|
+| GitHub reference pointers | `See Discussion #343` `Issue #342` |
+| Working context | Test commands, skill counts, quick lookups |
+
+## What NOT to Store → Use GitHub
+
+| Type | Where |
+|------|-------|
+| Research findings | Discussion (Research) |
+| Ideas / proposals | Discussion |
+| Architecture decisions | Discussion (ADR) |
+| Implementation tasks | Issue |
+| Patterns / learnings | Discussion (Knowledge) → Rule extraction |
+
+See `discussions-usage` rule for details.
+
+## Constraints
+
+1. **No duplication with CLAUDE.md or rules** — single source of truth
+2. **Topic files should be minimal** — GitHub reference pointers only
+
+## Directive Language in Config Files
+
+Config files are all loaded in parallel into the same context. Relative directives make it unclear which file's instruction is being referenced.
+
+| Bad | Good |
+|-----|------|
+| "here", "this", "this file" | Use explicit file/section names |
+| "the above rule" | `branch-workflow rule` |

package/plugin/shirokuma-skills-en/rules/nextjs/known-issues.md

@@ -0,0 +1,59 @@
+# Known Issues & CVEs
+
+## Critical CVEs
+
+### CVE-2025-29927 (Next.js)
+
+**Severity**: Critical (9.1)
+**Affected**: Next.js < 15.2.3
+**Issue**: Middleware auth bypass via `x-middleware-subrequest` header
+
+**Mitigation** (if upgrade not possible):
+```nginx
+if ($http_x_middleware_subrequest) {
+    return 403;
+}
+proxy_set_header x-middleware-subrequest "";
+```
+
+## Framework Issues
+
+### Next.js 16
+
+| Issue | Fix |
+|-------|-----|
+| Async params error | `const { slug } = await params` |
+| Node.js 18 dropped | Upgrade to Node.js 20.9.0+ |
+
+### React 19
+
+| Issue | Fix |
+|-------|-----|
+| Hydration mismatch | Use mounted state pattern |
+| ref as prop deprecation | Use `element.props.ref` |
+
+### Tailwind CSS v4
+
+| Issue | Fix |
+|-------|-----|
+| CSS variable syntax | Use `var()`: `w-[var(--width)]` |
+| @property inheritance | Use `@theme inline` |
+
+### Better Auth
+
+| Issue | Fix |
+|-------|-----|
+| Login redirect loop | Use `window.location.href` |
+| Role not in session | Query database for role |
+
+## Version Requirements
+
+- **Node.js**: 20.9.0+
+- **TypeScript**: 5.1.0+
+- **Safari**: 16.4+ (Tailwind v4)
+
+## Security Requirements
+
+- **BETTER_AUTH_SECRET**: 32+ characters
+- **bcrypt rounds**: 12+
+- **Rate limit**: 5 attempts / 15 min (production)

package/plugin/shirokuma-skills-en/rules/nextjs/lib-structure.md

@@ -0,0 +1,48 @@
+---
+paths:
+  - "lib/**/*.ts"
+  - "lib/**/*.tsx"
+  - "**/lib/**/*.ts"
+  - "**/lib/**/*.tsx"
+---
+
+# lib/ Directory Structure Rules
+
+## Required Structure
+
+```
+lib/
+├── actions/           # Server Actions
+│   ├── crud/          # Single-table CRUD
+│   └── domain/        # Multi-table business logic
+├── auth/              # Authentication
+├── context/           # React Context
+├── hooks/             # Custom hooks
+├── utils/             # Utility functions
+└── validations/       # Zod schemas
+```
+
+## Critical Rules
+
+1. **No files directly in lib/**
+   ```
+   lib/auth/index.ts  ← OK
+   lib/auth.ts        ← NG
+   ```
+
+2. **Use index.ts for re-export**
+   ```typescript
+   export { auth } from "./config"
+   export { verifyAdmin } from "./utils"
+   ```
+
+3. **Avoid `export *`**
+   - Causes name collision build errors
+   - Use explicit re-exports
+
+## Server Actions Structure
+
+| Directory | Type | Characteristics |
+|-----------|------|-----------------|
+| `lib/actions/crud/` | CRUD | Single table, standard operations |
+| `lib/actions/domain/` | Domain | Multiple tables, business workflows |

package/plugin/shirokuma-skills-en/rules/nextjs/radix-ui-hydration.md

@@ -0,0 +1,30 @@
+---
+paths:
+  - "components/**/*.tsx"
+  - "**/components/**/*.tsx"
+---
+
+# Radix UI Hydration Pattern
+
+## Problem
+
+Radix UI generates unique IDs that differ between SSR and CSR, causing hydration mismatch.
+
+Affected: DropdownMenu, Select, Dialog, Popover, Collapsible, Accordion, Tooltip.
+
+## Solution: mounted state pattern
+
+```tsx
+const [mounted, setMounted] = useState(false)
+useEffect(() => { setMounted(true) }, [])
+
+if (!mounted) return <PlaceholderWithoutRadixUI />
+return <ComponentWithRadixUI />
+```
+
+## Rules
+
+- Use `mounted` pattern for all Radix UI components in Client Components
+- SSR placeholder must match the visual layout of the full component
+- Prefer `useMounted()` hook if available (`hooks/use-mounted.ts`)
+- Never use `suppressHydrationWarning` as a workaround

package/plugin/shirokuma-skills-en/rules/nextjs/server-actions.md

@@ -0,0 +1,50 @@
+---
+paths:
+  - "lib/actions/**/*.ts"
+  - "**/lib/actions/**/*.ts"
+  - "**/actions.ts"
+---
+
+# Server Actions Conventions
+
+## Required Order
+
+1. **Authentication check**
+2. **CSRF verification** (mutations only)
+3. **Zod validation**
+4. **Business logic**
+5. **Revalidate path**
+
+## Template
+
+```typescript
+"use server"
+
+export async function createResource(formData: FormData): Promise<ActionResult> {
+  // 1. Auth
+  const { user } = await auth()
+  if (!user) return { error: "Unauthorized" }
+
+  // 2. CSRF (mutations only)
+  await verifyCsrfToken(formData)
+
+  // 3. Validation
+  const validated = schema.safeParse(Object.fromEntries(formData))
+  if (!validated.success) return { error: validated.error.message }
+
+  // 4. Business logic
+  const result = await db.insert(table).values(validated.data)
+
+  // 5. Revalidate
+  revalidatePath("/resources")
+  return { data: result }
+}
+```
+
+## Security Checklist
+
+- [ ] Auth check before any DB operation
+- [ ] CSRF token verified for mutations
+- [ ] Input validated with Zod
+- [ ] Ownership verified before update/delete
+- [ ] Rate limiting for destructive operations