Understanding the task hierarchy

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 six task types. The type system enforces which types can nest under which others:

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

A few things to notice:

• Bugs do not attach directly to an epic. Bugs belong under a story. If you try to parent a bug to an epic, the server rejects it — file the bug under the story it belongs to.
• 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.

Workspace admins can change these rules for any type — including creating entirely new types with custom parent relationships — via Settings → Task types. See Customising task types and workflows 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 all its children have completed; it cannot be closed manually while it still has unfinished children.

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

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.

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.

Related guides

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