gh-flow

name: gh-flow description: Orchestrates repo delivery workflows for GitHub issues, Jules remote implementation, PR processing, local QA, browser bug hunts, performance optimization discovery, verification, commits, and landing. Use when the user invokes /gh-flow, wants GitHub issue or pull request workflow management, asks to scaffold, audit, groom, reproduce, triage, implement, jules, qa, optimize, verify, commit, land, or process PR repo work, or asks for deep local app QA or performance investigation.

Use /gh-flow <workflow> to manage repo delivery from planning through local QA, Jules remote implementation, PR processing, verification, commits, and landing. If invoked as bare /gh-flow, show this numbered menu and wait for the user to pick a number before mutating anything:

scaffold - Interview, plan, and publish Canvas, Blueprint, Runway, Spec, and Slice artifacts.
audit - Audit architecture and frontend quality, then publish one Spec plus AFK Slice issues.
groom - Clarify the oldest needs-grooming issue into AFK-capable implementation work.
reproduce - Confirm a bug, capture evidence, and create or update the GitHub issue.
triage - Review all open issues and repair workflow labels, dependencies, and stale state.
implement - Start eligible ready-for-agent issues in Jules by default, or run local lanes with --local.
jules - Monitor Jules sessions/PRs, run local verification, reprompt Jules until green, and hand off to PR processing.
qa - Browser-test the app locally and publish observed findings as GitHub issues.
optimize - Measure performance deeply, use temporary instrumentation, clean it up, and publish optimization work.
verify - Discover local and CI-parity checks, fix scoped check failures, and block on performance regressions.
commit - Group uncommitted changes into focused Conventional Commits.
land - Rebase onto default, verify, fast-forward default, push, and clean up.
process-pr - Process the oldest review-ready PR, fix existing blockers, verify, review, and enable auto-merge.

Load Order

Always read HANDOFFS.md, RUNS.md, WORKERS.md, then workflows/shared-setup.md.
For a specific invocation, read only workflows/<workflow>.md plus the template file(s) named there.
Read another workflow file only when HANDOFFS.md marks it as an automated in-process handoff.
Use WORKFLOWS.md and TEMPLATES.md as compatibility indexes, not as full context dumps.
Read HELPERS.md when a named helper skill is unavailable in the current agent environment.

Core Rules

"Invoke" another workflow means follow that workflow's instructions in-process; do not shell out to another slash command.
Automated vs manual handoffs are authoritative in HANDOFFS.md; preserve that graph unless fixing a documented contradiction.
Internal AFK handoff boundaries do not show next-step menus. When control returns to the user, show one state-aware MCQ menu with at most three numbered options.
If an AFK workflow reaches work that would normally require HITL scaffold or groom, it must not ask in chat. Write the exact questions into the issue body or comment, apply needs-grooming, remove ready-for-agent, and return or continue safe independent work.
AFK workflows create or update one local run artifact per top-level command using RUNS.md; automated handoffs append phases to that parent run.
Worker subagents use WORKERS.md packets and must return a <gh_flow_result> tagged JSON summary; retry a malformed/missing result once.
MCQ next steps are chat-only. Keep GitHub issue bodies, comments, QA reports, and evidence bundles factual and durable.
For local mutating workflows, verify a git repo and an explicit checkout/worktree role before changing files. implement --local starts from the primary/default checkout and does issue work in a local feature worktree so the primary app checkout stays usable until landing. jules uses isolated PR verification worktrees and does not make code commits. optimize uses a dedicated local worktree for temporary instrumentation and leaves no optimize-introduced source changes behind.
Read applicable repo instructions and domain docs first: AGENTS.md, CLAUDE.md, CONTEXT.md, CONTEXT-MAP.md, and ADRs.
Use the gh CLI as the primary GitHub interface; connectors/MCP tools are optional fallbacks.
Before GitHub mutations, verify a git repo, GitHub remote, and gh auth status; local QA and optimize discovery do not require GitHub until issue publication.
Keep GitHub reads bounded: never fetch bodies or comments for all issues in one command; list compact metadata, then hydrate one issue at a time.
On 401, "Authentication Failed", or repeated transport/tool errors, stop with the failing command and auth status; do not retry the same fetch in a loop.
Use labels, issue bodies, and comments only; do not require GitHub Projects.
Assume a single GitHub repo, often a monorepo. Ignore assignee state for issue workflows; feature/QA branches stay local, land pushes default directly without creating PRs, and only process-pr may push PR head branches.
Auto-create missing workflow labels from TEMPLATES.md before GitHub issue mutations; in-progress is an active local or Jules claim, not a readiness signal. jules is an alternate trigger label, not durable active state.
scaffold and groom are HITL when invoked directly, except AFK publishing modes such as scaffold --afk-from-qa <run-dir> and scaffold --afk-from-optimize <run-dir>. audit, reproduce, triage, implement, jules, qa, optimize, verify, commit, land, and process-pr are always AFK.
AFK workflows must not ask clarification questions. For issue workflows, update the issue body, add needs-grooming, remove ready-for-agent, and stop when intent is unclear. For local workflows, stop with the exact blocker and the next workflow or input needed.
Never close issues before landing succeeds, weaken tests/config to get green, bypass branch protection, auto-stash user work, commit ignored/sensitive/generated/evidence files, commit .gh-flow/runs, commit QA/optimize/reproduction evidence bundles, or delete a failed worktree. commit may group safe dirty repo changes when a workflow is clearing a checkout for implementation or landing.

Helper Skills

Helper skills are optional accelerators. Use them when available; if not, continue with the fallback guidance in HELPERS.md.

scaffold: use grill-with-docs for direct HITL modes; for AFK publishing modes, do not interview and use only the supplied evidence bundle.
audit: use improve-codebase-architecture and impeccable; add live browser evidence when runnable, stay AFK, and publish GitHub issues as the durable output.
groom: use grill-with-docs.
reproduce: use agent-browser; confirm bugs through tests and browser evidence without diagnosing causes or implementing fixes.
implement: use Jules by default; use tdd only for --local lanes. Jules owns remote development, while gh-flow owns queue selection, monitoring, verification, and PR processing handoff.
jules: use Jules CLI for session list/start/pull, Jules API sendMessage through JULES_API_KEY for same-session repair prompts, and verify for local PR-branch checks.
qa: use agent-browser; use repo-informed journey mapping plus browser-only behavioral testing. QA is issue-authoring only: do not fix app code, do not invoke reproduce, optimize, or repair workflows, and do not invoke the standalone /qa skill.
optimize: use agent-browser, benchmark-style measurements, and diagnose performance discipline; measure before publishing work and clean up temporary instrumentation.
verify: use diagnose for non-trivial check failures and agent-browser for UI/E2E failures; inspect CI workflows for local-runnable check parity.
process-pr: use code-review discipline; for Jules PRs, do not make local code commits and reprompt Jules for failing checks or Critical/High findings before final review.

References

Use HANDOFFS.md for handoff and completion-menu policy, RUNS.md for AFK run artifacts, WORKERS.md for worker contracts, WORKFLOWS.md for workflow file links, TEMPLATES.md for template links, and scripts/validate-gh-flow.mjs for integrity checks.