# gh-projects-workflow

> GitHub Projects v2 workflow (personal account) + `gpw` helper CLI for listing/creating/moving draft issues, issues, and statuses across projects. Use for any GitHub Projects request (ex: list projects, list project items, set status). ALWAYS load this core skill together with exactly one role overlay: `gh-projects-workflow-pm` (backlog mgmt), `gh-projects-workflow-coder` (implementation), or `gh-projects-workflow-reviewer` (review/verification).

- Author: Anton Kuzmenko
- Repository: default-anton/dotfiles
- Version: 20260121203041
- Stars: 18
- Forks: 0
- Last Updated: 2026-02-06
- Source: https://github.com/default-anton/dotfiles
- Web: https://mule.run/skillshub/@@default-anton/dotfiles~gh-projects-workflow:20260121203041

---

---
name: gh-projects-workflow
description: "GitHub Projects v2 workflow (personal account) + `gpw` helper CLI for listing/creating/moving draft issues, issues, and statuses across projects. Use for any GitHub Projects request (ex: list projects, list project items, set status). ALWAYS load this core skill together with exactly one role overlay: `gh-projects-workflow-pm` (backlog mgmt), `gh-projects-workflow-coder` (implementation), or `gh-projects-workflow-reviewer` (review/verification)."
---

# GitHub Projects workflow (core; Projects v2)

## Mandatory: load a role overlay too

This skill defines the shared **model + commands**.

Also load **exactly one** role overlay skill:
- `gh-projects-workflow-pm`
- `gh-projects-workflow-coder`
- `gh-projects-workflow-reviewer`

## Model / invariants

Artifacts:
- **Draft issue**: Project draft item. Not directly actionable.
- **Issue**: GitHub issue (repo). Actionable.

Status field:
- `Todo`
- `In Progress`
- `In Review`
- `Done`

Rules:
- Only **issues** (not draft issues or PRs) may be `In Progress`.
- Every actionable issue body must include spec sections:
  - `## What`
  - `## Why`
  - `## How`
  - `## Verification`

## Requirements

- `gh` authenticated to your **user** account
- `jq`

## CLI

`gpw` lives in `~/.dotfiles/bin` (PATH).

Help:

```bash
gpw help
```

## Command index (what exists)

- Projects / repos
  - `gpw projects list`
  - `gpw repos list [--limit N]`
  - `gpw global ensure` (ensures the `Global` project exists)
  - `gpw project ensure --title TITLE`

- Project items (list)
  - `gpw project items --title TITLE [--status STATUS] [--drafts|--issues|--all] [--json]`
    - default mode: `--all`
    - text output: TSV
      - drafts: `draft<TAB>Status<TAB>ITEM_ID<TAB>Title`
      - issues: `issue<TAB>Status<TAB>OWNER/REPO#N<TAB>Title<TAB>URL`
      - prs: `pr<TAB>Status<TAB>OWNER/REPO#N<TAB>Title<TAB>URL`

- Read item content by `ITEM_ID`
  - `gpw item view --item ITEM_ID` (prints title/body for drafts; url/body for issues/PRs)
  - `gpw item view --item ITEM_ID --json`

- Draft items
  - `gpw draft create  --title TITLE [--body TEXT] [--project TITLE]`
  - `gpw draft convert --item ITEM_ID --repo OWNER/REPO [--project TITLE] [--to-project TITLE] [--delete-from-project]`

- Issues (“tasks”)
  - `gpw task create     --repo OWNER/REPO --title TITLE [--body TEXT] [--project TITLE]`
  - `gpw task view       --repo OWNER/REPO --issue N [--json]` (prints issue body)
  - `gpw task comment    --repo OWNER/REPO --issue N --body TEXT`
  - `gpw task set-status --repo OWNER/REPO --issue N --status "Todo|In Progress|In Review|Done" [--project TITLE]`

- Repo bootstrap
  - `gpw repo create --name NAME [--private|--public] [--with-project|--no-project] [--no-protect]`

- PRs
  - `gpw pr add        --repo OWNER/REPO --pr N [--project TITLE]` (adds existing PR #N to project; does not create PR)
  - `gpw pr view       --repo OWNER/REPO --pr N [--json]` (N = PR number)
  - `gpw pr set-status --repo OWNER/REPO --pr N --status "Todo|In Review|Done" [--project TITLE]` (N = PR number)

## Defaults

- Global project title: `Global` (hard-coded)

## References

- Copy/paste recipes + common flows: [references/commands.md](references/commands.md)
- GraphQL snippets + notes: [references/graphql.md](references/graphql.md)