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

Workspace admins can change these rules for any type — including creating entirely new types with custom parent relationships — via Settings → Workflows. See Customising 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 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.

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 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 — 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 workflows — change nesting rules per type
• Collaborating — task dependencies vs. parent-child hierarchy