| name | github-cli |
| description | Use the gh CLI for GitHub issues, PRs, comments, checks, and Actions state in this repo (sigilmakes/hades). Use whenever reading or writing GitHub state from an agent session. |
GitHub CLI
Use gh for GitHub work. Prefer structured commands over scraping web pages.
Repo: sigilmakes/hades
Rules
- Use
--repo sigilmakes/hades unless deliberately relying on the current remote.
- Prefer
--json and --jq for reads so output is machine-checkable.
- Use
--body-file for long issue/comment/PR bodies โ don't fight shell quoting.
- Prefer issue comments for progress/reviews/decisions/handoffs. Edit issue
bodies only when the plan/source-of-truth is structurally stale.
- Never merge feature branches to
main. Hades is exploration-only on
branches; PRs are for review, not for landing on main.
- Any GitHub text an agent writes must include:
Written by an agent on behalf of Willow.
Inspect state
gh issue list --repo sigilmakes/hades --state open --limit 20
gh pr list --repo sigilmakes/hades --state open --limit 20
gh pr view <number> --repo sigilmakes/hades --json state,mergeStateStatus,isDraft,baseRefName,headRefName
gh pr checks <number> --repo sigilmakes/hades
gh run list --repo sigilmakes/hades --branch <branch>
gh run view <run-id> --repo sigilmakes/hades --log
Use gh api for fields high-level commands omit:
gh api repos/sigilmakes/hades/issues/<number> --jq '{title, state, body}'
gh api repos/sigilmakes/hades/pulls/<number> --jq '{title, mergeable, rebaseable}'
Create an issue
cat > /tmp/issue-body.md <<'EOF'
...
...
- [ ] ...
---
Written by an agent on behalf of Willow.
EOF
gh issue create --repo sigilmakes/hades --title "type: short title" --body-file /tmp/issue-body.md
Comment on an issue
Comments are timeline records โ progress, reviews, verification, decisions,
blockers, handoffs. Use them over body edits for anything that's new history.
cat > /tmp/comment.md <<'EOF'
- ...
- ...
---
Written by an agent on behalf of Willow.
EOF
gh issue comment <number> --repo sigilmakes/hades --body-file /tmp/comment.md
Create a PR
Hades stacks on feature/integration โ base your PRs there, not main.
git status -sb
git branch --show-current
gh pr list --repo sigilmakes/hades --head "$(git branch --show-current)"
cat > /tmp/pr-body.md <<'EOF'
...
Closes
- `npm run build && npm test` โ expect 229 tests, 0 failures.
- (any feature-specific verification)
- ...
---
Written by an agent on behalf of Willow.
EOF
gh pr create --repo sigilmakes/hades --base feature/integration --title "feat(scope): short title" --body-file /tmp/pr-body.md
Edit existing GitHub text
gh issue view <number> --repo sigilmakes/hades --json body --jq .body > /tmp/body.md
gh issue edit <number> --repo sigilmakes/hades --body-file /tmp/body.md
For comments:
gh api repos/sigilmakes/hades/issues/<issue-number>/comments --jq '.[] | {id, body: .body[0:120]}'
gh api repos/sigilmakes/hades/issues/comments/<comment-id> -X PATCH -f body="$(cat /tmp/comment.md)"
Checks and Actions
gh pr checks <number> --repo sigilmakes/hades
gh run list --repo sigilmakes/hades --branch <branch>
gh run view <run-id> --repo sigilmakes/hades --log
CI exists (.github/workflows/ci.yml): Node 24, npm ci && build && test.
Gotchas
gh pr create --base feature/integration โ the default base is main, which
you must override or the PR targets the wrong base.gh issue edit --body-file replaces the whole body. Fetch first.- Ask before editing a body: "plan change, or just history?" History โ comment.
