---
name: run-queue
description: Execute the repo's plan queue (plans/queue/) sequentially - dispatch each plan to a cheap executor (claude-custom gateway via delegate.sh by default, or an in-session haiku Agent), review the returned diff + findings, verify, fix if needed, commit per plan, and push to all remotes only when the entire queue is done and verified. Resumable after token exhaustion or crashes via plans/active/. Use when the user says "/run-queue", "run the plan queue", "execute the queued plans". Companion skill: plan-queue authors the plans. Manually-triggered only.
---

# run-queue

Sequentially execute every plan in `plans/queue/` (authored by `plan-queue`).
The strong model (you) orchestrates and reviews; a weak model executes.
Token contract: you read only plan files, returned diffs/findings, and
verification output — never re-explore the repo yourself unless a fix round
requires it.

## Invocation

```
/run-queue [--executor gateway|agent] [--model TIER] [--max-fix N] [--dry-run]
```

Defaults: `--executor gateway --model haiku --max-fix 2`.
`--dry-run`: print the resolved execution order (respecting `depends_on`) and
exit without dispatching.

## Orchestration loop

### 0. Preconditions
- Repo has `plans/INDEX.md`; working tree is clean (if not, stop and ask —
  never clobber uncommitted user work).

### 1. Resume check
If `plans/active/` contains a plan (previous run died / tokens exhausted):
- The plan-start commit is the checkpoint, so `git checkout -- . && git clean -fd`
  (confirm nothing untracked is user work first) to reset any half-applied
  edits, then re-dispatch that plan (step 3). This is always safe because
  every plan starts from a clean committed state.

### 2. Pick next plan
- Lowest `NNN` in `plans/queue/` whose `depends_on` entries are ALL in
  `plans/done/`. If a plan is blocked, skip to the next unblocked one; if
  everything remaining is blocked, report and stop.
- `git mv plans/queue/<plan> plans/active/`, set its INDEX.md row to
  `in-progress`, commit: `plan: start NNN-<slug>`. This commit is the resume
  checkpoint.

### 3. Dispatch to the executor
Build the prompt with `run-plan.sh` (this skill dir):

- **gateway** (default): `~/.claude/skills/run-queue/run-plan.sh -d <repo-root> [-m TIER] plans/active/<plan>.md`
  — wraps the plan in the executor preamble and calls
  `~/.claude/skills/delegate-task/delegate.sh` (timeout 1800s, retries on).
- **agent**: `run-plan.sh -p plans/active/<plan>.md` prints the prompt only;
  pass it to the Agent tool (`subagent_type: general-purpose`,
  `model: haiku`, `run_in_background: false`, cwd = repo).

### 4. Review (strong model, diff-only)
Read ONLY the executor's report (diff + verification output + findings).
Then **run the plan's Verification commands yourself** — never trust the
executor's pasted output.

- **Pass** → step 5.
- **Fail** → up to `--max-fix` rounds:
  - Small gap: fix it directly yourself (Edit tool).
  - Larger miss: reset the tree (`git checkout -- . && git clean -fd`),
    re-dispatch with a corrective addendum appended to the prompt
    (`run-plan.sh -a "addendum text" ...`).
- **Exhausted fix rounds** → reset tree, append `## Failure notes` (what
  failed, last error) to the plan file, `git mv` it to `plans/failed/`,
  INDEX row → `failed`, commit `plan: fail NNN-<slug>`, continue with the
  next plan that doesn't depend on it.

### 5. Complete the plan
- Append `## Execution log` to the plan file: executor+model, attempts,
  fix rounds, the executor's Findings verbatim.
- `git mv plans/active/<plan> plans/done/`, INDEX row → `done` + commit hash
  placeholder, then ONE commit containing code changes + plan move + INDEX:
  message = the plan's title, plain human style. **Never** add
  Co-Authored-By/AI attribution (global rule). Backfill the commit hash into
  the INDEX row on the next commit or amend before creating it.
- Loop to step 2.

### 6. Ship gate (only when queue/ is empty)
- If `plans/failed/` is non-empty: report the failures, do NOT push. Done.
- Else: run the repo's full verification once more (union of the plans'
  Verification commands, or the project's standard build/test), then push
  every local branch's current state to **all** configured remotes
  (`git remote` loop), ship-it style.
- **Webhook warning**: if the repo auto-deploys on push (e.g. BarangaySystem
  via Gitea webhooks), say so before pushing and ask, unless the user already
  told you to ship in this conversation.

## Reporting
End with: plans completed/failed (titles), one-line finding per plan, commits
created, and whether the push happened.