issue-board

Files (8)

• SKILL.md
• gitlab-cli.md · references/
• hierarchy.md · references/
• links.md · references/
• ordering.md · references/
• expected.md · self-test/01-chain-clause-composed/
• manifest.json · self-test/01-chain-clause-composed/
• README.md · self-test/

SKILL.md (first lines)

# Driving GitLab and GitHub Issue Boards

**Check the repo before touching the board.** If `.nwave/` or `docs/feature/` exists, load
`phil:nwave-issue-board` first — it owns what a feature, a slice, and a step each become, and it
sends you back here for the mechanics. Acting from this skill alone in an nWave repo mints the
wrong objects: an issue per step instead of per slice, and no feature parent to hang them on.

Both forges are driven from the command line: `glab` for GitLab, `gh` for GitHub. Prefer the CLI
over an MCP server — the commands are auditable in the transcript, credentials stay in each tool's
own store, and no extra configuration is needed.

Check `gh --version` and `glab --version` against the latest upstream release before trusting board
behavior. Some distribution channels lag badly — Ubuntu's universe repository shipped `gh` 2.46
against upstream 2.97 — while vendor channels (GitHub's own apt repo, Homebrew, winget, dnf) track
releases. An upstream release tarball drops a single binary into `~/.local/bin` with no sudo.

## Always name the target repository

```sh
glab issue update 12 -R group/project --label 'status::in-progress' --unlabel 'status::to-do'
gh issue edit 12 -R owner/repo --add-label needs-review
```

Both tools infer the project from the current directory's git remote. Issue #12 exists in every
project, so running from the wrong directory mutates a different project's issue — successfully,
with no error. Pass `-R` on every invocation.

## Find the tier before choosing a convention

Two of GitLab's board mechanisms are gated behind Premium, and both fail silently on Free rather
than erroring. Establish the tier first.

```sh
glab api "groups/<group>/epics"   # 200 → Premium+ · 403 → Free · 404 → path wrong OR invisible to the token · 401 → not authenticated
```

Only the 200 case is observed (against an 18.9.1-ee instance); the rest are inferred from GitLab's
documented tier gating. Treat 404 with care — GitLab returns it for a group the token cannot see as
well as for one that does not exist, so it is not proof the path is wrong.

Epics need a real group; a project in a personal namespace has none, so the probe is unavailable
there. **Assume Free in that case** and keep `--unlabel` mandatory — the cost of being wrong that
way is a redundant flag, and the cost of the other way is cards in two columns. Do not substitute
`/api/v4/version` — `"enterprise": true` reports the EE *package*, not a paid subscription, and
reading it as a tier signal is wrong.

## GitLab boards are label views, not a status field

A board column is backed by a label, so moving a card means *swapping the label*. Never create a
board list to move a card: that reports success, adds an unwanted column, and leaves the card
exactly where it was. Board lists are created once, at setup; day-to-day work only touches labels.

**Scoped labels (`key::value`) require Premium or Ultimate.** On Premium and above, adding
`status::in-progress` makes GitLab drop the sibling `status::to-do` server-side. On **Free**, colons
carry no meaning — nothing enforces exclusion, so every move must remove the old label explicitly
and a missed `--unlabel` leaves the card in two columns at once. Keep `--unlabel` in every command:
mandatory on Free, belt-and-braces on Premium.

Confirm `--label` / `--unlabel` against `glab issue update --help` on your version; flag names drift
across major releases.

A label swap moves the card between columns and says nothing about where it lands inside one. See
*A column is a queue, so its order is a claim*, in `references/ordering.md`, for the position, which is a separate write.

## GitHub does not work the same way

GitHub has **no scoped labels and no label-based mutual exclusion**. Do not port the `status::`
convention across.

- **Issues** carry labels, assignees, and milestones, and are open or closed.
- A **board** is a Projects v2 board, where status is a project *field*, not a label — a separate
  API from Issues.

A card move on GitHub is three steps, not one:

1. `gh project item-add` — once, to make the issue a project item. An issue that was never added
   has no field to set, so editing it does nothing.

   **Create and add in the same breath.** An issue created with `gh issue create` is *not* a project
   item, so it has no Status and is **invisible in any kanban grouped by Status**, and a grooming scan
   reports the board clean while the card sits outside it. Wound: two hand-made cards, found only when a
   ranking run counted ten issues against eight board items (2026-08-14).

   Read Status back after adding rather than assuming it is empty. On a project with an
   add-to-project workflow enabled, `item-add` lands the card in the workflow's column — observed as
   `Todo` on `pmvanev/phil-claude-plugin` — so "newly added therefore unset" is not safe either way.
2. `gh project item-list` and `gh project field-list` — to resolve the item and field IDs.
3. `gh project item-edit` — which in practice wants node IDs (`--id`, `--field-id`,
   `--project-id`).

`gh auth login`'s default scopes **omit** `project`. Add it only if a board is actually needed:
`gh auth refresh -s project`. If `gh` is authenticated from `GH_TOKEN` or `GITHUB_TOKEN`, `refresh`
is unavailable — reissue the token with the scope instead. Check with `gh auth status`.

If a project needs a list rather than a board, plain issues plus open/closed is enough, and it works
with a repository-scoped token — which a Projects v2 board cannot, because projects are
owner-scoped.

## Position, sub-issue order and milestones

**Before reordering a column, ranking a backlog, reading which card is next, or setting a sub-issue
order or a milestone, read `references/ordering.md` whole.** It holds both forges' position calls, whose anchor parameters point
in opposite directions, and why a milestone is a goal.

## Links and dependencies

**Before writing a link into an issue body, read `references/links.md` whole.** A relative path renders
on both forges and 404s on GitHub.

**Before writing or reading a blocking link or a sub-issue edge, reading a parent's completion count,
or closing an issue that has a parent — setting Done included — read `references/hierarchy.md`
whole.** Each forge offers different link types per tier and counts a parent's children differently,
and a closed child counts as completed whatever the reason it closed.

## Leave a chain when you pivot

Recognizing a blocker mid-work and switching to it — whether the blocker already existed or you
just created it — is the moment the reasoning exists only in your head. Write both ends **before**
starting work on the blocker, not after you finish it.

From pmvanev/phil-claude-plugin, MIT.

More from pmvanev/phil-claude-plugin