Operate Epics, Subtasks, and Dependencies

Colony represents grouped work with normal provider issues plus durable Postgres relationships. A parent epic waits in waiting-for-subtasks; child issues move through their own pinned workflows; depends_on edges block only the work that needs another issue to finish.

Decide whether work is an epic

Use an epic when the outcome cannot be delivered safely in one pull request and the child results have a clear integration point. Do not use decomposition merely to parallelize a poorly specified issue.

An epic should state:

the final user or system outcome;
boundaries that all children must respect;
known ordering or dependency constraints;
how the combined result will be verified;
whether a final human review is required.

Start decomposition

Colony can enter planning when the issue carries the epic marker, when analysis returns an epic-scale plan verdict, or when an operator explicitly requests decomposition.

Colony Cloud
Self-Host

Use Decompose from the issue action menu or file the work as an epic from Issue Intake Studio. Review the proposed breakdown before treating child creation as approval of the implementation plan.

Apply colony:epic before intake, post /colony:decompose on an eligible issue, or import a plan with the MCP/CLI epic option. Use Slash Commands to confirm the action is valid in the issue’s current pinned workflow.

Planning creates child issues idempotently and records subtask relationships. The parent then enters waiting-for-subtasks; it does not consume a development Worker while it waits. Sweep tasks periodically reconcile child completion and decide whether the parent may continue or finish.

Choose the branch model

With feature branches disabled, child pull requests target the inherited/default branch and the parent primarily coordinates completion. With epic.use_feature_branches: true, Colony creates epic/<parent>, targets child work into that branch, and produces a final integration review toward the default branch.

epic:
  use_feature_branches: true
  rebase_strategy: on-complete
  auto_merge_subtasks: true
  review:
    require_human_final_review: true

Setting	Operational effect
`use_feature_branches`	Groups child changes on an epic branch instead of merging each child directly to the default branch.
`rebase_strategy`	Controls when Colony refreshes the epic branch while children are active.
`auto_merge_subtasks`	Allows approved child PRs to merge when the rest of the policy permits it.
`require_human_final_review`	Stops the final integrated result for a person even after automated epic review succeeds.

Epic configuration is read by Workers at startup. Restart or redeploy them after changing it, and ensure branch policy permits the coder identity to update epic/*.

Understand relationship types

Relationship	Meaning	Resolution
`subtask`	The child contributes to a parent epic.	Child reaches its required terminal/merge outcome; the Sweep reconciles the parent.
`depends_on`	One issue cannot proceed until another completes.	The blocker completes or an operator explicitly changes the dependency.
overlap-derived block	In-flight work touches conflicting files or branches.	The conflicting work completes or the Mayor safely unblocks it after reconciliation.

Subtask edges are not interchangeable with dependency edges. A parent can wait for its children without every child being ordered relative to every other child.

Monitor grouped work

Start from the parent and verify its state, epic branch, pinned workflow, and child list.
Inspect each child for current state, Worker task, pull request, and blockers.
Check dependency edges when a child is dependency-blocked; do not infer the blocker only from issue text or labels.
For feature-branch epics, confirm child PR targets and the current epic branch health.
After all children resolve, watch for the Sweep task and the parent’s final review or completion transition.

Cloud issue detail, Pipeline Live, and repository status provide the normal UI path. Self-host operators can use colony issues, colony tasks, colony history, colony why, and the monitor dashboard. Provider labels/tags are projections, not the dependency source of truth.

Intervene without duplicating work

Correct a child with its workflow-valid feedback action; do not re-run decomposition to replace one bad child.
Cancel an unnecessary child explicitly and verify how the parent policy treats cancellation.
Retry the exact failed task or transition only after fixing its cause.
Do not manually merge a child into a different target branch without reconciling the provider PR and Postgres state.
Do not delete child issues or dependency metadata as a shortcut; that can strand the parent.
Reclaim a Worker task only when the Worker is dead or cannot finish it. Reclaiming a healthy long-running task can duplicate execution.

Recover a parent that still waits

Confirm every child relationship and child pipeline row exists.
Separate active children from completed, cancelled, blocked, or missing children.
Verify that completed child PRs merged into the expected target branch.
Inspect pending or failed Sweep tasks and any dead-letter records.
Fix stale provider state or the specific child failure, then allow or retry the Sweep rather than forcing the parent directly to done.

If all children are complete but the parent remains blocked, investigate stale subtask edges and monitor consistency findings. Automatic stale-edge repair is optional and capped; repeated repairs escalate for human attention.