| name | ghpm-shared |
| description | Shared reference for all ghpm skills — prerequisites, config format, startup sequence, and error handling. |
| compatibility | Requires gh CLI authenticated with read:project and project scopes |
| metadata | {"author":"jackchuka","scope":"generic"} |
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:
- Read
.ghpm/config.json from the current directory. If missing, stop with init guidance (above).
- 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").
- 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
