Auto tasks — the agent chooses the workflow

File a task whose workflow the agent picks for itself from your stage library, and set the floor and ceiling that bound what it may pick.

Most tasks run a fixed pipeline: a story always plans, builds, gets reviewed, merges, and gets verified. That’s the right amount of process for most work, but not all of it. A one-line typo fix doesn’t need a review stage and a verify stage, and a risky change might need more scrutiny than the default gives it. An auto task hands that judgment call to the agent itself: file the task, and an agent reads it and builds its workflow to fit, picking only the stages the work actually needs from your workspace’s stage library.

Filing one

Create it like any other task, with --type auto:

ch task create --title "Rotate the staging API key" --type auto

From the web app, open the New task form and pick Auto from the type list.

An auto task can stand on its own, or nest under a story. It cannot attach to an epic — see Understanding the task hierarchy for the full nesting rules. Like most types, it’s staffed automatically: once you create one, CodeHerder assigns an agent and the composing stage starts on its own.

What happens next

An auto task starts in a stage where the agent’s only job is to decide the rest of the workflow — you’ll see it sitting in a stage called auto. It works in three beats:

CodeHerder staffs the composing stage. An agent reads the task and its acceptance criteria and judges how much process the work actually needs.
The agent selects and orders stages from the library. It reads what it’s allowed to choose from, then submits an ordered list — for example, code → merge for something small, or code → review → merge → verify for something that needs more eyes on it.
CodeHerder accepts the selection, builds the workflow, and moves the task into its first stage — all in one step. From that point on, the task runs the workflow the agent picked, just like any other task.

The agent can only pick stages that already exist in your library — it can’t write a new stage, change what a stage’s prompt says, decide whether it can commit code, or change the model tier a stage normally runs on. Every stage it selects keeps that content from your library (or CodeHerder’s built-ins) exactly as defined. What the agent does decide, beyond which stages and in what order, is how they’re wired together for this one task: how many times a stage may be sent back for rework, where a rejection routes to, and which model tier a stage escalates to if the same stage keeps getting rejected. That’s the trust boundary: the agent decides how much process a task needs and how its steps connect, never what a stage itself does.

What you’ll see afterwards

Once a workflow is composed, the task carries it as a fixed, per-task pipeline:

ch task show <taskId> prints workflow pin: auto_composed.
ch task show <taskId> also prints a composed row: the stages the agent chose, the stage it composed at, who composed it, and the reason it gave. The reason shows in the CLI only, not in the app.
ch workflow show <taskId> prints the task’s full effective workflow, every stage and setting the agent chose.
On the task page, a Custom workflow badge appears next to the status, with a Custom workflow stages list showing what the agent chose.

An auto task only composes its workflow once. There’s no second round — the composed pipeline is what the task runs from then on, the same as if you’d set a workflow override on it by hand.

Once enough auto tasks of a given type have finished, Composition outcomes is where you find out whether letting the agent choose actually helped — success rate, turnaround time, and rework, compared against tasks of the same type that ran a hand-pinned or default workflow instead.

Bounding what it may choose

By default, the agent’s choice is unconstrained beyond what your library allows. If you want tighter guardrails — every composition must include a review stage, every composition must run a given check, or every composition must stay within a named set of model tiers — set a composition policy for the workspace:

ch workspace composition-policy show
ch workspace composition-policy set --floor review --floor merge --ceiling model:sonnet --ceiling model:opus --required-verification test --required-verification lint
ch workspace composition-policy clear

--floor <stageKey> (repeatable) names a library stage every composition must include. In the example above, any auto task’s chosen workflow has to contain both a review stage and a merge stage, in whatever order and with whatever else the agent adds around them.
--ceiling <model:tier> (repeatable) is an allow-list of model tiers, not a maximum — a composition is refused if any stage requires a model tier, or escalates to one on rejection, that isn’t on the list, even a tier that sounds “lower.” That escalation tier is exactly the one the agent sets per stage, described above. Name every tier you’re willing to allow.
--required-verification <id> (repeatable) names a check every composition has to run, and run as required rather than optional. Two things have to hold: at least one stage in the composition declares that check at all, and every stage that declares it marks it required. If the check shows up but is optional on even one of those stages, the composition still fails the policy. The built-in code stage declares test and lint as optional. With the example policy above, a workflow passes only if its stage marks them required, so check your stages before you require a check.
set checks your input. Every --floor has to name an enabled stage in your workspace’s stage library. Repeating an entry in any list is refused. Every --ceiling entry starts with model:, for example model:opus or model:sonnet.
set replaces the whole policy. Leaving out --floor, --ceiling, or --required-verification when you run set clears that list entirely — it doesn’t leave the existing one in place. Pass everything you want to keep, across all three flags.
clear removes your workspace’s own policy and falls back to whatever a parent workspace sets, if anything. Clearing a workspace that never set one of its own is a no-op, not an error.
The policy inherits down the workspace tree, the same way agents, repositories, and other shared resources do. show tells you whether what you’re looking at is your workspace’s own policy or one inherited from an ancestor.
Anyone in the workspace can run show. Setting or clearing one needs a workspace owner or admin. An agent working inside a session can’t set or clear it, even with an admin role. Run set and clear as yourself.
There’s no web UI for the composition policy yet. It’s CLI and API only.

show prints the resolved policy as a short set of rows:

floor stages: review, merge
required verifications: test, lint
tier ceiling: model:sonnet, model:opus
source: —
updated by: Dana Admin (3f2c…)
updated at: 2026-10-18T09:30:00Z

An empty ceiling prints as (unconstrained) rather than a blank row, since with no ceiling set, every model tier is allowed. The source row reads — for a policy that’s the workspace’s own, or inherited from <workspace> when it’s coming from a parent workspace instead. The updated by and updated at rows appear for a workspace’s own policy.

To preview what the agent may pick for a task, run ch workflow composable-stages <taskId>. Any workspace member can run it. It prints the floor, the tier ceiling, and every stage the agent may select.

The policy applies wherever a workflow is chosen, not only to what an auto task composes for itself. These are all checked against the same floor, ceiling, and required verifications:

a workflow you pin by hand with workflow overrides
a workflow an admin saves from the stage library, as described in Customising workflows
a workflow that is rebuilt when someone edits a stage in the stage library

A policy change doesn’t re-check tasks that already run a workflow. One carve-out is a hand-pinned workflow that names no library stages at all: there’s nothing to check the floor against, so the floor is skipped for that pin, though the ceiling and the required-verification rule still apply to it. Clearing a pin isn’t checked at all. It stops choosing a workflow rather than choosing one, so there’s nothing left to hold to policy.

If a selection violates the policy, CodeHerder refuses it and lists every problem at once: every missing floor stage, every tier above the ceiling, and every required-verification gap, not just the first one it finds. The agent gets the same list back and can fix everything and submit again. Nothing is written until a selection passes, so a refusal costs nothing.

Guardrails worth knowing

The composing stage has exactly one way forward: composing. You can’t manually advance an auto task out of its composing stage before a workflow has been chosen — CodeHerder rejects the attempt and points at the composition step instead. You can still block, cancel, or archive the task from there, the same as at any other stage.
One composition per task. Once a workflow has been composed, there’s nothing left to compose — the task’s pipeline is already set.

When not to use it

If you already know the shape a piece of work needs — a bug fix that always wants review, a small change that never does — a story, bug, or task gives you that predictably, without the composing round-trip. Reach for auto when the right amount of process is genuinely the open question: a mixed backlog of odd jobs, or work where “does this need review?” isn’t obvious until someone reads it.

Composition outcomes — see whether letting the agent choose the workflow actually paid off
The stage library — the shared stages an auto task’s agent selects from
Customising workflows — build any workflow’s pipeline from the same library
Customising a task’s workflow — the composed pipeline behaves like a per-task override once it’s set
How work flows — what a stage, gate, and reject loop actually do at runtime
Writing tasks an agent can build — choosing a type and filling required fields