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).
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.
| name | Subissue Orchestration |
|---|---|
| description | 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). |
| version | 0.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-issuelistNativeSubissues(cwd, parentIssue)- List native sub-issuesremoveNativeSubissue(cwd, parentIssue, subissueNumber)- Unlink sub-issuegetParentIssue(cwd, subissueNumber)- Get parent of a sub-issueisNativeSubissuesAvailable(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 existgenerateChecklistMarkdown(subissues)- Create checklist from arrayupdateParentIssueChecklist(cwd, parentIssue, subissues)- Sync checklistaddSubissueToChecklist(cwd, parentIssue, subissue)- Add single itemmarkSubissueComplete(cwd, parentIssue, subissueNumber)- Check off itemsyncSubissueStates(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:
- Task tool spawns subagent →
sync-task-to-subissuecreates subissue - Subagent makes changes →
stacked-pr-subagent-stopcreates PR - PR body includes
Closes #subissueNumber(looked up fromtask-subissues.json) - PR merges → GitHub auto-closes the linked subissue
This provides end-to-end tracking from task → subissue → PR → merge.
Best Practices
- Native sub-issues are preferred when available
- Link subissues with "Parent Issue: #N" in body for compatibility
- Use consistent labeling (epic → task hierarchy)
- Keep subissues focused and atomic
- Let stacked PR workflow handle PR-subissue linking automatically