gh-project-orchestrator · diff
git:20261020.b8d18ad to git:20261020.f79b691
132 added, 4 removed. Audit A to A.
---
name: gh-project-orchestrator
description: |
Use when creating, managing, or linking GitHub Projects (V2) to issues, PRs, and
large integration workflows. Triggers on requests like "manage projects",
"create project for integration", "link issue to project", or "orchestrate
project workflow". Coordinates with issue-to-pr and pr-manager for complete
integration tracking.
---
# GitHub Project Orchestrator
Manage GitHub Projects V2 to track large integrations, coordinate multi-PR work, and maintain visibility across the development lifecycle.
## Overview
**Purpose**: Create structured project boards that link issues, PRs, and tasks for complex multi-step work.
## When to Use
Use this skill when:
- Creating new projects for large integrations
- Adding/linking issues and PRs to projects
- Tracking progress through custom fields
- Maintaining bidirectional links between projects, issues, and PRs
- Automating project status updates based on PR/issue state
- Orchestrating complex multi-step work
## Commands
### 1. List Projects
```
@gh-project-orchestrator List all projects
```
### 2. Create Project for Integration
```
@gh-project-orchestrator Create project for "Integration Name"
```
### 3. Add Items to Project
```
@gh-project-orchestrator Add issues #42, #43 to project "Integration Name"
@gh-project-orchestrator Link PR #123 to project "Integration Name"
```
### 4. Update Item Status
```
@gh-project-orchestrator Set project item #42 to "In Progress"
```
### 5. Setup Complete Integration
```
@gh-project-orchestrator Setup complete project for integration "Google Calendar"
```
**Creates**: Project + Epic issue + 6 sub-tasks + Cross-links
### 6. View Project Status
```
@gh-project-orchestrator Show status for project "Integration Name"
```
## Project Structure
### Standard Integration Project
| Component | Purpose |
|-----------|---------|
| **Project Board** | GitHub Project V2 with Status field |
| **Epic Issue** | Master tracking issue with full scope |
| **Sub-Tasks** | Draft items (6-10 tasks) |
| **Cross-Links** | Bidirectional references |
### Default Task Template
1. Setup/Configuration
2. Core Implementation (3-5 tasks)
3. Testing
4. Documentation
## Examples
### Example 1: Create Integration Project
```
@gh-project-orchestrator Setup integration for "Stripe Payment"
Output:
✅ Project Created Successfully
Project: #7 - Stripe Payment Integration
URL: https://github.com/OWNER/REPO/projects/7
📄 Epic Issue: #500
Scope: API integration, Auth flow, Data sync, Error handling, Documentation
✅ Tasks Created: 6
- Setup API credentials
- Implement payment intent
- Add webhook handlers
- Create payment UI
- Add error handling
- Write documentation
🔗 Cross-References: Epic ↔ Project ✓
```
### Example 2: Link PRs to Project
```
@gh-project-orchestrator Link all payment PRs to project "Stripe Payment"
Actions:
1. Found project #7: Stripe Payment Integration
2. Discovered 3 payment-related PRs: #234, #235, #236
3. Added all 3 PRs to project
4. Updated epic issue #500 with PR list
Output: "✅ 3 PRs linked to Project #7 and Epic #500"
```
### Example 3: Project Status Dashboard
```
@gh-project-orchestrator Show status for "Stripe Payment"
Output:
📊 Project Status: Stripe Payment Integration
Items: 8 total
┌──────────────┬──────────────────────────────┐
│ Status │ Count │ Items │
├──────────────┼───────┼────────────────────┤
│ Todo │ 3 │ Setup, Auth, Core │
│ In Progress │ 2 │ Sync, Webhook │
│ Review │ 1 │ PR #234 │
│ Done │ 2 │ Planning, Config │
└──────────────┴───────┴────────────────────┘
Progress: 25% (2/8 items complete)
```
## Authentication
**Required Scopes**: `read:project`, `write:project`
```bash
# Check auth status
gh auth status
# Re-authenticate with project scopes
gh auth login --scopes "repo,read:project,write:project"
```
## Best Practices
1. **One Project Per Integration** - Keep large integrations isolated
2. **Always Create Epic** - Master tracking issue with full scope
3. **Granular Tasks** - Break down into 1-2 day tasks
4. **Link Everything** - Every issue/PR should be in a project
5. **Update Status** - Move items through workflow as they progress
6. **Auto-Route PRs** - Use keywords to automatically link PRs to projects
## Integration
**Called by**:
- issue-to-pr (when creating integration epics)
- pr-manager (for batch PR operations)
- pr-opener (when creating PRs for integrations)
- User (manual project management)
**Calls to**:
- GitHub GraphQL API (for Projects V2)
- GitHub CLI (gh project, gh pr, gh issue)
**Coordinates with**:
- issue-to-pr (creates epic + project together)
- pr-manager (manages multiple project PRs)
- gh-prioritizer (sets priority on project items)
+ ## Project V2 GraphQL queries
+
+ Use `gh api graphql` for everything the `gh project` CLI does not cover (creating projects, setting field values, reading raw items). The `gh project` CLI requires `--owner`; the GraphQL API requires IDs.
+
+ ### Resolve owner, repo and project IDs
+
+ ```bash
+ # Owner (user) ID
+ gh api graphql -f query='
+ query($login:String!){ user(login:$login){ id login } }' \
+ -F login="<owner>" --jq '.data.user.id'
+
+ # Owner (organization) ID
+ gh api graphql -f query='
+ query($login:String!){ organization(login:$login){ id login } }' \
+ -F login="<owner>" --jq '.data.organization.id'
+
+ # Repository ID
+ gh api graphql -f query='
+ query($owner:String!,$name:String!){ repository(owner:$owner,name:$name){ id nameWithOwner } }' \
+ -F owner="<owner>" -F name="<repo>" --jq '.data.repository.id'
+ ```
+
+ ### Create a project (owner + repo + title)
+
+ ```bash
+ gh api graphql -f query='
+ mutation($ownerId: ID!, $repoId: ID!, $title: String!) {
+ createProjectV2(input: {ownerId: $ownerId, repositoryId: $repoId, title: $title}) {
+ projectV2 { id number title url }
+ }
+ }' \
+ -F ownerId="<owner-id>" -F repoId="<repo-id>" -F title="<project title>"
+ ```
+
+ Omit `repositoryId` to create a project that is not tied to a repository.
+
+ ### Add an issue or PR to a project
+
+ ```bash
+ # Resolve the content ID of an issue
+ gh api graphql -f query='
+ query($owner:String!,$repo:String!,$number:Int!){
+ repository(owner:$owner,name:$repo){ issue(number:$number){ id } }
+ }' -F owner="<owner>" -F repo="<repo>" -F number=42 \
+ --jq '.data.repository.issue.id'
+
+ # Add it to the project
+ gh api graphql -f query='
+ mutation($projectId: ID!, $contentId: ID!) {
+ addProjectV2ItemById(input: {projectId: $projectId, contentId: $contentId}) {
+ item { id }
+ }
+ }' -F projectId="<project-id>" -F contentId="<content-id>"
+ ```
+
+ ### Set a project field value (e.g. Status)
+
+ ```bash
+ # List fields and their single-select option IDs
+ gh api graphql -f query='
+ query($owner:String!,$number:Int!){
+ organization(login:$owner){
+ projectV2(number:$number){
+ id
+ fields(first:50){
+ nodes{
+ ... on ProjectV2SingleSelectField { id name options { id name } }
+ ... on ProjectV2Field { id name }
+ }
+ }
+ }
+ }
+ }' -F owner="<owner>" -F number=<project-number>
+
+ # Set the field value
+ gh api graphql -f query='
+ mutation($projectId: ID!, $itemId: ID!, $fieldId: ID!, $optionId: String!) {
+ updateProjectV2ItemFieldValue(input: {
+ projectId: $projectId,
+ itemId: $itemId,
+ fieldId: $fieldId,
+ value: {singleSelectOptionId: $optionId}
+ }) {
+ projectV2Item { id }
+ }
+ }' -F projectId="<project-id>" -F itemId="<item-id>" \
+ -F fieldId="<field-id>" -F optionId="<option-id>"
+ ```
+
+ ### List project items
+
+ ```bash
+ gh api graphql -f query='
+ query($owner:String!,$number:Int!){
+ organization(login:$owner){
+ projectV2(number:$number){
+ id
+ title
+ items(first:100){
+ nodes{
+ id
+ type
+ content{
+ ... on Issue { number title }
+ ... on PullRequest { number title }
+ }
+ fieldValues(first:20){
+ nodes{
+ ... on ProjectV2ItemFieldSingleSelectValue { name field { ... on ProjectV2SingleSelectField { name } } }
+ }
+ }
+ }
+ }
+ }
+ }
+ }' -F owner="<owner>" -F number=<project-number>
+ ```
+
+ ### CLI equivalents
+
+ ```bash
+ gh project list --owner "<owner>" --format json
+ gh project item-list <project-number> --owner "<owner>" --format json
+ gh project item-add <project-number> --owner "<owner>" --url "https://github.com/<owner>/<repo>/issues/42"
+ gh project field-list <project-number> --owner "<owner>" --format json
+ gh project field-create <project-number> --owner "<owner>" --name "Status" --data-type "SINGLE_SELECT" --single-select-options "Todo,In Progress,Review,Done"
+ ```
+
## References
- - [Acceptance Criteria](references/acceptance-criteria.md) - Quality standards and ✅/❌ examples
- - [Best Practices](references/best-practices.md) - Project management patterns
- - [GraphQL Queries](references/graphql-queries.md) - Complete GraphQL reference
- - [Workflow Examples](references/workflow-examples.md) - Real-world scenarios
+ - [Acceptance Criteria](references/acceptance-criteria.md) - Project setup, field mapping, and validation scenarios
+ - [Best Practices](references/best-practices.md) - Epic structure, linking rules, common failure modes
+ - [Integration Workflow](references/integration-workflow.md) - End-to-end multi-PR integration flow