skills/github-issues: Projects V2 reference gaps — project/field creation, singleSelectOptions overwrite semantics, view-creation limits

[surapuramakhil]

Context

The github-issues skill's references/projects.md is an excellent reference for item-level Projects V2 operations. While setting up an org board today (2026-08-16) I hit four gaps, all verified against the live GraphQL schema via introspection before filing.

Gap 1 — Creation-side admin is absent

The reference covers working within an existing project but never how to create the project or its fields:

mutation($o:ID!,$t:String!){
  createProjectV2(input:{ownerId:$o, title:$t}){ projectV2 { id number url } }  # note: payload key is projectV2, not project
}
mutation($p:ID!){
  createProjectV2Field(input:{projectId:$p, name:"Release", dataType:SINGLE_SELECT}){ projectV2Field{ id } }
}

The projectV2 vs project payload-key distinction is exactly the kind of silent validation error agents hit (I did).

Gap 2 — singleSelectOptions overwrite semantics undocumented

From schema introspection on UpdateProjectV2FieldInput.singleSelectOptions: "Empty input is ignored, provided values overwrite existing options, and existing options should be fetched for partial updates."

An agent that calls updateProjectV2Field with one option to "add" it will silently replace the entire option list. This is a data-loss footgun for board seeding.

Gap 3 — createProjectV2View limits

createProjectV2View accepts only name + layout (BOARD_LAYOUT / TABLE_LAYOUT / ROADMAP_LAYOUT). Grouping (groupByFields), sort, filters, and date-axis are read-only via API (also raised in community discussion 153532). Without a warning, agents ship views that look empty/broken until a human opens the UI and applies grouping+filter manually — worth a callout in the reference.

Gap 4 (minor) — addProjectV2ItemById idempotency

The docs mention it, the reference doesn't: re-adding existing content returns the existing item ID (no duplicate). One sentence so seed scripts can be safely re-run.

Proposal

An "Advanced administration" (project/field creation + seeding) section in references/projects.md covering the above. Happy to open the PR if the approach sounds right.