shirokuma-docs 0.1.0-alpha.1

package/plugin/shirokuma-skills-en/skills/committing-on-issue/SKILL.md

@@ -0,0 +1,227 @@
+---
+name: committing-on-issue
+description: Stage, commit, push changes with optional PR creation chain. Also handles PR merge with automatic Issue status update. Use when "commit changes", "push changes", "commit and create PR", "merge PR", "merge this PR".
+allowed-tools: Bash, Read, Grep, Glob, AskUserQuestion
+---
+
+# Committing
+
+Stage, commit, and optionally push changes to the remote.
+
+## Workflow
+
+### Step 1: Review Changes
+
+```bash
+git status --short
+git diff --stat
+git branch --show-current
+```
+
+Display a summary of changes to the user.
+
+### Step 2: Stage Files
+
+Stage specific files relevant to the current work. Prefer explicit file paths over `git add -A`.
+
+```bash
+git add {file1} {file2} ...
+```
+
+**Do NOT stage:**
+- `.env`, credentials, or secrets
+- Large binary files
+- Unrelated changes from other work
+
+If unsure which files to stage, use AskUserQuestion to present the file list as options.
+
+### Step 2.5: Plugin Version Bump Check
+
+Check if staged files include `plugin/` changes (excluding `.gitkeep`):
+
+```bash
+git diff --cached --name-only | grep '^plugin/' | grep -v '\.gitkeep$'
+```
+
+If plugin files are staged:
+1. Check if `package.json` version has been appropriately bumped
+2. If not bumped: follow `plugin-version-bump` rule to bump + run `node scripts/sync-versions.mjs`
+3. If already bumped: verify all `plugin.json` files match `package.json` version
+
+### Step 3: Write Commit Message
+
+Follow Conventional Commits format:
+
+```
+{type}: {description} (#{issue-number})
+
+{optional body}
+```
+
+| Type | When |
+|------|------|
+| `feat` | New feature or enhancement |
+| `fix` | Bug fix |
+| `refactor` | Code restructuring |
+| `docs` | Documentation |
+| `test` | Tests |
+| `chore` | Config, tooling |
+
+**Rules** (see `git-commit-style` rule for details):
+- First line under 72 characters
+- Reference issue number if applicable
+- Body for complex changes only
+- Do NOT include `Co-Authored-By` signature
+
+### Step 4: Commit
+
+```bash
+git commit -m "$(cat <<'EOF'
+{type}: {description} (#{issue-number})
+
+{optional body}
+EOF
+)"
+```
+
+### Step 5: Push (if on feature branch)
+
+If on a feature branch (not `develop` or `main`), push automatically:
+
+```bash
+git push -u origin {branch-name}
+```
+
+If on `develop` or `main`, do NOT push automatically. Inform the user that direct pushes to protected branches should be avoided per branch-workflow rules.
+
+### Step 6: Confirm
+
+```markdown
+## Committed
+
+**Branch:** {branch-name}
+**Commit:** {hash} {message}
+**Files:** {count} files changed
+**Pushed:** {yes/no}
+```
+
+### Step 7: PR Chain (after push)
+
+After a successful push on a feature branch, determine whether to chain into PR creation.
+
+**PR keyword detection**: Check the user's **initial message** (the `/committing-on-issue` invocation and surrounding text) for PR-related keywords:
+
+| Language | Keywords |
+|----------|----------|
+| Japanese | "PR作って", "PR作成", "プルリクエスト", "PRも作って", "PRも" |
+| English | "pull request", "create PR", "open PR" |
+
+**Pre-check before offering PR**:
+
+```bash
+gh pr list --head {branch-name} --json number,url --jq '.[0]'
+```
+
+If a PR already exists for this branch, show the existing URL and skip:
+
+```markdown
+PR already exists: {url}
+```
+
+**If PR keywords detected AND no existing PR:**
+
+Auto-invoke the `creating-pr-on-issue` skill via the Skill tool. Pass the current branch and related issue number as context.
+
+**If no PR keywords AND no existing PR:**
+
+Suggest the next step without auto-executing:
+
+```markdown
+Branch pushed. Create a PR?
+→ `/creating-pr-on-issue` to open a pull request to develop
+```
+
+**If NOT on a feature branch (pushed was skipped):**
+
+Skip this step entirely.
+
+### Step 8: Merge Chain
+
+Handles PR merge with automatic Issue status update. Activated by merge keywords or when invoked from `working-on-issue` orchestration.
+
+**Merge keyword detection**: Check the user's message for:
+
+| Language | Keywords |
+|----------|----------|
+| Japanese | "マージして", "マージ", "merge" |
+| English | "merge PR", "merge this", "merge it" |
+
+**If merge keywords detected (independent of commit flow):**
+
+1. **Merge the PR and update related Issues**:
+
+```bash
+shirokuma-docs issues merge --head {current-branch}
+```
+
+This single command handles: resolve PR from branch name, squash merge, extract linked Issues from PR body (`Closes/Fixes/Resolves #N`), update their Project Status to "Done", and delete the branch.
+
+**Status update idempotency**: `issues merge` CLI automatically updates related Issue Project Status to Done. If `ending-session --done` runs for the same issue later, it operates idempotently (no-op if already Done).
+
+If no PR found for the branch, the CLI reports an error. Inform the user and stop.
+
+Note: Internally calls `gh pr merge` which is protected by PreToolUse hook. The user will be prompted for confirmation.
+
+2. **Switch to develop**:
+
+```bash
+git checkout develop && git pull origin develop
+```
+
+3. **Confirm**:
+
+```markdown
+## Merged
+
+**PR:** (as reported by CLI output) → {base-branch}
+**Issues updated:** (as reported by CLI output)
+**Branch:** deleted, switched to develop
+```
+
+**If merge is part of commit flow** (e.g., user says "コミットしてマージして"):
+
+Execute Steps 1-6 → Step 7 (PR Chain) → Step 8 (Merge Chain) sequentially.
+
+## Arguments
+
+If invoked with a message argument (e.g., `/committing-on-issue fix typo in config`):
+- Use the provided text as the commit message basis
+- Still review changes before committing
+- PR-related keywords in the argument trigger the PR chain (e.g., `/committing-on-issue fix typo PRも作って`)
+- Merge keywords trigger the merge chain (e.g., `/committing-on-issue コミットしてマージして`)
+
+## Edge Cases
+
+| Situation | Action |
+|-----------|--------|
+| No changes to commit | Inform user, do nothing |
+| On develop or main | Commit but warn about pushing; suggest creating a feature branch |
+| Merge conflicts | Inform user, do not auto-resolve |
+| Pre-commit hook fails | Fix issue, create NEW commit (never amend) |
+| Mixed changes (multiple issues) | Use AskUserQuestion to select files per issue |
+| PR already exists for branch | Show existing PR URL, skip chain |
+| `gh` CLI not available | Skip PR chain, inform user |
+| No PR for current branch (merge) | Inform user, skip merge |
+| PR has unresolved reviews | Warn user, ask for confirmation |
+| No issue references in PR body | Skip status update, inform user |
+
+## Notes
+
+- Always review changes before committing
+- Never use `git add -A` or `git add .` without review
+- Never amend previous commits unless explicitly asked
+- Never force push
+- Push is automatic on feature branches, skipped on `develop` and `main`
+- PR chain activates only on direct invocation with PR keywords; does not interfere with `working-on-issue` orchestration
+- Merge chain can be invoked standalone (just "マージして") or chained with commit/PR
+- After merge, `shirokuma-docs issues merge` automatically updates related Issue status to Done

package/plugin/shirokuma-skills-en/skills/creating-pr-on-issue/SKILL.md

@@ -0,0 +1,225 @@
+---
+name: creating-pr-on-issue
+description: Create a GitHub pull request for the current branch. Use when "create pull request", "create PR", "open PR".
+allowed-tools: Bash, Read, Grep, Glob, AskUserQuestion
+---
+
+# Creating Pull Request
+
+Create a GitHub pull request from the current feature branch.
+
+## Workflow
+
+### Step 1: Verify Branch State
+
+PRs target `develop` for daily work (see `branch-workflow` rule):
+
+```bash
+git branch --show-current
+git status --short
+git log --oneline develop..HEAD
+```
+
+**Pre-checks:**
+- Must be on a feature branch (not `develop` or `main`)
+- All changes should be committed
+- Branch should have commits ahead of `develop`
+
+If on `develop` or `main`, inform user to create a feature branch first.
+
+### Step 2: Push Branch
+
+Ensure the branch is pushed and up to date:
+
+```bash
+git push -u origin {branch-name}
+```
+
+### Step 3: Analyze Changes
+
+Review all commits on the branch to draft PR content:
+
+```bash
+git log --oneline develop..HEAD
+git diff --stat develop..HEAD
+```
+
+Understand the full scope of changes, not just the latest commit.
+
+### Step 4: Create PR
+
+```bash
+gh pr create --base develop --title "{title}" --body "$(cat <<'EOF'
+## Summary
+- {bullet point 1}
+- {bullet point 2}
+
+## Related Issues
+{Closes #N or Refs #N}
+
+## Test plan
+- [ ] {test item 1}
+- [ ] {test item 2}
+EOF
+)"
+```
+
+**Title rules:**
+- Under 70 characters
+- Conventional commit prefixes (`feat:`, `fix:`, `chore:`, `docs:`, etc.) are always in English
+- **Text after the prefix must be in English**
+- No issue number in title (goes in body)
+
+**Title examples:**
+
+```
+feat: add branch workflow rules
+fix: resolve cross-repo Projects lookup
+docs: update CLAUDE.md command table
+chore: update dependencies
+```
+
+**Bad examples (non-English text in EN plugin):**
+
+```
+feat: ブランチワークフロールールを追加    ← Wrong: not English
+docs: CLAUDE.md のコマンド一覧を更新      ← Wrong: not English
+```
+
+**Body rules:**
+- Summary: 1-3 bullet points of what changed
+- Related Issues: `Closes #N` for completed items, `Refs #N` for related
+- Test plan: checklist of verification steps
+
+### Step 4b: Update Status
+
+If invoked with an issue number (e.g., `/creating-pr-on-issue 39`), update Status to Review immediately after PR creation:
+
+```bash
+shirokuma-docs issues update {number} --field-status "Review"
+```
+
+If no issue number was provided, skip this step (`ending-session` safety net covers it).
+
+### Step 5: Confirm
+
+```markdown
+## Pull Request Created
+
+**PR:** {url}
+**Branch:** {branch} → develop
+**Commits:** {count}
+
+### Summary
+{brief description}
+
+### Linked Issues
+- #{number} - {title}
+```
+
+### Step 6: Self-Review Chain
+
+After PR creation, **always auto-execute** self-review.
+
+#### 6a. File Category Detection
+
+Get changed files via `git diff --name-only develop..HEAD` and classify:
+
+| Category | Condition |
+|----------|-----------|
+| config | Files under `.claude/skills/`, `.claude/rules/`, `.claude/agents/`, `.claude/output-styles/`, `.claude/commands/`, `plugin/` |
+| code | `.ts`, `.tsx`, `.js`, `.jsx` files |
+| docs | `.md` files (excluding config paths above) |
+
+**Routing:**
+
+| File Composition | Review Method |
+|-----------------|---------------|
+| config only | Invoke `claude-config-reviewing` only |
+| code/docs only (no config) | Invoke `reviewing-on-issue` only (as before) |
+| mixed (config + code/docs) | Invoke `reviewing-on-issue` → `claude-config-reviewing` sequentially → merge results |
+
+**Result merging rules (mixed case):**
+- Status: either FAIL → FAIL
+- Critical/Warning: sum of both
+- Files with issues: merge
+- Auto-fixable: either no → no
+
+#### 6b. Self-Review Loop
+
+```mermaid
+graph LR
+  A[PR created] --> B[Category detection] --> C[Routing] --> D[Review] --> E{Issues found?}
+  E -->|FAIL + Auto-fixable| F[Auto-fix] --> G[Commit] --> H[Push] --> D
+  E -->|FAIL + Not auto-fixable| I[Stop loop, report to user]
+  E -->|PASS| J[Done]
+```
+
+**Loop limit**: Maximum 3 iterations (initial review + up to 2 fix-and-review cycles)
+
+**Steps:**
+
+1. Detect category and invoke appropriate skill(s) (pass PR number as context)
+2. Check the Self-Review Result:
+   - **PASS**: End loop, report completion
+   - **FAIL + Auto-fixable: yes**: Auto-fix based on findings → `git add` → `git commit` → `git push` → re-review
+   - **FAIL + Auto-fixable: no**: Stop loop, report issues requiring manual intervention
+3. After 3 iterations still FAIL: stop loop, report remaining issues
+
+**Safety measures:**
+- If issue count increases between iterations (fixes introduced new problems), stop loop and report
+- Accumulate feedback from each iteration (via `reviewing-on-issue` feedback accumulation)
+
+**Progress reporting:**
+
+```text
+Self-review [1/3]: Category detection → config + code (mixed)
+  Running reviewing-on-issue...
+  Running claude-config-reviewing...
+  → Merged result: 2 critical issues detected, auto-fixing...
+  → Fix complete, commit & push
+
+Self-review [2/3]: Re-reviewing...
+  → No issues. Self-review complete.
+```
+
+## Arguments
+
+If invoked with an issue number (e.g., `/creating-pr-on-issue 39`):
+- Include `Closes #39` in the PR body
+- Derive PR title from the issue context
+
+## Language
+
+PR titles and bodies must be in English. Conventional commit prefixes (`feat:`, `fix:`, etc.) are always in English.
+
+## Edge Cases
+
+| Situation | Action |
+|-----------|--------|
+| On develop or main | Error: must be on a feature branch |
+| Uncommitted changes | Warn user, suggest committing first |
+| No commits ahead of base | Error: nothing to create PR for |
+| PR already exists for branch | Show existing PR URL instead |
+| Push fails | Show error, suggest `git pull --rebase` |
+
+## Next Steps (Standalone Invocation Only)
+
+When invoked from the `working-on-issue` chain, the chain continues automatically after self-review; this section does not apply. Only suggest the next workflow step when invoked standalone:
+
+```
+PR created. Next step:
+→ `/ending-session` to save handover and update issue statuses
+```
+
+## Notes
+
+- Always push before creating PR
+- Never create PRs from `develop` or `main`
+- Daily work PRs target `develop`; only hotfixes target `main`
+- Direct PRs to `main` are prohibited (exception: hotfixes only)
+- If no branch exists or changes are uncommitted, use AskUserQuestion to suggest committing or creating a branch
+- Include issue references for automatic linking
+- PR body should be informative but concise
+- Self-review always runs automatically after PR creation
+- Do not include AI attribution lines (e.g. "🤖 Generated with Claude Code") in PR body

package/plugin/shirokuma-skills-en/skills/ending-session/SKILL.md

@@ -0,0 +1,232 @@
+---
+name: ending-session
+description: End a work session saving handover info and updating project items. Use when "end session", "finish work", "save handover".
+allowed-tools: Bash, Read, Write, Grep, Glob, AskUserQuestion
+---
+
+# Ending Session
+
+End the current session and auto-save handover information.
+
+## Handover is Mandatory
+
+Every session MUST end with a handover Discussion. This is **not optional** — even brief sessions produce useful context for future sessions.
+
+- If no significant work was done, write a brief summary of what was discussed or investigated
+- If the user tries to skip the handover, explain its importance and proceed with creation
+- Empty Summary or Next Steps sections are not acceptable — always provide at least one line for each
+
+## Workflow
+
+### Step 1: Gather Session Summary
+
+Analyze conversation to extract:
+1. **Summary**: What was accomplished (1-2 sentences)
+2. **Related Items**: Project items worked on
+3. **Key Decisions**: Important decisions with rationale
+4. **Blockers**: Any blockers encountered
+5. **Next Steps**: Actionable tasks for next session
+6. **Modified Files**: From `git status --short`
+7. **Commits**: From `git log --oneline` (this session)
+
+### Step 2: Get Modified Files, Commits, and Branch Info
+
+```bash
+git status --short | head -20
+git log --oneline -10
+git branch --show-current
+```
+
+### Step 3: Push Branch and Create PR (if on feature branch)
+
+If on a feature branch (not the base branch):
+
+#### 3a. Check for Uncommitted Changes
+
+```bash
+git status --short
+```
+
+If uncommitted changes exist, use AskUserQuestion to confirm whether to commit them before proceeding.
+Follow the `committing-on-issue` skill workflow: stage specific files, write a conventional commit message (no Co-Authored-By), and commit.
+
+#### 3b. Push Branch
+
+```bash
+git push -u origin {branch-name}
+```
+
+#### 3c. Create PR
+
+Follow the `creating-pr-on-issue` skill workflow. Create a PR targeting `develop` (see `branch-workflow` rule):
+
+```bash
+gh pr create --base develop --title "{title}" --body "$(cat <<'EOF'
+## Summary
+{1-3 bullet points of what was done}
+
+## Related Issues
+{Closes #N or Refs #N for each issue}
+
+## Test plan
+- [ ] {testing checklist items}
+EOF
+)"
+```
+
+**PR title:** Concise summary under 70 characters.
+**PR body:** Include `Closes #{number}` for items that are done, `Refs #{number}` for items still in progress.
+**PR base:** Always `develop` for daily work. Only hotfixes target `main`.
+
+#### 3d. Note the PR URL
+
+Save the PR URL for inclusion in the handover body.
+
+If on the base branch (no feature branch), skip this step entirely.
+
+### Step 4: Save Handover + Update Statuses (Single Command)
+
+Build the handover body using the template below, then run:
+
+```bash
+shirokuma-docs session end \
+  --title "$(date +%Y-%m-%d) - {brief summary}" \
+  --body "$HANDOVER_BODY" \
+  --done {completed_issue_numbers} \
+  --review {review_issue_numbers}
+```
+
+This single command:
+- Creates the handover Discussion (Handovers category)
+- Updates specified issues to "Done" or "Review" status
+
+**Options:**
+- `--title` (required) - Handover title, typically date + summary
+- `--body` (required) - Full handover body in markdown
+- `--done <numbers...>` - Issue numbers to mark as Done
+- `--review <numbers...>` - Issue numbers to mark as Review
+
+**Choosing --done vs --review:**
+- `--done`: Work is fully complete, no PR needed (or already merged)
+- `--review`: PR created, awaiting user review (auto-promotes to Done if PR already merged)
+
+**Determination algorithm** (for each issue):
+
+| Priority | Condition | Action |
+|----------|-----------|--------|
+| 0 | Status is Planning or Spec Review | Do not update status (pre-work status, planning in progress) |
+| 1 | Issue has a merged PR | `--done` |
+| 2 | Issue has an open PR | `--review` |
+| 3 | Work complete, no PR needed | `--done` |
+| 4 | Work still in progress | Do not update status |
+
+Use `shirokuma-docs issues show {number}` to check PR state.
+
+**Idempotency**: If `creating-pr-on-issue` already set Review, `--review` is a no-op. If `committing-on-issue` merge chain already set Done, `--done` is a no-op. `ending-session` acts as a safety net, catching any status updates that other skills missed.
+
+**Output:**
+```json
+{
+  "handover": {
+    "number": 31,
+    "title": "2026-02-02 - Feature implementation",
+    "url": "https://github.com/..."
+  },
+  "updatedIssues": [
+    { "number": 27, "status": "Done" },
+    { "number": 26, "status": "Review" }
+  ]
+}
+```
+
+**Local fallback** (if `session end` fails):
+
+```bash
+mkdir -p .claude/sessions
+echo "$HANDOVER_BODY" > .claude/sessions/$(date +%Y-%m-%d-%H%M%S)-handover.md
+```
+
+On success, `session end` automatically cleans up any PreCompact backups in `.claude/sessions/`.
+
+### Step 5: Display Summary
+
+```markdown
+## Session Ended
+
+**Saved to:** {handover.url or local path}
+**Branch:** {branch name}
+**PR:** {PR URL or "N/A"}
+
+### Accomplishments
+{summary}
+
+### Completed Items
+- #{number} → Done
+
+### Items for Review
+- #{number} → Review (PR #{pr_number})
+
+### Next Steps
+- [ ] {task 1}
+- [ ] {task 2}
+```
+
+## Handover Body Format
+
+```markdown
+## Summary
+{What was accomplished}
+
+## Related Items
+- #{number} - {title} - {status}
+
+## Key Decisions
+- {Decision and rationale}
+
+## Blockers
+- {Blockers, or none}
+
+## Next Steps
+- [ ] {Next task}
+
+## Commits (This Session)
+| Hash | Description |
+|------|-------------|
+| {hash} | {message} |
+
+## Pull Requests
+- {PR URL, or "No PR created (working on base branch)"}
+
+## Modified Files
+- `path/file.ts` - {Change description}
+
+## Notes
+{Additional information}
+```
+
+> **Note**: Write section headers and content in English.
+
+## Error Handling
+
+| Error | Action |
+|-------|--------|
+| `session end` fails | Save to local file |
+| No "Handovers" category | Save to local file |
+| gh not authenticated | Save to local file |
+| No changes in session | Still save a brief handover |
+| Issue not in project | Warn and continue |
+| `git push` fails | Warn user, save handover without PR |
+| `gh pr create` fails | Warn user, include branch name in handover |
+| On base branch (no feature branch) | Skip push/PR steps, save handover only |
+
+## Notes
+
+- Auto-save without confirmation for faster workflow
+- Always generate a summary even if brief
+- Local fallback ensures handover is never lost
+- `session end` handles both handover creation and status updates in one call
+- Use `--review` when PR is created, `--done` when work needs no review
+- Include PR URL in handover body for traceability
+- Never leave Summary or Next Steps empty (at least one line each)
+- Use `--review` for items with a PR already created (not `--done`)
+- Use TodoWrite to track progress when updating multiple items