shirokuma-docs 0.1.0-alpha.1

package/plugin/shirokuma-skills-en/skills/github-project-setup/SKILL.md

@@ -0,0 +1,206 @@
+---
+name: github-project-setup
+description: Automates GitHub Project initial setup with Status, Priority, Type, and Size fields. Use when "project setup", "GitHub Project setup", or starting a new project with kanban workflow.
+allowed-tools: Bash, Read, Glob
+---
+
+# GitHub Project Setup
+
+Automates GitHub Project initial setup including Status workflow, Priority, Type, and Size custom fields.
+
+## When to Use
+
+- Creating a new GitHub Project
+- Setting up a kanban workflow
+- When user says "project setup", "プロジェクト作成", or "GitHub Project"
+
+## Workflow
+
+### Step 1: Check Permissions
+
+```bash
+gh auth status
+```
+
+If permission is missing, ask user to run:
+
+```bash
+gh auth refresh -s project,read:project
+```
+
+### Step 2: Get Repository Info
+
+```bash
+OWNER=$(gh repo view --json owner -q '.owner.login' 2>/dev/null)
+REPO=$(gh repo view --json name -q '.name' 2>/dev/null)
+```
+
+### Step 3: Create Project
+
+```bash
+PROJECT_NAME="${1:-$REPO}"
+gh project create --owner $OWNER --title "$PROJECT_NAME" --format json
+```
+
+### Step 4: Link to Repository
+
+```bash
+gh project link $PROJECT_NUMBER --owner $OWNER --repo $OWNER/$REPO
+```
+
+This makes the project accessible from the repository's Projects tab.
+
+### Step 5: Get Field IDs
+
+```bash
+PROJECT_NUMBER=$(gh project list --owner $OWNER --format json | jq -r '.projects[0].number')
+FIELD_ID=$(gh project field-list $PROJECT_NUMBER --owner $OWNER --format json | jq -r '.fields[] | select(.name=="Status") | .id')
+PROJECT_ID=$(gh project view $PROJECT_NUMBER --owner $OWNER --format json | jq -r '.id')
+```
+
+### Step 6: Configure All Fields
+
+Use the setup script with language auto-detected from conversation:
+
+```bash
+python scripts/setup-project.py \
+  --lang={en|ja} \
+  --field-id=$FIELD_ID \
+  --project-id=$PROJECT_ID
+```
+
+**Fields created**:
+
+| Field | Options |
+|-------|---------|
+| Status | Icebox → Backlog → Spec Review → Ready → In Progress ⇄ Pending → Review → Testing → Done / Not Planned → Released |
+| Priority | Critical / High / Medium / Low |
+| Type | Feature / Bug / Chore / Docs / Research |
+| Size | XS / S / M / L / XL |
+
+See [scripts/setup-project.py](scripts/setup-project.py) for language dictionaries.
+
+### Step 7: Issue Types Setup
+
+GitHub Issue Types are organization-level settings (not project-level). They are configured via the GitHub UI by organization owners.
+
+**Note**: Issue Types are only available for organization repositories, not personal repositories.
+
+**Check if Issue Types are already configured:**
+
+Ask the user: "Has your organization set up Issue Types? (Settings → Issue Types)"
+
+**If not configured, guide the user:**
+
+1. Navigate to `https://github.com/organizations/{org}/settings/issue-types`
+2. Default types (already exist): Task, Bug, Feature
+3. Add custom types:
+
+| Type | Description | Color |
+|------|-------------|-------|
+| Chore | Maintenance, config, tooling, or refactoring | Gray |
+| Docs | Documentation improvements or additions | Blue |
+| Research | Investigation, spike, or exploration | Purple |
+
+**Important**: Issue Types are an organization-wide setting. All repositories in the organization share the same types. This step only needs to be done once per organization.
+
+See [reference/issue-types.md](reference/issue-types.md) for details and migration guide.
+
+### Step 8: Label Setup (Optional)
+
+Clean up default labels and create area-based labels matching the project structure.
+
+1. **Delete redundant labels** that duplicate the Type field (bug, enhancement, documentation)
+2. **Delete inapplicable labels** (good first issue, help wanted, question)
+3. **Create area labels** matching the project's module structure:
+
+```bash
+gh label create "area:{module}" --color "{color}" --description "{description}"
+```
+
+**Keep operational labels**: `duplicate`, `invalid`, `wontfix` (lifecycle/triage purpose).
+
+See [reference/labels.md](reference/labels.md) for full taxonomy and recommended colors.
+
+### Step 9: Enable Built-in Automations
+
+Enable recommended automations for the project. These cannot be set via API — guide the user to the GitHub UI.
+
+**Recommended workflows to enable:**
+
+| Workflow | Target Status | Purpose |
+|----------|--------------|---------|
+| Item closed | Done | Auto-Done when issue is closed |
+| Pull request merged | Done | Auto-Done when PR merges |
+
+**Check current status:**
+
+```bash
+shirokuma-docs projects workflows
+```
+
+**Guide the user:**
+
+1. Navigate to: `https://github.com/orgs/{owner}/projects/{number}/settings/workflows`
+2. Enable "Item closed" → set target to **Done**
+3. Enable "Pull request merged" → set target to **Done**
+
+**Note**: The `session end --review` CLI command and these automations are designed to work together (idempotent). No conflict arises from having both enabled.
+
+### Step 10: Report Results
+
+After completion, display:
+
+- Project name and URL
+- Configured Status list
+- Added custom fields
+- Label summary (deleted/created counts)
+
+## Status Workflow
+
+**Normal Flow**:
+
+Icebox → Backlog → Spec Review → Ready → In Progress → Review → Testing → Done / Not Planned → Released
+
+**Exception Flows**:
+
+| Pattern | Flow | Description |
+|---------|------|-------------|
+| Requirements unclear | Spec Review → Backlog | Needs reconsideration |
+| Blocked | Any → Pending → Original status | Temporary hold (reason required) |
+| Review feedback | Review → In Progress | Fix requested changes |
+| Test failed | Testing → In Progress | Bug fix needed |
+| Simple task | Backlog → Ready | Skip Spec Review if requirements are clear |
+
+**Operational Rules**:
+
+1. One task In Progress per person (WIP limit)
+2. Always document reason when moving to Pending
+3. Review tasks stuck in same status for over a week
+4. Keep Ready queue stocked with actionable tasks
+
+## Error Handling
+
+| Error | Solution |
+|-------|----------|
+| `missing scopes [project]` | Run `gh auth refresh -s project,read:project` |
+| `Project already exists` | Show existing project URL |
+| `Owner not found` | Use `--owner` option explicitly |
+
+## Notes
+
+- **Project name convention**: Project name = repository name (e.g., repo `shirokuma-docs` → project `shirokuma-docs`). This matches the CLI's `getProjectId()` lookup which searches by repository name.
+- Use `TodoWrite` for progress tracking (7+ steps)
+- Use `AskUserQuestion` to confirm overwrite when an existing project is found
+- Permission refresh requires interactive mode (user must run manually)
+- Language auto-detected from conversation (Japanese or English)
+- For AI development, Size (effort) is more useful than time estimates
+- XL-sized tasks should be split into smaller tasks
+
+## Related Resources
+
+- [scripts/setup-project.py](scripts/setup-project.py) - Setup script with language dictionaries
+- [reference/status-options.md](reference/status-options.md) - Status workflow and definitions
+- [reference/custom-fields.md](reference/custom-fields.md) - Custom field definitions
+- [reference/issue-types.md](reference/issue-types.md) - Issue Types setup and migration guide
+- [reference/labels.md](reference/labels.md) - Label taxonomy and setup guide

package/plugin/shirokuma-skills-en/skills/github-project-setup/reference/custom-fields.md

@@ -0,0 +1,42 @@
+# Custom Fields Reference
+
+## Overview
+
+| Field | Purpose | AI Development Use |
+|-------|---------|-------------------|
+| Priority | Urgency/importance | Task prioritization |
+| Type | Task category | Work classification |
+| Size | Effort estimation | Replaces time estimates |
+
+## Priority
+
+| Value | Color | Purpose |
+|-------|-------|---------|
+| Critical | Red | Urgent, needs immediate attention |
+| High | Orange | Important but not urgent |
+| Medium | Yellow | Normal priority |
+| Low | Gray | When time permits |
+
+## Type
+
+| Value | Color | Purpose |
+|-------|-------|---------|
+| Feature | Green | New functionality |
+| Bug | Red | Bug fix |
+| Chore | Gray | Refactoring, config changes |
+| Docs | Blue | Documentation |
+| Research | Purple | Investigation, PoC |
+
+## Size (AI Development)
+
+Traditional time estimates don't work well for AI-assisted development. Use Size to indicate effort/complexity.
+
+| Value | Color | Guideline |
+|-------|-------|-----------|
+| XS | Gray | Minutes to complete |
+| S | Green | Single session |
+| M | Yellow | Multiple sessions |
+| L | Orange | Full day or more |
+| XL | Red | Needs to be split |
+
+**Rule**: XL tasks must be split into smaller tasks.

package/plugin/shirokuma-skills-en/skills/github-project-setup/reference/issue-types.md

@@ -0,0 +1,85 @@
+# Issue Types Reference
+
+## Overview
+
+GitHub Issue Types are **organization-level** settings that categorize issues across all repositories. They replace the need for custom "Type" fields in Projects.
+
+**Setup URL**: `https://github.com/organizations/{org}/settings/issue-types`
+
+**Requirement**: Organization owner role (for UI setup). `admin:org` OAuth scope required only for API operations.
+
+## Recommended Types
+
+### Default Types (pre-configured)
+
+| Type | Description | Color |
+|------|-------------|-------|
+| Task | A specific piece of work | Default |
+| Bug | An unexpected problem or behavior | Default |
+| Feature | A request, idea, or new functionality | Default |
+
+### Custom Types (add manually)
+
+| Type | Description | Color |
+|------|-------------|-------|
+| Chore | Maintenance, config, tooling, or refactoring | Gray |
+| Docs | Documentation improvements or additions | Blue |
+| Research | Investigation, spike, or exploration | Purple |
+
+## Migration: Project Type Field → Issue Types
+
+If the project currently uses a custom "Type" single-select field, migrate to built-in Issue Types:
+
+### Step 1: Create Issue Types
+
+1. Go to `https://github.com/organizations/{org}/settings/issue-types`
+2. Add Chore, Docs, and Research types (Bug, Feature, Task already exist)
+
+### Step 2: Assign Types to Existing Issues
+
+For each open issue, set the Issue Type to match the current Project Type field value:
+
+```bash
+# List issues with their current Project Type field
+shirokuma-docs issues list
+```
+
+Set Issue Type via the GitHub UI (issue sidebar → Type dropdown) or via API:
+
+```bash
+gh api graphql \
+  -H 'GraphQL-Features: issue_types' \
+  -f query='
+    mutation($issueId: ID!, $typeId: ID!) {
+      updateIssue(input: {id: $issueId, issueTypeId: $typeId}) {
+        issue { number title }
+      }
+    }
+  ' -f issueId="$ISSUE_NODE_ID" -f typeId="$TYPE_ID"
+```
+
+### Step 3: Remove Project Type Field
+
+After all issues have been migrated:
+
+1. Go to Project Settings → Custom Fields
+2. Delete the "Type" single-select field
+3. Update `shirokuma-docs issues` commands if they reference the Project Type field
+
+### Step 4: Update Workflows
+
+Update files that reference the Project "Type" field:
+
+- `.claude/rules/shirokuma/github/project-items.md` — Type field definition
+- `plugin/shirokuma-skills-en/skills/github-project-setup/reference/custom-fields.md` — Type field reference
+- `plugin/shirokuma-skills-en/skills/github-project-setup/scripts/setup-project.py` — Type field creation
+- `plugin/shirokuma-skills-en/skills/github-project-setup/SKILL.md` — Step 6 Type field listing
+
+## Notes
+
+- Issue Types are only available for **organization** repositories, not personal repositories
+- Issue Types are shared across all repositories in the organization
+- Only organization owners can create or modify Issue Types
+- Issue Types appear in the issue sidebar, not in the Project board fields
+- The Project "Type" custom field and Issue Types are separate systems — during migration, both may coexist temporarily
+- GitHub allows up to 25 custom issue types per organization

package/plugin/shirokuma-skills-en/skills/github-project-setup/reference/labels.md

@@ -0,0 +1,86 @@
+# Labels Reference
+
+## Design Principle
+
+Labels and Type fields serve different purposes:
+
+| Mechanism | Role | Axis | Example |
+|-----------|------|------|---------|
+| Type (Project field / Issue Types) | **What** kind of work | Category | Bug, Feature, Chore |
+| Labels | **Where** the work applies | Cross-cutting attribute | area:cli, area:plugin |
+
+Labels should NOT duplicate Type. If a label maps 1:1 to a Type value, delete the label and use Type instead.
+
+## Recommended Label Taxonomy
+
+### Area Labels (required)
+
+Define areas based on the project's module structure. Prefix with `area:`.
+
+| Label | Color | Description |
+|-------|-------|-------------|
+| `area:cli` | `#0e8a16` | Core CLI and commands |
+| `area:plugin` | `#5319e7` | Plugin system (skills, rules, agents) |
+| `area:github` | `#1d76db` | GitHub integration commands |
+| `area:lint` | `#fbca04` | Lint and validation commands |
+
+**Customize for your project**: Replace these with areas that match your codebase structure (e.g., `area:api`, `area:web`, `area:database`).
+
+### Operational Labels (keep from defaults)
+
+| Label | Color | Description |
+|-------|-------|-------------|
+| `duplicate` | `#cfd3d7` | This issue or pull request already exists |
+| `invalid` | `#e4e669` | This doesn't seem right |
+| `wontfix` | `#ffffff` | This will not be worked on |
+
+These serve a lifecycle/triage purpose that Type does not cover.
+
+## Default Labels to Remove
+
+These GitHub default labels overlap with Type or are not applicable:
+
+| Label | Reason to Remove |
+|-------|-----------------|
+| `bug` | Redundant with Type: Bug |
+| `enhancement` | Redundant with Type: Feature |
+| `documentation` | Redundant with Type: Docs |
+| `good first issue` | Not applicable (private repo / AI-assisted) |
+| `help wanted` | Not applicable (private repo / AI-assisted) |
+| `question` | Use Discussions instead |
+
+## Label Assignment Rules
+
+1. **Area labels are optional** - Not every issue needs an area label. Use when the area is not obvious from the title.
+2. **Multiple area labels are allowed** - Cross-cutting issues may span multiple areas (e.g., `area:cli` + `area:github`).
+3. **Operational labels are applied during triage** - `duplicate`, `invalid`, `wontfix` are set when closing or redirecting issues.
+4. **AI should suggest area labels** - When creating issues, suggest an area label if the scope is clear.
+
+## Setup
+
+**Note**: The commands below use `gh label` directly. If `shirokuma-docs` CLI is installed, use `shirokuma-docs repo labels --create` instead for consistency with other GitHub operations.
+
+### Delete Redundant Labels
+
+```bash
+# Remove labels that overlap with Type
+for label in bug enhancement documentation "good first issue" "help wanted" question; do
+  gh label delete "$label" --yes
+done
+```
+
+### Create Area Labels
+
+```bash
+gh label create "area:cli" --color "0e8a16" --description "Core CLI and commands"
+gh label create "area:plugin" --color "5319e7" --description "Plugin system (skills, rules, agents)"
+gh label create "area:github" --color "1d76db" --description "GitHub integration commands"
+gh label create "area:lint" --color "fbca04" --description "Lint and validation commands"
+```
+
+## Notes
+
+- Labels are repository-level settings (unlike Issue Types which are organization-level)
+- Labels appear in issue lists, making them useful for quick visual filtering
+- The `gh label` commands work without special OAuth scopes (standard `repo` scope is sufficient)
+- When migrating from Type-duplicate labels, remove the labels from existing issues first, then delete the label definitions

package/plugin/shirokuma-skills-en/skills/github-project-setup/reference/status-options.md

@@ -0,0 +1,69 @@
+# Status Options Reference
+
+## Workflow Diagram
+
+```mermaid
+graph LR
+    Icebox[Icebox] --> Backlog[Backlog]
+    Backlog --> SpecReview[Spec Review]
+    SpecReview --> Ready[Ready]
+    SpecReview -.->|unclear| Backlog
+    Ready --> InProgress[In Progress]
+    InProgress --> Pending[Pending]
+    Pending -.->|unblocked| InProgress
+    InProgress --> Review[Review]
+    Review --> Testing[Testing]
+    Review -.->|changes requested| InProgress
+    Testing --> Done[Done]
+    Testing -.->|bug found| InProgress
+    Done --> Released[Released]
+    Backlog -.->|not planned| NotPlanned[Not Planned]
+    InProgress -.->|not planned| NotPlanned
+    Pending -.->|not planned| NotPlanned
+```
+
+## Status Definitions
+
+| Status | Color | Purpose | Next Status |
+|--------|-------|---------|-------------|
+| Icebox | Gray | Ideas for future consideration | Backlog |
+| Backlog | Blue | Prioritized work items | Spec Review |
+| Spec Review | Pink | Requirements/specs under review | Ready / Backlog |
+| Ready | Green | Ready to start, dependencies resolved | In Progress |
+| In Progress | Yellow | Actively being worked on (1 per person) | Review / Pending |
+| Pending | Red | Temporarily blocked (reason required) | Original status |
+| Review | Purple | Awaiting PR review | Testing / In Progress |
+| Testing | Orange | QA/testing in progress | Done / In Progress |
+| Done | Green | Completed and merged | Released |
+| Released | Green | Deployed to production | - |
+| Not Planned | Gray | Declined or not needed. Auto-set when Issue is closed with stateReason=NOT_PLANNED. | - |
+
+## Usage Examples
+
+### Icebox
+
+| When to use | Example |
+|-------------|---------|
+| Just thought of an idea | "Want dark mode support" |
+| Future consideration | "Consider for v2.0" |
+| Low priority | "nice-to-have feature" |
+
+### Pending
+
+| When to use | Example |
+|-------------|---------|
+| Waiting for other task/PR | "Waiting for #123 to merge" |
+| Waiting for external response | "Waiting for client confirmation" |
+| Technical blocker | "Reported library bug" |
+
+**Important**: Always document the blocking reason in comments.
+
+### Not Planned
+
+| When to use | Example |
+|-------------|---------|
+| Requirement no longer needed | "No longer needed due to spec change" |
+| Resolved in another issue | "Resolved in #456" |
+| Declined after evaluation | "ROI doesn't justify implementation" |
+
+**Important**: Auto-set when an Issue is closed with `stateReason=NOT_PLANNED`.

package/plugin/shirokuma-skills-en/skills/github-project-setup/scripts/locales/en.json

@@ -0,0 +1,35 @@
+{
+  "status": {
+    "Icebox": "Ideas for future",
+    "Backlog": "To do list",
+    "Spec Review": "Requirements review",
+    "Ready": "Ready to start",
+    "In Progress": "Working on it",
+    "Pending": "Blocked",
+    "Review": "Awaiting review",
+    "Testing": "Testing",
+    "Done": "Completed",
+    "Not Planned": "Explicitly not planned",
+    "Released": "Released"
+  },
+  "priority": {
+    "Critical": "Urgent",
+    "High": "High priority",
+    "Medium": "Normal",
+    "Low": "Low priority"
+  },
+  "type": {
+    "Feature": "New feature",
+    "Bug": "Bug fix",
+    "Chore": "Maintenance",
+    "Docs": "Documentation",
+    "Research": "Research"
+  },
+  "size": {
+    "XS": "Minutes",
+    "S": "Single session",
+    "M": "Multiple sessions",
+    "L": "Full day+",
+    "XL": "Split needed"
+  }
+}

package/plugin/shirokuma-skills-en/skills/github-project-setup/scripts/locales/ja.json

@@ -0,0 +1,35 @@
+{
+  "status": {
+    "Icebox": "アイデア・将来検討",
+    "Backlog": "やることリスト",
+    "Spec Review": "要件・仕様確認中",
+    "Ready": "着手可能",
+    "In Progress": "作業中",
+    "Pending": "一時保留・ブロック中",
+    "Review": "レビュー待ち",
+    "Testing": "テスト中",
+    "Done": "完了",
+    "Not Planned": "見送り・対応不要",
+    "Released": "リリース済み"
+  },
+  "priority": {
+    "Critical": "緊急・最優先",
+    "High": "高優先度",
+    "Medium": "通常",
+    "Low": "低優先度"
+  },
+  "type": {
+    "Feature": "新機能",
+    "Bug": "バグ修正",
+    "Chore": "雑務・リファクタ",
+    "Docs": "ドキュメント",
+    "Research": "調査・検証"
+  },
+  "size": {
+    "XS": "数分で完了",
+    "S": "1セッションで完了",
+    "M": "複数セッション",
+    "L": "1日以上",
+    "XL": "分割が必要"
+  }
+}