GitHub issue state machine and code integration patterns. Covers state transitions (needs-triage → accepted → in-progress → completed), branch naming (feat/123-desc), PR linking (Closes
Manages GitHub issue lifecycles from triage to completion. Use it when creating branches with issue numbers (feat/123-desc) or linking PRs to auto-close issues (Closes #123).
/plugin marketplace add poindexter12/waypoint/plugin install workflows@waypoint-marketplaceThis skill inherits all available tools. When active, it can use any tool Claude has access to.
State machine for GitHub issues and how they connect to code.
┌─────────────────┐
│ needs-triage │ ← New issue created
└────────┬────────┘
│ triage
┌────────▼────────┐
┌───────────│ accepted │ ← In backlog
│ └────────┬────────┘
│ │ start work
│ ┌────────▼────────┐
│ ┌──────│ in-progress │ ← Active development
│ │ └────────┬────────┘
│ │ │ PR merged
│ │ ┌────────▼────────┐
│ │ │ completed │ ← Issue resolved
│ │ └─────────────────┘
│ │
│ │ blocked
│ │ ┌─────────────────┐
│ └─────►│ blocked │ ← Waiting on dependency
│ └─────────────────┘
│
│ needs-info
│ ┌─────────────────┐
└──────────►│ needs-info │ ← Waiting for clarification
└─────────────────┘
| State | Label | Meaning |
|---|---|---|
| New | needs-triage | Just created, not reviewed |
| Clarification | needs-info | Waiting on reporter |
| Backlog | accepted | Triaged, waiting for work |
| Active | in-progress | Someone is working on it |
| Blocked | blocked | Can't proceed |
| State | Reason | Comment |
|---|---|---|
| Completed | Fixed/implemented | Via PR or manual |
| Duplicate | Same as another | "Duplicate of #N" |
| Won't Fix | Out of scope | Explain why |
| Invalid | Not a real issue | Cannot reproduce |
| Stale | No activity | Auto-closed after warning |
When starting work on issue #123:
feat/123-short-description # feature
fix/123-short-description # bug fix
chore/123-short-description # maintenance
docs/123-short-description # documentation
i18n/locale-code # internationalization (e.g., i18n/zh-CN, i18n/ja-JP)
i18n/123-locale-code # i18n with issue (e.g., i18n/42-es-MX)
Examples:
feat/42-add-dark-modefix/123-login-timeoutchore/99-update-depsi18n/zh-CN - Chinese (Simplified) translationsi18n/42-ja-JP - Japanese translations for issue #42Include issue number in PR title:
feat: add dark mode (#42)
fix: resolve login timeout (#123)
chore: update dependencies (#99)
Use closing keywords in PR body:
| Keyword | Effect |
|---|---|
Closes #123 | Auto-closes when merged |
Fixes #123 | Same as Closes |
Resolves #123 | Same as Closes |
Example PR description:
## Summary
Add dark mode toggle to settings page.
Closes #42
## Changes
- Add theme context
- Create toggle component
- Update color variables
Reference issues without auto-close:
Related to #45
See also #67
Depends on #89
When closing without PR, always comment:
gh issue close 123 --comment "Duplicate of #456"
gh issue close 123 --comment "Closing as won't fix: [reason]"
gh issue close 123 --comment "Cannot reproduce with provided steps. Please reopen with more details if issue persists."
gh issue close 123 --comment "Closing due to inactivity. Please reopen if still relevant."
Issues with no activity for N days (typically 90):
# Find stale issues
gh issue list --search "updated:<$(date -v-90d +%Y-%m-%d)"
stale labelThis issue has been inactive for 90 days.
It will be closed in 30 days if there's no further activity.
Please comment if this is still relevant.
name: Stale Issues
on:
schedule:
- cron: '0 0 * * *'
jobs:
stale:
runs-on: ubuntu-latest
steps:
- uses: actions/stale@v9
with:
stale-issue-message: 'This issue has been inactive for 90 days.'
days-before-stale: 90
days-before-close: 30
stale-issue-label: 'stale'
# Close all issues with label
gh issue list --label "stale" --json number --jq '.[].number' | \
xargs -I {} gh issue close {} --comment "Closing stale issue"
# Add label to all issues matching query
gh issue list --search "is:open label:bug" --json number --jq '.[].number' | \
xargs -I {} gh issue edit {} --add-label "needs-review"
# Move issue to another repo
gh issue transfer 123 owner/other-repo
# Create branch from issue
gh issue develop 123 --checkout
# Or manually
git checkout -b fix/123-description main
gh issue edit 123 --add-label "in-progress"
# Create PR that closes issue
gh pr create --title "fix: resolve issue (#123)" --body "Closes #123"
gh issue edit 123 \
--remove-label "in-progress" \
--add-label "blocked"
gh issue comment 123 --body "Blocked on #456"
Closes #123This skill defines how issues move through states:
needs-triage → Initial state (set by gh-issue-templates)accepted → After triage (applied by gh-wrangler using gh-issue-triage)in-progress → Work started (manual or via branch creation)blocked → Can't proceed (set manually with comment)When starting work on an issue:
# Branch naming from this skill
git checkout -b feat/123-description
# PR creation with linking
gh pr create --title "feat: description (#123)" --body "Closes #123"
gh-issue-templates - Creating well-formatted issuesgh-issue-triage - Labeling and prioritizationgh-wrangler - Interactive lifecycle managementThis skill should be used when the user asks to "create a slash command", "add a command", "write a custom command", "define command arguments", "use command frontmatter", "organize commands", "create command with file references", "interactive command", "use AskUserQuestion in command", or needs guidance on slash command structure, YAML frontmatter fields, dynamic arguments, bash execution in commands, user interaction patterns, or command development best practices for Claude Code.
This skill should be used when the user asks to "create an agent", "add an agent", "write a subagent", "agent frontmatter", "when to use description", "agent examples", "agent tools", "agent colors", "autonomous agent", or needs guidance on agent structure, system prompts, triggering conditions, or agent development best practices for Claude Code plugins.
This skill should be used when the user asks to "create a hook", "add a PreToolUse/PostToolUse/Stop hook", "validate tool use", "implement prompt-based hooks", "use ${CLAUDE_PLUGIN_ROOT}", "set up event-driven automation", "block dangerous commands", or mentions hook events (PreToolUse, PostToolUse, Stop, SubagentStop, SessionStart, SessionEnd, UserPromptSubmit, PreCompact, Notification). Provides comprehensive guidance for creating and implementing Claude Code plugin hooks with focus on advanced prompt-based hooks API.