Split a big idea into tasks that land in order
You have a big idea. “Add team billing.” “Move us to a new login system.” You write it as one ticket and hand it to an agent.
The ticket is too big. A person would struggle with it too. Small tasks, each with a clear check, are the ones that merge. This post shows how CodeHerder turns one idea into many small tasks, and how it keeps them in order.
Write the idea once, as an epic
An epic is a container for one deliverable. You do not build it directly. You describe it, and an agent in its planning stage reads your spec and splits the work into child tasks.
The epic cannot leave planning until its proposal, design and spec fields are filled. It also needs at least one child that is not cancelled. An epic holds at most 50 direct children. If you need more, file the rest under another parent.
Our own database migration worked this way. We planned it as 10 epics and 75 stories. Each story was small enough to prove by itself.
Put the work in order
Some tasks cannot start before another task lands. A dependency states that. The task that waits is the dependent. The task it waits for is the upstream.
While a dependency is unreleased, CodeHerder starts no agent on the dependent. You choose when the wait ends. There are three release conditions:
- “Upstream is done” is the default. The dependency releases when the upstream reaches a finished stage.
- “Upstream is planned” works for epics and initiatives. The dependent needs the upstream’s child tasks to exist, but not to be finished.
- “Upstream opens its merge request” needs Stacked dependencies. The next section explains it.
To add one from the CLI:
ch task depends-on <taskId> <upstreamTaskId>
ch task depends-on <taskId> <upstreamTaskId> --release-when planned
For developers: stacked dependencies
Say task B builds on task A. Without stacking, B waits for A to merge. With stacking, B starts as soon as A opens its merge request.
The setting is off by default. A workspace admin turns it on in Settings → General, or runs ch workspace edit <workspace> --stacked-dependencies on.
Then this happens:
- The upstream opens its merge request. The dependency releases.
- The dependent starts on the upstream’s branch. Its merge request targets that branch.
- The dependent reaches its merge stage, but waits there until the upstream merges.
- After the merge, the agent retargets the merge request to the base branch. If the host squash-merged the upstream, the agent also rebases.
Keep stacks about three tasks deep. A deeper stack means more rebases after each merge.
Some repo settings work against stacking. Squash-only merges are one. Branches that do not delete after merge are another. Run ch workspace stacking-check to list them.
When the plan changes
Plans change. CodeHerder handles the common cases like this:
- If an upstream is cancelled, its dependents are still released. A comment on each dependent says the upstream’s work did not land. An agent or a person decides what to do next.
- If you add a dependency to a task already underway, CodeHerder discards that task’s in-progress work and returns it to its first stage. It restarts from current main when the dependency releases. Set dependencies before work starts where you can.
- A parent waits until its last child finishes. An agent then reads each child’s outcome and closes the parent. Nothing closes it for you.
See the whole picture
The Tasks page has a Graph view. It draws a parent as a frame around its children. A task that waits on a dependency shows a Waiting on N badge. Its page lists the upstreams in a Waiting on dependencies box.
A parent also shows what its whole branch cost. Look for Total with subtasks on its page.
What it does not do
- A task cannot depend on itself, and dependencies cannot form a cycle. The server refuses both.
- A dependency cannot wait on a person or on a release. Use a blocker for that.
- Stacked dependencies belong to one workspace. Child workspaces do not inherit the setting.
- The tree does not write your spec. A vague epic gives vague children.
Next steps
Write the epic’s brief first. Writing a brief shows what a good one holds, and the starter briefs give you a place to begin. For every rule and command, read the docs on the task hierarchy and task dependencies.