Build Queue

Build Queue

/build-queue --queue runs an unattended overnight orchestration of multiple phase plans. Each queue item gets the full /plan-expedite -> /build-phase chain. Halts are converted to GitHub issues, not retries — the operator triages in the morning from the summary report.

---

Constraints

Execution model: autonomous, queue-driven, halt-then-proceed (HEAVY). This skill exists so the operator can stage 3-5 pending phase plans, kick off /build-queue before bed, and wake up to a triage list. The whole point is that no halt — even a reviewer-gate failure on a code step — pulls the operator out of bed. Therefore:

1. Halt-then-proceed, not halt-then-retry. This is the load-bearing design choice. When any queue item halts (via the /build-phase halt contract — see [.claude/rules/code-quality.md § "Build-phase halt contract"](../../rules/code-quality.md)), this skill does NOT auto-retry, does NOT mutate the plan, does NOT try a different approach. It captures the halt context, files a single GitHub issue on the plan's repo titled [build-queue parked] : , marks the queue item as PARKED, and proceeds to the next item. Auto-retry would fight the halt contract (5 legitimate halts, anything else is a defect) and burn tokens on undiagnosable failures. The operator's morning triage IS the retry decision.

1. Sequential, never parallel. Queue items run one at a time. Parallel /build-phase on different plans has burned tokens in the past (memory: feedback_parallel_buildphase_same_plan). The queue's whole value is honest, sequential, surviveable execution.

1. Kill-switch is the only mid-run control. Between queue items, this skill checks for a .build-queue-killswitch file in the queue file's directory. If present (any contents, any size), it stops cleanly after the current item: writes a partial morning summary noting the kill-switch was hit, persists state for resume, and exits. The operator creates it with touch /.build-queue-killswitch. The skill never asks "should I continue?" — the file is the answer.

1. Final output is the morning summary, verbatim. When the queue drains (or the kill-switch stops it), the morning summary IS the final output. It is also written to .build-queue-report-.md next to the queue file for later reference.

This is by strong operator preference; treat any deviation as a defect.

---

When to use

• 3+ phase plans are staged across one or more projects and can ship overnight unattended.
• The operator has time to triage parked items in the morning but does not want to babysit reviewer gates at 3am.
• Plans have already been through /plan-expedite once (issues minted) OR are fresh and want the full prep chain — /build-queue calls /plan-expedite per item, so either is fine.

When NOT to use

• Single phase: use /build-phase directly (or /plan-expedite + /build-phase if not yet prepped).
• Plans with Type: wait steps as the only remaining work — /build-phase will halt on wait steps and /build-queue will park them; nothing useful happens overnight.
• Mid-day interactive work where the operator wants to react to each halt — the park-then-proceed posture is wrong for that mode.
• When the queue's plans are not yet through /plan-review and /plan-wrap — let /plan-expedite (invoked per-item by this skill) handle it.

Arguments

| Arg | Required | Default | Description | |---|---|---|---| | --queue | yes | -- | Path to queue file (see "Queue file format" below) | | --dry-run | no | -- | Parse queue + print resolved item list + exit. No /plan-expedite or /build-phase calls. | | --resume | no | -- | Resume from a prior partial run. Skips queue items already marked DONE or PARKED in .build-queue-state. |

No other flags. Per-item flags (which /build-phase to run, phase number, etc.) live in the queue file, not on the /build-queue invocation.

---

Queue file format

Plain text. One queue item per non-blank, non-comment line. Comments start with #.

# Each line:  [--phase N] [extra build-phase flags]
# Plan paths resolve relative to the queue file's directory if not absolute.

documentation/phase-g-plan.md
documentation/phase-2.1-plan.md --phase 1
../toybox/documentation/phase-n-plan.md
../alpha4gate/documentation/phase-4.7-plan.md --phase 2 --steps 1,2,3

Parse rules:

• Lines starting with # are comments; ignored.
• Blank lines ignored.
• First whitespace-separated token is the plan path; everything else is forwarded to /build-phase as flags.
• A plan path containing whitespace must be wrapped in double quotes (rare on this workspace).
• Order = execution order. No reordering.

At Step 0 pre-flight, resolve every plan path to an absolute path and verify the file exists. Any missing plan path is a queue-level pre-flight error: print all missing paths and exit without running anything. (Halting mid-queue on a typo would waste the night.)

---

Steps

Step 0: Pre-flight

Before invoking any sub-skill, do all of the following. Halt the entire run on any failure here — these are setup errors that compound if ignored.

1. Kill-switch check. If .build-queue-killswitch exists in the queue file's directory at startup, print kill-switch present at startup; refusing to run. rm to clear. and exit. The operator may have forgotten it from a prior session.

1. Parse queue file. Apply the parse rules above. Emit a resolved table of (item-index, abs-plan-path, forwarded-flags).

1. Verify plan files exist. For each resolved plan path, check the file exists and is readable. Collect all failures; if any, print the full list and exit.

1. State file check. Look for .build-queue-state in the queue file's directory (schema below). If --resume was passed:

• If the file exists AND its queue_path matches AND its queue_mtime matches the current queue file's mtime (1-second tolerance): use the existing state, skip items already marked DONE or PARKED.
• If the file exists BUT the queue file has been edited since: discard and start fresh (print a warning).
• If the file does not exist: start fresh.
• If --resume was NOT passed and the state file exists: rename it to .build-queue-state.prior- and start fresh. (Resume is opt-in to avoid silent surprises.)

1. Dry-run exit. If --dry-run was passed, print the resolved item list (including which items would be skipped under --resume) and exit without invoking any sub-skill.

Step 1: Per-item loop

For each queue item in order (skipping those already DONE or PARKED under --resume):

1. Kill-switch poll (between items). Check for .build-queue-killswitch. If present: write a partial morning summary noting the kill-switch was hit before item N, persist state, exit.

1. cd to plan's project root. This is the directory containing the plan file. All subsequent gh and worktree calls must run from here, not from the queue file's directory. (gh repo context — see [.claude/rules/windows-shell.md](../../rules/windows-shell.md).)

1. Invoke /plan-expedite via the Skill tool with args: "--plan ".

• Success: proceed to step 4.
• Halt: park this item (see "Park procedure" below). Proceed to next item.

1. Invoke /build-phase via the Skill tool with args: "--plan ".

• Success: append the DONE entry below to .build-queue-state's items[]. Proceed to next item.
• Halt: park this item (PARKED entry shape below). Proceed to next item.

1. State file update. After each item (DONE or PARKED), rewrite .build-queue-state (exact filename, in the queue file's directory) as a complete, valid JSON document — not an incremental append — BEFORE moving to the next item. The full items[] array (all entries so far) must be present. Each entry must include item, plan, verdict, and timestamp keys; DONE entries additionally include commits and issues_closed; PARKED entries additionally include halt_reason and issue (number or null). If the process is killed mid-loop, the next --resume run starts from the right place.

DONE entry appended to .build-queue-state:

``json {"item": 1, "plan": "C:/.../phase-g-plan.md", "verdict": "DONE", "timestamp": "2026-05-23T22:47:00Z", "commits": 7, "issues_closed": [41, 42, 43]} ``

PARKED entry appended to .build-queue-state:

``json {"item": 2, "plan": "C:/.../phase-2.1-plan.md", "verdict": "PARKED", "timestamp": "2026-05-23T23:18:00Z", "halt_reason": "Quality-gate hard fail", "issue": 99} ``

When narrating per-item completion in the run output, refer to the state file as .build-queue-state (exact filename — not "the state file" or "state was updated") and include the appended JSON entry verbatim, so the appended shape and the filename are both visible per item.

Park procedure (on any halt)

When /plan-expedite or /build-phase halts for any reason — halt contract, autofix failure, missing plan field, anything:

1. Capture context. Grab:

• The halt message verbatim (from the sub-skill's final output).
• The plan path (absolute).
• The queue item index.
• Current branch + last commit on the worktree, if a worktree exists (git worktree list shows it).
• Timestamp.

1. File a GitHub issue. From the plan's project root (cwd from Step 1.2), use gh issue create with --body-file (NOT inline --body — workspace rule). Title: [build-queue parked] : . Body:

```markdown ## Parked by /build-queue

• Queue item: of
• Plan:
• Timestamp:
• Worktree:
• Branch:
• Last commit:

## Halt output

## Resume

Triage this halt, then either:

• Fix and re-run the single plan: /plan-expedite --plan then /build-phase --plan
• Remove the item from the queue (or mark it DONE in the queue file via comment) and resume the overnight: /build-queue --queue --resume

```

On gh failure (rate limit, auth, repo not found): print the captured context to stdout AND write it to .build-queue-park-item-.md next to the queue file. The item still gets marked PARKED in state — the issue filing is best-effort observability, not a halt condition.

1. State file update. Append {"item": N, "verdict": "PARKED", "plan": "", "halt_reason": "", "issue": , "timestamp": ""} to items[].

1. Proceed. Continue the loop. Do NOT halt the overnight run on a park — that's the whole design.

Step 2: Morning summary

After the loop drains (or the kill-switch stops it), emit the morning summary to stdout AND write it to .build-queue-report-.md in the queue file's directory.

# /build-queue summary

Queue: 
Started: 
Ended: 
Duration: 
Status: 

## Items

| # | Plan | Verdict | Commits | Issues closed | Park issue |
|---|------|---------|---------|---------------|------------|
| 1 | phase-g-plan.md | DONE | 7 | #41, #42, #43 | -- |
| 2 | phase-2.1-plan.md | PARKED | 2 | #44 | #99 |
| 3 | phase-n-plan.md | DONE | 5 | #50, #51 | -- |
| 4 | phase-4.7-plan.md | SKIPPED (kill-switch) | -- | -- | -- |

## Triage list (parked items)

- #99 (phase-2.1, item 2):  — see issue for context.

## Numbers

- Items attempted: 3 of 4
- Items DONE: 2
- Items PARKED: 1
- Items SKIPPED: 1 (kill-switch)
- Total commits landed: 12
- Total issues closed: 5
- Total park issues filed: 1

When there are zero parked items, the "Triage list" section is omitted. When there are zero DONE items, that's worth surfacing prominently at the top of the summary ("Status: COMPLETE (0 of N items DONE — investigate").

---

State file schema

.build-queue-state in the queue file's directory, JSON. Gitignored.

{
  "queue_path": "queue.txt",
  "queue_mtime": 1779200000.0,
  "started": "2026-05-23T22:00:00Z",
  "items": [
    {
      "item": 1,
      "plan": "C:/.../phase-g-plan.md",
      "verdict": "DONE",
      "commits": 7,
      "issues_closed": [41, 42, 43],
      "timestamp": "2026-05-23T22:47:00Z"
    },
    {
      "item": 2,
      "plan": "C:/.../phase-2.1-plan.md",
      "verdict": "PARKED",
      "halt_reason": "Quality-gate hard fail (test count regressed)",
      "issue": 99,
      "timestamp": "2026-05-23T23:18:00Z"
    }
  ],
  "kill_switch_hit_before_item": null
}

Comparison uses 1-second tolerance for queue_mtime (same NTFS/FAT32 reasoning as /plan-expedite's state file).

Malformed state file under --resume: rename to .build-queue-state.malformed- and start fresh with a warning. Do NOT halt — this is observability state, not load-bearing.

---

Relationship to other skills

| Skill | Role | |---|---| | /plan-expedite | Invoked per-item to prep each plan (plan-review-autofix + plan-wrap-autofix + repo-sync + session-wrap) | | /build-phase | Invoked per-item to execute the plan's build steps; the halt contract here is the source of truth for what halts mean | | /loop | Different shape — /loop repeats one prompt on an interval; /build-queue drains a queue of distinct plans once | | /repo-update | Not invoked by this skill; each /build-phase step closes its own issue, but the post-phase docs+README+commit pass is left for the operator to run per-project in the morning |

Limitations

• One queue at a time per directory. Two /build-queue runs on the same queue file have undefined behavior (state file races). Don't do that.
• Per-item halts file an issue on the plan's repo — requires gh auth status to be valid for every distinct repo in the queue. Pre-flight does NOT verify gh auth per repo; first halt on a non-authed repo falls back to the local .build-queue-park-item-N.md file.
• No cross-item dependencies. If item 2's plan depends on item 1 landing first, that's an ordering responsibility of the operator (and the queue ordering preserves it). The skill does not detect dependency violations.
• No auto-rollback. If a /build-phase lands partial commits then halts mid-step, those commits remain on the branch. /build-phase itself does not roll back; /build-queue does not either. The morning triage owns rollback decisions.
• The morning summary's "commits landed" and "issues closed" counts come from /build-phase's own state output, NOT a separate git log scan. If /build-phase lies or under-reports, the summary inherits that.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: aberson
• Source: aberson/claude-skills
• License: MIT

Install and usage instructions live in the source repository linked above.