Document GitHub GraphQL API for sub-issues and dependencies

[jdelfino]

Research and document the exact GitHub CLI / GraphQL API calls for sub-issues and dependency management.

File

Add to .claude/skills/github-issues/SKILL.md (or a separate reference doc linked from AGENTS.md)

What

The gh CLI does not natively support sub-issue creation or blocked-by relationships. Document the GraphQL mutations/queries:

Required operations:

1. Create sub-issue (set parent-child relationship)

   • GraphQL mutation: addSubIssue(issueId, subIssueId)
   • Query: list sub-issues of a parent

2. Add blocked-by / blocking relationship

   • GraphQL mutation: addBlockedBy(issueId, blockingIssueId)
   • Query: list issues blocked by a given issue
   • Query: check if an issue has any open blocking children

3. Query unblocked children

   • Find sub-issues of #N that have no open blocked-by dependencies
   • This is needed by /work to know which children to work on next

Deliverable:

A reference section with exact gh api graphql commands for each operation, tested against the agent-workflow repo.

Why

Multiple tasks (planner, coordinator, reviewers) need these API calls. Documenting them once prevents three sessions doing the same research and arriving at incompatible approaches.

[jdelfino]

Finding from setup: GitHub UI supports no:blocked-by filter to find unblocked issues. This may be available via the search API as well — need to verify if gh issue list or the GraphQL search supports this qualifier. If so, querying for ready children is straightforward:

# Potential approach for finding unblocked children of #N
gh search issues --repo jdelfino/agent-workflow "no:blocked-by parent-issue:#N state:open"

This was an open question during planning — looks like GitHub solved it for us.

[jdelfino]

More filters available in GitHub Issues search:

• no:blocked-by — find unblocked issues (ready work)
• has:blocking — find issues that block something else
• blocking:<issue-id> — find issues blocking a specific issue
• label:epic — filter by label
• These likely work with gh search issues and possibly the GraphQL search API

This set of filters covers all the queries the workflow needs:

1. Find ready children of #N: sub-issues of #N that are open + no:blocked-by
2. Check if #N has blocking children: sub-issues of #N with label blocking
3. Find all epics: label:epic

The GraphQL research task should verify these work programmatically (via gh search issues or GraphQL), not just in the UI.

[jdelfino]

Correction: search filters are UI-only, but GraphQL works.

Tested no:blocked-by, is:blocked, blocking:#N via gh search issues and the REST search API — they all silently ignore the filters and return all issues. These qualifiers only work in the GitHub web UI search bar.

However, the GraphQL API fully exposes the data:

# Find unblocked open children of issue #N
query {
  repository(owner: "...", name: "...") {
    issue(number: N) {
      subIssues(first: 50) {
        nodes {
          number
          title
          state
          blockedBy(first: 1) { totalCount }
        }
      }
    }
  }
}

Filter client-side: state == OPEN && blockedBy.totalCount == 0 → ready work.

Available GraphQL connections on Issue:

• subIssues(first: N) — child issues
• parentIssue — parent issue (if any)
• blockedBy(first: N) — issues blocking this one
• blocking(first: N) — issues this one blocks

This covers all workflow needs. The /work skill should use gh api graphql rather than gh search issues for dependency queries.

[jdelfino]

REST API also exists for dependencies:

GET  /repos/{owner}/{repo}/issues/{N}/dependencies/blocked_by   # what blocks #N
GET  /repos/{owner}/{repo}/issues/{N}/dependencies/blocking      # what #N blocks
POST /repos/{owner}/{repo}/issues/{N}/dependencies/blocked_by    # add blocker
DELETE /repos/{owner}/{repo}/issues/{N}/dependencies/blocked_by/{id}  # remove blocker

Docs: https://docs.github.com/en/rest/issues/issue-dependencies

Recommended approach for the skills:

• Queries (find ready children): GraphQL — single call gets sub-issues with blockedBy counts
• Mutations (add/remove blocking): REST — simpler than GraphQL mutations
• gh CLI: doesn't support --blocked-by flag yet (Add new flags gh issue create --[blocked-by/blocking] and gh issue edit --[add/remove]-[blocked-by/blocking] cli/cli#11757)

Note: the no:blocked-by search filter works in the UI but not via the REST search API. The UI likely translates these to GraphQL internally.

[jdelfino]

Implemented in PR #29