RobinNorberg/omc-gh-project

OMC GitHub Project

Manage GitHub Projects (v2) boards for the current repository. Lists project items, updates card statuses, manages iterations, and adds issues or PRs to projects.

When this skill is invoked, immediately execute the workflow below. Do not only restate or summarize these instructions back to the user.

Trigger Patterns

• "gh project"
• "github project"
• "project board"
• "manage board"
• "project status"
• "omc-gh-project"

---

Step 1: Load Configuration

Read .omcp/config.json:

cat .omcp/config.json 2>/dev/null || echo "NOT_FOUND"

Extract from the github key:

• owner — GitHub owner (org or user)
• repo — repository name

If config is NOT_FOUND or missing the github key: tell the user to run /oh-my-copilot:omc-gh-setup first and stop.

---

Step 2: Discover Projects

List all projects accessible to the owner.

gh project list --owner {owner} --format json --limit 10 2>&1

Present the projects:

### GitHub Projects ({N})
| # | Title | Items | Status |
|---|-------|-------|--------|
| 1 | Sprint Board | 24 | Open |
| 2 | Roadmap | 12 | Open |

If no projects are found, report "No projects found for {owner}. Create one at https://github.com/orgs/{owner}/projects or https://github.com/users/{owner}/projects."

---

Step 3: List Project Items

Prompt the user to select a project, or accept a project number directly.

gh project item-list {projectNumber} --owner {owner} --format json --limit 50 2>&1

Present the items grouped by status:

### Project: {projectTitle}

#### Todo ({N})
| Type | # | Title | Assignees |
|------|---|-------|-----------|
| Issue | #42 | Fix login timeout | alice |
| Draft | — | Research caching options | — |

#### In Progress ({N})
| Type | # | Title | Assignees |
|------|---|-------|-----------|
| PR | #38 | Add retry logic | bob |

#### Done ({N})
| Type | # | Title | Completed |
|------|---|-------|-----------|
| Issue | #35 | Set up CI | 2026-03-28 |

---

Step 4: Update Item Status

Move an item between status columns.

4a. Get the project and field IDs

gh project field-list {projectNumber} --owner {owner} --format json 2>&1

Find the Status field and its available options (e.g. Todo, In Progress, Done).

4b. Update the item status

gh project item-edit --project-id {projectId} --id {itemId} --field-id {statusFieldId} --single-select-option-id {optionId} 2>&1

Confirm:

Moved #{issueNumber} "{title}" → {newStatus}

---

Step 5: Assign to Iteration (Optional)

If the project uses iteration fields (sprint-like cycles):

5a. List available iterations

gh project field-list {projectNumber} --owner {owner} --format json 2>&1

Find the Iteration field and its available iterations.

5b. Assign item to iteration

gh project item-edit --project-id {projectId} --id {itemId} --field-id {iterationFieldId} --iteration-id {iterationId} 2>&1

Confirm:

Assigned #{issueNumber} "{title}" → {iterationName}

---

Step 6: Add Items to Project

Add an existing issue or PR to the project.

gh project item-add {projectNumber} --owner {owner} --url "https://github.com/{owner}/{repo}/issues/{issueNumber}" 2>&1

Or for a PR:

gh project item-add {projectNumber} --owner {owner} --url "https://github.com/{owner}/{repo}/pull/{prNumber}" 2>&1

Confirm:

Added #{number} "{title}" to project "{projectTitle}"

---

Step 7: Create Draft Item (Optional)

Create a new draft item directly in the project (no backing issue/PR).

gh project item-create {projectNumber} --owner {owner} --title "{title}" --format json 2>&1

Confirm:

Created draft item "{title}" in project "{projectTitle}"

---

Limitations

GitHub Projects v2 CLI support is still evolving. Known limitations:

| Operation | CLI Support | Workaround | |-----------|------------|------------| | List items | Full | — | | Update status field | Full | — | | Update iteration field | Full | — | | Custom field updates | Partial | Use gh api graphql for complex field types | | Capacity tracking | Not available | GitHub Projects has no built-in capacity tracking | | Velocity/burndown | Not available | Use project insights in the web UI | | Create project | Not via gh project | Use web UI or gh api graphql |

For operations not supported by gh project, use the GraphQL API:

gh api graphql -f query='
  mutation {
    updateProjectV2ItemFieldValue(
      input: {
        projectId: "{projectId}"
        itemId: "{itemId}"
        fieldId: "{fieldId}"
        value: { text: "{value}" }
      }
    ) {
      projectV2Item { id }
    }
  }
' 2>&1

---

Error Handling

| Error | Action | |-------|--------| | .omcp/config.json missing | Tell user to run /oh-my-copilot:omc-gh-setup first | | gh auth required | Prompt user to authenticate; stop execution | | No projects found | Suggest creating a project in the web UI | | Project item not found | Verify item ID; it may have been removed | | Field update fails | May require project scope; suggest gh auth refresh -s project | | GraphQL errors | Check query syntax; GitHub Projects v2 API is in active development | | Rate limit / 403 | Wait 2 seconds and retry once; if still failing, note as unavailable |