Github Mcp Orchestrator

Strict Rules

1. Group related requests into a single epic

   • Don't create multiple epics for a single feature
   • Use descriptive epic titles that capture the outcome

2. Child issues must be small and independently completable

   • Aim for issues that can be completed in 1-3 days
   • If an issue feels too big, break it down further

3. Handle dependencies explicitly

   • Create all issues but do NOT assign agents/copilots when dependencies exist
   • Surface the dependency chain clearly
   • Use "Depends on #123" or "Blocked by #456" language

4. Always include structured metadata

   • Definition of Done
   • Acceptance Criteria
   • Labels (type, area, priority, estimate)
   • T-shirt sizing (xs/s/m/l/xl) is acceptable for estimates

5. Never create duplicate issues

   • Search existing issues first using GitHub MCP tools
   • Reuse or update existing issues if appropriate

6. Respect repo conventions

   • Detect existing labels, milestones, and issue templates
   • Fall back to default taxonomy if none exist (see reference/labeling.md)

Workflow

1. Intake & Clarify Internally

• Parse the user's request
• Identify the core outcome/goal
• Determine scope boundaries
• Make reasonable assumptions (no user questions)

2. Repo Scan

• Search for existing issues that might be related
• Check available labels and milestones
• Identify any existing epics this might belong to

3. Draft Plan

• Design epic structure
• Break down into child issues
• Group by domain (frontend, backend, infra, etc.)
• Identify dependencies
• Assign labels and estimates

4. Create Issues via GitHub MCP

A. Create Epic Issue

const epic = await mcp__github__issue_write({
  method: "create",
  owner: "{owner}",
  repo: "{repo}",
  title: "Add Spotify Playlist Integration",
  body: epicBody, // From templates/epic.md
  labels: ["type:epic", "area:integration", "priority:p1"],
  type: "epic" // If repo supports issue types
})

B. Create Child Issues

for (const task of tasks) {
  const childIssue = await mcp__github__issue_write({
    method: "create",
    owner: "{owner}",
    repo: "{repo}",
    title: task.title,
    body: task.body, // From templates/task.md
    labels: task.labels
  })

  // Link child to parent using sub-issues
  await mcp__github__sub_issue_write({
    method: "add",
    owner: "{owner}",
    repo: "{repo}",
    issue_number: epic.number,
    sub_issue_id: childIssue.id
  })
}

C. Set Priority Order (optional)

// Set execution order for sub-issues
await mcp__github__sub_issue_write({
  method: "reprioritize",
  owner: "{owner}",
  repo: "{repo}",
  issue_number: epic.number,
  sub_issue_id: childIssue.id,
  after_id: previousIssue.id // Place after this issue
})

5. Output Summary

Generate an Issue Map showing:

Epic: #123 Add User Authentication
├─ #124 [database] Create user and session tables (estimate: M)
├─ #125 [backend] Implement auth API endpoints (estimate: S, depends on #124)
├─ #126 [frontend] Build login/register UI (estimate: M)
└─ #127 [frontend] Add protected routes (estimate: L, depends on #125, #126)

Dependencies:
  #125 ← #124
  #127 ← #125, #126

Include direct links to all created issues.

Reference Documentation

• Labeling taxonomy: See reference/labeling.md
• Dependency handling: See reference/dependencies.md
• GitHub MCP operations: See reference/mcp-ops.md
• Epic template: See templates/epic.md
• Task template: See templates/task.md

Output Format

Always conclude with:

1. Summary: Brief description of what was created
2. Issue Map: Tree view showing epic + children + dependencies
3. Direct Links: URLs to all created issues
4. Next Steps: Suggested order of execution (respecting dependencies)