Ghpm Shared

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/.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 # "" (started 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](../ghpm-init/SKILL.md) | Initialize config from GitHub Projects v2 | | [ghpm-status](../ghpm-status/SKILL.md) | Project health dashboard | | [ghpm-view](../ghpm-view/SKILL.md) | Query items by view or ad-hoc filter | | [ghpm-suggest](../ghpm-suggest/SKILL.md) | Context-aware work recommendations | | [ghpm-work](../ghpm-work/SKILL.md) | Start a work session on an issue | | [ghpm-issue](../ghpm-issue/SKILL.md) | File an issue and add to project |

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: jackchuka
• Source: jackchuka/ghpm
• License: MIT

Install and usage instructions live in the source repository linked above.