# GitHub Issues Project Management with Claude Code: Plans, Gates and a Board

> Claude GitHub PMS is an open-source Claude Code plugin that turns GitHub Issues into your project management system, with evidence required before an issue can advance.

*2026-10-19T12:49:02Z*

# GitHub Issues Project Management with Claude Code

If you let Claude Code work on your repos, the work needs somewhere to be tracked. Most teams end up with a second tool that the agent doesn't see and that drifts from what's actually in the code.

Claude GitHub PMS (gh-pms) takes the other route: GitHub Issues project management, driven from Claude Code. It's an open-source Claude Code plugin that uses GitHub's own primitives as the system of record. Plans are milestones, features and bugs are native issue types, status lives on a Projects v2 board, and an issue can't move forward until the evidence for that step is written down.

**The short answer:** install the plugin, run `/gh-pms:gh-init` once per repo, then talk to Claude normally. Requests become issues, issues follow a gated lifecycle, and everything stays visible in the Issues, Milestones and Projects tabs.

![The lifecycle, one gate at a time](/uploads/sites/c345bccc-2d8f-4569-8da0-2b15a05b5151/media/gh-pms-evidence-gated-lifecycle.webp)

## The problem

Most teams use GitHub Issues as a plain backlog. Status is whatever someone typed in the title, "done" can mean "I think it works", and an AI agent working in the repo has no shared definition of either.

Two things go wrong when an agent does the work:

- **Work isn't tracked.** The agent finishes a task, but no issue records what changed or how it was checked.
- **"Done" is a claim.** Nothing asks for proof before the status flips.

## How it works

### Plans become milestones

A request that would produce three or more features becomes a **milestone** plus a tracker issue (`gh-plan`). `gh-breakdown` then creates child **sub-issues**, attaches them to the milestone and adds them to the project board, so the milestone's progress bar moves as they close.

![Plans become milestones](/uploads/sites/c345bccc-2d8f-4569-8da0-2b15a05b5151/media/gh-pms-plan-to-milestones.png)

### Native primitives first

- **Issue Types** (Feature, Bug, Task) are set through GraphQL when your organization has them. On user accounts or orgs without them, the plugin falls back to `type:*` labels.
- **Status** lives in a Projects v2 `Status` field when a project is attached, otherwise in `status:*` labels. Both are updated together.
- **Severity** (critical, high, medium, low) is available on every issue kind, as a label and a project field.
- **Relationships** (`depends on`, `blocks`, `related to`, `duplicate of`) are written into the issue body and cross-referenced in comments, so they show up in both timelines.

### An evidence-gated lifecycle

Statuses run from `todo` and `in-progress` through testing and docs to `in-review` and `done`. Moving between some of them is free. Others are gates that require an evidence comment with specific `## Sections`, defined in `plugins/gh-pms/workflows/default.yaml`:

| Gate | Moves | Required sections |
|---|---|---|
| 1 | in-progress → ready-for-testing | Summary, Changes (with file paths), Verification |
| 2 | in-testing → ready-for-docs | Summary, Results, Coverage |
| 3 | in-docs → documented | docs evidence (skipped for bugs, hotfixes and testcases) |
| 4 | documented → in-review | Summary, Quality, Checklist, and a PR containing `Closes #N` |
| 5 | in-review → done | your approval |

Bugs get their own Gate 1 sections: Reproduction, Root cause, Fix and Regression test. Only you can pass Gate 5.

A few guardrails sit on top: one in-progress issue per assignee, a 30-second cooldown between gated transitions on the same issue, and a branching policy that refuses feature work on `main`. Gate 4 also refuses to open review while required PR checks are failing or pending.

### What ships in the plugin

- **22 skills**, from `gh-init`, `gh-plan` and `gh-feature` to `gh-push`, `gh-triage`, `gh-metrics` and `gh-test-plan` (counted from `plugins/gh-pms/skills`).
- **4 hooks**: `SessionStart` injects a summary of the current state, `UserPromptSubmit` classifies the prompt, `PreToolUse` blocks a PR without `Closes #N`, and `Stop` flags stale in-progress issues.
- **One orchestrator agent** for multi-issue coordination.
- **Per-repo config** in `.github/gh-pms.yaml`, so you can change severities, gate sections or the branch template without forking the plugin.

## Getting started

```bash
# Add the marketplace (one-time)
/plugin marketplace add fadymondy/gh-pms

# Install the plugin
/plugin install gh-pms@gh-pms
```

You need the GitHub MCP configured in Claude Code, the `gh` CLI, and `jq`. For Projects v2 also run `gh auth refresh -s project`.

Then, in any GitHub repo:

```bash
/gh-pms:gh-init                  # labels + templates only
/gh-pms:gh-init --with-project   # also create the gh-pms Projects v2 board
```

From there you just describe the work. "Plan the migration of the auth flow" creates a milestone and sub-issues. "The login page redirects to 404 after 2FA" files a bug with the Bug type and a severity.

## Honest limits

- **It needs GitHub.** There is no other backend.
- **Issue Types are org-level.** On a personal account the plugin uses labels instead.
- **The gate checks structure, not truth.** It confirms the required sections and file paths exist. It can't confirm the tests really passed, which is why Gate 5 is a human decision.
- **Some friction is deliberate.** The cooldown and WIP limit will slow down anyone used to batch-closing issues.

## FAQ

**Do my teammates need to learn a new tool?** No. They keep using Issues, Milestones and the Projects board. The plugin only changes how Claude Code creates and moves the work.

**Does it work without a Projects v2 board?** Yes. Status falls back to `status:*` labels. `gh-init --with-project` adds the board.

**Can I change the gates?** Yes. Override sections, severities or the branch template in `.github/gh-pms.yaml`.

**Is it open source?** Yes, MIT licensed.

**Is it built on ToGO or another framework?** No. It's a Claude Code plugin made of skills, hooks and shell helpers.

## Next steps

- Read why I built it: [Why I built Claude GitHub PMS](https://fadymondy.com/en/blog/why-i-built-claude-github-pms).
- Source and README: [github.com/fadymondy/gh-pms](https://github.com/fadymondy/gh-pms).
- Discuss it on [Product Hunt](https://www.producthunt.com/products/claude-github-pms) (launching 20 October).
- Website: [gh-pms.fadymondy.com](https://gh-pms.fadymondy.com).

---

Source: https://gh-pms.fadymondy.com/en/blog/github-issues-project-management-claude-code