---
name: github-projects
description: >-
  Drive feature work on this app from a GitHub Projects (v2) board: plan each
  feature as a card, move it across columns as it progresses, and let multiple
  agents coordinate by leaving issue COMMENTS + @mentions on the card. Wraps the
  `gh project` CLI (zero deps). Pairs with the github-workflow skill, which owns
  the branch → PR → merge → deploy cycle. Triggers: "plan on the board", "add to
  the project", "move the card", "what's in progress", "hand off to <agent>",
  "comment on the card", "track this feature", "project board".
---

# GitHub Projects board

This skill is the **coordination + tracking** layer for building this app. The
mechanics of resolving a card (branch → commit → PR → merge → deploy, test gates,
filing twreact-ui/korm-js gaps) live in the **github-workflow** skill. The board is
how that work is **planned, made visible, and handed between agents**.

## Model (read once)
- A **board** (Project v2) has columns = the single-select **`Status`** field
  options (e.g. `Todo` · `In Progress` · `In Review` · `Done`).
- A **card** is a real **issue** added to the board — *not* a draft note. Real
  issues carry **comment threads + @mentions**, which is how agents talk. Draft
  items can't be commented on; use them only for scratch ideas.
- **Agent ↔ agent comms = issue comments + @mentions** on the card. The board is
  the shared state; the comment thread is the conversation + handoff log.

## 0. Prereqs
```bash
gh auth status                                   # must be logged in
gh auth refresh -s project                       # Projects needs the `project` scope
REPO=$(gh repo view --json nameWithOwner -q .nameWithOwner)
OWNER=${REPO%/*}                                 # board owner; override if it lives under a different org
```
The recipes below also use `NUM` (the project/board number, from §1) and `ISSUE`
(the card's issue number) — set them per task, e.g. `NUM=1 ISSUE=42`.

## 1. Find or create the board
```bash
gh project list --owner "$OWNER"                                 # find the number (NUM)
gh project create --owner "$OWNER" --title "__APP_NAME__"        # or create one
gh project view  "$NUM" --owner "$OWNER" --web                   # open it
gh project link  "$NUM" --owner "$OWNER" --repo "$REPO"          # link to this repo
```
New boards ship a default `Status` field (`Todo/In Progress/Done`). Inspect/extend:
```bash
gh project field-list   "$NUM" --owner "$OWNER"
gh project field-create "$NUM" --owner "$OWNER" --name "Agent" --data-type TEXT
```

## 2. Plan a feature → card
A feature is an **issue** on the board. Follow the app's "add a feature" happy path
(module registry → schema → model → seed:rbac → page) — see the app-builder skill.
```bash
gh issue create -R "$REPO" --title "<feature>" --label "enhancement" --body "<scope>"
gh project item-add "$NUM" --owner "$OWNER" --url <issue-url>     # add the card
# scratch idea (no comment thread — promote to an issue to actually work it):
gh project item-create "$NUM" --owner "$OWNER" --title "<idea>" --body "<note>"
```
A **missing twreact-ui component** or **korm-js gap** is its own issue on the
*upstream* repo (github-workflow skill) — never a local re-implementation — but you
can still add a card here to track that you're blocked on it.

## 3. Move a card across columns (set `Status`)
`item-edit` needs four IDs. Resolve them with the built-in `--jq`, no external jq:
```bash
TO="In Progress"                                           # target column
PID=$(gh project view       "$NUM" --owner "$OWNER" --format json --jq '.id')
FID=$(gh project field-list "$NUM" --owner "$OWNER" --format json \
        --jq '.fields[] | select(.name=="Status") | .id')
OPT=$(gh project field-list "$NUM" --owner "$OWNER" --format json \
        --jq ".fields[] | select(.name==\"Status\") | .options[] | select(.name==\"$TO\") | .id")
IID=$(gh project item-list  "$NUM" --owner "$OWNER" --format json \
        --jq ".items[] | select(.content.number==$ISSUE) | .id")
gh project item-edit --id "$IID" --field-id "$FID" --project-id "$PID" --single-select-option-id "$OPT"
```
Convention: a card moves `Todo → In Progress` when an agent **claims** it,
`→ In Review` when its PR opens (CI must be green), `→ Done` when the PR merges.

## 4. Agents talk on the card (comments + @mentions)
The card's issue thread is the message bus. Use a parseable prefix so other agents
can scan it; **always @mention** the agent (or human) you're handing to:
```bash
# claim a card (then move it to In Progress):
gh issue comment "$ISSUE" -R "$REPO" --body "🤖 agent-a [CLAIM] taking this — branch feat/$ISSUE-<slug>."
# hand off:
gh issue comment "$ISSUE" -R "$REPO" --body "🤖 agent-a [HANDOFF] @agent-b
- did: module + schema + model + seed:rbac, unit tests green
- next: client page (compose twreact-ui + @api registry; gate with <Can>)
- branch: feat/$ISSUE-<slug>"
# pick up context before you act:
gh issue view "$ISSUE" -R "$REPO" --comments
```
Marker vocabulary (keep it small): `[CLAIM]` · `[HANDOFF]` · `[BLOCKED]` ·
`[QUESTION]` · `[REVIEW]` · `[DONE]`. One claimer per card — if an unresolved
`[CLAIM]` is already there, comment `[QUESTION]` instead of grabbing it.

## 5. Track progress
```bash
gh project item-list "$NUM" --owner "$OWNER"                                # whole board
gh project item-list "$NUM" --owner "$OWNER" --query "is:open -status:Done"     # active work
gh project item-list "$NUM" --owner "$OWNER" --query "status:Blocked"           # what's stuck
```

## Guardrails
- Cards are **issues** (commentable). Don't hand off via draft notes.
- Branch → PR → merge → deploy + test gates + compose-only/upstream-gap rules:
  **github-workflow** skill. This skill only plans, moves, and coordinates.
- One card → one claimer → one branch → one PR. Never commit to `main`.
- Never push secrets. Move a card to `In Review` only with CI green.