/run-github-project

name: run-github-project
description: Use when asked to set up or repair a repository's GitHub Project configuration, reconcile Project epics or human checkpoints, triage Backlog work, plan and execute the next authorized issue, or drain authorized issues through implementation, review, merge, and reconciliation.

Run GitHub Project

Core Principle

Treat the Project as the live control plane. Require the readiness label and a human-authorized Planning transition, preserve that authority through contract-preserving re-plans, and return true human work to Backlog.

Park dependency-blocked Backlog items. After authorized execution is empty, route unblocked `needs-triage` items through the unchanged `triage` approval gate without manufacturing Planning authority.

Treat configured epics and human work as a separate live frontier. Reconcile a bare epic only after its native dependencies close and issue-close authority is present. Surface every currently actionable human step without assigning it or pausing independent work. Return `waiting-for-human` when that frontier is the only work left.

Pair each occupied slot with one warm worktree and one persistent ticket agent. Run independent slot agents concurrently in `drain`. Keep claims, shared Project state, merges, and reconciliation in one controller lane while each ticket agent owns its worktree, branch, and non-merge PR mutations. Preserve context across one ticket's passes; never reuse it for another. After bounded ticket-local required-CI repair fails, park the preserved claim outside implementation capacity, refresh the live control plane, and continue unrelated work.

Select The Mode

Select and record the mode before checking execution preconditions:

• 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.
• Use `drain` only when the user explicitly asks to drain, run all, repeat, or

continue until empty.

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;
• 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 expected Done automation and whether it archives the Project item.

Store names beside IDs and verify every pair at startup. Treat a renamed name as repairable drift; stop if an ID resolves to a different object. Never create or rename Project fields or options. Apply the clean-cutover gate in [references/planning-lane.md](references/planning-lane.md) before accepting the new schema. Permit `closing-keyword` only when the configured base is the current default branch; require `close-after-merge` otherwise.

If the file is missing or the trusted instructions do not reference it, discover the repository's linked Projects and their fields, then ask the user unresolved questions one at a time. Present the complete configuration draft and the minimal trusted-instruction reference together. Write both only after confirmation, preserving comments, formatting, and unrelated content. If either already exists, show and apply only the missing or stale portion.

Creating or repairing either file pauses `next` or `drain` until both are committed to the verified base. Do not commit them implicitly. In `setup`, validate the written pair against live state and finish `configuration-ready-to-commit`; if the user explicitly authorizes a dedicated configuration commit, make only that commit and verify whether the base contains both files. Finish `configuration-valid` when it does; otherwise finish `configuration-ready-to-commit` with the exact commit and missing-base evidence. Do not run Project work. In `next` or `drain`, continue the same invocation only after the user commits them or explicitly authorizes a dedicated configuration commit and the base contains both.

Record the