tomevault-io GitHub Workflow Skill
Mechanics for GitHub Issue and PR operations using gh CLI. Agents decide when to use these
operations and what content to include.
Authentication
All gh commands MUST be run through the authenticated wrapper script:
scripts/workflow/gh.sh <command> [args...]
The wrapper ensures a valid GitHub App token is available (generating and caching as needed), so
there is no session-level token to manage or refresh. If the wrapper exits non-zero before reaching
gh, authentication has failed — abort the operation.
Every gh command shown in this skill must be prefixed with scripts/workflow/gh.sh instead of
bare gh. For example:
# Skill example says:
# gh issue view 1
# You run:
# scripts/workflow/gh.sh issue view 1
Issue Operations
Create
gh issue create --title "<title>" --body "<body>" --label "<label>" --label "<label>" ...
Issue body template: see references/templates.md: Issue Body Template.
Read
gh issue view <number> --json number,title,body,labels,state,assignees,comments
Update
gh issue edit <number> --title "<title>" --body "<body>" --add-label "<label>" --remove-label "<label>"
For mutually exclusive label swaps, remove and add in a single command:
gh issue edit <number> --remove-label "status:in-progress" --add-label "status:review"
Close
gh issue close <number> --reason completed
gh issue close <number> --reason "not planned"
Closing is a GitHub state change -- no status label swap is needed.
Assign
gh issue edit <number> --add-assignee <username>
gh issue edit <number> --remove-assignee <username>
Comment
gh issue comment <number> --body "<comment>"
gh pr comment <number> --body "<comment>"
Comment templates (blocker, escalation): see references/templates.md.
PR Operations
Create
Build title in conventional commit format: <type>(<scope>): <description> Build body with
Closes #<issueNumber>.
gh pr create --head <branch> --base <baseBranch> --title "<title>" --body "<body>"
Add --draft for draft PRs.
Read
Find PR linked to a task issue:
gh pr list --search "Closes #<N>" --json number,title,headRefName,url
View PR metadata:
gh pr view <number> --json number,title,body,state,isDraft,headRefName,baseRefName,files,reviewDecision,statusCheckRollup,reviews
View full diff:
gh pr diff <number>
Update
gh pr ready <number>
gh pr edit <number> --title "<title>" --body "<body>"
Merge
gh pr merge <number> --squash --delete-branch
Use --merge, --squash, or --rebase for merge strategy.
Review
gh pr review <number> --comment --body "<comment>"
All PR reviews use --comment because the workflow operates under a single GitHub App identity, and
GitHub prevents self-review (--approve / --request-changes) on self-authored PRs. The canonical
verdict is the task issue's status label (status:approved or status:needs-changes), not the
GitHub review state.
CI Status
gh pr checks <number> --json name,state,conclusion
Label Management
Label definitions are maintained by docs/specs/workflow/script-label-setup.md.
Rules: see references/labels.md for mutually exclusive categories and valid status transitions.
Key rules:
- Mutually exclusive categories (type, status, priority): exactly one label per category
- Status transitions must follow the valid transition table
- Swap labels atomically:
--remove-label "old" --add-label "new"in one command
Query Patterns
By status
gh issue list --label "task:implement" --label "status:<status>" --state open --limit 100 --json number,title,labels,assignees
By priority
gh issue list --label "task:implement" --label "priority:<level>" --state open --limit 100 --json number,title,labels,assignees
Refinement tasks
gh issue list --label "task:refinement" --state open --limit 100 --json number,title,labels,body
All open tasks
gh issue list --label "task:implement" --state open --limit 100 --json number,title,labels,assignees
By spec reference
gh issue list --state open --search "in:body docs/specs/<name>.md" --limit 100 --json number,title,labels,body
Dependencies
ghCLI on PATH- Authenticated wrapper:
scripts/workflow/gh.sh(spec:docs/specs/workflow/github-cli.md) - Labels created per
docs/specs/workflow/script-label-setup.md - Development protocol:
docs/specs/workflow/workflow.md
Converted and distributed by TomeVault — claim your Tome and manage your conversions.