When to Use Tasks
Use a task when the work:- Splits into steps that can run in parallel or must run in a specific order.
- Needs pass/fail acceptance criteria the agent can check on its own.
- Should retry or repair intermediate failures without you babysitting it.
- Might resume later — you close your laptop, come back, and the task picks up where it left off.
Anatomy of a Task
A task is defined by atask.yaml DAG. Each node is a subtask; edges are dependencies. When you run the task, Craft Agents spawns a child session per subtask, respecting the dependency order.
Subtasks with no
depends_on run first, in parallel. Downstream subtasks unlock as their dependencies complete.
Acceptance Criteria and the Repair Loop
After a subtask’s child session finishes, Craft Agents evaluates the subtask’s acceptance criteria. If a criterion fails, the runner enters a repair loop: it feeds the failure back into the child session with instructions to fix it, and re-checks. This continues until the criteria pass or the loop hits its retry cap. Write acceptance criteria as short, verifiable statements. Prefer concrete signals — a test command exits cleanly, a file exists, a URL returns 200 — over subjective descriptions.Subtask Union
When a task runs, the parent session inherits a subtask union: the combined label set, project binding, and status signals of all its child sessions. This means the task card on the Kanban board reflects the aggregate state — for example, subtask progress like3 / 5 shows how many subtasks have satisfied their acceptance criteria.
Durable Resume
Task state is persisted after every subtask transition. If you quit the app, lose power, or your machine sleeps mid-run, reopening the task resumes from the last completed subtask. In-flight subtasks either continue or restart cleanly — you never lose the DAG’s progress.The Task Editor
Open a task to see the Task Editor. It has two modes:
The Results tab collects the outputs of every subtask into one place — useful for reviewing what the agent produced without opening each child session individually. The Session binding control ties the task to a specific parent session so results and artifacts stay linked.
The task Playground is available in Manual mode only. Manual runs let you step through subtasks one at a time to inspect behavior before turning the task loose end-to-end.
Creating and Running Tasks
Any Claude- or Pi-backed session can create a Task on your behalf. The agent produces the board Task,task.yaml, and an orchestrator session in the Todo column — nothing starts running until you launch it. You can supply as much or as little as you want in the request; the agent fills in what it can:
Agent-created Tasks get a unique slug automatically, so asking for the same Task twice never overwrites an existing one. If the agent references a source or skill that doesn’t exist in the workspace, it reports the mismatch as a warning and still creates the Task so you can fix it in the editor.
You can also:
- Create a task from the Kanban board’s New Task button — it inherits the active project filter.
- Create a subtask on an existing task and run it directly from the card.
- Use Run from tile on the board to start any task without opening it first.
Tips
Keep acceptance criteria machine-checkable
Keep acceptance criteria machine-checkable
“Tests pass” beats “code looks clean”. The repair loop only helps when it has a clear signal to react to.
Start small, then split
Start small, then split
Draft the task as two or three subtasks first, run it, and split further only when a subtask keeps failing or grows too broad.
Bind tasks to a project
Bind tasks to a project
Tasks bound to a project inherit its working directory and context, so subtasks don’t have to re-establish where the code lives on every step.