| 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:
- Anchors loaded — read
.github/project-ids.json to confirm field IDs are current
- Graph available —
[ -f graphify-out/graph.json ] (rebuild with npm run brain:build if missing)
- 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:
- What was done (with citations to playbook or graph node)
- What was skipped and why
- Any surprises or anomalies
- 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.
