/run-github-project

name: run-github-project
description: Use when asked to set up, review, or operate a repository's GitHub Project workflow, including ready claims, human-owned Planning work, unknown remote mutation outcomes, Backlog triage, epics, checkpoints, next-issue execution, or an authorized drain.
compatibility: "External skill providers are mode-specific: review and setup require none; execution, triage, and Wayfinder lanes use the providers documented in references/workflow-providers.md."
disable-model-invocation: true

Run GitHub Project

Core Principle

The Project is the live control plane. Apply these invariants throughout:

1. **Live authority:** use complete, fresh GitHub and Project state for every claim, selection, and finish decision; a local cache or partial read is only a hint. 2. **Controller ownership:** the controller alone claims, assigns, mutates shared Project state, merges, closes issues, and reconciles. A ticket agent owns only its worktree, branch, and non-merge PR mutations. 3. **Unknown outcomes:** treat a failed or timed-out remote mutation as unknown; authoritatively reconcile it before retrying or reporting success. 4. **Preservation:** retain blocked, dependency-gated, and human-owned work. Put it in its authoritative frontier or partial-drain report rather than changing its state to make the queue appear empty.

Require the readiness label and a human-authorized Planning transition; preserve that authority through contract-preserving replans and return true human work to Backlog. In `drain`, pair each occupied slot with one warm worktree and persistent ticket agent, run independent slots concurrently, and park only qualifying terminal required-CI claims outside capacity before refreshing the control plane.

Check External Skill Providers

Review and setup modes require no external skills. Before `next` or `drain`, read [references/workflow-providers.md](references/workflow-providers.md). It is the source of truth for required, conditional, and optional providers, their source repositories, installation commands, and lane-specific fallback behavior. Never install a provider implicitly.

Select The Mode

Select and record the mode before checking execution preconditions:

• Use `review` only when the user asks to inspect, assess, or explain the

Project workflow without operating it.

• Use `setup` only when the user explicitly asks to set up, configure, validate,

or repair the repository binding without running Project work.

• Use `next` by default for execution and process at most one selected issue.
• When the user explicitly names a Wayfinder child, keep `next` and record that

selection; never reinterpret it as permission to drain or bypass a claim.

• Use `drain` only when the user explicitly asks to drain, run all, repeat, or

continue until empty.

In `review`, inspect only the repository, supplied state, and read-only remote state that the user permits. Apply the live-authority, controller-ownership, unknown-outcome, and preservation invariants to the requested workflow seam. Do not configure or write the binding; rank, claim, transition, triage, plan, or delegate Project work; mutate an issue, PR, or Project item; push; merge; or close anything. Do not require execution dependencies, merge authority, issue-close authority, or ticket-agent capacity. Finish `review-complete` with the evidence, safe next action, and any uncertainty, or `review-blocked` when the permitted evidence cannot support the requested assessment. Never continue into setup or [Check Preconditions](#check-preconditions).

In `setup`, follow [Configure The Project](#configure-the-project) plus the read-only retry, pagination, unknown-state, and bounded-failure rules in [Handle GitHub Access Failures](#handle-github-access-failures). Discard a partial logical read and report `configuration-blocked` when a complete live configuration read cannot be established. Never apply mutation-reconciliation rules because setup permits no remote mutation.

Perform the repository, authentication, Project, field, label, branch, automation, and cutover reads needed to produce and validate the configuration. Do not require `tdd`, `to-plan`, `triage`, review providers, merge authority, issue-close authority, an execution-clean worktree, or ticket-agent capacity. Never rank or claim work; assign or transition an issue; mutate a Project item, issue, or PR; create a ticket worktree; plan or implement a ticket; push; or merge. Finish `configuration-valid` only when the verified base contains the live-validated pair. Finish `configuration-ready-to-commit` when the validated pair is not on the verified base, whether it is uncommitted or committed only on another branch. Otherwise finish `configuration-blocked`. Never continue into [Check Preconditions](#check-preconditions).

Configure The Project

Read `docs/agents/run-github-project.md` through the closest trusted `AGENTS.md` or `CLAUDE.md`. Require the trusted instructions to reference that file explicitly. Use [references/project-config.md](references/project-config.md) as its structure. Require:

• repository identity, default and base branches, and issue-closure policy;
• Project owner, number, URL, and node ID;
• Status field name and ID plus Backlog, Planning, Ready to implement, In

progress, and Done option names and IDs;

• the exact repository label mapped to the `needs-triage` role;
• the exact repository label name and ID mapped to the epic work shape;
• the exact repository label name and ID mapped to the human-work role;
• an optional complete Wayfinder label block with exact names and live IDs for

its map, research, prototype, grilling, and task labels;

• Priority field name and ID plus option names and IDs in descending order;
• execution-approver GitHub logins allowed to authorize Planning;
• an optional trusted Project filter expression;
• the repository merge method or merge-queue policy;
• the expe