/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, role-labelled human work, unknown remote mutation outcomes, Todo 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: fresh board state and this run's operation-specific grants decide every claim, write and finish. Default lanes are `Backlog` → `Todo` → `Ready to implement` → `In progress` → `Done`; resolve them through the trusted binding's verified option IDs.

Invariants

1. **Column authority:** current column membership authorizes a ticket, never transition history. Backlog is read-only: never claim, plan, triage, close epics or resume cleanup there; only humans move items out. Automatic work starts at Todo. 2. **Live authority:** claims, selection, merge, recovery and finish need complete fresh state; caches and partial reads are hints; rehydrate only changed or unverified records. Recheck operation-specific authority before each claim, write or merge, even from a reused snapshot; ranker eligibility grants nothing. 3. **Controller ownership:** only the controller claims, assigns, mutates shared Project state, merges, closes issues and reconciles; a ticket agent owns only its worktree, branch and non-merge PR changes. 4. **Unknown outcomes:** reconcile an unknown or failed mutation or publication before retrying, freeing capacity or reporting success. 5. **Preservation:** keep blocked, dependency-gated and human work in its frontier with owner, claim, slot, draft, artifacts, grants and budgets; never change state to empty the queue. Released capacity resumes only in free slots. 6. **Retained owner:** feedback, repairs and amendments keep the owner, claim and slot without a Todo/Ready reset; renew affected checks and reviews at the final head, never relying on earlier-head evidence. 7. **No invented gates:** never infer a permission, capacity limit, provider or prerequisite the supplied state lacks; independent runnable work continues while others wait. 8. **Supplied state:** decide review, setup or analysis from supplied complete state without another Project or repository read (still read references); judge the described environment, not providers missing from this workspace. A validated proposed diff is `configuration-ready-to-commit` even unwritten and uncommitted. Profile selection calls no routing service and grants no claim or merge authority; ignore legacy routing fields without editing them. 9. **No escape hatch:** renewal or amendment never resumes parked CI, grants live turns or resets qualification. Unknown or stale evidence blocks dependants; material architecture changes need full replan and review; changed authority or qualification needs a stakeholder or source decision.

A verified handoff covers in-scope implementation, tests and repairs under `deliver-spec`, with one independent integrated-candidate review. Replans keep verified plan state; true human work returns to a decision pause. `drain` parks verified authority pauses and qualifying terminal required-CI claims outside capacity before refreshing; in `next`, a required-CI stall keeps its slot. A wrong plan seam still failing after one diagnosis and two repairs needs the replan packet; a repeated non-CI failure stays with its owner, who asks one capability-selected read-only evidence helper and resumes only on new direction, else reports the exact blocker.

Select the mode

• `review`: inspect or explain only. `setup`: configure or validate the binding only.
• `next`: default; at most one selected issue; after the startup merge decision settles, returns `waiting-for-human` without further waiting. A named Wayfinder child stays `next`.
• `drain`: only on explicit drain/run-all/until-empty request; no ticket cap. With only remote or human waits left it runs the read-only [Project Watcher](references/drain-scheduler.md#project-watcher), never replacing the Refresh Gate.

Resolve merge permission once at startup under [run authority](references/authority-and-pauses.md): honor an explicit merge or no-merge instruction; otherwise ask with a 60-second default-no deadline while delivery continues. Without permission, deliver ready PRs and pause only merges.

Read before acting

| Mode | Mandatory reference | | --- | --- | | `review` or `setup` | [Review and setup](references/review-and-setup.md) | | `next` or `drain` | [Review and setup](references/review-and-setup.md) for binding validation, then [execution controller](references/execution-controller.md) and [ticket lifecycle](references/ticket-lifecycle.md) |

Execution also reads [workflow providers](references/workflow-providers.md) first (never install one implicitly), [authority and pauses](references/authority-and-pauses.md), and [review contracts](references/review-contracts.md) before acceptance work; `drain` reads [drain scheduler](references/drain-scheduler.md) completely before drain queue work. Read the matching section first, even for analysis:

| Question involves | Read | | --- | --- | | Pre-dispatch readiness, qualification, live turns | [Unattended readiness](references/execution-controller.md#unattended-readiness) | | Capacity, shared paths, refresh, timing, CI parking | [Drain scheduler](references/drain-scheduler.md) | | Planner yield, amendment, replan | [Todo lane](references/todo-lane.md#yield-a-planner-for-delivery) | | Configuration change or renewal | [Project config](references/project-config.md#renew-presentation-only-configuration) | | Agent profiles or helper assignment | [Agent routing](references/agent-routing.md) |

Answer each item

Per ticket or s