gh-project-manage

title	GitHub Project Management
name	gh-project-manage
description	User-invocable front door for managing the OpenDeck Roadmap (GitHub project
version	1.0.0
created	2026-04-24T17:52:03.000Z
lastmod	2026-04-24T17:52:03.000Z

DEPRECATED for core project ops (2026-07-17). Core GitHub Projects operations (create / field / item / view / status / sub-issue) are now provided by the shared, cross-project gh-projects-mcp MCP server + global gh-project-manage skill (canonical: EMBLEM-NLP/gh-projects-mcp). Prefer those for generic work. This repo's OpenDeck-specific scripts stay — the shared MCP has no parity yet for Insights charts, workflow toggling, milestone-date backfill, or sprint/iteration assignment (the parity backlog; see .claude/agents/gh-project-manager.md). Use the local scripts for those four.

Charter

Invoke this skill when you need to interact with the OpenDeck GitHub project (#4). It preflights the project anchors, routes the request to the right playbook, and delegates heavy execution to the gh-project-manager subagent. The skill itself never mutates the project directly — all mutations go through the subagent.

Playbook-first principle. Check knowledge/github/playbooks/ before writing any gh or GraphQL commands from memory. The playbooks encode decisions (label taxonomy, target-version convention, view naming) that aren't derivable from the API docs.

Inputs and Outputs

Inputs:

• Intent (what you want to do — audit, triage, add view, link PR, health check, etc.)
• Optional: issue/PR number to operate on
• Optional: field values to set (priority, area, target, status)

Outputs:

• Subagent hand-off report (what was done, what was skipped, any surprises)
• For audits: 6-point health-check results with action items
• For triage: confirmation of fields set (priority, area, target, status)
• Every recommendation cites the playbook path or graph node that justified it

Pre-flight

Before delegating, verify:

1. Anchors loaded — read .github/project-ids.json to confirm field IDs are current
2. Graph available — [ -f graphify-out/graph.json ] (rebuild with npm run brain:build if missing)
3. gh CLI authenticated — gh auth status returns an active token with project scope

If condition 3 fails: ask the user to run gh auth refresh -s project.

Intent Routing

User intent	Playbook to read first
Health audit / "audit the project"	knowledge/github/playbooks/project-health-audit.md
Add or fix a view	knowledge/github/playbooks/adding-a-view.md
Triage an issue (set fields)	knowledge/github/playbooks/triaging-an-issue.md
Link a PR to an issue	knowledge/github/playbooks/linking-a-pr.md
Break a large issue into sub-issues	knowledge/github/playbooks/sub-issue-hierarchies.md
Choose milestone vs target field	knowledge/github/playbooks/milestone-vs-target-field.md
GraphQL / API question	/graphify query "<question>" → knowledge/github/reference/graphql/

For any intent not listed, run /graphify query "<intent>" to surface the most relevant reference doc before proceeding.

Workflow

Step 1: Pre-flight

Run the three checks above. Do not delegate until all pass.

Step 2: Read the Playbook

Navigate to the playbook matching the user's intent (see routing table). Read it fully before constructing any commands. The playbook's "Known local anchors" section points to the exact script, field ID, or memory note that operationalises it.

Step 3: Delegate to gh-project-manager Subagent

Spawn the subagent with a precise task brief:

Task: [what needs to happen]
Relevant playbook: knowledge/github/playbooks/<file>.md
Project anchors: project #4 (PVT_kwHODNwyZM4BVh2a), repo thisis-romar/opendeck-factory
Field IDs: .github/project-ids.json
Items in scope: [issue/PR numbers if applicable]
Expected output: [what the subagent should return]

The subagent has full tool access (Bash, gh CLI, gh api graphql). It may not merge PRs or push branches without explicit user approval.

Step 4: Receive Report and Verify

The subagent returns:

1. What was done (with citations to playbook or graph node)
2. What was skipped and why
3. Any surprises or anomalies
4. Recommended follow-up actions

For mutations (field updates, issue creation): verify with gh project item-list 4 --owner thisis-romar --format json that the expected field values are set.

Known Fragile Areas

• Primer portal dialogs — Save/Delete/Cancel inside GitHub confirmation dialogs render in #__primerPortalRoot__. See the subagent's gotchas section for the exact Playwright selector.
• GraphQL on Windows — use spawnSync('gh', ['api', 'graphql', '-f', ...]) not execSync. Shell argument splitting breaks multi-word queries.
• View mutations — the API cannot create or modify layout type. Use npm run views:fix (Playwright) when the 5 canonical views need repair.
• Billing banner — a payment-issue banner may appear on the project. Project automations may fail silently. Fixing billing is always out of scope for this skill; surface it in audit output only.

Safety

• Never merge PRs or push branches without explicit user approval.
• Never touch feat/windows-mcp-computer-use or feat/gh-projects-views unless the user explicitly names them.
• Never hardcode credentials, tokens, or project IDs outside .github/project-ids.json.