Gh flow

gh-flow

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

1. scaffold - Interview, plan, and publish from feature input, app docs, QA evidence, or optimize evidence.
2. audit - Inspect the repo locally and publish Audit Specs/Slices directly.
3. groom - Clarify the live needs-grooming and ready-for-human queue into AFK-capable work using repo-wide context, processing both together.
4. reproduce - Confirm a bug, capture evidence, and create or update the GitHub issue.
5. triage - Reconcile all open issues, resolve ordinary ambiguity with YAGNI decisions, and expose the complete ready frontier.
6. implement - Locally implement dependency-independent ready-for-agent frontier batches through verification, conflict-aware integration, QA when needed, landing, and cleanup.
7. qa - Browser-test the app locally and publish observed non-performance findings.
8. optimize - Measure performance locally and publish Performance Specs/Slices from evidence.
9. verify - Report local and CI-parity checks by default; use --fix for scoped local repair.
10. commit - Group uncommitted changes into focused Conventional Commits.
11. land - Land a selected branch through its default-base PR when present, otherwise rebase, verify, fast-forward/push default, and finalize issues. Persistent branch/worktree cleanup is deferred to cleanup.
12. cleanup - Safely remove local worktrees and branches for confirmed-landed targets. Scans all locally discoverable landed candidates and preserves anything that cannot be proven safe.
13. pr review - Review a targeted PR and publish an approve/request-changes review.
14. pr fix - Fix existing PR feedback, failed checks, and stale or unresolved threads.
15. pr rebase - Rebase a writable PR branch onto its PR base and verify conflict fixes.
16. pr process - Process actionable PRs through rebase, fix, verify, review, and auto-merge.
17. pr stack - Stack open PRs by shared files/lines and dependency surfaces: retarget dependent PR bases onto parent branches, rebase each onto its base, and flag irreconcilable conflicts.

Load Order

• Read HANDOFFS.md, RUNS.md, WORKERS.md, ISSUES.md, then workflows/shared-setup.md as the default shared setup for mutating workflows, except lightweight leaves that declare their own load set below.
• commit is a lightweight leaf: on invocation read only workflows/commit.md and the ## commit section of MENUS.md, and run the scripts/commit-snapshot.mjs helper; read the shared corpus only when the workflow's ambiguity stop needs more context.
• For a specific invocation, read only workflows/<workflow-slug>.md plus the template file(s) named there; spaces in workflow names become hyphens.
• Read another workflow file only when HANDOFFS.md marks it as an automated in-process handoff.
• Read MENUS.md only when returning control to the user.
• Use WORKFLOWS.md and TEMPLATES.md as compatibility indexes, not full context dumps.
• Read HELPERS.md when a named helper skill is unavailable in the current agent environment.

Orchestration Defaults

• Treat the top-level agent as the orchestrator. When sub-agent or worker tools are available, delegate independent lanes for implementation, review, QA, reproduction, performance measurement, PR repair, and stack analysis while the parent coordinates scope, sequencing, evidence, GitHub state, and final decisions.
• Sub-agents are optional accelerators, not hard requirements. If the current agent environment cannot spawn them, process the same work packets sequentially and preserve the same run artifacts, checks, and summaries.
• Use any available to-do list or list manager as the live control surface for non-trivial workflows. Track workflow phases, worker lanes, blockers, verification, GitHub publication, landing, and cleanup; keep it current as work moves from pending to in-progress to done.
• Keep list-manager state aligned with durable artifacts. The list manager is for active orchestration, while .gh-flow/runs, issue comments, QA reports, optimize reports, and commits remain the durable record.
• Treat GitHub issues as the durable control surface. Specs are issue maps, Slices are detailed work tickets, the frontier is the open unblocked/unclaimed ready set, and PR workflows must resolve or create a pr-tracking anchor issue before acting.

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, use MENUS.md to show one state-aware MCQ menu with at most three numbered options, owned by the top-level command; triage is the exception and returns a factual non-interactive report with no question or menu.
• AFK means no in-chat clarification questions, not read-only. Workflow side effects are governed by the capability matrix in workflows/shared-setup.md; invoked workflows inherit stricter caller limits.
• AFK workflows create or update one local run artifact per top-level command using RUNS.md; automated handoffs append phases to that parent run.
• When sub-agents are available, prefer delegation for independent, bounded lanes; worker subagents use WORKERS.md packets and must return a <gh_flow_result> tagged JSON summary; retry a malformed/missing result once.
• For any workflow with more than one meaningful phase, initialize or update the host tool's to-do/list manager before starting mutations, then refresh it after each phase, handoff, worker result, verification result, and blocker.
• MCQ next steps are chat-only and are forbidden for triage. Keep GitHub issue bodies, comments, QA reports, optimize reports, commits, and evidence bundles factual and durable.
• If an AFK workflow reaches work that would normally require HITL scaffold or groom, it must not ask in chat. triage is the AFK exception: resolve ordinary decision questions with the smallest reversible YAGNI choice and leave at least one safely actionable issue ready-for-agent; only a true external authority/input or reproduction gate may remain. Other AFK workflows write the exact questions durably, apply needs-grooming, remove readiness, and return or continue safe independent work.
• ready-for-agent is an individual implementation gate: each labeled issue must be self-contained, AFK-capable, unblocked, unclaimed, and free of unresolved material decisions or reproduction needs. The ready set is the complete frontier. Likely overlap never filters readiness or lane selection; use blocked only for an actual prerequisite dependency with Blocked by and resolve overlap during integration.
• triage uses preservation-first reconciliation: read every open issue and its complete comments, presume existing readiness is valid routing intent, resolve grooming-style ambiguity with documented YAGNI decisions, compute the full minimal state diff, and only then mutate. Never clear routing labels before analysis; add readiness to every eligible frontier issue, guarantee at least one ready issue whenever any work can safely move, and remove readiness only for a concrete current disqualifier with the exact reason recorded.
• For local mutating workflows, verify a git repo and an explicit checkout/worktree role before changing files. implement coordinates batches from the primary/default checkout or reuses the current existing issue-owned feature worktree for one resolved issue without creating another worktree. optimize uses a dedicated local worktree for temporary instrumentation and leaves no optimize-introduced source changes behind before publication. reproduce may use temporary edits from a clean checkout but never commits source changes.
• 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 measurement do not require GitHub until 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. Assignees are non-authoritative metadata for issue workflows; feature, integration, and optimize branches stay local. land merges an authoritative default-base PR when present or pushes default directly when absent; it never creates a PR or pushes a PR head. Only pr fix, pr rebase, pr process, and pr stack may push PR head branches.
• Auto-create missing workflow labels from TEMPLATES.md before GitHub issue mutations; in-progress is an active local-work claim, not a readiness signal.
• 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, qa, optimize, verify, commit, land, cleanup, pr review, pr fix, pr rebase, pr process, and pr stack are always AFK. process-pr is a deprecated compatibility alias for pr process.
• Never close issues before landing succeeds except triage may close already-satisfied issues with verification evidence on default, and groom may close duplicate, superseded, or canceled issues as not planned after explicit user confirmation. Never 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.

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 when available; delegate independent architectural, UX, and evidence-gathering passes when sub-agents exist, then reconcile findings through the list manager.
• groom: invoke batch-grill-me across the entire live needs-grooming and ready-for-human queue so each round asks every current frontier question, not just questions for one selected issue.
• reproduce: use agent-browser; confirm bugs through tests and browser evidence without diagnosing causes or implementing fixes.
• implement: use tdd when available for local lanes, plus sub-agent lane workers, reviewer workers, integration workers, and list-manager tracking for batches.
• qa: use agent-browser; use repo-informed journey mapping plus browser-only behavioral testing; split broad journeys across sub-agents when available and consolidate evidence before publication.
• optimize: use agent-browser, benchmark-style measurements, and diagnose performance discipline locally; delegate isolated measurement or hypothesis lanes only when their artifacts can be compared cleanly.
• verify: report checks by default; in --fix, repair locally only when the caller owns changes, track each check/fix in the list manager, and route ambiguous failures to grooming or a blocker.
• pr review: use code-review discipline; delegate independent review passes when possible, then publish one reconciled GitHub review with selective inline comments and approve only when Critical/High findings, required checks, merge conflicts, and actionable unresolved threads are clear.
• pr fix, pr rebase, pr process: for ordinary writable PRs, repair existing feedback or base drift with scoped verification; run stack analysis before standalone rebases when open PRs share dependency surfaces, delegate independent failures or PRs when sub-agents are available, and keep the parent responsible for final branch state.
• pr stack: retarget dependent PRs onto parent PR branches, rebase each onto its assigned base, create replacement PRs for closed-unmerged PRs, and flag irreconcilable conflicts; infer dependencies from line overlap plus big-picture contract/schema/route/config/generated-file coupling, and use sub-agents for independent stack branches only after the parent defines ordering and ownership.

References

Use HANDOFFS.md for handoff policy, MENUS.md for terminal completion menus, RUNS.md for AFK run artifacts, WORKERS.md for worker contracts, ISSUES.md for issue maps/frontier/PR anchors, WORKFLOWS.md for workflow file links, TEMPLATES.md for template links, and scripts/validate-gh-flow.mjs for integrity checks.