Repo Github Gh CLI

GitHub CLI (SoloDevBoard)

Use this skill when the user asks for command-line GitHub operations. Prioritise issue and project-management workflows used by SoloDevBoard.

Tool Selection

• Prefer GitHub MCP tools for issue search, pull requests, labels, and notifications when those tools cover the requested operation.
• Prefer gh for GitHub Projects v2 item operations, field edits, and ad-hoc project inspection because those workflows are not fully covered by MCP in this repository.
• Do not fall back to gh after an MCP failure unless the missing capability or limitation is clear.
• Before mutating project items, confirm authentication state with gh auth status and ensure the token includes the project scope.

Shell Selection

• Default to bash examples for this repository when the current shell is WSL or Linux.
• Do not use PowerShell backtick escaping or Get-Date syntax in WSL bash sessions.
• Use cross-platform commands where possible. For example, prefer gh project view 8 --owner markheydon --web over shell-specific browser launch commands.

Scope

• Issue creation, updates, and triage
• Label taxonomy operations aligned to plan/LABEL_STRATEGY.md
• Pull request status and checks (creation metadata: plan/PULL_REQUEST_POLICY.md)
• CI/CD workflow triggering and monitoring
• Basic project board item operations

Avoid broad, low-value commands (for example gists, codespaces, SSH/GPG key management) unless explicitly requested.

Usage

Label Taxonomy

Always align labels to plan/LABEL_STRATEGY.md groups:

• type/
• priority/
• status/
• area/
• size/

Always apply at least one type/ and one priority/ label on issue creation.

Vetted Command Patterns

# Create an issue with repo taxonomy labels
gh issue create \
	--repo owner/repo \
	--title "[Story] Add OAuth login" \
	--body-file issue.md \
	--label "type/story,priority/high,status/todo,area/infrastructure"

# List open todo issues for a work area
gh issue list \
	--repo owner/repo \
	--state open \
	--label "status/todo,area/dashboard" \
	--limit 50

# Transition issue state labels
gh issue edit 123 \
	--repo owner/repo \
	--remove-label "status/todo" \
	--add-label "status/in-progress"

# Inspect pull request checks
gh pr checks 123 --repo owner/repo

# Add a multi-line issue comment using a body file to preserve real line breaks
gh issue comment 123 \
	--repo owner/repo \
	--body-file comment.md

# Trigger and monitor workflow runs
gh workflow run ci.yml --repo owner/repo --ref main
gh run list --repo owner/repo --workflow ci.yml --limit 10

# Add an issue to a project (requires project permissions)
gh project item-add 5 --owner owner --url https://github.com/owner/repo/issues/123

# === SoloDevBoard Roadmap (Project #8) ===

# List all project items and their current state
gh project item-list 8 --owner markheydon --format json

# Add an issue to the SoloDevBoard Roadmap
gh project item-add 8 --owner markheydon --url https://github.com/markheydon/solo-dev-board/issues/123

# View the roadmap board in the browser
gh project view 8 --owner markheydon --web

# Set a single-select project field on an existing item
gh project item-edit \
	--id "$item_id" \
	--project-id "PVT_kwHOAJefG84BQ6bh" \
	--field-id "PVTSSF_lAHOAJefG84BQ6bhzg-5WGY" \
	--single-select-option-id "df9275ed"

# Set a number field on an existing item
gh project item-edit \
	--id "$item_id" \
	--project-id "PVT_kwHOAJefG84BQ6bh" \
	--field-id "PVTF_lAHOAJefG84BQ6bhzg_Lx34" \
	--number 1

# NOTE: Prefer `gh project item-edit` for project field updates.
# Use raw GraphQL only when `gh project` does not expose the required operation.
# See `.agents/skills/repo-github-project/SKILL.md` for the SoloDevBoard-specific field IDs and queue workflow.

# Capture the project item id from item-add (item-list defaults to 30 items).
item_id=$(gh project item-add 8 --owner markheydon \
	--url https://github.com/markheydon/solo-dev-board/issues/123 \
	--format json --jq .id)

# Look up an existing item without listing the whole board.
gh project item-list 8 --owner markheydon --query 123 --format json --jq '.items[0].id'

Issue hierarchy and blocking

gh issue has no first-class sub-issue or block commands yet (cli/cli#11757, cli/cli#10298). Agents must still set both via API and must not leave them as a GitHub UI chore for the user.

Sub-issues: GitHub MCP sub_issue_write (method: add). sub_issue_id is the issue database id (gh api repos/OWNER/REPO/issues/N --jq .id), not the # number.

Blocking: REST issue dependencies. POST against the blocked issue; issue_id is the blocking issue's database id as a JSON integer (a quoted string returns 422).

# Resolve database ids (not issue numbers).
blocker_id=$(gh api repos/markheydon/solo-dev-board/issues/382 --jq .id)

# Mark #273 as blocked by #382.
gh api -X POST repos/markheydon/solo-dev-board/issues/273/dependencies/blocked_by \
	--input - <<EOF
{"issue_id": ${blocker_id}}
EOF

# HTTP 422 "already been taken" means the link already exists — treat as success.
# List current blockers:
gh api repos/markheydon/solo-dev-board/issues/273/dependencies/blocked_by --jq '.[].number'

The inverse endpoint is .../issues/{number}/dependencies/blocking (this issue blocks others). Prefer blocked_by so the dependent issue is the path parameter.

Safety Rules

• Use --repo owner/repo for multi-repository operations to avoid acting on the wrong repository.
• Prefer gh issue edit/gh pr edit over ad-hoc API mutations for common updates.
• Prefer gh project item-edit over raw gh api graphql mutations for project field updates.
• For multi-line issue or pull request comments, prefer --body-file or a heredoc-backed temp file instead of embedding \n escapes in --body strings.
• For bulk operations, list and review targets first before piping into mutation commands.
• Confirm authentication state with gh auth status before mutating operations.
• In WSL or Linux, keep jq filters in single quotes and avoid PowerShell-specific quoting patterns.

Refer to the GitHub CLI documentation for command details.