issue-pr-flow

Issue → PR Workflow

You are driving a developer through an issue-tracked development cycle on either GitHub (via gh) or GitLab (via glab). The aim is to make every meaningful change traceable: an issue describes intent, a branch carries the work, a PR/MR captures the diff and review, and merge closes the loop. You handle the orchestration; the platform CLIs do the talking; the user makes the calls.

Core principles

• Detect, don't assume. Different repos live on different hosts and have different CLIs installed. Always run platform detection before issuing platform-specific commands.
• Surface, then act. When the repo is missing scaffolding (issue templates / labels / CI), report the gap and propose a concrete fix. Wait for the user's "yes" before writing files or pushing config. Never silently mutate someone else's repo.
• Route by intent. Feature, bug, and chore have different cost/ceremony. Identify the route up front so you don't drag a one-line typo fix through architecture review, and don't speed-run a cross-module feature without exploration.
• Compose, don't reinvent. For non-trivial features, hand off the implementation to the feature-dev:feature-dev workflow and keep this skill responsible for the issue/PR wrapping. Don't re-implement codebase exploration here.
• Persist context to the repo. Long-lived project knowledge belongs in CLAUDE.md (and sibling docs the user already maintains), not in this conversation. After substantial work, suggest CLAUDE.md updates so future sessions don't relearn the same lessons.

Phase 0 — Locate the repo, then probe the environment

0a. Make sure you're inside the target repo

The whole skill operates on the current working directory's git repo. Two common entry states:

• User invokes the skill while already cd'd into a clone — proceed.
• User names a repo but hasn't cloned it locally (e.g. "do this on the X project on our internal GitLab") — stop and clone first. Ask which directory to clone into, then use gh repo clone <owner>/<repo> / glab repo clone <group>/<project> / git clone <url> and cd in. Don't try to run any of this skill's scripts before the working directory is the repo.

If detect_env.sh returns {"platform":"unknown","reason":"not_a_git_repo",...}, that's the signal to do the clone-and-cd dance above.

0b. Run the detection script

bash ${CLAUDE_PLUGIN_ROOT}/skills/issue-pr-flow/scripts/detect_env.sh

This reports: platform (github / gitlab / unknown), platform_source (how it was inferred: env / url / cli / unknown), host, remote URL, owner/repo slug, default and current branch, per-host CLI auth status, and recommended_cli + ready flags. See references/scripts.md for the full schema.

0c. Handle the unknown-platform case

URL substring matching only catches github.com and gitlab.<tld>. Self-hosted GitHub Enterprise or GitLab on an IP address (e.g. http://10.100.181.168/group/repo) or a custom domain falls through. When that happens the script tries one more rule — if exactly one of gh / glab is authenticated for this host, take its hint — but if both or neither are authed for the host, you'll get platform: unknown.

Resolve it by:

1. Asking the user which platform this is (one short question).
2. Re-running the script with the override: IPF_PLATFORM=gitlab bash …/detect_env.sh (or github). Use this same env var for init_check.sh too.
3. If the user's CLI isn't yet authed for this host, ask them to run glab auth login --hostname <host> or gh auth login --hostname <host> once. Don't try to authenticate on their behalf — this is interactive and account-sensitive.

For self-hosted GitLab specifics (HTTP vs HTTPS API protocol, ssh vs https git protocol), see references/platform-gitlab.md.

0d. Stop conditions

If after all of the above:

• the matching CLI is missing → ask the user to install it (brew install gh / brew install glab); don't fall back to raw curl against the API, you lose the CLI's auth handling and pagination
• the CLI is installed but not authed for this host → ask them to run the appropriate auth login and confirm before retrying
• platform is genuinely indeterminate → don't guess — ask

Once ready: true, all subsequent platform commands route through the matching CLI. See references/platform-github.md or references/platform-gitlab.md for the command tables. Pick one CLI and stick to it for the rest of the session unless the user switches repos.

Phase 1 — Repo readiness check

Run the bundled init check (pass IPF_PLATFORM if Phase 0 needed it):

bash ${CLAUDE_PLUGIN_ROOT}/skills/issue-pr-flow/scripts/init_check.sh
# or, for self-hosted on an IP / custom domain:
IPF_PLATFORM=gitlab bash ${CLAUDE_PLUGIN_ROOT}/skills/issue-pr-flow/scripts/init_check.sh

It reports the objective, fixed-path facts: issue templates, PR/MR template, CI config file paths, and the live label list. If platform is unknown the script returns {"error":"platform_unknown",...} instead of an empty report — that's the cue to set IPF_PLATFORM and re-run, not to assume the repo has nothing.

The script intentionally does not evaluate CI health or test infrastructure — those are too varied to pattern-match reliably. When they need to be assessed, you do it by reading the project (build manifest, README, CI files, git history) and asking the user as needed. references/init.md §4b walks the CI health questions and §5 walks the test-infrastructure assessment.

Do not create or push anything based on this report — just summarize the gaps and ask whether the user wants to backfill them. Init covers six categories, each its own confirmation: issue templates → PR template → labels → CI (existence + health) → test infrastructure (existence + health) → CLAUDE.md. Group related changes into one commit per category and explain what the commit will contain before running git add.

If the user says "skip init for now" — respect that and move on to Phase 2 immediately. The check is opportunistic, not a gate.

Phase 2 — Intent routing

Ask the user (or infer from their initial message) which of these the work is:

Route	When	Reference
feature	New capability, cross-module change, anything that may need an ADR or architecture discussion	references/route-feature.md
bug	Reproducible defect with a known wrong behavior to fix	references/route-bugfix.md
chore	Docs, deps bumps, config tweaks, small refactors with no behavior change	references/route-chore.md

If the user is ambiguous ("just make it work better"), ask one targeted clarifying question rather than guessing. Misrouting bugs as features wastes time on exploration; misrouting features as chores skips needed design.

Once routed, read the corresponding reference file in full before continuing. Each reference encodes the route's checklist, branch naming, label set, commit message conventions, and the issue/PR template for that route. Don't try to remember the rules from this SKILL.md — go read the source of truth for the route.

Phase 3 — Drive the route to merge

Each route is a sequence of: create issue → branch → implement (route-specific) → push → open PR → CI green → review → merge → cleanup. The reference files spell out the platform-specific commands.

Two things this SKILL.md owns regardless of route:

1. Hand-off boundaries. When the route file says "delegate to feature-dev", spawn the feature-dev:feature-dev workflow on the implementation portion only. Wrap its output back into your issue/PR. Don't let it open the PR — you own that to keep label/template conventions consistent.
2. Stop at every irreversible step. Pushing branches, opening PRs, requesting reviews, merging, and deleting branches all need explicit user approval the first time you do them in a session. After the user okays a step once, you can proceed without re-asking on the same PR — but a new PR resets the gate.

Phase 4 — Knowledge persistence

After the PR merges, ask whether anything from this work should land in CLAUDE.md (or a sibling docs/DECISIONS.md style file if the repo has one). Good candidates: a non-obvious convention you discovered, a constraint that bit you mid-implementation, an architectural decision worth recording. Bad candidates: routine commit details, anything reconstructible from git log.

If the user agrees, propose a concrete diff to CLAUDE.md and commit it as a follow-up (separate from the feature PR — typically directly to the default branch if the project allows, otherwise as a tiny chore PR). The point is to keep future Claude sessions from relearning the same context.

Bundled resources

skills/issue-pr-flow/
├── SKILL.md                       (this file — entry point and orchestration)
├── references/
│   ├── platform-github.md         gh command table, auth, edge cases
│   ├── platform-gitlab.md         glab command table, auth, edge cases
│   ├── init.md                    issue template / label palette / CI starters
│   ├── route-feature.md           feature route: full ceremony, feature-dev hand-off
│   ├── route-bugfix.md            bug route: reproduce → locate → fix → test → PR
│   ├── route-chore.md             chore route: lightweight, single-commit PRs
│   └── scripts.md                 schemas + usage for the bundled scripts
├── scripts/
│   ├── detect_env.sh              platform + CLI + auth probe → JSON
│   ├── init_check.sh              templates / labels / CI presence report → JSON
│   └── apply_labels.sh            sync repo labels from a JSON palette (gh/glab)
└── assets/templates/
    ├── github/                    issue templates, PR template, labels.json, ci yml
    └── gitlab/                    issue templates, MR template, labels.json, ci yml

Read references on demand — don't load them all upfront. Run scripts via bash ${CLAUDE_PLUGIN_ROOT}/skills/issue-pr-flow/scripts/<name>.sh so paths resolve regardless of where the user invokes you.

Anti-patterns to avoid

• Running gh/glab commands without first running detect_env.sh — you'll either use the wrong tool or hit a missing-auth error mid-flow.
• Treating platform: unknown as "no platform" and giving up — for self-hosted instances on IP / custom domain, set IPF_PLATFORM=github|gitlab and retry. Don't silently switch to writing files and skipping the platform commands.
• Creating issue templates / labels / CI files without confirmation — these are repo-wide policy changes; the user must opt in.
• Reimplementing feature exploration — for non-trivial features, delegate to feature-dev:feature-dev and let its code-explorer / code-architect / code-reviewer agents do their job.
• Letting a feature route skip the issue — the issue is the durable record of why; the PR records what. Both are cheap to create.
• Pushing or merging without a beat of explicit confirmation per PR — even on solo repos, the speed bump catches mistakes.