t1k:projects

Field	Value
Module	`github`
Version	`0.7.3`
Effort	`medium`
Tools	—

Keywords: add to project, backlog column, gh project, github project, item-edit, move card, project board, project v2, projectv2, set status on board, single-select

How to invoke

/t1k:projects

TheOneKit GitHub Projects (V2)

Drive GitHub Projects (V2) boards entirely through the gh CLI (gh project ...), falling back to gh api graphql only for the few ProjectV2 operations gh does not expose. No MCP — the GitHub MCP server has no ProjectV2 tools and we intentionally do not add one.

Projects V2 are owned by an org or user (not a repo). All commands take --owner <org-or-user> and a project number (the N in github.com/orgs/<org>/projects/N).

Prerequisite — the `project` token scope

gh project requires the project scope on your token. Verify and refresh once:

gh auth status                 # look for "Token scopes:" — must include 'project' (and 'read:project')
gh auth refresh -s project     # adds the scope if missing (opens browser/device flow)

Without it every gh project call fails with your token has not been granted the required scopes.

Decision table — pick the command

Goal	Command	Reference
Find a project’s number	`gh project list --owner <org>`	`references/discover.md`
Read items / fields	`gh project item-list` / `field-list`	`references/read.md`
Add an existing issue/PR	`gh project item-add`	`references/items.md`
Add a draft note	`gh project item-create`	`references/items.md`
Set a text/number/date field	`gh project item-edit --text/--number/--date`	`references/edit-fields.md`
Move card to a Status column	`gh project item-edit --field-id … --single-select-option-id …`	`references/edit-fields.md`
Set an iteration (sprint)	`gh project item-edit --field-id … --iteration-id …`	`references/edit-fields.md`
Archive / delete an item	`gh project item-archive` / `item-delete`	`references/items.md`
Add/remove a field; link a repo	`gh project field-create` / `link`	`references/structure.md`
Anything `gh` lacks	`gh api graphql`	`references/graphql.md`

The one workflow you must understand — moving a card across columns

The Status column is a single-select field. To set it you need TWO ids that are NOT human-readable — get them from field-list --format json:

The field id of the Status field (PVTSSF_…).
The option id of the target column value, e.g. Done (…).

# 1. Resolve the field id and the option id for the target column
gh project field-list <N> --owner <org> --format json \
  | jq '.fields[] | select(.name=="Status") | {id, options}'

# 2. Resolve the item id (PVTI_…) for the issue/PR
gh project item-list <N> --owner <org> --format json \
  | jq '.items[] | select(.content.number==123) | .id'

# 3. Move the card
gh project item-edit \
  --project-id <PVT_…> \
  --id <PVTI_…> \
  --field-id <PVTSSF_…> \
  --single-select-option-id <option-id>

item-edit requires the project node id (PVT_…), not the number — get it from gh project view <N> --owner <org> --format json | jq .id. Full id-plumbing and a copy-paste resolver script: references/edit-fields.md.

Common recipes

Add every open issue in a repo to a board — references/recipes.md § add-all-open-issues
Set Status=Done when a PR merges — references/recipes.md § status-on-merge
Bulk-move several items — references/recipes.md § bulk-move

Boundary — what this skill does NOT do (SSOT)

This skill is Projects-board-only. It complements, and never duplicates, these core skills:

For…	Use instead
Git operations (commit, push, branch, PR create/merge)	`t1k-git`
Filing skill/agent bugs against a kit repo	`t1k-issue`
Triaging issues / PRs (labeling, prioritizing, processing)	`t1k-triage`
Watching a PR’s CI to green	`t1k-babysit-pr`

Creating or editing the issues/PRs themselves is out of scope — this skill only places them on a board and moves them between columns.

Gotchas

gh project takes the project number; gh api graphql and item-edit --project-id take the node id (PVT_…). Mixing them up is the most common error — see references/edit-fields.md.
--owner is mandatory and is the org or user login, never a repo name.
item-add needs the issue/PR URL, not its number.
A draft created with item-create has no content — it cannot be converted to a real issue via gh; use the web UI or GraphQL.
Org projects may require SSO authorization on the token: gh auth refresh -s project then authorize the org if prompted.