Task lifecycle

The board

In harness-demo every stage is a column on a kanban board, and a task's status is the column it rests in. One status, one column, one owner. A card shows a "working" badge while a unit is working on it.

Pick a status to see who owns it and every way out of it. The switches add the moves that exist only with full autonomy or merged review.

The board of the bookmarks project during a qa unit, with the Live dock on the right.

Who moves the card

Only two kinds of move exist, and they never mix.

You move a card when a human decision is needed: submit a draft, answer questions, approve a plan or send it back, accept or comment on a prototype, reopen a parked task. In the dashboard these are drags or buttons. A drag is allowed only along a human move, and it is refused while a unit is working on that task.

Every human move also exists as a command, for when you work from a terminal:

harness new --title "Dark mode toggle" --draft "Users want a dark theme." --kind ui
harness submit T-007        # draft → spec
harness answer T-007 Q1 a   # answer an open question, with an optional note
harness approve T-007       # planned → prototype (ui) or ready
harness revise T-007 "split criterion 2 into two checks"   # planned → plan, with what the plan should change
harness comment T-007 "move the toggle left of the avatar"
harness accept T-007        # prototype → ready
harness reopen T-007        # parked → the status it was parked from

Add --project <path> when you are not inside the project folder.

The harness moves a card after a unit ends and its contracts pass. No agent writes status directly; the runner does, from the unit's outcome.

The interview

Agents ask instead of guessing. The writer asks product questions at draft time; the planner asks questions that only appear once it has read the code. Both use the same protocol:

1. The agent appends a question to ## Questions with two to four lettered options, the recommended one first.
2. It sets status: needs-input and resume: to its own stage, and ends the unit green.
3. The dashboard shows the open questions as a picker on the card.
4. Your answer is written under the question, and the question flips to answered.
5. When no question is open, the harness moves the task back to the stage in resume.

The writer sees the other tasks on the board, so a recommended option never duplicates another task's work; the spec names such tasks in its out-of-scope list instead.

### Q1 · Where should the toggle live? · open

- (a) Header, right of the nav — recommended: visible on every page
- (b) Settings page only
- (c) Both

> **Answer:**

The task drawer of T-003 with the writer's two questions and their lettered options.

The prototype step

Tasks with kind: ui get one more stage before code. The designer builds a prototype as a route in the app and leaves a picture of it in the task's artifacts folder. With an app (the project sets app and it started), the designer opens the route in the browser and takes a 1440×900 prototype.png, plus prototype-2.png and on for more states. Without one, it draws prototype.svg: a 1440 px wide wireframe with the page's real copy, layout and colours, one column per state, nothing overlapping. The designer never starts or stops a server: the runner owns the app. The dashboard shows the picture on the card and in the drawer; a round that leaves none gets a note in ## Log, and you can still review the route. The card stops in prototype and waits for you:

• Accept moves the task to ready.
• Comment sends it back to the designer for another round, with your comment in ### Review.

Rounds are capped by limits.prototypeRounds, 3 by default. The prototype route is dropped at delivery unless the plan says to keep it.

The task drawer of T-001 on the Prototype tab, with Accept, a comment box and the round's picture.

How much autonomy

By default, with autonomy.mode: gated, the harness stops for you twice per task: to approve the plan and to review a prototype.

At the plan gate you can also send the plan back. Request changes in the Plan tab of the drawer, or harness revise, writes your comment into a ### Review block at the end of ## Plan, and the task returns to plan. The next plan round reads the newest comment and must leave the block unchanged. While the plan is back with the planner, or while a unit works on the task, a second request is refused.

autonomy.mode: full turns both gates off. A planned task moves on by itself, and a finished prototype goes straight to ready. Two things still need a human even in full mode: a draft needs Submit, and an open question needs an answer.

Branches and delivery

• The first time a task enters implementing, the harness creates the branch harness/T-NNN-<slug> from the project's base branch. That branch is the only one the scope contract allows.
• After every implement unit with a green gate, the harness commits on that branch.
• By default delivery is the commit: with deliver: { pr: false }, a task ends in done.
• The base branch must be clean before a batch. The supervisor refuses a dirty tree it did not make.

Delivery by pull request

Set deliver.pr: true in config.json, and deliver.remote if it is not origin. A done task then gets one more step. The runner does it itself: no agent, no tokens (harness/deliver.ts).

1. It checks the branch contract: the task branch exists, it is ahead of the base branch, and every commit subject starts with T-NNN:.
2. It writes the pull request body to .harness/artifacts/T-NNN/pr-body.md: the goal from the spec, the plan, each acceptance criterion with a ✓ and its command for [closes], a ✓ and its screenshot for a [found] criterion qa walked in the browser (the others stay unchecked, for a human), a line that says how many qa walked, the qa and judge verdicts with their unit numbers, and the commits.
3. It pushes the branch with git push -u <remote> <branch>.
4. It opens the pull request with gh pr create. It asks gh pr view <branch> first, so a retry never opens a second one.
5. It writes pr: <url> into the task file and moves the task from done to delivered.

Nothing ever merges. The only gh commands the harness runs are gh auth status, gh pr view and gh pr create; merging is yours. If the branch contract, the push or gh fails, the task is parked with the reason (parked: deliver: …), and Reopen retries the step.

With deliver.pr on, the supervisor checks before it starts: a remote, gh installed and logged in, and the base branch on the remote. If one is missing, it exits with code 2 and prints the fix. HARNESS_GH replaces the gh command the way AGENT_CMD replaces the agent; the self-tests use it.

The board with T-001 delivered and T-002 done, and the drawer of T-001 with its pull request link.

What one task costs

A task from draft to pull request is five agent units, each with a fresh context: spec, plan, implement, qa and judge. A UI task adds a prototype round, and an interview adds one more spec unit. Delivery is a runner step that spends no tokens. That is more than a single long session would use. The trade is visibility, since every card rests in the column that owns it, and a clean context for every role.

harness-demo measured it on a pilot: four real tasks on the bookmarks example, run by claude -p on a subscription login with the default models, gated autonomy and delivery on. Claude passed the human gates on the recommended options. All four tasks ended in an open pull request, and nothing was merged. T-005 ran after qa and the designer got a browser.

Across the pilot, harness stats counted 47 units, 5 of them the stand-in's, and 5 parked units: 24:49 of agent time, 72.1k tokens and $9.13 API-equivalent. Tokens are input plus output. Prompt-cache reads come on top and cost much less. On a subscription login the API-equivalent is what the same tokens would cost on the API, not a bill. Every failure became a contract or a prompt line with a test; the lessons page lists the general ones.