Github projects manager

GitHub Projects Manager

Execution layer for GitHub Projects V2 operations. The project-advisor skill handles governance and decision-making; this skill handles the actual CLI and GraphQL commands.

When to use

• Creating issues and adding them to project boards
• Setting or updating custom project fields (Status, Priority, Billing Scope, Approval, Root Cause, Person Days, etc.)
• Batch field transitions (e.g. "set Approval to Submitted on 16 items")
• Querying board state (items by status, field counts, stale items)
• Converting drafts to issues
• Auditing board hygiene — coverage (open issues that never made it onto the board) and reconciliation (board Status disagreeing with the issue's real state / close-reason). See Board Hygiene below.

Loading sequence

1. Identify the target project (from caller context, issue URL, or #number)
2. Read workflow/projects/{slug}.yaml for field values, governance rules, and state mappings
3. If a bound context exists (e.g. workflow/contexts/customer-a.yaml), read project_custom_fields for field-specific overrides and readonly field lists

Issue Creation (3-step atomic)

Every issue creation follows this exact sequence — no shortcuts:

Step 1: gh issue create --repo {org}/{issue_repo} --title --body --label
Step 2: gh project item-add {number} --owner {org} --url {issue_url}
Step 3: Verify — confirm the item appears on the board

After creation, immediately classify with at minimum:

• Status (from project config default)
• All billing fields if the project has them (Billing Scope, Root Cause, Approval)

Connectedness is not optional. An issue that exists but is not on the board is invisible to everyone who works from the board. Step 2 + 3 are mandatory — never gh issue create without adding to the project and confirming it landed. The same applies when you touch an existing issue for this project: if it is not on the board, add it. Periodically verify the whole set with the coverage audit (Board Hygiene below) — orphaned issues are a silent failure mode.

Field Updates

Approach: gh project item-edit (preferred)

For standard project fields, use the gh project item-edit CLI command. This is simpler than GraphQL and works for single-select and number fields:

# Single-select field
gh project item-edit --project-id "$PROJECT_ID" \
  --id "$ITEM_ID" \
  --field-id "$FIELD_ID" \
  --single-select-option-id "$OPTION_ID"

# Number field
gh project item-edit --project-id "$PROJECT_ID" \
  --id "$ITEM_ID" \
  --field-id "$FIELD_ID" \
  --number 0.5

# Text field
gh project item-edit --project-id "$PROJECT_ID" \
  --id "$ITEM_ID" \
  --field-id "$FIELD_ID" \
  --text "E16"

Resolving IDs

Before setting fields, resolve all required IDs:

# Get Project ID from item-add output, or:
PROJECT_ID=$(gh api graphql -f query='
  query($org: String!, $num: Int!) {
    organization(login: $org) {
      projectV2(number: $num) { id }
    }
  }' -f org="$ORG" -F num=$NUM \
  --jq '.data.organization.projectV2.id')

# Get all field IDs + option IDs in one call:
gh project field-list $NUM --owner $ORG --format json \
  | jq -r '.fields[] | "\(.name) | \(.id) | \(.options // [] | map("\(.name)=\(.id)") | join("; "))"'

Cache field IDs for the duration of a run — they don't change between calls within the same session.

Fallback: GraphQL mutations

For complex operations or when gh project item-edit fails, use the GraphQL patterns documented in references/graphql-patterns.md.

Batch Operations

For batch field updates (e.g. transitioning 16 items from Org Internal to Submitted):

1. Resolve field + option IDs once
2. Get all item IDs for the target issues
3. Run updates in parallel (& + wait) — max 10 concurrent
4. Verify all updated items after wait completes
5. Report: Updated N/M items successfully

Board Hygiene (audit + reconcile)

Beyond creating and updating, this skill verifies the board tells the truth. Two read-only checks, both driven by workflow/projects/{slug}.yaml:

• Coverage — open issues in the project's tracked repos that are not on the board (orphans). A per-issue check is projectItems.totalCount == 0.

• Reconciliation — the board Status vs the issue's real state / stateReason. Classify each Status into declined | done | active from the config's status_mapping, then:

  Board class	Issue must be	Mismatch
  declined	CLOSED + NOT_PLANNED	OPEN → close not_planned · CLOSED/COMPLETED → human decides
  done	CLOSED	OPEN → finish or move board off done
  active	OPEN	CLOSED → stale board

Run both with the tested helper (config-first — pass the Status strings from status_mapping, not guesses):

scripts/board-audit.sh --owner "$ORG" --project "$NUM" \
  --declined "<status_mapping.declined>" --done "<status_mapping.done>" \
  --repos "<audit.coverage_repos, comma-joined>"

All four inputs come from workflow/projects/{slug}.yaml — project.org, project.number, status_mapping.declined/done, and the optional audit.coverage_repos list. Nothing board-specific is baked into the skill.

Contradictions are never auto-fixed — "declined but closed as completed" or "closed but board still active" go to the human (board wrong, or issue wrong?). Repair primitives (add-to-board, close as not_planned, change an already-closed issue's reason without reopening, set board Status, archived-repo issues) and the full recipes live in references/board-audit.md.

Bound Context Integration

When called by a coordinator skill (e.g. customer-a-coordinator), the caller provides:

• Project number and org
• Which fields to set and with which values
• A bound context path (e.g. workflow/contexts/customer-a.yaml)

Read project_custom_fields from the bound context for:

• Exact field names and valid options
• Readonly fields (DO NOT WRITE)
• Field naming conventions (e.g. English-only for CustomerA)

Rules

1. Config-first: Always read workflow/projects/{slug}.yaml before any operation. Never hardcode field values, emojis, or status names.
2. Verify after write: Every create or update must be verified.
3. Respect readonly fields: If a field is in project_fields_readonly, never write to it even if the caller requests it.
4. Atomic transitions: Batch updates are all-or-nothing. If one fails, report the failure — don't silently skip.
5. No issue closure without review: Per governance, issues go through "In Review" before "Done" — never skip to Done directly.
6. Connectedness is mandatory: every issue this skill creates or touches for a project must be on that project's board. Orphans are a silent failure — run the coverage audit periodically, not just at create time.
7. Reconcile, don't assume: board Status and issue state must agree (declined↔closed/not_planned, done↔closed, active↔open). Fix the clear direction; route genuine contradictions to the human — never auto-flip a closed issue's meaning or a customer board's Status on a guess.

Error Recovery

Error	Cause	Fix
"Could not resolve to a ProjectV2"	Wrong project number or org	Check workflow/projects/{slug}.yaml
"Resource not accessible"	Token lacks project scope	gh auth refresh -s project
"Field value not found"	Emoji mismatch or typo	Re-read field-list, use exact option name
"Item not found"	Issue not on board yet	Run gh project item-add first
Invalid option ID	Schema drift	Re-fetch gh project field-list
"type String! was provided invalid value"	Digit-only option ID sent with -F (coerced to Int)	Use -f value=$OPTION_ID (string), not -F
Orphans miscounted / wrong	comm fed sort -n (numeric) input	Sort both lists with LC_ALL=C sort (lexical) before comm

Reference

• references/graphql-patterns.md — Full GraphQL mutation and query patterns
• references/board-audit.md — Coverage + reconciliation rules, repair primitives (close-reason change, archived-repo issues), gotchas
• scripts/board-audit.sh — Read-only board-hygiene checker (coverage + reconcile)
• workflow/projects/{slug}.yaml — Per-project field configs
• project-advisor skill — Governance rules and decision framework