internal-read-gh-issue-projects-relationships

SKILL.md preview

---
name: internal-read-gh-issue-projects-relationships
description: >-
  Read-only: discover repo-scoped GitHub Projects for issue and PR mutation, normative gh shapes for attaching issues and
  pull requests to projects, and issue relationship playbook (body links, duplicates, parent/sub-issues). Callers add
  --repo and owner flags per target; mutations live in internal-write-gh-issue-commands and internal-write-gh-pr-commands.
---

# Internal: Issue projects + relationships (`internal-read-gh-issue-projects-relationships`)

**Read-only.** Consumed by **`@gh-issues`** (plan + mutation summary), **`@gh-pr`** (via **`internal-read-gh-pr-description`** §6.5–6.6), **[`internal-write-gh-issue-commands`](../../../write/gh/issue-commands/SKILL.md)** (normative attach fences), and **[`internal-write-gh-pr-commands`](../../../write/gh/pr-commands/SKILL.md)** (PR **`item-add`**). **No `gh` mutations** in this file.

**Project list shapes** — **[`internal-read-gh-project-list`](../project-list/SKILL.md)** (auth + `gh project list` bases).

**Fork / PR target repo** — resolve **`owner/repo`** for issues the same way **`@gh-issues`** resolves the mutation target (see **[`internal-read-gh-repo-stream`](../repo-stream/SKILL.md)** when the issue is filed on **`$PR_TARGET_REPO`** rather than the fork root). **Project discovery `--owner`** must match the **login that owns the repository** where the issue is created (first segment of **`nameWithOwner`** for that repo).

**Pull requests (`@gh-pr`)** — use the same **`PR_TARGET_REPO`** for **`https://github.com/OWNER/REPO/pull/<N>`** URLs passed to **`gh project item-add --url`**. Run **`item-add` for the PR** after **`gh pr create`** (or **`gh pr edit`**) returns a PR number; then **`item-add` per confirmed issue** URL on that same **`OWNER/REPO`**. Do not substitute the fork’s **`github.com/FORK_OWNER/repo`** host in URLs when issues and PR are tracked on the **upstream** destination unless the issue genuinely lives on the fork.

---

## 1. Auth and capability probes

**`gh issue create`**, **`gh issue edit --add-project`**, **`gh project list`**, and **`gh project item-add`** need the **`project`** scope for project features. **`gh auth status`** shows current scopes.

If a command fails with missing **`project`** (or GraphQL mentions **`read:project`** / **`project`** scope), refresh:

```bash
gh auth refresh -s project
```

**GitHub Enterprise Server** may lack Projects v2 features or ship older **`gh`** flags. When **`gh issue create --help`** does not list **`--project`**, or **`gh project list`** errors with an unsupported API message, **stop** automated attach, record the error in chat, and fall back to **web UI** (Issues + Projects) or an operator-run attach.

---

## 2. Discover projects for the issue target repo

1. Resolve **`TARGET_REPO`** — `owner/repo` passed to **`gh issue create` / `gh issue edit`** (default: current **`gh`** context; else **`--repo owner/repo`**).
2. Load owner login:

```bash
gh repo view --json nameWithOwner --repo owner/repo
```

Use **`owner.login`** from **`gh repo view --json owner,nameWithOwner --repo owner/repo`** when you need the owner object explicitly.

3. List candidate projects for that owner (open projects first; add **`--closed`** only when grooming closed boards):

```bash
gh project list --owner OWNER_LOGIN --limit 50 --format json
```

4. **Choose a project title** for **`--project` / `--add-project`**:
   - **One unambiguous title** in the list → use it in the mutation summary and in **[`internal-write-gh-issue-commands`](../../../write/gh/issue-commands/SKILL.md)** fences.
   - **Several titles match** the user’s intent (or duplicate titles) → **structured AskQuestion** in **`@gh-issues`**: pick one project, **skip** attach for this run, or **abort** until clarified.
   - **No projects** or **`gh project list` fails** after auth → **skip** project attach; state **why** (no boards, scope, or GHE limitation)—not a silent success.

The CLI d

…