shirokuma-docs 0.1.0-alpha.1

package/plugin/shirokuma-hooks/hooks/scripts/block-destructive-commands.sh

@@ -0,0 +1,87 @@
+#!/bin/bash
+set -euo pipefail
+
+# Block destructive git/GitHub commands based on configurable rules.
+# Used as a PreToolUse hook for the Bash tool.
+#
+# Configuration:
+#   Default rules:  ${CLAUDE_PLUGIN_ROOT}/hooks/blocked-commands.json
+#   Project override: .claude/shirokuma-hooks.json (in project root)
+#
+# The project override can disable specific rules by ID:
+#   { "disabled": ["pr-merge"] }
+#
+# False-positive prevention:
+#   Quoted strings (single and double) are stripped from the command
+#   before pattern matching, so text inside --body "..." or similar
+#   arguments does not trigger blocks.
+#
+# Limitation: Commands constructed via eval or variable expansion
+# (e.g., cmd="git push --force" && eval "$cmd") are not detected.
+# This hook performs string matching on the direct command text only.
+#
+# Input: JSON on stdin (Claude Code hook format)
+# Output: JSON with permissionDecision (deny) or exit 0 (allow)
+
+INPUT=$(cat)
+COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty')
+
+if [ -z "$COMMAND" ]; then
+  exit 0
+fi
+
+# Strip quoted strings to avoid false positives on argument values.
+# First collapse newlines (multi-line bodies), then remove quoted content.
+COMMAND_STRIPPED=$(echo "$COMMAND" | tr '\n' ' ' | sed "s/'[^']*'//g" | sed 's/"[^"]*"//g')
+
+# Locate config files
+PLUGIN_ROOT="${CLAUDE_PLUGIN_ROOT:-}"
+DEFAULT_CONFIG="${PLUGIN_ROOT}/hooks/blocked-commands.json"
+PROJECT_CONFIG=".claude/shirokuma-hooks.json"
+
+# Load disabled rule IDs from project override
+DISABLED_IDS="[]"
+if [ -f "$PROJECT_CONFIG" ]; then
+  DISABLED_IDS=$(jq -r '.disabled // []' "$PROJECT_CONFIG" 2>/dev/null || echo "[]")
+fi
+
+# Load rules from default config
+if [ ! -f "$DEFAULT_CONFIG" ]; then
+  # No config found — allow all (fail open)
+  exit 0
+fi
+
+RULES=$(jq -c '.rules[]' "$DEFAULT_CONFIG" 2>/dev/null) || exit 0
+
+# Check each enabled rule against the stripped command
+while IFS= read -r rule; do
+  RULE_ID=$(echo "$rule" | jq -r '.id')
+  ENABLED=$(echo "$rule" | jq -r '.enabled')
+  PATTERN=$(echo "$rule" | jq -r '.pattern')
+  REASON=$(echo "$rule" | jq -r '.reason')
+
+  # Skip disabled rules
+  if [ "$ENABLED" != "true" ]; then
+    continue
+  fi
+
+  # Skip rules disabled by project override
+  if echo "$DISABLED_IDS" | jq -e --arg id "$RULE_ID" 'index($id) != null' > /dev/null 2>&1; then
+    continue
+  fi
+
+  # Match against stripped command (no quoted content)
+  if echo "$COMMAND_STRIPPED" | grep -qE "$PATTERN"; then
+    jq -n --arg reason "$REASON" '{
+      hookSpecificOutput: {
+        hookEventName: "PreToolUse",
+        permissionDecision: "deny",
+        permissionDecisionReason: $reason
+      }
+    }'
+    exit 0
+  fi
+done <<< "$RULES"
+
+# Allow all other commands
+exit 0

package/plugin/shirokuma-skills-en/.claude-plugin/plugin.json

@@ -0,0 +1,21 @@
+{
+  "name": "shirokuma-skills-en",
+  "description": "Reusable AI skills and rules for Claude Code following Agent Skills standard",
+  "version": "0.1.0-alpha.1",
+  "author": {
+    "name": "ShirokumaLibrary"
+  },
+  "homepage": "https://github.com/ShirokumaLibrary/shirokuma-docs",
+  "repository": "https://github.com/ShirokumaLibrary/shirokuma-docs",
+  "keywords": [
+    "claude-code",
+    "skills",
+    "rules",
+    "nextjs",
+    "typescript",
+    "code-review",
+    "frontend",
+    "agent-skills"
+  ],
+  "license": "MIT"
+}

package/plugin/shirokuma-skills-en/rules/best-practices-first.md

@@ -0,0 +1,154 @@
+# Best Practices First Mode (Manager)
+
+**Role**: Orchestrate specialized skills and delegate work. Minimize direct work.
+
+## Core Principle: Delegate First
+
+**Manager (You)**:
+- Task analysis and decomposition
+- Select appropriate skill
+- Integrate and report skill results
+- Propose new skills when needed
+
+**Available Skills**:
+
+| Name | Type | Purpose |
+|------|------|---------|
+| planning-on-issue | Skill | **Plan creation** (all issues, depth scales with content) |
+| working-on-issue | Skill | **Work dispatcher** (entry point for tasks) |
+| best-practices-researching | Skill (`context: fork`) | Research and best practices |
+| nextjs-vibe-coding | Skill | TDD implementation |
+| frontend-designing | Skill | Impressive UI / unique design |
+| reviewing-on-issue | Skill (`context: fork`) | Code/security review |
+| claude-config-reviewing | Skill (`context: fork`) | Claude config file review |
+| managing-github-items | Skill | Issue / Discussion creation |
+| showing-github | Skill | GitHub data display / dashboard |
+| Explore | Built-in | Codebase exploration |
+| Plan | Built-in | Architecture design |
+
+> **Skills** → Skill tool, **Skills with `context: fork`** → Skill tool (runs as isolated sub-agent), **Built-in** → Task tool (subagent_type)
+
+## Preferred Entry Point
+
+When the user provides a task with an issue number or work description → delegate to `working-on-issue`.
+`working-on-issue` checks for a plan and auto-delegates to `planning-on-issue` if needed.
+
+Use the decision flow below only when `working-on-issue` is not applicable (e.g., exploration, architecture, simple questions).
+
+## Decision Flow
+
+### 1. On Task Receipt
+
+User Request → Task Analysis → Skill Selection
+
+| Task Type | Route To | Method |
+|-----------|----------|--------|
+| Implementation | nextjs-vibe-coding | Skill tool (via working-on-issue) |
+| Design | frontend-designing | Skill tool (via working-on-issue) |
+| Research | best-practices-researching | Skill tool |
+| Review | reviewing-on-issue | Skill tool |
+| Issue / Discussion creation | managing-github-items | Skill tool |
+| GitHub data display | showing-github | Skill tool |
+| Exploration | Explore | Task tool (Built-in) |
+| Architecture | Plan | Task tool (Built-in) |
+| Claude Config | claude-config-reviewing | Skill tool |
+| None match | Propose new skill | — |
+
+### 2. Skill Selection Criteria
+
+| Keyword/Pattern | Route To | Example |
+|-----------------|----------|---------|
+| implement, add feature, create page | `nextjs-vibe-coding` (Skill) | "implement dashboard" |
+| impressive, design, unique | `frontend-designing` (Skill) | "make UI impressive" |
+| research, best practices | `best-practices-researching` (Skill) | "Drizzle best practice?" |
+| review, audit | `reviewing-on-issue` (Skill) | "security review" |
+| create issue, make issue, follow-up | `managing-github-items` (Skill) | "make this an issue" |
+| dashboard, show issues, project status | `showing-github` (Skill) | "show dashboard" |
+| structure, explore files | `Explore` (Built-in) | "where is auth?" |
+| design, architecture | `Plan` (Built-in) | "design auth system" |
+
+### 3. When No Skill Matches
+
+Propose a new skill:
+
+```markdown
+## Proposal: New Skill `{skill-name}`
+
+**Purpose**: {What the skill does}
+**Triggers**: {When to use it}
+**Tools**: {Required tools}
+
+Create it?
+```
+
+## Manager Responsibilities
+
+### Do:
+- Analyze tasks and select appropriate skills
+- Run multiple skills in parallel (independent tasks)
+- Integrate skill results and report to user
+- Detect missing skills and propose new ones
+
+### Don't:
+- Write code directly (→ nextjs-vibe-coding Skill)
+- Explore files directly (→ Explore)
+- Do lengthy research (→ best-practices-researching Skill)
+
+### Exceptions (direct handling OK):
+- Simple question answers
+- Minor config file edits
+- Fine-tuning skill results
+- Confirmation dialogues with user
+
+## User Confirmation Rules
+
+Use **AskUserQuestion** (not plain text prompts) when:
+- Deviating from instructions
+- Multiple implementation approaches exist (present as selectable options)
+- Edge cases require user decision (branch conflicts, ambiguous requirements)
+
+Use **TodoWrite** when:
+- Working on 3+ step tasks to show progress
+- Orchestrating multi-issue sessions
+- Running delegated chains (Review → Commit → PR)
+
+## Response Style
+
+1. **Show task understanding**: 1-2 line summary
+2. **State skill selection**: With reasoning
+3. **Report results**: After skill completion
+4. **Suggest next actions**: As needed
+
+## Parallel Skill Execution
+
+Run independent tasks in parallel. Sequential only when dependent.
+
+## Error Recovery Protocol
+
+When failure occurs:
+
+**1. Root Cause Analysis**
+- Clarify what went wrong
+- Identify overlooked points from user report
+
+**2. System Improvement Proposal** (mandatory)
+Propose changes to Claude config files:
+- Specify which config file to change
+- Show concrete additions/modifications
+- Explain purpose and effect
+- Get confirmation before implementing
+
+Target files: deployed skill/rule configuration files, `CLAUDE.md`
+
+**Important**: No memory between sessions. Always propose system improvements, not just "I'll be careful next time."
+
+## GitHub Operations Rule
+
+- Always use `shirokuma-docs gh-*` CLI for GitHub operations
+- Direct `gh` command use is prohibited (bypasses Projects integration)
+- Cross-repository operations: Use `--repo {alias}` (aliases defined in `shirokuma-docs.config.yaml` `crossRepos`)
+
+## Project Reference
+
+- **Tech Stack / Critical Rules**: `CLAUDE.md`
+

package/plugin/shirokuma-skills-en/rules/config-authoring-flow.md

@@ -0,0 +1,39 @@
+# Config Authoring Flow
+
+When creating or updating Claude Code configuration files (rules, skills, agents, output-styles, plugins), follow this flow to ensure quality and consistency.
+
+## Required Tools
+
+| Tool | Type | When |
+|------|------|------|
+| `managing-rules` | Skill | Creating or updating rules |
+| `managing-skills` | Skill | Creating or updating skills |
+| `managing-agents` | Skill | Creating or updating agents |
+| `managing-output-styles` | Skill | Creating or updating output styles |
+| `managing-plugins` | Skill | Creating or updating plugins |
+| `claude-config-reviewing` | Skill | After any config creation/update (quality check) |
+
+## Flow
+
+1. **Before writing**: Invoke the relevant managing-* skill for best practices and templates
+2. **Write**: Create or update the config file following the skill's guidance
+3. **After writing**: Run the `claude-config-reviewing` skill to verify quality
+
+### Example: Creating a new rule
+
+```
+1. Invoke managing-rules skill -> get template and best practices
+2. Write plugin/shirokuma-skills-en/rules/my-rule.md
+3. Invoke claude-config-reviewing skill -> verify quality and consistency
+```
+
+## When This Applies
+
+- Creating new files in `.claude/rules/`, `.claude/skills/`, `.claude/agents/`, `.claude/output-styles/`, `.claude/commands/`
+- Creating new files in `plugin/` directories (skills, agents, rules, plugins)
+- Updating existing config files with structural changes (not typo fixes)
+
+## Exceptions
+
+- Minor typo fixes or single-line edits do not require the full flow
+- The reviewer skill step can be skipped if explicitly told by the user

package/plugin/shirokuma-skills-en/rules/git-commit-style.md

@@ -0,0 +1,58 @@
+# Git Commit Style
+
+## Commit Message Format
+
+```
+{type}: {description} (#{issue-number})
+
+{optional body}
+```
+
+## Conventional Commit Types
+
+| Type | When |
+|------|------|
+| `feat` | New feature or enhancement |
+| `fix` | Bug fix |
+| `refactor` | Code restructuring (no behavior change) |
+| `docs` | Documentation only |
+| `test` | Adding or updating tests |
+| `chore` | Config, tooling, dependencies |
+
+## Rules
+
+1. **First line under 72 characters**
+2. **Reference issue number** when applicable: `(#39)`
+3. **No Co-Authored-By signature** - Do not append `Co-Authored-By: Claude ...` or any AI attribution lines to commit messages
+4. **Imperative mood** in description: "add feature" not "added feature"
+5. **Body is optional** - Use for complex changes that need explanation
+6. **Blank line** between subject and body
+
+## Examples
+
+```
+feat: add branch workflow rules (#39)
+
+fix: pass repo name to getProjectId for cross-repo support (#34)
+
+refactor: separate marketplace and plugin directory structure (#27)
+
+chore: update dependencies
+```
+
+## Code Language
+
+| Element | Language |
+|---------|----------|
+| Code / Variable names | English |
+| Comments / JSDoc / TSDoc | English |
+| Commit messages | English (conventional commits format) |
+| CLI output messages | Per i18n dictionary (`i18n/cli/`) |
+
+## What NOT to Do
+
+- Do not include `Co-Authored-By` lines
+- Do not include `Signed-off-by` lines unless required by project
+- Do not use `--no-verify` to skip hooks
+- Do not amend commits unless explicitly asked
+- Do not force push to the base branch

package/plugin/shirokuma-skills-en/rules/github/branch-workflow.md

@@ -0,0 +1,313 @@
+<!-- managed-by: shirokuma-docs@0.1.0 -->
+
+# Branch Workflow
+
+## Branch Model
+
+| Branch | Role | Branches from | Merges to | Persistent | Protected |
+|--------|------|---------------|-----------|-----------|-----------|
+| `main` | Production releases. Tagged for each version | - | - | Yes | Yes |
+| `develop` | Integration. Default branch for PRs | `main` (initial) | `main` (release PR) | Yes | Yes |
+| `feat/*`, `fix/*`, `chore/*`, `docs/*` | Daily work | `develop` | `develop` (PR) | No | No |
+| `hotfix/*` | Urgent production fix | `main` | `main` (PR), then cherry-pick to `develop` | No | No |
+| `release/X.x` | Old major maintenance (only when needed) | tag | stays on branch (tag) | Conditional | Yes |
+
+**Key principles:**
+- `develop` is the **default branch** on GitHub (PR target)
+- `main` reflects **production state** only
+- Feature branches always branch from `develop`
+- Direct commits to `develop` or `main` are not allowed
+
+## Base Branch Detection
+
+For daily work, the base branch is `develop`. Detect dynamically:
+
+```bash
+git symbolic-ref refs/remotes/origin/HEAD 2>/dev/null | sed 's@^refs/remotes/origin/@@'
+```
+
+If the above fails (e.g., shallow clone), fall back to:
+
+```bash
+gh repo view --json defaultBranchRef -q .defaultBranchRef.name
+```
+
+The result should be `develop`. If it returns `main`, the default branch has not been changed yet (see Default Branch Setup below).
+
+## Branch Naming
+
+### Feature Branches
+
+```
+{type}/{issue-number}-{slug}
+```
+
+| Type | When |
+|------|------|
+| `feat` | Feature, Enhancement |
+| `fix` | Bug fix |
+| `chore` | Chore, Refactor, Config, Research |
+| `docs` | Documentation |
+
+**Slug rules:**
+- Derive from issue title
+- Lowercase, kebab-case
+- Max 40 characters
+- English only
+
+**Examples:**
+```
+feat/39-branch-workflow-rules
+fix/34-cross-repo-project-resolution
+chore/27-plugin-directory-structure
+docs/32-session-naming-convention
+```
+
+### Hotfix Branches
+
+```
+hotfix/{issue-number}-{slug}
+```
+
+Branch from `main`, not `develop`. Used for urgent production fixes only.
+
+### Release Maintenance Branches
+
+```
+release/{major}.x
+```
+
+Created from a tag when old major version needs a patch. Not used for regular releases.
+
+## Daily Workflow
+
+1. Branch from `develop`
+2. Commit changes during session
+3. Push branch and create PR to `develop`
+4. User reviews and merges PR
+
+### 1. Branch Creation (Session Start)
+
+When user selects an item to work on:
+
+```bash
+git checkout develop
+git pull origin develop
+git checkout -b {type}/{issue-number}-{slug}
+```
+
+- Determine `{type}` from issue's Type field (Feature->feat, Bug->fix, Chore->chore, Docs->docs)
+- Generate `{slug}` from issue title
+
+### 2. Development (During Session)
+
+- Commit frequently with descriptive messages
+- Reference issue number in commits: `feat: add branch workflow rules (#39)`
+- Follow existing commit message conventions
+
+### 3. PR Creation (Session End)
+
+When work is complete or session ends:
+
+```bash
+git push -u origin {branch-name}
+gh pr create --base develop --title "{title}" --body "{body}"
+```
+
+- PR title: concise summary (under 70 characters)
+- PR body: Summary bullets, test plan, linked issues
+- Link issue: include `Closes #{number}` or `Refs #{number}` in body
+- Status moves to **Review**
+
+### 4. Review and Merge
+
+- User reviews the PR on GitHub
+- **AI MUST NOT merge PRs without explicit user instruction** - Enforced by PreToolUse hook (see Destructive Command Protection below)
+- Merge via squash merge (recommended) only after user approval
+- Branch is deleted after merge
+- Status moves to **Done** after merge
+
+## Hotfix Workflow
+
+For urgent production fixes that cannot wait for the normal develop cycle.
+
+### When to Use
+
+- Critical bug in production (`main`)
+- Security vulnerability requiring immediate patch
+- NOT for regular bug fixes (use normal workflow via `develop`)
+
+### Steps
+
+```bash
+# 1. Branch from main
+git checkout main
+git pull origin main
+git checkout -b hotfix/{issue-number}-{slug}
+
+# 2. Fix the issue, commit
+
+# 3. Create PR to main
+git push -u origin hotfix/{issue-number}-{slug}
+gh pr create --base main --title "hotfix: {description}" --body "{body}"
+
+# 4. After merge to main, sync to develop
+git checkout develop
+git pull origin develop
+git cherry-pick {hotfix-commit-hash}
+# Or: git merge main (if multiple commits)
+git push origin develop
+```
+
+**Important:** Always sync the fix to `develop` after merging to `main` to prevent regression.
+
+## Release Workflow
+
+Releases are created by merging `develop` into `main`.
+
+### Steps
+
+```bash
+# 1. Create PR from develop to main
+gh pr create --base main --head develop --title "release: v{version}" --body "{changelog}"
+
+# 2. After PR merge, tag the release
+git checkout main
+git pull origin main
+git tag v{version}
+git push origin v{version}
+```
+
+### Tagging Convention
+
+```
+v{major}.{minor}.{patch}
+```
+
+All versions are recorded as tags. Release branches are NOT created for regular releases.
+
+## Maintenance Branches
+
+### When to Create `release/X.x`
+
+Only when ALL of these conditions are met:
+- A new major version has been released
+- The old major version still needs patches
+- Users cannot upgrade to the new major version
+
+### How to Use
+
+```bash
+# Create from the last tag of that major version
+git checkout v1.2.3
+git checkout -b release/1.x
+git push -u origin release/1.x
+
+# Apply fixes on this branch
+git checkout release/1.x
+git checkout -b fix/{issue-number}-{slug}
+# ... fix and PR to release/1.x
+
+# Tag the patch release
+git tag v1.2.4
+git push origin v1.2.4
+```
+
+Do NOT merge `release/X.x` back to `develop` or `main`.
+
+## Default Branch Setup
+
+To switch the default branch from `main` to `develop`:
+
+### 1. Create the develop branch (if it doesn't exist)
+
+```bash
+git checkout main
+git checkout -b develop
+git push -u origin develop
+```
+
+### 2. Change default branch on GitHub
+
+```bash
+gh repo edit --default-branch develop
+```
+
+Or: GitHub Settings > General > Default branch > Change to `develop`
+
+### 3. Update local HEAD reference
+
+```bash
+git remote set-head origin develop
+```
+
+### 4. Protect both branches
+
+Ensure branch protection rules are set for both `main` and `develop`:
+- Require PR reviews before merging
+- Require status checks to pass
+- No direct pushes
+
+## Rules
+
+1. **Always branch from develop** - Ensure `develop` is up to date before branching
+2. **One branch per issue** - Do not mix unrelated changes
+3. **Push before session end** - Unpushed work risks being lost
+4. **PR required for merge** - No direct pushes to `develop` or `main`
+5. **Never merge without user approval** - Enforced by PreToolUse hook
+6. **Delete branch after merge** - Keep repository clean
+7. **PR to develop for daily work** - Only hotfixes target `main` directly
+8. **Tag every release** - All versions recorded as tags on `main`
+
+## Destructive Command Protection
+
+The shirokuma-skills-en plugin includes a PreToolUse hook that **blocks** destructive commands before execution. This is not advisory — the commands are denied at the tool level.
+
+### Default Blocked Commands
+
+Defined in `hooks/blocked-commands.json`:
+
+| Rule ID | Blocked Command | Reason |
+|---------|-----------------|--------|
+| `pr-merge` | `gh pr merge` / `issues merge` | PR merge requires explicit user approval |
+| `force-push` | `git push --force` / `git push -f` | Force push overwrites remote history |
+| `hard-reset` | `git reset --hard` | Discards all uncommitted changes |
+| `discard-worktree` | `git checkout .` / `git restore .` | Discards working tree changes |
+| `clean-untracked` | `git clean -f` | Deletes untracked files |
+| `force-delete-branch` | `git branch -D` | Force deletes a branch |
+
+When blocked, the AI receives a denial reason and must ask the user for approval before retrying.
+
+### Project Override
+
+Projects can disable specific rules by creating `.claude/shirokuma-hooks.json`:
+
+```json
+{
+  "disabled": ["pr-merge"]
+}
+```
+
+This disables the listed rule IDs, allowing those commands to run. Other rules remain active.
+
+### False-Positive Prevention
+
+The hook strips quoted strings from commands before pattern matching. Text inside `--body "..."` or similar arguments does not trigger blocks.
+
+### Files
+
+- `hooks/hooks.json` — Hook registration
+- `hooks/blocked-commands.json` — Rule definitions (default config)
+- `hooks/scripts/block-destructive-commands.sh` — Hook script
+
+## Edge Cases
+
+| Situation | Action |
+|-----------|--------|
+| Already on a feature branch | Continue working, skip branch creation |
+| Multiple issues in one session | Create separate branches, or group related items |
+| Uncommitted changes on develop | Stash or commit before branching |
+| Branch already exists for issue | Switch to existing branch |
+| Conflict with develop | Rebase before PR: `git rebase develop` |
+| Default branch is still `main` | Follow Default Branch Setup section |
+| Need to fix production urgently | Use Hotfix Workflow |