Customising task types and workflows

Tailor a workspace's task types — their stages, gates, fields, and parent rules — from Settings → Task types or the ch CLI.

Every workspace ships with the same six built-in task types described in Core concepts: initiative, epic, feature, bug, story, and task. Workspace owners and admins can customise any of them — or create entirely new ones — from Settings → Task types in the left sidebar, or from the ch CLI.

Open the catalog

Navigate to Settings → Task types. The catalog table lists every type visible in your workspace:

Column	What it shows
Key	The type’s unique, permanent identifier
Label	The human-readable display name
Stages	How many stages are in the pipeline
Parents	Which types this one can nest under

Types marked Inherited come from a parent workspace. They are usable here for creating tasks, but schema edits must be made in the workspace that owns them. Workspace owners and admins can disable an inherited type for this workspace and its descendants without affecting the parent — see Disabling an inherited type below.

Creating, editing, or restoring a version of a type requires a workspace owner or admin, on the Starter plan or above — see Plans and limits. Disabling a type (including an inherited one) needs owner or admin too, but no particular plan. Agents (and members signed in as an agent account) see the same table in a read-only view.

Create or edit a type

Create a new type: click + New type (owners and admins only).
Edit an existing type: click any row in the catalog table, then click Edit.

Key and label

Every type has a key — a short lowercase identifier (for example, feature or sprint-task). The key must start with a letter and contain only lowercase letters, digits, underscores, and hyphens (a-z 0-9 _ -). The key is permanent: once a type is created, its key cannot be changed. Choose it carefully.

The label is the display name users see when creating a task, and can be updated at any time.

Stages

The Stages section shows the type’s pipeline as an ordered list. For a detailed explanation of what each stage means and how work moves through them, see How work flows.

In the editor you can:

Add a stage — click + Add stage and name it.
Reorder — use the ↑ and ↓ arrows to rearrange the order.
Remove — click ✕ next to a stage.

If you remove a stage that still has live tasks, the app prompts you to choose a surviving stage to move those tasks to before the change is applied.

Extra transitions

By default, each stage can only advance to the next stage in the pipeline. For each stage you can enable extra transitions — non-linear edges to other stages, such as a backward loop that sends a task back for rework or a skip-forward shortcut. Under each stage in the editor you will see an extra transitions from ‘’ panel with a checkbox for every other stage in the pipeline. The implicit forward step to the next stage is always present and shown as permanently checked; only the additional edges appear as editable checkboxes. Backward edges are labelled ↩ to make reject loops easy to identify.

These extra edges define which status transitions are legal for that task type. The engine only permits a transition if it is on this list (or is a standard operational transition such as blocking or cancelling), so adding a backward loop here is what allows reviewers to send a task back for rework.

Per-stage settings

Under each stage in the editor, a settings panel lets you control how agents behave when working that stage. The panel has five controls:

Required capabilities — a comma-separated list of capability labels (for example, model:opus) an agent’s launch config must carry to run this stage. This is a hard staffing gate, not a ranking signal: the engine only runs the stage on a launch config whose own capabilities fully cover this list. A stage that no launch config in the workspace covers is unstaffable — any task that reaches it queues indefinitely, with no agent ever picking it up. See Capabilities and routing in Agents and the CLI for the full explanation, including the separate, softer capability signal that only ranks agents during auto-staffing of unassigned work, or Capabilities for the complete picture across every place capabilities appear.

Writable — when checked, the agent at this stage can commit source code and open merge requests. When unchecked, the stage is planning-only: the agent reads and researches freely but does not commit any changes. See How work flows for how writable and non-writable stages fit into the default pipelines.

Gather feedback — when checked, CodeHerder prompts the agent to submit a feedback item to the Feedback inbox when the stage completes. Use this on stages where agent observations about the workflow are particularly valuable.

Max re-runs before blocking — a number that caps how many times a task can be sent back into this stage from a downstream reject loop (0 = no limit). When the cap is reached, CodeHerder automatically moves the task to blocked and files a blocker note explaining how many times the stage was re-entered and which stage to resume from; a human then decides whether to continue or cancel. The review → code and verify → code directions are tracked independently — rounds from each direction count separately against the cap on the same code stage. The built-in feature, bug, and story types default to 3 on the code stage. See How work flows for the full reject-loop behaviour.

Stage prompt — a standing instruction prepended to every agent session that works this stage. Use it to add stage-specific guidance that applies on every run — for example, directing an agent to follow a particular convention or check a specific condition before advancing.

Two further per-stage settings exist — a custom container image and a setup script for it — but the web editor above doesn’t show them; you set them from the CLI instead. See Running a stage in your own container image.

Approval gates

The toggle is available on every stage, but it only takes effect on a stage CodeHerder can leave on its own — for the built-in feature, bug, and story types, that’s the todo stage a task starts at, before any agent has picked it up. Turning it on for a stage an agent or reviewer leaves explicitly (plan, code, review, merge, verify) has no effect, since those hand-offs are never gated. For each stage, tick approval required to leave ‘’ and then configure who must approve:

By kind — any member of kind human or agent.
Specific member — pick an individual workspace member from the dropdown.

You can also enable requester can’t self-approve to enforce separation of duties: whoever approves must be a different identity than whoever requested the advance.

See Approvals & staying in control for how the approval flow works: the pending-advance state, how to approve or reject, and how to find tasks waiting on you.

Custom fields

The Fields section lists the type’s custom fields. Each field has:

Key — a short identifier, used when filling the field (for example, with ch task field).
Label — the display name shown in the web app.
Type — markdown (free-form text) or child-tasks (a list of linked subtasks) — these are the two types you can pick when adding a field here. The built-in Acceptance criteria field on story and feature tasks uses a third type, checklist: a task-list value (- [ ] / - [x]) that renders as tickable checkboxes and, on required fields, blocks the task from advancing to merge or done until every item is ticked. See Writing tasks an agent can build for how to write and tick a checklist field.
Required — marks the field as required.

Click + Add field to add a new field, or Remove to delete one.

Allowed parent kinds

The Allowed parent kinds section controls which other types this type can nest under. Check one or more parent types, or leave all unchecked to make the type top-level only.

Disable and restore

Locally-owned types

To retire a type without losing historical data, click Disable on the type’s detail page. A disabled type:

is hidden from new-task creation,
leaves all existing tasks of that type working normally.

Click Restore to re-enable it.

Disabling an inherited type

Workspace owners and admins can disable an inherited type for this workspace and its descendants, without touching the parent workspace that owns it. On the inherited type’s detail page, click Disable here. This hides the type from new-task creation in this workspace and all its descendant workspaces. The parent workspace and any sibling workspaces are not affected. Existing tasks of that type keep working normally.

While a type is disabled, its detail page shows a disabled badge. Click Restore there to remove the per-workspace disable and make the type available here again.

Note that schema edits to an inherited type — its stages, fields, and parent rules — are still only possible in the workspace that owns it. See Managing workspaces for an overview of how groups and workspaces share resources down the hierarchy.

Version history

Every time you save a type, CodeHerder records a snapshot of its configuration. The Version history panel on the type’s detail page lists every past version with its label, date, and any change note. Click Restore to roll back to a previous configuration. If the restore would remove a stage that still has live tasks, the app prompts you to migrate those tasks to a surviving stage first.

Manage task types from the CLI

Workspace owners and admins can also manage the catalog from the ch CLI — useful for scripting changes or keeping a type’s schema in version control alongside your repo.

To view a workspace’s configured types, their pipelines, and field definitions:

ch workspace task-schema show              # all types in the workspace
ch workspace task-schema show --type bug   # one specific type

In the default view, inherited types are marked [inherited]; edit those from the workspace that owns them. Add --json to print each type’s full schema as machine-readable JSON — the exact shape set expects.

Create or replace a type

ch workspace task-schema set <type> --from-file <path>

set replaces the whole schema for <type>: it creates the type if the key is new, or overwrites it entirely if the key already exists. Include every stage, gate, and field you want to keep — not just what you’re changing.

The fastest way to edit an existing type is a show → edit → set round-trip:

Run ch workspace task-schema show --json and find the entry whose typeKey matches the type you want to change.
Copy that entry’s schema object into a file (for example, bug.json) and make your edits.
ch workspace task-schema set bug --from-file bug.json

The file you pass to set is the type’s schema object — the same one show --json returns under schema. Its key field must match <type>, or be left out of the file entirely. Pass - instead of a path to read the schema from standard input.

Moving tasks off a stage you remove or rename

If set would remove or rename a stage that still has tasks sitting in it, CodeHerder refuses the change and lists which stages are still occupied. Re-run the command with a --migrate <old-stage>=<new-stage> flag for each occupied stage to move those tasks onto a surviving stage before the change is applied — the CLI equivalent of the web editor’s prompt described in Stages above. You can repeat --migrate for more than one stage:

ch workspace task-schema set story --from-file story.json \
  --migrate drafting=ready

Delete a type

ch workspace task-schema delete <type>

For a locally-owned type, this is the same soft delete as clicking Disable in the web app (see Disable and restore above): the type is hidden from new-task creation, but any existing tasks of that type keep working normally. Restore it from the type’s detail page in the web app.

Deleting an inherited type disables it only for this workspace and its descendants — the same as Disable here in the web app (see Disabling an inherited type above); the workspace that owns the type is unaffected.

Core concepts — the full object model this catalog builds on
How work flows — how a type’s stages and gates drive an agent through a task
Understanding the task hierarchy — how allowed parent kinds shape nesting
Approvals & staying in control — how approval gates fit into a stage
Running a stage in your own container image — the two per-stage settings the web editor doesn’t show