Work Items Guide

Work items are Holon's durable unit of tracked work. Use them when an objective needs its own lifecycle, progress tracking, or cross-turn continuity.

When to Use a Work Item

Create or update a work item when the task:

spans multiple turns
needs resumable progress
waits on external state such as CI, callbacks, or operator input
has clear acceptance criteria that should be tracked explicitly

Avoid creating work items for:

casual questions
one-shot explanations
short inspections
lightweight current-turn tasks that can finish immediately

Work Item Lifecycle

A work item can be:

open — still active
completed — explicitly finished
current — the agent's active focus
blocked — waiting on a specific blocker
waiting for operator — needs clarification or approval
runnable — ready for execution

The key distinction is:

lifecycle describes whether the objective is open or completed
focus describes whether the item is current
readiness describes whether the scheduler should resume it

What a Work Item Stores

Each work item can contain:

objective — short statement of the goal
plan artifact — durable markdown file describing the intended approach
plan status — draft, ready, or needs_input
todo list — checklist of meaningful progress steps
blocked by — specific blocker when progress cannot continue
recheck deadline — fallback time for reconsidering a blocked item

Treat the work item as coordination state, not a scratchpad.

Core Operations

Typical work-item operations:

CreateWorkItem — create a new tracked objective
PickWorkItem — make an open item the current focus
UpdateWorkItem — refine objective, plan status, blocker, or todo list
ListWorkItems — inspect current, open, blocked, or completed work
GetWorkItem — inspect one work item in detail
CompleteWorkItem — mark the objective done

Example Workflow

Inspect whether the objective already has an open work item
Create one only if the objective has its own lifecycle
Edit the durable plan artifact once the acceptance boundary is clear
Update the todo list after material progress
Record blockers explicitly instead of silently broadening scope
Complete the item only after acceptance evidence exists

Plan Status

Use plan status intentionally:

draft — the objective exists, but the approach is still forming
ready — the plan is stable enough to execute
needs_input — the next step depends on operator input

This matters because the runtime can distinguish active runnable work from work that should pause.

Scheduler Readiness Model

Work item readiness is scheduler input. An open runnable work item is eligible for scheduler resume or a system tick, while blocked or waiting items should pause until their unblock condition changes.

Ending a turn only rests the agent. It does not mark the current work item as blocked, waiting, or non-runnable. If no immediate progress is possible, call WaitFor:

use wake=operator_input when operator input is required
use wake=task_result with resource=<task_id> when waiting on a task
use wake=external with resource=<external object> when waiting on an outside system such as a PR, CI run, URL, or durable inbox source
use an external trigger when an external system can actively wake the agent

Keep work items runnable only when the next scheduler resume can make useful progress. This avoids loops where an agent sleeps while leaving an open item eligible for repeated system ticks.

Todo List Best Practices

Good todo items are:

outcome-focused
durable across turns
updated after real progress

Avoid:

logging every tiny shell command
using the todo list as temporary notes
leaving stale checklists after the plan changes

Blocking and Waiting

When a work item cannot proceed:

call WaitFor with a concrete reason
use wake=operator_input if operator clarification is required
use wake=task_result or wake=external for concrete task or outside waits
attach external waiting mechanisms only when the work is truly cross-turn

This keeps the scheduler and future turns aligned with reality.

Relationship to Tasks

Work items and tasks are different:

Surface	Purpose
Work item	Tracks the objective and progress
Task	Represents running execution such as a command or child agent

A single work item may create multiple tasks over time. Tasks are execution; work items are intent and progress.

Relationship to Agents

Agents can switch focus between work items, but they should usually maintain one current tracked objective at a time. If the objective changes meaningfully, update or switch the work item before doing high-commitment work.

Common Mistakes

creating a new work item for every small sub-question
failing to update the plan after the scope changes
keeping an item open without recording the blocker
completing the item without verification evidence