# Ghpm Shared

> Shared reference for all ghpm skills — prerequisites, config format, startup sequence, and error handling.

- **Type:** Skill
- **Install:** `agentstack add skill-jackchuka-ghpm-ghpm-shared`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [jackchuka](https://agentstack.voostack.com/s/jackchuka)
- **Installs:** 0
- **Category:** [Developer Tools](https://agentstack.voostack.com/c/developer-tools)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [jackchuka](https://github.com/jackchuka)
- **Source:** https://github.com/jackchuka/ghpm/tree/main/skills/ghpm-shared

## Install

```sh
agentstack add skill-jackchuka-ghpm-ghpm-shared
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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](https://github.com/jackchuka)
- **Source:** [jackchuka/ghpm](https://github.com/jackchuka/ghpm)
- **License:** MIT

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

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-jackchuka-ghpm-ghpm-shared
- Seller: https://agentstack.voostack.com/s/jackchuka
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.