← Back to Writing

Lesson 6: Build a Task Queue Agents Can Follow

About this artifact

essayon-the-recordmaintained

method · since 2026

What you'll learn: write tasks with acceptance criteria, dependencies, and status; define how an agent chooses one eligible task; and require it to stop after reporting the result. What you need: the specs/ directory from Lesson 1, the repository layout from Lesson 4 or one repository, the permission file from Lesson 5, and five tasks you want to complete. Time: about twenty minutes to set up, then five per well-defined item. Cost: no additional services; agent runs use your existing model allowance or usage billing.

The idea#

Give an agent a task queue with explicit eligibility rules. Each task needs an observable result, a status, and dependencies. The selection rule in this lesson takes the lowest-numbered ready item whose dependencies are done. It permits one item per session.

A backlog is the collection of planned work. The queue adds a rule for selecting eligible work from that collection. You still decide priorities, approve requirements, and resolve questions the repository cannot answer. The agent applies those decisions when it selects the next task.

A task queue separates ready, doing, review, and done. The agent selects the lowest-numbered ready item with completed dependencies, works one item, then stops at review. Newly discovered tasks remain draft until approved.

Why start here#

Earlier lessons defined requirements, decisions, checks, repository scope, and agent permissions. The queue connects those instructions to a particular task. Since the end of May, my queue file had received more than twelve hundred edits by the time I wrote this lesson. Accurate task records had become necessary for repeated agent runs.

Start with a supervised session. Lesson 7 adds review and verification controls before unattended operation.

The template#

Save this as BACKLOG.md beside the standing instruction file. The repo field names the repository. tier records a model-assignment category; choose the actual model for each category in your runner or session setup.

# Queue

## Pick rule
Read this whole file. Take the lowest-numbered item whose status is ready
and whose depends_on items are all done; if none qualifies, say so and
stop. Before taking an item whose pr is empty, search the merge history
for its id; if the work is already there, mark it done with the merge
commit in notes (the one done you may set) and pick again.
One item per session: set it doing, finish it, set it review, and stop.
Never edit an item you are not holding. The one exception is appending:
work you discover is a new item at the bottom with status draft, never a
wider current one.

Status: draft -> ready -> doing -> review -> done. I move draft to ready
and review to done (except the merge-history case); you move ready to doing to review. For code, done
means merged. For a queue-only investigation, done means I have reviewed
and accepted its draft children. blocked waits for me.
Tier: judge (the acceptance needs a decision), build (a checkable
acceptance line), mechanical (the steps are already listed in the item).

## B-001 health() returns ok
- repo: api
- status: ready
- depends_on: []
- tier: build
- spec: specs/api/002-health.md
- acceptance: python -m pytest api/tests -q passes with a test asserting health() returns {"ok": true}
- pr: -
- notes: -

## B-002 Work out what the status page needs
- repo: specs
- status: ready
- depends_on: [B-001]
- tier: judge
- acceptance: this item is done when it has appended B-00N children as draft, each with an acceptance line I can run, and it has asked me nothing it could have found in the repository
- pr: -
- notes: an investigate item; its output is items, not code. Context: nothing exists yet. The page lives in web/ and shows when a nightly job, to be created in infra/, last ran; the job writes its last-run time to a file api/ can read

Add the following instruction to the standing file. Here, home means the assigned repository. This exception permits a narrowly scoped edit to the shared queue:

Before starting work, read BACKLOG.md and take the item its pick rule names. It is the one file outside your home you may edit: only the item you hold, plus new draft items at the bottom. When it is finished, set its status and stop.

Each part, and the mistake it prevents#

The selection rule expresses your ordering policy. Lowest item number is a simple policy for this example, so choose numbers and dependencies deliberately. Changing the policy is still a human decision; the queue cannot infer which business outcome matters most.

The one-item limit keeps a session's work reviewable. The agent changes its selected item from ready to doing to review. You set done after merging code or accepting an investigation's draft children. This template defines code completion as merged; deployment requires separate verification.

Acceptance criteria describe an observable result. For health(), the result is its return value and the check is a test assertion. For a status page, finding a string in its source cannot establish that a browser fetches and displays the latest timestamp. Match the check to the claim.

Dependencies determine eligibility. An item marked ready can still be ineligible because another item remains under review. Missing or stale dependency entries cause the agent to select work in the wrong order.

The tier field groups work by the judgment it requires. judge, build, and mechanical are model-selection labels, not guarantees of model capability. Choose models using observed performance on the task, and revise the assignments when that evidence changes.

An investigation item produces proposed tasks rather than implementation. Its children stay draft until you review their assumptions, scope, and acceptance criteria. Record questions requiring your decision instead of allowing the investigation to approve its own requirements.

A worked example#

The recorded exercise used the four repositories, permission file, and queue above, with three additional build items. A fresh session received the standing file and "work the next item":

B-001 is done and set to review. `python -m pytest api/tests -q` exited 0 in
this session with 1 test passing. The work is a local commit only: `api/` has
no remote, so nothing is pushed.

**What shipped** (Home: api, spec `specs/api/002-health.md`)
- `api/src/health.py` has `health()`, which returns `{"ok": True}`.
- `api/tests/test_health.py` asserts that return value.
- Commit `30c7333` is on branch `b-001-health`, cut from `main`. It holds only
  those two files, added by path.
- In `BACKLOG.md` I changed only B-001's status and notes.
- Nothing under the spec's Out of scope changed (no HTTP server, `web/`, or
  `infra/`).

**Choices I made**
- The test adds `api/src` to `sys.path` itself. That way it imports `health`
  whether pytest runs from the project root, as the verify command does, or
  from inside `api/`.
- I left `pr` as `-` and put the commit and branch in notes, since there is no
  PR to link.

**What the spec could be read to demand that I left out**
- Nothing. It asks only for the function and a test.

**Follow-ups that deserve their own spec**
- `api/` has no remote, so the branch can't be pushed or reviewed as a PR
  until one exists.
- There is no `.gitignore`, so `__pycache__/` shows as untracked. I left it
  alone.
[one bullet about a commit hook on my machine omitted]

I stopped after this one item, as the pick rule says. B-002 is ready now that
B-001 is in review, but its dependency isn't `done` (merged) yet, so it isn't
eligible until you merge.

The transcript says "done and set to review." The actual queue status was review: the local implementation was ready for inspection, but the queue's completion rule still required a merge. B-002 remained ineligible until B-001 reached done. The passing test established the function's return value, without showing an HTTP route or deployed service.

I merged the branch and set B-001 to done. A new session selected the investigation:

I took B-002 and set it to `review`. Its output is items, not code, so I added
six draft children (B-006 to B-011) to `BACKLOG.md`, which is the only file I
edited. The file on disk matches what I wrote, and no other repo changed.

Home: specs. The work is in the queue file, not in any repo, so nothing was
committed or pushed.

**What shipped.** Each child is confined to one home, and each has an
acceptance line you can run:
- **B-006 (specs):** a spec for the last-run file contract.
- **B-007 (api):** a `last_run()` reader function, with pytest.
- **B-008 (infra):** a nightly job script that writes the file, checked with a
  temp path.
- **B-009 (web):** a `status.html` page, checked with grep.
- **B-010 (api):** an HTTP route, only if you choose the route option below.
- **B-011 (infra):** scheduling the job, which waits on your approval of a
  cloud resource.

**Choices I made, and why.**
- I set the file format to `{"last_run": "<ISO 8601 UTC>"}`, with the path
  taken from an environment variable. A missing file means the job has never
  run. Without a fixed contract the three homes can't build in parallel.
- I made B-006 the root, because the layout skill says the spec comes first.
  B-008 and B-009 also cite specs that don't exist yet
  (`specs/infra/001-nightly-job.md`, `specs/web/002-status-page.md`), so their
  notes say each needs its own spec first.
- I gave B-008's acceptance a temp-file check so it runs locally with no
  cloud.

**What the spec could be read to demand that I left out.**
- I did not write the specs themselves, because a spec is a separate change in
  the specs home.
- B-011 doesn't pretend to have an executable acceptance line. Its line is
  your written approval.

**Two questions the repo can't answer.**
1. **Where does the last-run file physically live?** `infra/` and `api/` are
  separate repos with no shared storage. I'd pick an object in a bucket that
  `infra/` creates. That is a new cloud resource, so it needs your approval.
2. **How does `web/` read it?** The options are a static `/last-run.json`
  published beside the site, or an `api/` HTTP route. I'd pick static, since
  it adds no server or web framework. If you agree, drop B-010.

**Follow-ups worth their own spec.**
- A staleness rule: when should the page flag the job as overdue?
- Job failure reporting, since a last-run time says nothing about whether the
  run succeeded.

I stopped at one item per session, as the pick rule says. B-003 is the next
ready item.

Two of the six children were recorded as follows:

## B-007 api: last_run() reads the last-run file
- repo: api
- status: draft
- depends_on: [B-006]
- tier: build
- spec: specs/api/003-last-run.md
- acceptance: python -m pytest api/tests -q passes with tests asserting
  last_run(path) returns {"last_run": "<ts>"} for a valid file and
  {"last_run": None} for a missing file
- pr: -
- notes: new function in api/src/last_run.py; health() untouched. No HTTP
  layer here (see B-010).

## B-009 web: status page shows the last run
- repo: web
- status: draft
- depends_on: [B-006]
- tier: build
- spec: specs/web/002-status-page.md
- acceptance: web/public/status.html exists and contains the text "Last run"
  and a fetch of "/last-run.json"
- pr: -
- notes: needs its own spec first. Default: static page that fetches
  /last-run.json and renders "Last run: <ts>" or "never". OWNER QUESTION: is
  /last-run.json served as a static file (job publishes it beside the site) or
  through an api HTTP route (B-010)? I would pick static, since it adds no
  server to api/.

The second run changed only the queue, producing six draft children and two decisions the repository could not answer. No application code was written. The Home: specs line identified the kind of work, while the queue itself remained outside a Git repository in this scratch example. The report correctly stated that nothing was committed or pushed.

The B-009 source-text criterion is limited: it can confirm a file contains the expected text and fetch path. It cannot confirm browser rendering or a working data source. Review that gap before approving the child for implementation. An earlier investigation prompt also omitted whether the job already existed; adding that fact removed an unnecessary clarification.

How it scales#

At the time of the original lesson, my queue held several hundred items across fourteen repositories. A planning pass reviewed answered draft and blocked items when fewer than five items were ready. That pass still needed the recorded answers and approval rules to determine eligibility.

You own acceptance criteria and model assignments. The agent can propose children, record discovered work as draft, and update the item it holds. Parallel writers require additional coordination; this template demonstrates one session at a time and does not implement a shared task lock.

From the field#

On July 28, my task runner selected three items in a row whose changes had already merged. The status-recording tool had reverted their completion states. Each run spent its effort confirming work already present in the repositories.

I added a merge-history check before selection: search for the item identifier and reconcile the queue when its work is already merged. Check that the matching commit actually implements the item before recording completion. A matching identifier alone is insufficient evidence.

Exercise#

  1. Save BACKLOG.md beside the standing file and add the instruction to read it.
  2. Replace the examples with five numbered tasks. Give each a repository, status, dependencies, acceptance criteria, and relevant spec. Turn undefined work into an investigation that produces draft children.
  3. Assign each task a model category using tier. If the task still needs requirements decisions, identify those in an investigation first.
  4. Start a fresh session with the standing file and say "work the next item." Watch it name the eligible item, work within scope, set review, and stop.
  5. Review the result and its evidence. Merge accepted code before marking its item done. Review and accept an investigation's children before completing that investigation.

You're done when#

Complete one sufficiently specified item while watching the session. Confirm the chosen item met the dependency rule, the evidence supports its acceptance criteria, only permitted queue entries changed, and the agent stopped after one item. Mark it done only after the required review and merge or acceptance.

A question about information already available in the item indicates missing context or a reading failure. A question about an unresolved product decision can be correct. The goal is to remove avoidable clarification while preserving necessary approval.

Common mistakes#

Vague acceptance criteria make review subjective. Stale status repeats completed work. Editing unrelated items can change another task's priority or requirements. Assigning an unresolved design decision to a model intended for prescribed steps does not remove that decision.

Further reading#

loop-harness provides the public schema and generator skill used in my setup. The Kanban Guide describes work-in-progress limits and workflow policies. Bill Wake's INVEST describes criteria for useful work items.

Next lesson#

Automate Code Review, Merge Checks, and Deployment Verification adds independent review and checks at each stage of a change.

Questions this post answers

What makes a task queue usable by an AI agent?
Each item has an identifier, repository, status, acceptance criteria, dependencies, and any relevant spec. A written rule tells the agent which eligible item to select, how to report its result, and when to stop. You still set priorities and approve work.
What belongs in the acceptance criteria?
Describe an observable result and how to check it. A function task can name the return value and its test. An investigation can require draft child tasks and unresolved questions for your review. Criteria must match the task's actual scope.
How should the queue handle work that is not yet defined?
Create an investigation item that asks for findings and draft child tasks. The agent reads the available project context and identifies decisions it cannot resolve. You review the children and their acceptance criteria before marking them ready.
What does the tier field mean?
Tier identifies the kind of model assignment: judge for work needing decisions, build for implementation with checkable criteria, and mechanical for prescribed steps. You choose which available model performs each category. Price alone does not establish suitability.