# Writing tasks an agent can build

Source: https://codeherder.com/docs/writing-tasks/

How to write a task an agent can actually build, with fields it can act on.

The quality of your tasks directly determines the quality of an agent’s output. A task with a vague title and no acceptance criteria will be attempted — and often not quite hit the mark. A task with a clear type, a concise description, and a concrete checklist of success conditions gives the engine everything it needs to route the task correctly and the agent everything it needs to build confidently.

## Choose the right type

Every task has a **type** (set with `--type`) that controls its workflow pipeline. CodeHerder ships with seven built-in types:

| Type | Use when | Pipeline |
| --- | --- | --- |
| `story` | A concrete, buildable unit of work that fits in one MR | `todo → plan → code → review → merge → verify → done` |
| `task` | A lightweight to-do for yourself or a specific member | `todo → code → merge → done` |
| `bug` | A defect to triage and fix | `todo → plan → code → review → merge → verify → done` |
| `feature` | Same full pipeline as story — plan-first with review, merge, and verify | `todo → plan → code → review → merge → verify → done` |
| `epic` | A scoped deliverable that groups stories | `todo → planning → in_progress → done` |
| `initiative` | A cross-team objective that groups epics | `todo → planning → in_progress → done` |
| `auto` | Let the agent decide how much workflow the task needs | `todo → auto → …` (the agent composes the rest) |

For most concrete work, **`story`** is the right starting point. A story gives an agent a brief planning stage to read the description and confirm the acceptance criteria before it writes any code — which keeps build sessions focused and traceable. Stories are auto-staffed: once you create one and fill its required fields, the engine assigns an agent and begins work automatically.

**`feature`** is identical to `story` — same pipeline, same gates, same auto-staffing. Use it when your team’s conventions distinguish “features” from “stories”, or when the parent epic expects feature-typed children. Use **`task`** for lightweight to-dos, including work you want to direct at a specific person with the **Assignee** dropdown. An unassigned `task` auto-staffs like every other built-in type.

**`epic`** and **`initiative`** are containers — they group child work items and never run a build stage themselves. A container’s `in_progress` status means “child tasks are being worked”, not “an agent is coding”. See [Core concepts](https://codeherder.com/docs/concepts/) for the full hierarchy rules and [How work flows](https://codeherder.com/docs/how-work-flows/) for the stage machine.

**`auto`** hands the pipeline decision itself to the agent: instead of you picking `story` versus `task`, the agent reads the work and composes a workflow proportionate to it, from the same stages your other types are built from. Reach for it when the right amount of process isn’t obvious up front. See [Auto tasks — the agent chooses the workflow](https://codeherder.com/docs/auto-tasks/) for the full walkthrough.

## Create a task

```
ch task create --title "Add password-reset flow" --type story
```

`--title` is required. `--type` defaults to `task` if omitted. The command prints the new task’s ID — copy it, as you will need it to set fields in the next step.

### Title and description — three input forms

Both `--title` and `--description` accept three ways to supply text:

- **Inline**: pass the text as a quoted string — `--title "My task"`.
- **File**: `--title-file <path>` (or `--description-file <path>`) reads straight from a file.
- **Stdin**: `--title-file -` reads from stdin, and so does bare `--title -`.

At most one of `--title` or `--description` may read from stdin in a single invocation. See [Using the ch CLI](https://codeherder.com/docs/using-the-cli/#supplying-text-inline-a-file-or-stdin) for how these forms work across the rest of the CLI, not just task creation.

`--description` is optional. When omitted, no description is stored; you can add or change it later — see [Editing and cancelling tasks](https://codeherder.com/docs/editing-tasks/).

```
# Description from a file:
ch task create --title "Deploy OAuth callback" --type story --description-file brief.md

# Title from stdin:
echo "Add rate limiting" | ch task create --title - --type story
```

### Priority

`--priority` controls the order in which the engine picks up tasks. Valid values: `high`, `normal` (default), and `low`. High-priority tasks are staffed before normal, and normal before low.

```
ch task create --title "Fix login crash" --type bug --priority high
```

### Parent task

Pass `--parent <taskId>` to nest this task under an existing one at creation time. The parent must be a type that accepts children of this task’s type — stories attach to epics, features and bugs attach to epics or stories, and plain tasks have no restriction. For how to re-parent or detach an existing task, see [Attach to parent work](https://codeherder.com/docs/writing-tasks/#attach-to-parent-work) below. For the complete nesting rules, see [Task hierarchy](https://codeherder.com/docs/hierarchy/).

### Dependencies

`--depends-on` declares an upstream task that must reach `done` before this task can advance. Repeat the flag to declare multiple upstreams at once:

```
ch task create --title "Deploy new API" --type story \
  --depends-on <migrationTaskId> \
  --depends-on <schemaTaskId>
```

CodeHerder blocks every forward stage advance — planning stages included — until each upstream finishes. An upstream satisfies the gate however it finishes; if it’s cancelled or archived rather than completed, CodeHerder leaves a note on this task saying the upstream’s work never landed, so a human can judge whether the task should still go ahead — see [Task dependencies](https://codeherder.com/docs/collaborating/#task-dependencies) for the full model, including what happens after creation (adding edges, removing them, and viewing the dependency graph).

### Due date

`--due-at` sets a deadline. Pass an RFC 3339 timestamp:

```
ch task create --title "Security audit" --type story --due-at 2026-07-01T00:00:00Z
```

The due date isn’t shown in the task list or on the web app’s task detail page — `ch task show` is the only place it’s visible. To update or clear it after creation, see [Editing and cancelling tasks](https://codeherder.com/docs/editing-tasks/).

### Base branch

By default a task’s sandbox branches from your repo’s default branch, and its merge request lands there too. Pass `--base-branch` to build against something else instead — a release branch, say:

```
ch task create --title "Backport the auth fix" --type story --base-branch release/2.1
```

See [Choosing a task’s base branch](https://codeherder.com/docs/base-branch/) for how to change or clear it after creation, and how CodeHerder resolves one when a task doesn’t set it.

### Required capabilities

Pass `--cap` to signal that this task needs a specific capability — such as a language skill or model tier. Repeat for multiple requirements:

```
ch task create --title "Write Go migration" --type story --cap go --cap model:opus
```

This is a hard requirement, not a preference: only an agent whose launch config covers every capability you list can ever run the task, and a set no launch config can satisfy leaves the task stuck. If a task is already stranded on a typo’d or no-longer-covered capability, fix it in place with `ch task edit <taskId> --cap <label>...` or clear it with `ch task edit <taskId> --clear-caps`, rather than recreating the task. For a full explanation of how capability routing works and what to do if a task is not being picked up, see [Agents and the CLI](https://codeherder.com/docs/agents-and-cli/) and [Capabilities](https://codeherder.com/docs/capabilities/).

## Fill required fields

Each type has fields the engine checks (via stage gates) before advancing to the next stage. Set them with `ch task edit`, passing the field key as a flag:

```
ch task edit <taskId> --<fieldKey>-file <path>
```

| Type | Gate-required fields |
| --- | --- |
| `story` (built-in workflow) | `acceptance` and `plan` (at `plan`); `artifact` (at `code`); `verification` (at `verify`) |
| `task` | `artifact` (at `code`) |
| `bug` | `repro` (at `plan`); `artifact` (at `code`); `verification` (at `verify`) |
| `feature` (built-in workflow) | `acceptance` and `plan` (at `plan`); `artifact` (at `code`); `verification` (at `verify`) |
| `epic` | `proposal`, `design`, `spec`, plus at least one accepted child — a story, feature, bug, or task (all at `planning`) |
| `initiative` | `proposal`, `design`, `spec`, plus at least one child epic (all at `planning`) |

This is the built-in `story` and `feature` workflow. A workspace that has customised either one keeps its own gates instead, so run `ch task fields <taskId>` on any single task to see exactly what it requires.

The `plan` field holds the planning agent’s implementation plan — what it intends to build and how. The planning agent writes it while the task sits at `plan`, and the stage gate holds a story or feature at `plan` until both `plan` and `acceptance` are present.

The `artifact` field holds the merge request or commit link that the code agent opens. It is filled automatically by the agent and enforced by the `code` stage gate — the task cannot advance to `review` until it is set.

The `verification` field records proof that the merged change works on the default branch. Like `artifact`, it is filled automatically — here by the verify-stage agent — and enforced by a stage gate: a story, feature, or bug cannot advance from `verify` to `done` until it is set.

For a bug, supply concrete reproduction steps:

```
ch task edit <taskId> --repro-file repro.md
```

Read any field’s current value back with `ch task field`:

```
ch task field <taskId> acceptance
```

Run `ch task fields` to list every field the type declares — set or not, and whether each is writable right now:

```
ch task fields <taskId>
```

See [When a field can be written](https://codeherder.com/docs/editing-tasks/#when-a-field-can-be-written) for what the lock means.

To check readiness instead, see `ch task validate` below.

## Write acceptance criteria

For `story` and `feature` tasks on the built-in workflow, `acceptance` is one of two fields the stage gate checks before the task can advance out of `plan` — the other is `plan`, the planning agent’s implementation plan (see [How work flows](https://codeherder.com/docs/how-work-flows/)). A task missing either one cannot leave `plan`.

Set acceptance criteria from a file:

```
ch task edit <taskId> --acceptance-file criteria.md
```

Acceptance criteria are a checklist, not a plain list. Write each item as a GFM task-list line (`- [ ]`), and the task page renders it as a tickable checkbox with a progress badge showing how many items are done:

```
- [ ] Login form accepts email and password
- [ ] Invalid credentials show a clear error message
- [ ] Session persists across page reloads
- [ ] Successful login redirects to the dashboard
```

Ticking an item is how a criterion gets signed off. **Every item must be ticked before the task can advance to `merge` or `done`** — an unticked item blocks the close. This is separate from the presence check above: the **stage gate** lets the task leave `plan` once the field is written; the **checklist gate** additionally requires every item ticked before the task can reach `merge` or `done`.

Tick items by clicking the checkbox on the task page, or by editing the marker (`[ ]` → `[x]`) and re-saving the field:

```
ch task edit <taskId> --acceptance-file criteria.md
```

A plain bullet list without `[ ]` still renders as text, but none of its items count as checklist items — no checkboxes, no progress badge, and nothing to tick before closing. Use `- [ ]` items for every criterion you want tracked and enforced.

Avoid vague items like “the feature works” or “the code is clean”. The agent reads the acceptance criteria literally when deciding what to build, and so should you when reviewing and ticking the result. If an item could be satisfied without the agent actually solving the underlying problem, tighten it.

To check whether a task’s required fields are filled before the engine tries to advance it:

```
ch task validate <taskId>
```

`validate` runs the **rigor gate** as a dry run and reports any missing fields. This is related to the stage gate but not identical: the rigor gate only checks fields marked required outright — like `acceptance` or `repro` — while an agent-filled field like `plan`, `artifact`, or `verification` is enforced by the stage gate at transition time and never shows up in `validate` ’s output. See **Planning stages and stage gates** in [How work flows](https://codeherder.com/docs/how-work-flows/) for the distinction. `validate` exits 0 if the task is ready to advance, 2 if there are violations.

## Attach to parent work

To nest a task under a parent at creation time, pass `--parent`:

```
ch task create --title "Implement OAuth callback" --type story --parent <epicId>
```

The parent must be a type that accepts this task’s type as a child. Stories attach to epics, features and bugs attach to epics or stories. Plain tasks have no parent-type restriction. See [Task hierarchy](https://codeherder.com/docs/hierarchy/) for the full set of rules.

To attach an existing task to a parent (or move it):

```
ch task set-parent <taskId> <parentId>
```

To detach a task from its parent and make it a root-level item:

```
ch task set-parent <taskId> --clear
```

## What the engine does next

Every built-in type is **auto-staffed**: once an unassigned task of one of these types is created and its first-stage fields are ready, the engine assigns a capable idle agent and begins work automatically. That’s initiative, epic, feature, bug, story, task, and auto. You do not need to assign anything manually; the engine handles routing.

`task` is the lightweight to-do type, and it auto-staffs too. See [Assigning and claiming work](https://codeherder.com/docs/assigning-work/) to direct a `task` at yourself or another member via the web app.

---

For the full list of pipeline stages and how the stage gate works, see [How work flows](https://codeherder.com/docs/how-work-flows/). For the object model behind types and their hierarchies, see [Core concepts](https://codeherder.com/docs/concepts/). For monitoring a task after it starts, see [Finding and tracking your work](https://codeherder.com/docs/tracking-work/).

## Related guides

- [How work flows](https://codeherder.com/docs/how-work-flows/) — the stages every task moves through
- [Assigning and claiming work](https://codeherder.com/docs/assigning-work/) — who ends up working a task
- [Approvals & staying in control](https://codeherder.com/docs/approvals/) — gate advances behind a designated approver
- [Reviewing an agent’s work](https://codeherder.com/docs/reviewing-work/) — the human side of the review stage
- [Why isn’t my task moving?](https://codeherder.com/docs/task-not-moving/) — diagnose a stuck task
- [Writing in the house prose style](https://codeherder.com/docs/writing-style/) — the plain-English style CodeHerder asks every agent to write descriptions, comments, and hand-off notes in