Understanding the task 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. Each type has two rules: the types it can sit under, and the types it accepts as children.
| Type | Can sit under | Accepts as children |
|---|---|---|
| Initiative | No limit | Epics only |
| Epic | Initiatives | Stories, Features, Bugs, Tasks |
| Story | Epics | No limit |
| Feature | Epics, Stories | No limit |
| Bug | Epics, Stories | No limit |
| Task | No limit | No limit |
| Auto | Epics, Stories | No limit |
A move has to pass both rules at once. The child’s type must allow that parent, and the parent’s type must accept that child. If either side says no, CodeHerder refuses the move.
Put together, the built-in rules allow these combinations:
- An initiative holds epics.
- An epic holds stories, features, bugs, and tasks.
- A story holds features, bugs, tasks, and auto tasks.
- A feature, bug, task, or auto task holds tasks.
A few things to notice:
- A bug attaches directly to an epic, or under a story. File it under the epic when it doesn’t need story-level detail. File it 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 small to-do belongs to the deliverable rather than to one story.
- An epic does not accept auto tasks. An auto task can stand on its own or sit under a story. See Auto tasks — the agent chooses the workflow.
- Initiatives have no parent rule. Nothing stops you putting one under a story, feature, bug, or task. Keep initiatives at the top level.
Workspace admins can change these rules for any type, or create new types with their own parent relationships, in Settings → Workflows. See Customising workflows.
Other rules for moving a task
These rules apply when you create a child and when you move one:
- Same workspace. A parent must belong to the same workspace as its child.
- No cycles. A task cannot go under itself or under one of its own descendants.
- 50 direct children. A parent holds at most 50 direct children. CodeHerder refuses the 51st. File the rest as a separate batch under another parent.
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 splits the work into child tasks.
A container cannot leave planning until:
- The proposal, design, and spec fields are filled. The proposal and design have a minimum length: 80 characters for an initiative, 50 for an epic.
- It has at least one child that is not cancelled, of a type it accepts.
To preview these checks, run ch task validate <taskId>.
When the container advances to in_progress, it waits for its child tasks. When every child is finished (done, cancelled, or archived), an agent starts in in_progress. That agent reviews the child outcomes and closes the container. Nothing closes it for you. See Waiting for child tasks to finish.
If you try to move any task with an open child to done, CodeHerder refuses and tells you how many children are still open. An agent that finishes its own task is handled differently: the task waits.
For a container you create yourself, add children by passing --parent when you create each child.
Waiting for child tasks to finish
One rule covers every task that has children. It holds for a story, an epic, an initiative and any custom type.
- While a child is open, the task waits. CodeHerder starts no agent in its current stage. The task gets no blocker and does not show as blocked.
- When the last child finishes, an agent starts in the task’s current stage. The agent’s brief has a Child tasks section with each child’s outcome.
- Nothing else moves the task. No sweep closes it or advances it. The agent moves the task through its own workflow, one stage at a time, like any other stage. Items deferred to a later stage are proved at that stage.
A child finishes when it reaches an end stage: done, cancelled, archived, or a failed end stage. A failed child still ends the wait. The agent sees the failure in its brief and decides what to do. It can create a replacement child.
If you move a task with open children to done yourself, CodeHerder refuses. An agent that finishes its own task while a child is open does not fail: the task keeps its stage and waits.
What you see
ch task show <taskId>shows a start refusal row while children are open. It readsWaits for <N> open child tasks. This stage starts again when the last one finishes.ch task statusprintsTask <title> (<id>) waits for its open child tasks. This stage starts again when the last one finishes.when an agent finishes a task early.- If an earlier agent asked for a move while children were open,
ch task show <taskId>adds ajoin-waitrow. That move did not happen. The next agent reads it in its brief. - The activity feed says Waiting for child tasks. By default the feed hides this sentence. Turn on All events to see it. See Why isn’t my task moving?.
- If all children finished but the task’s stage runs no agent,
ch task show <taskId>shows the start refusal Finished children, stage runs no agent. Move the task to a stage that runs an agent.
To see where the children stand, run ch task children <taskId>.
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, and the new task’s type must allow that parent. If the combination is not allowed, the server returns an error that explains why.
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. A task at the depth limit that has more children shows ... (+N more, raise with --depth) under it. Pass --json to get nested JSON instead of the ASCII tree. ch task tree fetches every child itself, so you don’t need --cursor.
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 is one line, root first, with each task as its title and ID joined by >. For example: Q4 launch (<id>) > Checkout (<id>). A top-level task prints no ancestors — task is a root.
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 page.
- Parent row. The metadata section shows the immediate parent. Click it to open the parent. The pencil (edit) control on this row opens the Move to a parent task panel.
- Ancestors row. When a task has a parent, this row shows the full chain. Each item is a link.
- Children list. Each row shows the child’s title with status, priority, and type badges. A child that has its own children has an expand control that shows its subtasks in place.
- Add child. This button in the Children header opens the new-task form with the parent already set. It appears only on types that other types can sit under. With the built-in types, that means initiatives, epics, and stories.
The Move panel and the Parent task picker on the new-task form list only open tasks. The Move panel also limits the list to this workspace and to the types this task can sit under. A built-in Task or Initiative has no parent rule. If it is top-level, the Parent row has no edit control. If it already has a parent, the panel offers only Move to top level. To give a Task a parent, use the CLI: ch task set-parent <taskId> <parentId>. The same applies to a Task child of a story: Add child doesn’t offer it, so create it with --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.
What a branch of the tree cost
Once a branch has recorded spend, its parent task shows what the whole branch cost. In the Tasks list, look for the total $X line under its Cost. On the task’s page, look for Total with subtasks. From the CLI, run:
ch task show <parentId>
The spend (with subtasks) row is the branch total. The spend row stays the parent’s own spend, and only that spend counts toward its budget. What one task cost explains the details.
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
- Task dependencies — how dependencies differ from parent-child hierarchy
Last updated