Ghpm

GHPM

Use GitHub as the single source of truth (SSOT) for project work shared by humans and AI agents. This skill handles task intake, triage, issue/project schemas, status updates, handoff logs, and GitHub automation through gh, git, GraphQL, REST, and Actions. Does NOT replace product judgment, private planning, secrets management, or code review.

Security

• Never paste secrets into issues, project fields, PR bodies, workflow logs, or comments.
• Treat public repos as public evidence ledgers; redact customer data and credentials.
• Use least-privilege tokens. For Projects, verify project scope before edits: gh auth status.
• Prefer GH_TOKEN in Actions; do not write PATs to workflow files.
• If a task needs private data, store only a pointer: owner, system, access request, and redacted summary.

Use When

• User asks to manage tasks, status, roadmap, project boards, issue labels, GitHub Projects, or handoff/handover.
• Work spans humans + AI agents and needs durable context between sessions.
• Need convert chat/plans/TODOs into GitHub Issues with evidence, owners, dependencies, status.
• Need chain skills into execution pipelines and report progress from GitHub state.
• Need automate triage/status/comments with GitHub Actions or gh api.

Core Model

Use GitHub primitives deliberately:

Prefer Projects Status for live state. Use labels for taxonomy and search. If no Project exists, use status:* labels as a lightweight fallback.

Workflow

1. Orient repo and auth:

   git remote -v
   gh repo view --json nameWithOwner,defaultBranchRef,owner
   gh auth status
   gh project list --owner OWNER
   gh issue list --state open --limit 50 --json number,title,labels,assignees,updatedAt
   

2. Choose operating mode:

   • Bootstrap: create labels, project fields, templates, automation.
   • Intake: turn request/plan/chat into GitHub issues.
   • Execute: link branch/PR/checks to issues, update status.
   • Handoff: write current state, blockers, commands, next owner.
   • Audit: compare GitHub state against local repo/plans/CI.

3. Load only needed references:

   • references/schema-and-taxonomy.md for labels, fields, issue body contract.
   • references/command-cookbook.md for gh, GraphQL, REST, and Actions snippets.
   • references/skill-pipelines.md for chained workflows with other skills.

4. Update GitHub first, then local artifacts:

   • If a task changes, update issue/project/comment.
   • If code changes, link PR/branch/checks back to the issue.
   • If docs/plans change, put the canonical task state in GitHub and link local files.

5. Report from evidence:

   • Cite issue/PR/project URLs, check names, branch names, timestamps.
   • End with unresolved questions only if GitHub/current repo cannot answer them.

Task Contract

Every task issue should contain:

## Outcome
What done means.

## Context
Relevant repo, branch, files, links, constraints.

## Acceptance Criteria
- [ ] Verifiable condition

## Handoff Log
- YYYY-MM-DD HH:mm TZ - actor: state, evidence, next step.

## Skill Chain
Suggested skills and order, e.g. mk-scout -> mk-plan -> mk-cook -> mk-test -> mk-git -> mk-ship.

Keep the issue body as the contract. Use comments for chronological updates.

Operating Rules

• Use gh first for normal operations; use gh api graphql when Projects fields need precise reads/writes.
• Never silently create broad label taxonomies; inspect existing labels and extend minimally.
• Keep statuses mutually exclusive: one live status only.
• Record blockers as both field/label and comment with owner + unblock condition.
• Prefer issue dependencies/sub-issues when available; otherwise cross-link with Blocked by #N and Blocks #M.
• For AI handoff, include exact commands already run, tests/checks result, touched files, and next safe command.
• For humans, summarize current decision, risk, and what needs approval.

Quick Commands

# Create task
gh issue create --title "feat: add billing webhook retry" \
  --label "type:feature,priority:p1,status:ready,agent:ai-ok" \
  --body-file /tmp/task.md

# Update state
gh issue edit 123 --remove-label status:ready --add-label status:in-progress
gh issue comment 123 --body-file /tmp/handoff.md

# Link branch
gh issue develop 123 --checkout

# Trigger automation
gh workflow run project-triage.yml --ref main -f issue=123

Output Format

When using this skill, return concise evidence-based status:

**GHPM Status**
- Repo: OWNER/REPO
- Project: URL or none
- Issues: #N title [status, owner, priority]
- Actions: workflow/check result
- Handoff: last comment URL, next owner/action

Unresolved questions:
- None