ghpm — Shared Reference

Prerequisites

• gh CLI installed and authenticated
• Token scopes: read:project, project
• GitHub Projects v2 (not classic projects)

Config Files

All ghpm files live under .ghpm/:

File	Purpose
.ghpm/config.json	Project config (fields, views, repos)
.ghpm/cache.json	Cached project items
.ghpm/sessions/<number>.json	Active work session per issue

The entire .ghpm/ directory is gitignored (project-specific).

If .ghpm/config.json is missing, tell the user to run /ghpm-init first and stop.

Startup Sequence

Every skill that reads project data should follow this sequence:

1. Read .ghpm/config.json from the current directory. If missing, stop with init guidance (above).
2. Load cache following references/cache.md. If the cache is stale or missing, automatically re-fetch — no user prompt needed. If the re-fetch fails (network error, rate limit), fall back to the stale cache if available and note the age inline (e.g., "Using cached data from 2 hours ago").
3. Check for stale sessions: list .ghpm/sessions/*.json. For each session file, read started_at and compare to now. If a session is older than 24 hours, prompt the user:

   Found stale session for #<num> "<title>" (started <N> days ago).
   Wrap up and post journal, or discard?
   

   • Wrap up: follow the wrap-up sequence from ghpm-work (gather git context, post journal, clear session).
   • Discard: delete the session file silently.
   • If the user declines both, leave it and continue — don't block the current skill.

Error Handling

• Auth expired (gh auth status fails): tell the user to run gh auth login and stop.
• Rate limited (HTTP 403 with rate limit message): tell the user to wait and retry later.
• Network error: if cache exists (even stale), offer to use stale cache as fallback.
• Permission denied (HTTP 403/404 on project): tell the user to check token scopes (read:project, project).

Write Operations & Prompts

Skills that modify project items are write operations. Whether to confirm with the user is controlled by prompts config — see references/prompts.md for resolution logic.

Default behavior (no config): always prompt.

Agent Integrations

Optional hooks/rules enhance ghpm-work sessions (auto session context, stale session detection). See references/integrations.md for details. Installed by /ghpm-init when an agent is detected. Without hooks, all skills work via explicit commands.

Skills

Skill	Purpose
ghpm-init	Initialize config from GitHub Projects v2
ghpm-status	Project health dashboard
ghpm-view	Query items by view or ad-hoc filter
ghpm-suggest	Context-aware work recommendations
ghpm-work	Start a work session on an issue