wp-github-flow
Use when shipping work through GitHub — fixing a GitHub issue by URL/number, or committing and PR-ing uncommitted working-tree changes. Covers resolving ISSUE_REPO vs CODE_REPO, grouping changes into scoped conventional commits (type(scope): summary), branching from fresh origin/base, discovering labels via gh label list, opening PRs with gh pr create, cross-repo Closes footer, merging with --merge (never --squash), and re-syncing after merge. Triggers: \"commit my changes\", \"commit scope by scope\", \"create a branch and PR\", \"open a PR for these changes\", \"fix issue #NNN\", \"debug this GitHub issue\", \"group my changes into commits\", \"push and open a PR\", \"what branch should I use\", \"conventional commit for this change\", \"close this issue with a PR\", \"write a PR description\", \"gh pr create\", \"gh issue view\", \"Closes footer\", \"branch name for this fix\", \"gh label list\", \"bugfix branch\", \"cross-repo close\", \"ISSUE_REPO vs CODE_REPO\", \"stale remote or
mralaminahamed · Static checks on file
Installation
Read the source and dependencies before running a command. Copying does not install or execute anything.
npx skills add mralaminahamed/wp-dev-skills --skill wp-github-flowAbout this skill
name: wp-github-flow
description: "Use when shipping work through GitHub — fixing a GitHub issue by URL/number, or committing and PR-ing uncommitted working-tree changes. Covers resolving ISSUE_REPO vs CODE_REPO, grouping changes into scoped conventional commits (type(scope): summary), branching from fresh origin/base, discovering labels via gh label list, opening PRs with gh pr create, cross-repo Closes footer, merging with --merge (never --squash), and re-syncing after merge. Triggers: "commit my changes", "commit scope by scope", "create a branch and PR", "open a PR for these changes", "fix issue #NNN", "debug this GitHub issue", "group my changes into commits", "push and open a PR", "what branch should I use", "conventional commit for this change", "close this issue with a PR", "write a PR description", "gh pr create", "gh issue view", "Closes footer", "branch name for this fix", "gh label list", "bugfix branch", "cross-repo close", "ISSUE_REPO vs CODE_REPO", "stale remote origin", "PR body template", "merge the open PR", "re-sync after merge", "sequential PRs". Not for: plugin version releases — use wp-plugin-release; WP.org SVN — use wp-org-submission."
GitHub Contribution Flow
Model note: Issue-driven mode (root-cause tracing + fix) requires
sonnetoropus. Changes-driven mode (group + commit existing edits) is mechanical and works well onhaiku.
Overview
Two entry modes that converge on the same shipping flow (branch → scoped commits → push → PR):
- Issue-driven — fetch issue → trace root cause → fix → ship. Wraps
superpowers:systematic-debugging. Root cause MUST be confirmed before any fix is written. - Changes-driven — read the working tree → group changes by conventional-commit scope → one commit per scope → ship. No issue required.
Both end at §6 Branch, Commit, PR, which is shared.
When to use
Issue-driven:
- User says "analyze/debug/fix/investigate issue #NNN"
- User pastes a GitHub issue URL and asks to debug it
- User says "find the root cause of this bug" with an issue reference
Changes-driven:
- "commit my changes", "commit these scope by scope", "commit by scope"
- "create a branch and PR", "open a PR for these changes"
- "read all changes from X and commit + create PR"
- Any request whose end goal is commits/branch/PR from existing working-tree edits
Not for: Plugin version releases or WP.org SVN deploy — use wp-plugin-release and wp-org-submission. QA failure triage on an already-open PR — use wp-ci-qa.
Required Sub-Skill
Issue-driven only: Invoke superpowers:systematic-debugging before any fix. Do NOT skip Phase 1 (root cause investigation). Changes-driven mode skips this — the edits already exist.
References
references/gh-reference.md—ghCLI commands, branch naming rules, label discovery, PR template sections, common CI failuresreferences/project-entry-points.md— project layout template: repos, plugin dirs, entry-point files, and key conventions; copy and fill in for your projectreferences/conventional-commits.md— type/scope table, WP-specific scope list, summary rules, multi-commit PR rules, footer conventions, rebase reword
Repo ≠ where the issue lives
The repo that hosts the issue is often NOT the repo that holds the code / receives the PR. Resolve two names up front and keep them distinct:
ISSUE_REPO— wheregh issue view/gh issue editrun.CODE_REPO— where the affected code lives; where you branch, push, andgh pr create --repo "$CODE_REPO".
When they differ, the PR's close footer must be cross-repo: Closes ISSUE_OWNER/ISSUE_REPO#N (a bare Closes #N only closes an issue in the same repo).
Real example: issues live in my-org/my-plugin, but the buggy code + PR live in my-org/my-plugin-pro → PR opens on my-plugin-pro, body says Closes my-org/my-plugin#247.
Changes-Driven Workflow
Use this when the user wants to ship existing uncommitted edits. Skip to §6's mechanics but commit scope by scope rather than one lump.
A. Read every change
git status
git diff # unstaged
git diff --staged # staged
Read the full diff, not just the file list — a single file can contain edits belonging to different scopes, and the commit message's "why" depends on what actually changed.
B. Group changes by scope
Map each change to one conventional-commit scope. Scopes are project-defined — read the repo's CLAUDE.md for the list, don't assume.
- ShopFlow:
api, cart, checkout, orders, products, customers, payments, shipping, taxes, coupons, inventory, admin, dashboard, blocks, spa, database, templates, email, reports, build, i18n.
Group by what the change is about, not just which directory it lives in. Examples from real sessions:
pages/Coupons/index.jsx+pages/Coupons/CouponList/index.jsx→ bothcouponspages/AbandonedCart/index.jsx,pages/Transactions/...→admin.yarnrc.yml,package.json→build
One scope can span multiple files; one file can split across commits via git add -p if it genuinely mixes concerns (rare — prefer not to).
Exception — one cohesive cross-cutting task = one commit. Scope-by-scope is the default, but when the change is a single logical task that inherently touches many files across categories (e.g. fixing all findings from an audit, a mechanical rename, a dir restructure), a single commit with an enumerated body is cleaner and more honest than forcing fragile per-file git add -p splits. Judge by intent: distinct concerns → separate commits; one purpose expressed across many files → one commit.
C. Branch first, then commit each scope
Create the branch (§6.1), then make one commit per scope so each is independently reviewable and revertable:
git add <files-for-scope-1>
git commit -m "fix(coupons): <imperative summary>"
git add <files-for
Read the complete source ↗