controller.md

Controller guide

Use the work-queue skill in Codex or Claude Code. The controller is your interactive agent session. Detached workers run the provider selected in .work-queue/config.toml.

The loop

Read current state -> choose ready tasks -> start workers -> collect results
                  -> check requirements and tests -> merge -> clean up

1. Run wq tick on each wake or return from a worker. It checks saved state against processes and Git, then prints the next actions in priority order.
2. Handle the first action that can proceed. Record a blocked action and its reason, then continue with independent entries. After changing work or queue settings, run another tick before choosing the next action.
3. Publish wq report --publish before yielding. The terminal gets a short update; the full report is saved.

The session has no built-in timer. wq watch prints events for a host to deliver to the controller. You can also resume manually with wq tick --recover.

If no action can proceed, publish the blockers and wait for a worker result, user answer, or other state change. Do not repeatedly retry an unchanged blocker.

Build a task

Pick ready work from wq queue list. Check dependencies and the task's current requirements. Split only where pieces can be built and verified separately. Work that edits the same files should run in order.

The controller may use its host's native agents to review or split work. Start tracked coding workers through wq headless, so their processes and checkouts survive a session restart.

wq dispatch worker --file src/notes.py
wq provision --slug save-notes --item L1 --piece "Keep saved notes after restart" --file src/notes.py
wq headless --worktree .claude/worktrees/loop-save-notes --item L1 --prompt "Implement L1. Read its cited requirements and preserve existing note editing. Prove a saved note survives restart. Work only in this checkout."

Replace the example task, file, and brief. Repeat --file for each assigned file. Use the worktree path printed by provision. dispatch worker only checks whether work may start. provision checks admission again and reserves the checkout with its file assignments, so later workers can be checked for overlap. headless consumes that reservation and starts the process; it refuses duplicate or unreserved launches.

A useful brief names the task, relevant requirement sections and change ID, completion test, allowed files, shared interfaces, and behavior to preserve. Include the assigned database or device lane when the task needs one. Workers report scope problems to the controller; they do not recruit more workers.

Collect and verify

When tick prints reap, run the command it gives, for example:

wq reap --agent save-notes

This reads the provider result and checks Git changes. A provider's successful exit alone does not prove the task is done. Inspect the diff and run the relevant tests against the agreed requirements.

wq gate run quick --worktree .claude/worktrees/loop-save-notes
wq gate await JOB

Use the returned job ID in place of JOB. Run the full pr gate before offering the work for merge. Gates run in the background under a lock; use wq gate list to find their logs.

If work is incomplete, retain its checkout and name the remaining work. wq tidy preserves dirty, unpushed, or otherwise unverified work. Do not force removal to clear a hold.

Merge and clean up

Once the change is reviewed and the project's checks pass, push its feature branch and create its pull request using your normal GitHub tools within the user's authorization. Do not push directly to main or force-push. A pull request is a proposed merge, often shortened to PR in commands.

wq land queue
wq land arm 123
wq land settle
wq tidy

Use the pull request number shown by the queue. arm updates the branch, checks current requirements and required checks, then requests automatic merging. Unknown or missing merge facts hold the action. settle records observed merges and frees the merge slot. It tracks merged IDs, so a lower-numbered request merged later is still handled.

wq ci plan advises whether a push fits the continuous integration (CI) budget. It does not block pushes made through other tools. See the reference before relying on the budget policy.

When requirements change

Follow amend mode: update the agreed body and append a short Change C-ID record in the same document. Use the same change ID in every affected document and task. History explains why the target changed; it does not override the current body.

Each affected task carries a Task contract: the source file, named sections, change ID, and Git version it was written against. This is the task's reference to its requirements. See the shared guide for the exact format.

The queue checks that reference before starting work and before merging. Its source of committed requirements is the configured remote main branch. Merge the accepted definition change there before starting its tasks. Uncommitted edits to the cited source hold the task until resolved.

A cited section edit or applicable accepted change holds affected work. Unrelated changes may continue. Existing tasks without references still work in projects without definitions/spec.md; tasks governed by that file need a reference.

To resolve a hold:

1. Read the latest body and change record. Update the task's scope, completion criteria, and reference.
2. Inspect the worker's saved changes. Finish or stop the old worker before recording a new reference.
3. Rework and verify the affected result. Keep completed work that still satisfies the requirement.
4. Run wq queue reconcile L1 --agent save-notes to record that review against the updated task, then tick again.

Reconciliation records your completed review. It does not rewrite code, answer questions, or restart a worker. Pending automatic merges for affected work must be cancelled before work continues. A failed cancellation remains a hold.

Holds and recovery

What happened	Next step
Session or machine restarted	Run wq tick --recover, then follow the printed actions.
Worker ended without a result	Run wq reap --agent ID; inspect its log and retained checkout.
Queue paused	Read wq report; fix the reason, then use wq steer resume.
You need to stop new work	Use wq steer pause. Existing work is retained.
A decision needs your answer	Use wq answer NUMBER "your answer". Unanswered questions remain visible.
A rule's decision is unclear	Read wq explain ID.
Configuration is invalid	Correct the exact setting named in the error. Unknown settings are rejected.
Saved state is corrupt	Stop controller writes. Keep the damaged file and worker checkouts; restore a known-good state backup, then recover. Never replace it with an empty state to clear the error.
Cleanup refuses a file, branch, or database	Inspect its reason. Preserve it until ownership and saved work are known.

The optional Claude Bash hook checks selected shell commands. It is not a Codex hook or a complete security boundary. Both providers still need their normal permissions and project rules.