subissue-orchestration

Use this skill when the user wants to "create subissue", "break down issue", "split into tasks", "track subtasks", or manage hierarchical GitHub issues. Creates subissues with parent linking using GitHub's native sub-issues API (with markdown fallback).

⭐4stars🔀0forks📁View on GitHub🕐Updated Jan 11, 2026

When & Why to Use This Skill

Subissue Orchestration is a specialized Claude skill designed to streamline GitHub project management by automating the creation and tracking of hierarchical issues. It leverages GitHub's native sub-issues API and markdown fallbacks to help developers break down complex epics into manageable tasks, ensuring seamless progress tracking and automated PR-to-issue coordination.

Use Cases

  • Epic Breakdown: Decompose large-scale features or epics into smaller, actionable sub-issues with native parent-child linking for better visibility.
  • Automated Task Tracking: Generate and synchronize markdown checklists within parent issues to maintain a real-time overview of project progress.
  • PR-Subissue Coordination: Automatically link Pull Requests to specific sub-issues, ensuring tasks are closed and tracked end-to-end upon merging.
  • Bulk Task Creation: Rapidly initialize multiple sub-tasks from a simple list to set up development sprints or feature milestones efficiently.
  • Hierarchical Organization: Manage complex development workflows with up to 8 levels of nesting, integrated directly with GitHub Projects for advanced filtering.
nameSubissue Orchestration
descriptionUse this skill when the user wants to "create subissue", "break down issue", "split into tasks", "track subtasks", or manage hierarchical GitHub issues. Creates subissues with parent linking using GitHub's native sub-issues API (with markdown fallback).
version0.2.0

Subissue Orchestration

Hierarchical issue management using GitHub's native sub-issues API with automatic PR-subissue coordination.

Purpose

Subissue Orchestration enables breaking down large epics or features into smaller, trackable tasks. Uses GitHub's native sub-issues API (GA 2025) for proper parent-child relationships that appear in GitHub's UI and Projects, with markdown checklist fallback for compatibility.

Native Sub-Issues (Primary)

GitHub's native sub-issues provide:

  • Proper parent-child relationships visible in GitHub UI
  • Integration with GitHub Projects (filtering, grouping by parent)
  • Up to 100 sub-issues per parent, 8 levels of nesting
  • Cross-repository support

The sync-task-to-subissue hook automatically links created subissues using the native API.

When to Use

  • Breaking down epics into implementation tasks
  • Creating subtasks from a task list
  • Tracking progress with automated checklists
  • Managing complex feature development with multiple developers

Core Capabilities

Native Sub-Issues API

Utilities from native-subissues.ts:

  • addNativeSubissue(cwd, parentIssue, subissueNumber) - Link as native sub-issue
  • listNativeSubissues(cwd, parentIssue) - List native sub-issues
  • removeNativeSubissue(cwd, parentIssue, subissueNumber) - Unlink sub-issue
  • getParentIssue(cwd, subissueNumber) - Get parent of a sub-issue
  • isNativeSubissuesAvailable(cwd) - Check if API is available

Subissue Creation

Create child issues with native linking:

PARENT=42
TITLE="Implement OAuth integration"

# Create subissue
SUBISSUE=$(gh issue create \
  --title "$TITLE" \
  --label "task" \
  --body "**Parent Issue:** #$PARENT

Implementation details for OAuth integration..." \
  --json number -q .number)

# Link as native sub-issue (preferred)
SUBISSUE_ID=$(gh api repos/{owner}/{repo}/issues/$SUBISSUE --jq '.id')
gh api repos/{owner}/{repo}/issues/$PARENT/sub_issues -X POST -f sub_issue_id=$SUBISSUE_ID

Checklist Management (Fallback)

For repos without native sub-issues, markdown checklists are still supported.

Utilities from subissue-checklist.ts:

  • hasNativeSubissues(cwd, parentIssue) - Check if native sub-issues exist
  • generateChecklistMarkdown(subissues) - Create checklist from array
  • updateParentIssueChecklist(cwd, parentIssue, subissues) - Sync checklist
  • addSubissueToChecklist(cwd, parentIssue, subissue) - Add single item
  • markSubissueComplete(cwd, parentIssue, subissueNumber) - Check off item
  • syncSubissueStates(cwd, parentIssue, subissueNumbers) - Sync all states

Bulk Creation

# Create multiple subissues from list
PARENT=42
TASKS=("OAuth integration" "Email auth" "Password reset" "2FA support")

for task in "${TASKS[@]}"; do
  gh issue create \
    --title "$task" \
    --label "task" \
    --body "**Parent Issue:** #$PARENT" \
    --json number -q .number
done

# Generate and update parent checklist
syncSubissueStates "$PWD" $PARENT

Examples

Create Epic with Subtasks

# Create parent epic
PARENT=$(gh issue create \
  --title "Authentication System" \
  --label "epic" \
  --body "## Subtasks

- [ ] Implement OAuth
- [ ] Implement email auth
- [ ] Add password reset
- [ ] Add 2FA support" \
  --json number -q .number)

# Create subissues
for task in "Implement OAuth" "Implement email auth" "Add password reset" "Add 2FA support"; do
  gh issue create --title "$task" --label "task" --body "**Parent Issue:** #$PARENT"
done

Auto-Sync Checklist

# Mark subissue as complete
gh issue close 43

# Update parent checklist
markSubissueComplete "$PWD" 42 43
# Changes "- [ ] #43 OAuth integration" to "- [x] #43 OAuth integration"

PR-Subissue Coordination

When using stacked PRs with subagents, PRs automatically include Closes #X to close the associated subissue when merged.

Workflow:

  1. Task tool spawns subagent → sync-task-to-subissue creates subissue
  2. Subagent makes changes → stacked-pr-subagent-stop creates PR
  3. PR body includes Closes #subissueNumber (looked up from task-subissues.json)
  4. PR merges → GitHub auto-closes the linked subissue

This provides end-to-end tracking from task → subissue → PR → merge.

Best Practices

  1. Native sub-issues are preferred when available
  2. Link subissues with "Parent Issue: #N" in body for compatibility
  3. Use consistent labeling (epic → task hierarchy)
  4. Keep subissues focused and atomic
  5. Let stacked PR workflow handle PR-subissue linking automatically