# Understanding the task hierarchy

Source: https://codeherder.com/docs/hierarchy/

How work nests from initiative to epic to story, the rules that govern each level, and how to navigate the tree from the CLI and web app.

CodeHerder organises work as a tree. At the top sit **initiatives** — large, cross-team objectives. These decompose into **epics** (scoped deliverables), which in turn contain the buildable items that agents actually execute: stories, features, bugs, and tasks.

Understanding the hierarchy helps you plan at the right level, connect related work, and track progress across a whole initiative without losing sight of individual tasks.

## The built-in nesting rules

Every workspace ships with seven types. The type system enforces which types can nest under which others:

| Parent type | Accepted children |
| --- | --- |
| **Initiative** | Epics only |
| **Epic** | Stories, Features, Bugs, Tasks |
| **Story** | Features, Bugs, Tasks, Auto |
| **Feature** | Tasks |
| **Bug** | Tasks |
| **Task** | Tasks |
| **Auto** | Tasks |

A move has to clear two checks at once: the child’s type has to allow that parent, and the parent’s type has to accept that child. Both sides decide together, so a type that would normally nest somewhere can still be refused if the other side doesn’t accept it.

A few things to notice:

- **A bug attaches directly to an epic, or under a story** — wherever it belongs in your backlog. File it straight under the epic when it doesn’t need story-level detail, or under the story it was found in when it does.
- **Epics accept features and tasks directly** — not just stories. Use this when a self-contained feature or lightweight to-do belongs directly to the deliverable rather than a particular story.
- **Stories, features, bugs, and tasks may not nest under an initiative directly.** Initiatives decompose only into epics.
- **An auto task can stand on its own or sit under a story, but not under an epic** — even though an auto task allows either as a parent, an epic’s own children list doesn’t include auto tasks, so the epic side of the check refuses it. See [Auto tasks — the agent chooses the workflow](https://codeherder.com/docs/auto-tasks/).

Workspace admins can change these rules for any type — including creating entirely new types with custom parent relationships — via **Settings → Workflows**. See [Customising workflows](https://codeherder.com/docs/task-types/) for a walkthrough.

## How containers get their children

Initiatives and epics are **containers**: they never run a build stage themselves. Their `planning` stage is where a planning agent reads the spec and decomposes the work into child tasks.

A container cannot leave `planning` until:

1. The **proposal**, **design**, and **spec** fields are filled.
2. At least **one child task** has been created.

Once those conditions are met and the container advances to `in_progress`, it stays there — no agent is spawned for this stage; it simply means “child tasks are being worked”. The container closes (moves to `done`) once every child has reached an end state — cancelled or archived children included — and it cannot be closed manually while any child is still open.

For containers you create yourself rather than through an agent’s planning stage, add children by passing `--parent` when creating each child task.

## Nesting tasks manually

### At creation time

Pass `--parent` to attach a new task to an existing one:

```
ch task create --title "Add OAuth callback" --type story --parent <epicId>
ch task create --title "Investigate login crash" --type bug --parent <storyId>
```

The parent must accept the new task’s type. If the type combination is not allowed, the server returns an error explaining the constraint.

### After creation

To attach an existing task to a parent — or move it to a different one:

```
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
```

## Navigating the tree from the CLI

### See the full subtree

Print a depth-first render of everything beneath a task:

```
ch task tree <taskId>
ch task tree <taskId> --depth 2    # limit how many levels to show
```

The default depth is 5. Pass `--json` to get nested JSON instead of the ASCII tree. `ch task tree` fetches every child internally, so no `--cursor` is needed.

### See direct children

List the immediate children of a task, oldest first:

```
ch task children <taskId>
ch task children <taskId> --limit 20 --cursor <token>
```

See [Paging through long lists](https://codeherder.com/docs/using-the-cli/#paging-through-long-lists).

### See the ancestor chain

Print the full path from the root down to a task:

```
ch task ancestors <taskId>
```

The output shows the chain from root to the task — for example, Initiative → Epic → Story — so you can orient yourself without opening the web app.

## Navigating the tree in the web app

Every task detail page exposes the full tree context:

- **Breadcrumb** — the top of the page shows the ancestor chain as a clickable path. Each item links to that ancestor’s detail page.
- **Parent row** — the metadata section shows the task’s immediate parent. Click it to jump to the parent’s detail page. The Parent row also has a **Move** link — click it to open the **Move to a parent task** panel, where you search for and select a new parent (or clear it to make the task top-level).
- **Children list** — tasks that nest under this one are listed in the body of the page. Each row shows the child’s title, status, and priority.
- **+ Add child** — a button in the Children section header opens the new-task form with this task pre-selected as the parent.

The Tasks page’s [Graph view](https://codeherder.com/docs/tracking-work/#graph-view) shows the same nesting a different way, drawing a parent task as a labelled frame around its children so several branches of the tree are visible together.

## Related guides

- [Core concepts](https://codeherder.com/docs/concepts/) — the full object model: workspaces, tasks, agents, and how they fit together
- [Writing tasks an agent can build](https://codeherder.com/docs/writing-tasks/) — choose the right type and attach tasks to parent work
- [How work flows](https://codeherder.com/docs/how-work-flows/) — container pipelines and how planning decomposes work
- [Customising workflows](https://codeherder.com/docs/task-types/) — change nesting rules per type
- [Collaborating](https://codeherder.com/docs/collaborating/) — task dependencies vs. parent-child hierarchy