deepwork

Give Deepwork a goal and a team of agents works it, with the kanban board as the task list:

1. Deepwork breaks the goal into tickets.
2. Each ticket gets a lead agent that takes it through its phases with its own sub-agents.
3. Leads run in parallel, in waves.
4. Rounds repeat until the goal is done, nothing is left, progress stalls, rounds run out or the budget is spent.

A goal that changes code in a git repository runs the dev flow. You approve the design and the plan. Each code ticket is written test-first in its own git worktree, with one commit. Every commit is verified and reviewed (with verify=off, accepted as written), then landed on the run branch. The whole branch is reviewed, and you choose how it finishes. Other goals (research, reading, analysis) run the plain flow: you approve the plan and each ticket is worked and verified. When at least two tickets finish with a result, and the run was not stopped, blocked or over budget, one last ticket merges the results into a single verified report that cites the ticket behind every claim (synthesize=off turns it off).

Deepwork needs only the harness, state, kanban and ide workers.

Profiles

Profile	What it does	Model to pin
deepwork	the orchestrator you talk to	none: uses the session's
deepwork-lead	runs one ticket through its phases	a fast, cheap one
deepwork-worker	research, reading, analysis	optional
deepwork-impl	writes the failing test and the code, and commits	a strong one
deepwork-adversary	verifies and reviews each ticket (the default checker)	a mid-tier one
deepwork-verifier	base of the checkers, used for judges	none: each judge sets one

Every profile except deepwork is hidden.

Install

iii trigger directory::download-kit kit=iii/deepwork apply=true --timeout-ms 1200000

Sometimes the reply is a plan instead of an install. That happens when there are warnings or decisions, for example a profile with the same id already exists. Review the plan and apply it in the ADE under Directory → Kits, or run:

iii trigger directory::kits::apply plan_id=<plan_id> --timeout-ms 1200000

Applying can take minutes. If the command times out, the apply keeps running, so check Directory → Kits instead of running it again.

Pin the models

The kit ships without models because it can't know your providers. Add a model: :: line to these files:

• agents/deepwork-lead.md
• agents/deepwork-impl.md
• agents/deepwork-adversary.md
• agents/deepwork-worker.md (optional)

Use the provider::model form so reasoning_effort reaches the provider. Kit updates keep your edits.

A tier without its own model uses the one set on Default (agents/default.md). If Default has none, it uses the orchestrator's model. An unpinned lead spends one turn per phase on that model. With judges=, deepwork-verifier must resolve no model at all, Default included, or the run won't start.

Run it

In the console, pick Deepwork and type the goal. To change the defaults, add an args: line:

Add per-user rate limits to the login route.
args: max_rounds=2 concurrency=4 budget_usd=5

Arg	Default	What it does
flow	auto	dev for code goals in a git repository, plain for the rest. Set it to force one
approve	on	waits for you on open design questions and on the plan, and in the dev flow on the finish. off runs straight through and keeps the branch
synthesize	on	in the plain flow, ends the run with one ticket that merges the done tickets' results into a single report, verified like any other ticket. It runs when at least two tickets are done, and not after a stop, a block or the budget. off reports per ticket
plan_only	off	on plans and stops: the run ticket and its cards go on the board, nothing runs. Edit the cards, then start with resume=
isolation	ticket	in the dev flow, each code ticket works in its own worktree, branched from the run branch and landed on it when verified. shared runs every ticket in the run worktree, so tickets that share a file or a test target wait for a later wave
max_rounds	3	rounds over the queue
attempts	2	tries per ticket per round. A rejected try is retried with the reasons
concurrency	8	leads per wave, at most 8. A ticket waits for its Depends on: tickets. With isolation=shared, tickets that share a file never share a wave
verify	on	checks each ticket
verifier	deepwork-adversary	the checker profile: deepwork-adversary* or deepwork-verifier*
judges	–	comma-separated model ids. One deepwork-verifier per model checks each ticket and the majority wins. At most 7 in the dev flow, 8 in the plain flow
deadline_min	20	minutes each phase gets
critic	on	one last check for anything missing once the queue is empty. In the dev flow, this is the branch review
max_items	5 × concurrency	the most tickets a run creates
budget_usd	–	soft cost cap. It is checked before each wave, and no new wave starts once it is reached. A model without catalog pricing, or a call without usage, isn't counted, so the cap can be overshot
notify	–	a function id that gets the final report, such as a Slack or email send
project	–	an existing kanban project (id or name) for the run. Without it, each run creates its own project, deepwork: ·
release	–	an existing kanban release (id or name). Agents can't create releases
resume	–	the key of an earlier run ticket to pick up from the board instead of planning anew (see Resume a run)

Hard cost cap

The console only has the soft budget_usd. For a hard cap, start the run from the CLI:

iii trigger harness::send --json '{"message":"<goal + args>","model":"<provider::model>","options":{"agent":"deepwork","max_cost_usd":5,"max_total_tokens":2000000}}'

You must pass model, because the profile sets none. Every model the run uses needs catalog pricing, judges included. The design, plan and finish questions show up in that session in the console. Pass approve=off to skip them.

The dev flow

1. Design. Deepwork reads the repository and asks about anything the code can't answer. It asks one question at a time and offers two or three options, with its own pick first.

2. Plan. The design goes on the run ticket. Each task becomes a subtask with Files:, Test first:, Implement:, Verify: and Commit: lines. You answer one card: Start, Stop, or type your changes. If you type changes, Deepwork rewrites the plan and asks again.

3. Worktree. The run gets a new branch, deepwork/, in .worktrees/. That folder is excluded locally, so your checkout is untouched. Run Deepwork from the repository's top folder. The test suite runs once to get a baseline. Each code ticket then works in its own worktree, .worktrees/-, on a branch off the run branch. A fresh copy may need an install step before it builds (a Node project): Deepwork reads it from the repository and runs it in each ticket worktree. Build output is never shared between worktrees, so a compiled project builds once per ticket.

4. Code tickets. Each code ticket follows four steps:

   1. Write a failing test.
   2. Write the least code that makes it pass, and commit once.
   3. Verify and review the commit, side by side. Verify re-runs the Verify: lines. Review checks that the tests are unchanged and nothing outside Files: moved.
   4. Land the commit on the run branch. A conflict with a sibling is a rejection, retried next round on the new base.

   A rejection goes back to the same code session with the reasons. Research tickets in the same run are worked and verified without a commit.

5. Branch review. Once the queue is empty, one reviewer runs the full test suite and the linter and reviews the whole diff. Its findings become tickets for the next round.

6. Finish. You pick one: merge into your branch, push and open a PR, keep the branch, or discard it.

Sub-agents work only inside their worktree. They never push, merge, rebase, reset, switch, stash or clean. Deepwork pushes or merges only when you pick that at the finish. Loose ends the goal doesn't need become Backlog subtasks labelled pending.

The board

• Run ticket. It is titled deepwork: and labelled dw:run. Every ticket of the run is its subtask, so its page shows the run's progress. Each round adds a comment with the cost.

• Queue. The subtasks in To do are the queue, in board order. In progress means a lead is on the ticket. The session tree shows each lead as ·