{"id":49425324,"url":"https://github.com/fadymondy/gh-pms","last_synced_at":"2026-04-29T09:01:25.296Z","repository":{"id":354530563,"uuid":"1223990134","full_name":"fadymondy/gh-pms","owner":"fadymondy","description":"GitHub Issues as a project-management system for Claude Code — plans, features, bugs, evidence-gated lifecycle, PR-driven review. Backed by GitHub primitives.","archived":false,"fork":false,"pushed_at":"2026-04-28T23:10:28.000Z","size":81,"stargazers_count":0,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-29T01:13:06.435Z","etag":null,"topics":["claude-code","claude-code-plugin","github-issues","orchestra-mcp","pms","project-management","workflow"],"latest_commit_sha":null,"homepage":null,"language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/fadymondy.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":".github/CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":".github/SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"github":["fadymondy"]}},"created_at":"2026-04-28T21:17:01.000Z","updated_at":"2026-04-28T23:10:31.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/fadymondy/gh-pms","commit_stats":null,"previous_names":["fadymondy/gh-pms"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/fadymondy/gh-pms","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fadymondy%2Fgh-pms","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fadymondy%2Fgh-pms/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fadymondy%2Fgh-pms/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fadymondy%2Fgh-pms/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/fadymondy","download_url":"https://codeload.github.com/fadymondy/gh-pms/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fadymondy%2Fgh-pms/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32418173,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-29T06:29:02.080Z","status":"ssl_error","status_checked_at":"2026-04-29T06:29:00.631Z","response_time":110,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["claude-code","claude-code-plugin","github-issues","orchestra-mcp","pms","project-management","workflow"],"created_at":"2026-04-29T09:01:01.431Z","updated_at":"2026-04-29T09:01:25.284Z","avatar_url":"https://github.com/fadymondy.png","language":"Shell","funding_links":["https://github.com/sponsors/fadymondy"],"categories":[],"sub_categories":[],"readme":"# Github PMS Plugin\n\n**GitHub Issues as a project-management system for Claude Code.**\n\nA Claude Code plugin marketplace that turns GitHub Issues into the source of truth for your project: plans, features, bugs, evidence-gated lifecycle, PR-driven review. Inspired by Orchestra MCP and Studio PMS, backed by GitHub's first-class primitives — **Issue Types**, **Projects v2**, **Milestones**, **sub-issues**, and **relationships** — not just labels.\n\n## Why\n\nMost teams use GitHub Issues as a dumb backlog. `gh-pms` adds the structure that real project management needs:\n\n- **Plans** = Milestones with due dates and native progress bars\n- **Features / Bugs** use GitHub's native **Issue Types** when available, fall back to labels otherwise\n- **Status** tracked in a Projects v2 board's `Status` field (when configured) or `status:*` labels\n- **Sub-issues** for plan → feature breakdown, **dependency relationships** (`depends on`, `blocks`, `related to`, `duplicate of`)\n- **Evidence-gated lifecycle** — 5 gates with required `## Sections` (file paths, test results, self-review)\n- **WIP limits**, **cooldowns**, **kind-specific skips** (bugs auto-skip the docs gate)\n- **PR-driven review** — `Closes #N` keyword + `AskUserQuestion` approval + `gh pr merge` closes the loop\n\nEverything lives natively in GitHub. Open the Issues, Milestones, or Projects tab and you see exactly where the project is.\n\n## What's new in v0.8\n\nSee [CHANGELOG.md](CHANGELOG.md#080) for the full list. Highlights:\n\n- gh-test-plan skill — generate testcase sub-issues from acceptance criteria (#17, PR #31)\n- gh-search skill — ad-hoc issue queries beyond gh-status (#16, PR #30)\n- gh-bulk skill — safe batch label / close / reassign / set-severity (#15, PR #29)\n\nSee `CHANGELOG.md` for the full v0.8.0 entry.\n\n### From v0.7: (previous release)\n\nSee [CHANGELOG.md](CHANGELOG.md#070) for the full list. Highlights:\n\n- gh-metrics skill — time-in-status, gate failure rate, throughput (#13, PR #27)\n- Optional AI reviewer on Gate 4 (sub-agent code review before user approval) (#12, PR #26)\n- Wire Effort field end-to-end (gh-feature input + gh-status velocity) (#11, PR #25)\n\nSee `CHANGELOG.md` for the full v0.7.0 entry.\n\n### From v0.6: (previous release)\n\nSee [CHANGELOG.md](CHANGELOG.md#060) for the full list. Highlights:\n\n- gh-triage skill — accept/reject/dedupe the type:request inbox (#8, PR #23)\n- CI gate on Gate 4 — refuse review-ready when checks are red (#7, PR #22)\n- Per-repo config in .github/gh-pms.yaml (#6, PR #21)\n\nSee `CHANGELOG.md` for the full v0.6.0 entry.\n\n### From v0.5: (previous release)\n\nTwo skills that close adoption gaps the v0.4 release made obvious — sessions starting blind to the issue tracker, and releases requiring a manual edit-bump-tag dance.\n\n- **`gh-context`** ✨ — compact session-start summary of WIP, pipeline, milestones, recent closes, deferred requests. Auto-runs via the new `SessionStart` hook so the agent picks up where the last session left off (#9).\n- **`gh-release`** ✨ — bundle PRs merged since the last tag into a structured CHANGELOG entry, bump `plugin.json`, refresh the README banner, tag, and (optionally) create a GitHub release in one shot. Idempotent; refuses without an anchor (#5).\n\nSee [CHANGELOG.md](CHANGELOG.md) for the full list.\n\n### From v0.4: severity first-class\n\nSeverity is now a first-class dimension on **every** issue kind, not just bugs. A P0 feature blocking a launch is meaningfully different from a polish item — that signal was previously lost. Closes #2.\n\n- **Canonical scale** — `workflows/default.yaml#severities` is now the single source of truth (`default: medium` + four values, each mapped to a `severity:*` label and a Project v2 `Severity` field option). Per-repo severity scales become a config-only change.\n- **`gh-feature`** ✨ — accepts an optional `severity` on every kind (not just hotfix). Applied as label + Project field. Hotfixes still default to `critical`.\n- **`gh-task`** — sub-issue tasks inherit the parent feature's severity by default; override when the task is meaningfully more or less urgent. Checkbox tasks inherit implicitly.\n- **`gh-bug`** — references the canonical scale instead of defining its own. Same defaults, no behavior change.\n- **`gh-status`** — within each Status bucket, issues are sorted Critical → Low so urgent items surface first regardless of kind.\n- **Templates** — `feature.md`, `chore.md`, `testcase.md` gain a `## Severity` section. `plan.md` / `prd.md` stay exempt (they aggregate child severities).\n\nBackwards compatible — existing issues without a `severity:*` label remain valid, and skills called without `severity` get `medium`.\n\n### From v0.3: `gh-push` skill + branching policy\n\nThe \"every feature must end with a linked PR\" rule is baked into the lifecycle:\n\n- **`gh-push` skill** — One command to commit, push, open PR with `Closes #N`, post Gate 4 self-review evidence, ask the user to approve, and `gh pr merge`. Mirrors the popular `/push` pattern but PR-aware and lifecycle-integrated. Supports `--message`, `--no-merge`, `--admin`, `--squash` / `--merge` / `--rebase`, `--dry`, `--force`.\n- **Branching policy** — `workflows/default.yaml#branching` defines `protected_base` (default: `main` / `master`), `pr_required_kinds` (feature / bug / hotfix / chore / testcase), `branch_template` (default: `{kind_short}/{number}-{slug}`), and `pr_must_close_issue: true`. The rule is enforced in three places: `gh-current` auto-creates the branch on start, `gh-advance` Gate 1 refuses if HEAD is on the protected base, and `gh-push` refuses to ship from the protected base.\n- **`gh-current`** records `branch` + `base` in the per-issue state file so `gh-push` finds them later. The \"🚧 Work started\" comment mentions the branch name.\n- **`gh-advance`** Gate 1 has a clear rescue-recipe error if work is on the wrong branch. One-off legacy state can opt out with the `[gh-pms: branch-exception]` marker in the issue body.\n\n### From v0.2: GitHub-native primitives\n\n- **Issue Types** (orgs only): `Feature`, `Bug`, `Task` set via GraphQL, not labels — when the org has them enabled\n- **Projects v2** integration: `gh-init --with-project` provisions a `gh-pms` board with `Status`, `Severity`, `Effort`, `Service` custom fields\n- **Milestones for plans**: `gh-plan` creates a milestone; `gh-breakdown` attaches every child via `--milestone`; closes auto-progress\n- **`gh-relate` skill**: encode `depends_on`, `blocks`, `related_to`, `duplicate_of` between issues\n- **Auto-detection**: `gh-init` queries the org for available features and provisions only what's missing; user-account repos gracefully fall back to labels\n- **Unified status setter**: `lib/ghcall.sh set-status \u003cissue\u003e \"\u003cStatus\u003e\"` updates label + project field atomically\n\nSee [CHANGELOG.md](CHANGELOG.md) for the full list.\n\n## Install\n\n```bash\n# Add the marketplace (one-time)\n/plugin marketplace add fadymondy/gh-pms\n\n# Install the plugin\n/plugin install gh-pms@gh-pms\n```\n\nRequires:\n\n- **GitHub MCP** — already configured in Claude Code (auth via OAuth or PAT)\n- **`gh` CLI** — for batch label / project / milestone ops: `brew install gh \u0026\u0026 gh auth login`\n- **`gh` `project` scope** — only if you want Projects v2 integration: `gh auth refresh -s project`\n- **`jq`** — for JSON parsing in hooks: `brew install jq`\n\n## Quick start\n\nIn any GitHub repo:\n\n```bash\n# 1. Bootstrap (creates labels + templates; optionally creates a Project)\n/gh-pms:gh-init                  # labels + templates only\n/gh-pms:gh-init --with-project   # also create the gh-pms Projects v2 board\n\n# 2. From now on, just talk normally — the plugin auto-classifies prompts\n#    and ensures every actionable request becomes an issue.\n```\n\nExamples:\n\n```text\n\"Plan the migration of auth flow to the bridge\"\n  → /gh-pms:gh-plan creates milestone + tracker issue\n  → /gh-pms:gh-breakdown creates feature sub-issues, attaches them to the milestone\n\n\"Add a /entities endpoint that returns sentiment scores\"\n  → /gh-pms:gh-feature creates issue, sets Issue Type \"Feature\" (if org), adds to project\n  → /gh-pms:gh-current sets Status: In Progress\n  → work happens, gates open, PR opens with Closes #N\n  → user approves, PR merges, issue auto-closes\n\n\"Build the launch-blocking SSO refresh — this is P0\"\n  → /gh-pms:gh-feature with severity: critical\n  → severity:critical label + Severity = Critical on the project board\n\n\"The login page redirects to 404 after 2FA\"\n  → /gh-pms:gh-bug creates issue, sets Issue Type \"Bug\", severity:medium\n\n\"#42 depends on #38 and #39\"\n  → /gh-pms:gh-relate updates body sections on all three, posts cross-reference comments\n```\n\n## What gets created in your repo\n\nAfter `gh-init`:\n\n```text\n.github/\n├── ISSUE_TEMPLATE/\n│   ├── feature.md\n│   ├── bug.md\n│   ├── chore.md\n│   ├── plan.md\n│   ├── prd.md\n│   ├── request.md\n│   └── testcase.md\n└── PULL_REQUEST_TEMPLATE.md\n```\n\nLabels (always created — used directly when native features unavailable, otherwise as a visible-at-a-glance secondary signal):\n\n```text\ntype:      feature, bug, hotfix, chore, plan, prd, testcase, request\nstatus:    todo, in-progress, ready-for-testing, in-testing,\n           ready-for-docs, in-docs, documented, in-review, blocked, done\nseverity:  critical, high, medium, low\nsvc:       app, bridge, studio, edge, db, devops\n```\n\nGitHub native (provisioned when available + opted in):\n\n```text\nIssue Types  (org-level): Feature, Bug, Task — set via GraphQL on creation\nProjects v2  (--with-project): gh-pms board with fields Status / Severity / Effort / Service\nMilestones   (always): one per plan, with optional due date + auto-progress\n```\n\n## The lifecycle\n\n```text\n   todo  ──(free)──► in-progress\n                          │\n                       Gate 1   (## Summary, ## Changes [files], ## Verification)\n                          ▼\n                   ready-for-testing  ──(free)──► in-testing\n                                                       │\n                                                    Gate 2   (## Summary, ## Results, ## Coverage)\n                                                       ▼\n                                                ready-for-docs\n                                                       │\n                                                  (free) │  [auto-skip if bug/hotfix/testcase]\n                                                       ▼\n                                                    in-docs ──Gate 3──► documented\n                                                                              │\n                                                                           Gate 4   (## Summary, ## Quality, ## Checklist [files], PR with Closes #N)\n                                                                              ▼\n                                                                         in-review\n                                                                              │\n                                                                           Gate 5   (user approval via AskUserQuestion)\n                                                                              ▼\n                                                                            done\n```\n\n## Skills\n\n| Skill                     | Mirrors                                       |\n| ------------------------- | --------------------------------------------- |\n| `/gh-pms:gh-init`         | (bootstrap)                                   |\n| `/gh-pms:gh-plan`         | `pms_create_plan` (now creates milestone)     |\n| `/gh-pms:gh-breakdown`    | `pms_breakdown_plan` (attaches to milestone)  |\n| `/gh-pms:gh-feature`      | `pms_create_feature` (sets native type)       |\n| `/gh-pms:gh-bug`          | `pms_create_bug_report` (sets native type)    |\n| `/gh-pms:gh-task`         | `pms_create_task`                             |\n| `/gh-pms:gh-current`      | `pms_set_current_feature` (auto-creates feature branch) |\n| `/gh-pms:gh-advance`      | `pms_advance_feature` (Gate 1 refuses from protected base) |\n| `/gh-pms:gh-push` ✨      | (new in v0.3) — commit + push + PR + Gate 4 + Gate 5 in one shot |\n| `/gh-pms:gh-validate`     | `pms_validate_gates`                          |\n| `/gh-pms:gh-review`       | `pms_request_review` + `pms_submit_review`    |\n| `/gh-pms:gh-relate`       | (new in v0.2) — manage issue relationships    |\n| `/gh-pms:gh-request`      | `pms_create_request`                          |\n| `/gh-pms:gh-status`       | `pms_list_features` (reads project board)     |\n| `/gh-pms:gh-context` ✨   | (new in v0.5) — session-start summary         |\n| `/gh-pms:gh-release` ✨   | (new in v0.5) — version bump + tag + release  |\n| `/gh-pms:gh-triage` ✨    | (new in v0.5) — drain the type:request inbox  |\n| `/gh-pms:gh-reopen` ✨    | (new in v0.7) — re-enter a done issue         |\n| `/gh-pms:gh-metrics` ✨   | (new in v0.7) — flow analytics + velocity     |\n| `/gh-pms:gh-bulk` ✨      | (new in v0.8) — safe batch ops                |\n| `/gh-pms:gh-search` ✨    | (new in v0.8) — ad-hoc issue queries          |\n| `/gh-pms:gh-test-plan` ✨ | (new in v0.8) — testcases from acceptance     |\n\n## Hooks\n\n| Event                                       | Behavior                                                                  |\n| ------------------------------------------- | ------------------------------------------------------------------------- |\n| `SessionStart`                              | Injects a `gh-context` summary so the agent isn't blind on a new session  |\n| `UserPromptSubmit`                          | Classifies the prompt, injects a context reminder for the agent           |\n| `PreToolUse` on `mcp__github__create_pull_request` | Blocks PR creation if `Closes #N` is missing from the body         |\n| `Stop`                                      | Surfaces stale in-progress issues at end of turn                          |\n\n## Programmatic guardrails\n\n- **WIP limit** — One in-progress issue per assignee\n- **Gate cooldown** — 30s minimum between transitions on the same issue (prevents fake batch-advancement)\n- **Kind-specific skips** — Bugs/hotfixes/testcases skip Gate 3 (docs)\n- **Branching policy** (v0.3) — Feature work must land on a feature branch, not on `main` / `master`. `gh-current` auto-creates the branch; `gh-advance` Gate 1 refuses from the protected base; `gh-push` refuses to ship from the protected base. Bootstrap commits with no issue number are exempt.\n- **PR enforcement** — Every feature must end with a PR containing `Closes #N` so merge auto-closes the issue. Gate 4 requires it; `gh-push` injects it automatically.\n- **CI gate on Gate 4** (v0.5+) — `documented → in-review` refuses if any required PR check is failing or still pending. `lib/check-pr-checks.sh` is the source of truth. Override only with `--ignore-checks \"\u003creason\u003e\"`, which records the reason in a `## Check overrides` section of the evidence comment for audit.\n- **User-only Gate 5** — Only `gh-push` Step 5 (or `gh-review`'s Phase 2) can move to `done`, and only after `AskUserQuestion` approval\n- **Native primitives preferred** — Issue Types, Project Status field, and Milestones are used when available; labels stay as a fallback and visible-at-a-glance signal\n\n## Configuration\n\nThe plugin's defaults live in [`plugins/gh-pms/workflows/default.yaml`](plugins/gh-pms/workflows/default.yaml). To override per repo, drop a `.github/gh-pms.yaml` in the repo (an annotated example lives at [`plugins/gh-pms/templates/gh-pms.yaml.example`](plugins/gh-pms/templates/gh-pms.yaml.example) — `gh-init --customize` copies it for you).\n\nThe merge is shallow at the top-level key: any section you set in your override **replaces** its default counterpart wholesale. To extend a list, copy the defaults into your override and add yours.\n\nInspect the merged result anytime:\n\n```bash\n${CLAUDE_PLUGIN_ROOT}/lib/load-config.sh 0 | jq .\n```\n\nCommon overrides:\n\n- **Severity scale** — replace the `severities` block to use blocker/high/medium/nit instead of the default critical/high/medium/low\n- **Service taxonomy** — swap `github_features.project_fields[Service].options` to your team's repo set; `gh-init bootstrap-labels` creates the matching `svc:*` labels automatically\n- **Gate evidence** — add or remove required sections per gate (e.g. add a `Threat model` section to Gate 1 for security-sensitive repos)\n- **Branching policy** — change `protected_base` or `branch_template` to fit non-`main` defaults\n- **Custom kinds** — add a new issue kind beyond feature/bug/hotfix/chore/testcase/plan/prd/request\n\n## License\n\nMIT — see [LICENSE](LICENSE)\n\n## Author\n\n[Fady Mondy](https://github.com/fadymondy)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffadymondy%2Fgh-pms","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffadymondy%2Fgh-pms","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffadymondy%2Fgh-pms/lists"}