shirokuma-docs 0.1.0-alpha.1

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

@@ -0,0 +1,144 @@
+---
+name: best-practices-researching
+description: Researches official documentation and project patterns before implementation. Use when starting a new feature, when unsure about best practices, or when the user asks "research best practices for X" or "how should I implement Y".
+context: fork
+agent: general-purpose
+model: opus
+allowed-tools: Read, Grep, Glob, WebSearch, WebFetch, Bash, AskUserQuestion, TodoWrite
+---
+
+# Best Practices Researcher
+
+Researches official documentation and project patterns to provide implementation guidance.
+
+## Core Responsibilities
+
+- Search official documentation for recommended patterns
+- Check existing project patterns for consistency
+- Synthesize findings into actionable recommendations
+- Save research results for future reference
+
+## Tech Stack Documentation Sources
+
+| Technology | Official Documentation |
+|------------|----------------------|
+| 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 |
+
+## Workflow
+
+### 1. Understand the Request
+
+Parse what the user wants to implement or understand:
+- Feature type (CRUD, auth, UI component, etc.)
+- Technologies involved
+- Specific concerns or constraints
+
+Use `AskUserQuestion` when the research direction is unclear. Use `TodoWrite` when researching multiple technologies.
+
+### 2. Search Project Patterns
+
+Check existing patterns in the project:
+
+```bash
+# Search in project code
+Grep: [relevant pattern] in {project}/
+```
+
+**Reference patterns** (provided in `nextjs-vibe-coding` skill knowledge base):
+- `code-patterns.md` - Server Actions, i18n, forms
+- `better-auth.md` - Authentication patterns
+- `drizzle-orm.md` - Database patterns
+- `tailwind-v4.md` - Styling patterns
+
+### 3. Search Official Documentation
+
+Use WebSearch for official recommendations:
+
+```
+WebSearch: "[technology] [feature] best practices 2026"
+WebSearch: "[technology] official documentation [topic]"
+```
+
+**Priority order**:
+1. Official documentation
+2. GitHub issues/discussions
+3. Community best practices
+
+### 4. Synthesize Findings
+
+Compare official recommendations with project patterns:
+- Identify gaps or inconsistencies
+- Note project-specific adaptations
+- Flag any conflicts
+
+### 5. Save Research (Optional)
+
+For significant research, create a Discussion in the Research category:
+
+```bash
+shirokuma-docs discussions create --category Research --title "[Research] {topic}" --body "{findings}"
+```
+
+## Output Format
+
+```markdown
+# Research: [Topic]
+
+## Summary
+[1-2 sentence overview of findings]
+
+## Official Recommendations
+- **[Source]**: [Key recommendation]
+- **[Source]**: [Key recommendation]
+
+## Project Patterns
+- **[File]**: [Existing pattern in project]
+- **[File]**: [Related implementation]
+
+## Recommendations
+
+### Do
+- [Concrete recommendation with code example if applicable]
+
+### Avoid
+- [Anti-pattern to avoid]
+
+## Implementation Notes
+[Any specific considerations for this project]
+
+## Sources
+- [URL 1]
+- [URL 2]
+```
+
+## Key Principles
+
+1. **Official First**: Always prioritize official documentation
+2. **Project Consistency**: Align with existing project patterns
+3. **Actionable Output**: Provide concrete, implementable recommendations
+4. **Source Attribution**: Always cite sources for traceability
+5. **Brevity**: Keep findings concise and scannable
+
+## Anti-Patterns
+
+- Do not include unverified information in recommendations
+- Do not omit source URLs
+- Do not reference outdated version documentation
+
+## Completion Checklist
+
+- [ ] Referenced at least one official documentation source
+- [ ] All recommendations have source attribution
+- [ ] Compared findings against existing project patterns
+
+## Notes
+
+- Results can be passed to `nextjs-vibe-coding` skill for implementation
+- Use `context: fork` to run as isolated sub-agent without polluting main context

package/plugin/shirokuma-skills-en/skills/claude-config-reviewing/SKILL.md

@@ -0,0 +1,210 @@
+---
+name: claude-config-reviewing
+description: Reviews Claude Code configuration files (skills, rules, agents, output-styles, plugins) for quality, consistency, and Anthropic's best practices. Use PROACTIVELY after creating or updating any .claude/ configuration. Triggers: "config review", "quality check", "review config".
+context: fork
+agent: general-purpose
+model: opus
+allowed-tools: Read, Grep, Glob, WebSearch, WebFetch
+---
+
+# Claude Config Reviewer
+
+Reviews Claude Code configuration files for quality and Anthropic's best practices.
+
+> Reference: [Building Effective Agents](https://www.anthropic.com/engineering/building-effective-agents)
+
+## Core Responsibilities
+
+- Validate structure against best practices
+- Detect anti-patterns and temporary markers
+- Check for broken internal links
+- Verify required sections exist
+- Report issues with severity levels
+
+## Workflow
+
+1. **Discover**: Find all config files in `.claude/` and `.claude/plugins/`
+2. **Categorize**: Group by type (agents, skills, commands, output-styles, plugins)
+3. **Validate**: Check each file against its type-specific rules
+4. **Report**: Generate findings with severity and fix suggestions
+
+## Validation Rules
+
+### All Files
+
+| Check | Severity | Pattern (and variations) |
+|-------|----------|--------------------------|
+| Temporary markers | Warning | `**NEW**`, `TODO:`, `FIXME:`, `WIP`, `TBD`, `DRAFT`, `PLACEHOLDER`, `XXX:` |
+| Manual date stamps | Warning | `Last Updated:`, `Updated:`, `Modified:`, `Created:`, `Date:`, `Version:`, `Rev:` |
+| ASCII art diagrams | Warning | Box-drawing characters, repeated decorators (`===`, `---` as borders) |
+| Broken links | Error | `[text](path)` where path doesn't exist |
+| Parent reference loop | Warning | `[../CLAUDE.md]`, `See parent project` |
+| Missing language in code blocks | Info | ` ``` ` without language specifier |
+| File too long | Warning | > 500 lines for SKILL.md |
+
+**Pattern Matching**: Use fuzzy matching for similar patterns:
+- Dates: `/\d{4}[-/]\d{2}[-/]\d{2}/` outside code blocks
+- Markers: Case-insensitive (`TODO`, `Todo`, `todo`)
+- Versions: `v1.0`, `1.0.0`, `ver. 1.0`
+- ASCII art: `/[+\-|]{3,}/` forming boxes
+
+### Skills (`.claude/skills/` and `.claude/plugins/*/skills/`)
+
+| Check | Severity |
+|-------|----------|
+| Missing SKILL.md | Error |
+| No description in SKILL.md frontmatter | Error |
+| Reference to non-existent file | Error |
+
+### Agents (`.claude/agents/`)
+
+| Check | Severity |
+|-------|----------|
+| Missing `name` in frontmatter | Error |
+| Missing `description` in frontmatter | Error |
+| Invalid name format (must be lowercase-hyphen) | Error |
+| Description without invocation triggers | Warning |
+| No workflow section | Warning |
+| Excessive tools (> 5 without justification) | Info |
+
+**Anthropic Best Practices Checks**:
+
+| Check | Severity | Rationale |
+|-------|----------|-----------|
+| Heavy agent (> 500 lines, ~25k+ tokens) | Warning | Bottlenecks in multi-agent workflows |
+| Kitchen sink pattern (all tools + broad scope) | Warning | Violates single responsibility |
+| Too many responsibilities (> 3 core tasks) | Warning | "Start simple" principle |
+| Missing "When to Use" guidance | Info | Clear invocation triggers needed |
+| Reviewer with Write/Edit tools | Warning | Checker agents should be read-only |
+| Generator without Write tool | Info | May be incomplete |
+
+### Commands (`.claude/commands/`)
+
+| Check | Severity |
+|-------|----------|
+| Empty command file | Error |
+| No description comment at top | Warning |
+
+### Output Styles (`.claude/output-styles/`)
+
+| Check | Severity |
+|-------|----------|
+| Missing style definition | Error |
+
+## Anti-Patterns to Detect
+
+```text
+# Temporary markers (case-insensitive, with variations)
+**NEW**, **WIP**, **DRAFT**, **PLACEHOLDER**
+TODO:, TODO(xxx):, FIXME:, HACK:, XXX:, NOTE:
+TBD, N/A, COMING SOON, IN PROGRESS
+[WIP], [DRAFT], [TODO]
+
+# Manual date stamps (git tracks this - detect variations)
+Last Updated: 2025-xx-xx
+Updated:, Modified:, Created:, Revised:
+Date: xxxx-xx-xx
+Version: 1.0.0, v1.0, Rev. 1.0
+(any YYYY-MM-DD or YYYY/MM/DD outside code blocks)
+
+# Stale references
+(patterns/old-file.md)  # file doesn't exist
+(../missing.md)         # broken relative link
+
+# Vague descriptions
+description: Does stuff
+description: Agent for things
+description: [TODO]
+
+# Kitchen sink agents (violates single responsibility)
+tools: All
+tools: Read, Write, Edit, Bash, WebFetch, WebSearch, Task  # Too many
+
+# Checker agents with write access (Creator-Checker violation)
+name: code-reviewer
+tools: Read, Write, Edit      # Reviewers should be read-only
+```
+
+**ASCII Art Alternatives** (context-size conscious):
+
+| Instead of | Use |
+|------------|-----|
+| Box diagrams | Markdown tables, bullet lists |
+| Flow arrows | Numbered steps, `1. → 2. → 3.` |
+| Tree structures | Indented lists, file path notation |
+| Decorative borders | Markdown headings (`##`) |
+
+## Report Format
+
+```markdown
+# Claude Config Review
+
+**Scanned**: {count} files in .claude/
+**Issues**: {error_count} errors, {warning_count} warnings, {info_count} info
+
+## Errors (Must Fix)
+
+- [{file}] {issue description}
+  Fix: {suggestion}
+
+## Warnings (Should Fix)
+
+- [{file}] {issue description}
+  Fix: {suggestion}
+
+## Info (Consider)
+
+- [{file}] {issue description}
+
+## Summary
+
+{Overall assessment and next steps}
+
+Self-Review Result: {PASS|FAIL}
+  Critical: {count}
+  Warning: {count}
+  Info: {count}
+  Files with issues: {file1, file2, ...}
+  Auto-fixable: {yes|no}
+```
+
+**Self-Review Result must always be output at the end of the report.**
+
+**Status determination:**
+- Error > 0 → FAIL
+- Error = 0 → PASS
+
+**Auto-fixable determination:**
+- yes: Mechanical fixes such as removing temporary markers, adding code block language specifiers
+- no: Broken links (need target verification), structural issues (need design decisions)
+
+## Workflow Pattern Recognition
+
+When reviewing skills/agents, identify which pattern they follow:
+
+| Pattern | Indicators | Recommendation |
+|---------|------------|----------------|
+| **Analyzer** | Read-only tools, "review/check/analyze" in description | Ensure no Write/Edit tools |
+| **Generator** | Write tool, "create/generate" in description | Verify output format defined |
+| **Transformer** | Edit tool, "refactor/migrate/update" in description | Check safety rules exist |
+| **Investigator** | Bash + Read, "debug/diagnose" in description | Ensure root cause workflow |
+| **Orchestrator** | Task tool, coordinates subagents | Verify delegation logic |
+
+**Creator-Checker Pair Detection**:
+- If name contains "reviewer/auditor/checker" should be read-only
+- If name contains "builder/generator/coder" needs Write tool
+
+## Key Points
+
+- Run after any `.claude/` file creation or update
+- Focus on actionable issues with clear fixes
+- Errors must be fixed, warnings are recommended
+- Keep report concise and scannable
+- Reference Anthropic's best practices when suggesting fixes
+- Use `context: fork` to run as isolated sub-agent without polluting main context
+- **Fork constraint**: TodoWrite / AskUserQuestion are unavailable due to `context: fork`; return results as a report only
+
+## Anti-Patterns
+
+- Do not auto-fix detected issues (report only)
+- Do not review plugin-generated rules in `.claude/rules/shirokuma/`

package/plugin/shirokuma-skills-en/skills/codebase-rule-discovery/SKILL.md

@@ -0,0 +1,208 @@
+---
+name: codebase-rule-discovery
+description: Analyzes TypeScript applications to discover patterns and propose coding conventions for shirokuma-docs lint rules. Use when "rule discovery", "convention proposal", "pattern analysis", or when investigating codebases to extract patterns or propose new conventions.
+allowed-tools: Read, Grep, Glob, Bash, AskUserQuestion, TodoWrite
+---
+
+# Codebase Rule Discovery
+
+Analyzes TypeScript applications in the monorepo for two purposes:
+1. **Pattern Discovery**: Extract existing patterns across apps
+2. **Convention Proposal**: Propose new conventions that enable mechanical checks
+
+## When to Use
+
+- User requests "ルール発見", "rule discovery"
+- User says "パターン分析", "pattern analysis"
+- User mentions "規約提案", "convention proposal"
+- User asks "もっとチェックできるようにしたい"
+- User wants to "統一感を上げたい", "機械的チェックを増やしたい"
+
+## Two Modes
+
+### Mode 1: Pattern Discovery
+
+**Goal**: Find what patterns already exist across apps
+
+```
+Analyze existing code → Discover common patterns → Propose rules
+```
+
+### Mode 2: Convention Proposal
+
+**Goal**: Propose conventions that ENABLE more mechanical checks
+
+```
+Checkability analysis → Propose conventions → Implement rules after adoption
+```
+
+**Key Question**: "How should code be written to enable mechanical checks?"
+
+## Target Applications
+
+| App | Path | Description |
+|-----|------|-------------|
+| Blog CMS (admin) | `nextjs-tdd-blog-cms/apps/admin/` | CMS admin panel |
+| Blog CMS (public) | `nextjs-tdd-blog-cms/apps/public/` | Public blog |
+| shirokuma-docs | `shirokuma-docs/src/` | Documentation generation CLI |
+
+## Workflow: Pattern Discovery
+
+Use `TodoWrite` for progress tracking (6+ steps). Use `AskUserQuestion` to confirm priority when proposing conventions.
+
+### Step 1-7: See workflow file
+
+See [workflows/analyze-codebase.md](workflows/analyze-codebase.md)
+
+## Workflow: Convention Proposal
+
+### Step 1: Identify Check Opportunities
+
+Analyze what COULD be checked if conventions existed:
+
+| Category | Current State | If Standardized |
+|----------|--------------|-----------------|
+| File placement | Mixed | Domain-based placement check possible |
+| Naming | Partially consistent | Auto-rename suggestions possible |
+| i18n keys | Freeform | Key format validation possible |
+
+### Step 2: Analyze Current Structure
+
+```bash
+# File structure analysis
+find apps/ -name "*.ts" -o -name "*.tsx" | head -100
+
+# Directory patterns
+ls -la apps/admin/lib/
+ls -la apps/public/lib/
+
+# Naming conventions
+find apps/ -name "*.tsx" | xargs basename -a | sort | uniq -c | sort -rn
+```
+
+### Step 3: Propose Conventions
+
+For each opportunity, document:
+
+1. **Current State**: How it's done now (with variations)
+2. **Proposed Convention**: Specific rule
+3. **Migration Cost**: How much code needs changing
+4. **Check Enabled**: What lint rule becomes possible
+5. **Benefits**: Why it's worth standardizing
+
+### Step 4: Generate Convention Proposal
+
+Use [templates/convention-proposal.md](templates/convention-proposal.md)
+
+### Step 5: Save as Knowledge Discussion
+
+Before proposing a rule, save findings as a Knowledge Discussion to preserve context and rationale.
+
+```bash
+# For confirmed patterns → Knowledge category
+shirokuma-docs discussions create --category Knowledge --title "{Pattern Name}" --body "..."
+
+# For investigations still in progress → Research category
+shirokuma-docs discussions create --category Research --title "[Research] convention-{category}" --body "..."
+```
+
+**Choose the category based on confidence level:**
+
+| Confidence | Category | Next Step |
+|------------|----------|-----------|
+| Confirmed (pattern observed 2+ times) | Knowledge | Proceed to Rule extraction (Step 6) |
+| Tentative (needs more validation) | Research | Wait for more evidence before Rule |
+
+The Discussion serves as the **source of truth** for the rationale behind the rule. Always create it before proposing a rule.
+
+### Step 6: Extract Rule (if Knowledge)
+
+When a pattern is recorded as Knowledge (confirmed), propose a Rule for AI consumption:
+
+1. Use `managing-rules` skill to create the rule file
+2. Keep the rule concise and actionable (AI audience)
+3. Add source reference: `<!-- Source: Discussion #{N} -->`
+4. The Knowledge Discussion retains the full context; the Rule is a distilled extract
+
+## Convention Categories
+
+### 1. File Placement Conventions
+
+| Area | Convention | Enables |
+|------|------------|---------|
+| Server Actions | `lib/actions/{domain}.ts` | Domain completeness check |
+| Components | `components/{Domain}/` | Component dependency check |
+| Hooks | `hooks/use{Name}.ts` | Hook naming check |
+| Types | `types/{domain}.ts` | Type definition duplication check |
+
+### 2. Naming Conventions
+
+| Target | Convention | Example |
+|--------|------------|---------|
+| Server Action files | `{domain}-actions.ts` | `post-actions.ts` |
+| Component files | `{Name}.tsx` (PascalCase) | `PostCard.tsx` |
+| Hook files | `use{Name}.ts` | `useAuth.ts` |
+| Test files | `{name}.test.ts` | `post-actions.test.ts` |
+
+### 3. Code Structure Conventions
+
+| Area | Convention | Enables |
+|------|------------|---------|
+| Server Action order | Auth → CSRF → Validation → Processing | Order check |
+| Export style | Prefer named exports | Improved unused export detection |
+| i18n keys | `{domain}.{action}.{element}` | Key format check |
+
+### 4. Annotation Conventions
+
+| Tag | Required For | Enables |
+|-----|-------------|---------|
+| `@serverAction` | Server Actions | Auto documentation generation |
+| `@screen` | Page components | Screen catalog generation |
+| `@usedComponents` | Screens | Dependency graph generation |
+
+## Existing Rules (Reference)
+
+| Rule | Status |
+|------|--------|
+| server-action-structure | Implemented |
+| annotation-required | Implemented |
+| testdoc-* | Implemented |
+
+Check `shirokuma-docs/src/lint/rules/` for current implementations.
+
+## Anti-Patterns
+
+- Do not propose rules that duplicate existing rules
+- Do not mark a pattern as confirmed with fewer than 2 observations
+
+## Quick Reference
+
+```bash
+# Pattern discovery (Mode 1)
+"discover patterns in blog-cms"
+
+# Convention proposal (Mode 2)
+"propose conventions for better checking"
+
+# Specific areas
+"propose file placement conventions"
+"propose naming conventions"
+"propose i18n key conventions"
+```
+
+## Related Resources
+
+- [patterns/discovery-categories.md](patterns/discovery-categories.md) - What to look for
+- [templates/rule-proposal.md](templates/rule-proposal.md) - Rule proposal format
+- [templates/convention-proposal.md](templates/convention-proposal.md) - Convention proposal format
+- [workflows/analyze-codebase.md](workflows/analyze-codebase.md) - Detailed workflow
+
+## Output
+
+Convention proposals should answer:
+
+1. **What**: Specific convention content
+2. **Why**: Why this convention is needed
+3. **Check**: What checks become possible
+4. **Migration**: Migration cost for existing code
+5. **Priority**: P0/P1/P2