issue-tracker-github

GitHub Issue Tracker

Maps abstract task operations to gh CLI commands. See gh issue --help and gh project --help for full flag details.

Repo Context

Available labels: !gh label list --json name -q '[.[].name] | join(", ")' 2>/dev/null || echo "none"

GitHub Projects: !${CLAUDE_PLUGIN_ROOT}/skills/issue-tracker-github/scripts/gh-repo-projects.sh

Safety Rule: Pull Requests

Never create a pull request without explicit user confirmation. PR creation is a high-impact action that affects shared repository state and triggers notifications for the entire team. Always present the proposed PR title, body, base branch, and head branch to the user and wait for approval before running gh pr create.

Available Scripts

Scripts are in ${CLAUDE_PLUGIN_ROOT}/skills/issue-tracker-github/scripts/:

Script	Purpose
gh-link-sub-issues.sh	Link 1+ issues as sub-issues of a parent (bulk-capable)
gh-list-sub-issues.sh	List sub-issues of a parent via GraphQL
gh-project-set-status.sh	Update a GitHub Projects v2 item status (or custom single-select field)

Quick Reference

Operation	Command Pattern
FETCH_ISSUE	gh issue view <number> --json title,body,state,labels,assignees
LIST_CHILDREN	gh-list-sub-issues.sh <parent> or parse tracking issue body
CREATE_ISSUE	gh issue create --title "..." --body "..." --label "..."
UPDATE_ISSUE	gh issue edit <number> --add-label/--title/--body/--assignee
ADD_DEPENDENCY	Add cross-references to issue bodies (see Dependency Pattern)
QUERY_DEPENDENCY_TREE	Recursively parse cross-references from issue bodies
CLOSE_ISSUE	gh issue close <number>

Two Modes

With GitHub Projects

Check the GitHub Projects line in Repo Context above. If projects are configured, use them for workflow tracking:

# Add issue to project
gh project item-add <project-number> --owner @me --url "$(gh issue view <number> --json url -q .url)"

# Update status via custom field
gh project item-edit --id <item-id> --project-id <project-id> --field-id <status-field-id> --single-select-option-id <option-id>

Projects provide sprint/kanban views. Use project fields for status tracking instead of labels.

Without GitHub Projects

Use tracking issues as parent issue replacements. A tracking issue contains a task list in its body that references child issues:

## Tasks

- [ ] #101 Set up database schema
- [ ] #102 Implement API endpoints
- [x] #100 Write design doc

GitHub renders task list progress automatically. Use labels for grouping (e.g., feature:auth, phase:1).

Single-issue rule: Plans with only a single issue do not require a parent issue. Only create a parent when there are multiple child work items to organize.

Hierarchy Pattern

GitHub supports sub-issues via its GraphQL API (beta). Use this as the primary approach. Fall back to tracking issues for repos where sub-issues are not enabled.

Creating a Parent Issue

A parent issue groups multiple child work items. Create one only when the plan has multiple child issues to organize.

# Create the parent issue (no sub-issue linking needed at this step)
gh issue create --title "Authentication overhaul" --body "Parent issue tracking auth work items." --label "feature:auth"
# Note the returned issue number (e.g., 42) -- use it when linking children below

Primary: Sub-Issues via API

CREATE_ISSUE with parent:

1. Create child issues first (batch all creates before linking):

   gh issue create --title "Set up database schema" --body "..." --label "feature:auth"
   gh issue create --title "Implement API endpoints" --body "..." --label "feature:auth"
   gh issue create --title "Write tests" --body "..." --label "feature:auth"
   

2. Bulk-link all children to the parent in one call:

   ${CLAUDE_PLUGIN_ROOT}/skills/issue-tracker-github/scripts/gh-link-sub-issues.sh <parent-number> <child-1> <child-2> <child-3>
   

   The script resolves node IDs internally and links each child as a sub-issue. It handles errors per-child (skips failures, reports at the end). If the script fails (sub-issues not enabled on this repo), fall back to the Tracking Issues pattern below.

LIST_CHILDREN:

${CLAUDE_PLUGIN_ROOT}/skills/issue-tracker-github/scripts/gh-list-sub-issues.sh <parent-number>

Returns JSON array of {number, title, state} objects.

Efficient Bulk Pattern

When creating a parent issue with many children (e.g., flight-plan creating 5+ work units):

1. Create the parent issue first (no linking yet)
2. Create all child issues with gh issue create (no linking yet)
3. Collect issue numbers from the create output
4. Bulk-link all children in a single script invocation:

   ${CLAUDE_PLUGIN_ROOT}/skills/issue-tracker-github/scripts/gh-link-sub-issues.sh 42 43 44 45 46 47
   

This is more efficient than interleaving creates and links — the script resolves the parent node ID once and reuses it for all children.

Fallback: Tracking Issues

For repos where sub-issues are not enabled, use a tracking issue (parent issue) with a task list in its body:

## Tasks

- [ ] #101 Set up database schema
- [ ] #102 Implement API endpoints
- [x] #100 Write design doc

GitHub renders task list progress automatically. Use labels for grouping (e.g., feature:auth, phase:1).

CREATE_ISSUE with parent (tracking issue fallback):

1. Create the child issue:

   gh issue create --title "Implement login" --body "Details..." --label "feature:auth"
   

2. Append the new issue to the tracking issue's task list:

   gh issue edit <parent-number> --body "$(gh issue view <parent-number> --json body -q .body)
   - [ ] #<new-number> Implement login"
   

LIST_CHILDREN (tracking issue fallback):

Parse the tracking issue body for task list items:

gh issue view <parent-number> --json body -q .body | grep -oE '#[0-9]+'

Then fetch each child: gh issue view <number> --json number,title,state.

Dependency Pattern

GitHub has no native dependency links. Use structured cross-references in issue bodies.

Format:

• blocks type: Add **Blocked by:** #X, #Y to the dependent issue's body
• related type: Add **Related to:** #Z to both issues' bodies

ADD_DEPENDENCY (blocks):

gh issue edit <dependent> --body "**Blocked by:** #<blocker>
$(gh issue view <dependent> --json body -q .body)"

ADD_DEPENDENCY (related):

Add **Related to:** #<other> to both issues' bodies.

Idempotency: Before appending a dependency line, read the current body and check if the reference already exists. This prevents duplicate entries on retry.

QUERY_DEPENDENCY_TREE:

1. Fetch the root issue body
2. Extract **Blocked by:** and **Related to:** references
3. Recursively fetch referenced issues and their cross-references
4. Build adjacency list from collected references

CLI Reference

Run gh issue --help and gh project --help for the full flag reference. This skill documents recommended patterns for Reaper's abstract operations, not the complete CLI surface. Agents may discover and use additional flags beyond what is documented here.