/pm:hierarchy is PM’s multi-agent dispatch harness. Give it a parent epic and it computes an execution plan from child priorities and depends-on links, then dispatches each child as an isolated agent in its own git worktree, converging them back through sequential merge. Everything is recomputed from current state each time — there is no “hierarchy in progress” flag to get out of sync.
Planning the execution
Before dispatching, preview the computed batches with plan-hierarchy:
This prints:
Batches run in order. Epics within a batch have no mutual dependencies and may dispatch in parallel. The dependsOn field lists each epic’s sibling ids it depends on within this hierarchy — use it to check transitively whether a later batch depends on a blocked child. A dependency cycle among children exits non-zero, naming the cycle.
plan-hierarchy is a pure read — it recomputes from current parent, priority, links, and autonomy blocks every time. There is no “hierarchy in progress” flag to get out of sync; re-running it at any point reflects current reality.
Preflight requirements
Before dispatch, every child epic in the plan must show autonomous: true. Any child that doesn’t was not cleared in the preflight step. Use set-autonomy to grant trust:
Run the full preflight scan for each child first — read its complete source, identify destructive or irreversible actions, and record your answers before setting --level autonomous. PM blocks dispatch for any non-autonomous child; do not skip the preflight.
Dispatching
Each child runs as an isolated subagent in its own git worktree on its own branch (hierarchy-child/<epic-id>). Epics within the same batch that have no dependencies on each other may be dispatched in parallel using the Task tool.
The orchestrator is the sole writer of .conductor/state.json throughout. Children never write state directly — they return a fixed report, and you apply all state transitions in one pass after the batch (marking each merged child archived). This is what makes parallel dispatch safe for the state file: there is only ever one writer, so there is nothing to merge-conflict on state.json.
Merge convergence and conflict resolution
After each child completes, merge its worktree branch back sequentially — one at a time, even though the work ran in parallel. On a merge conflict, work through the resolution ladder in order:
- Attempt the merge normally (fast path).
- On conflict, dispatch a subagent to read both sides plus the merge base and resolve it.
- If the subagent reports
STATUS: uncertain, escalate — retry with a more capable model before finalizing.
- If still genuinely unresolvable, commit the best-effort resolution and log a follow-up epic under the same parent, then continue.
Mechanical conflicts — such as a shared CHANGELOG header or usage string — resolve automatically at the merge step and are never a real logic collision.
After any conflict resolution, before committing the merge, verify that every touched file has no leftover conflict markers (<<<<<<<, =======, >>>>>>>) and that every touched .mjs/.js file passes node -c <file>. Neither check is optional and neither substitutes for the other.
A dependency cycle exits non-zero and names the cycle. Fix the offending links on the child epics before retrying. Do not retry blindly — a cycle is a real data problem, not a transient failure.
Changelog fragments
Children write their changelog entries to .changesets/<epic-id>.md, never to CHANGELOG.md’s shared ## [Unreleased] section directly. Writing to that shared header is a guaranteed merge conflict across every parallel batch. Because each child touches only its own fragment file, fragments never conflict with each other.
Use /pm:changesets to list pending fragments and consolidate them into CHANGELOG.md once, at release time.
Cleanup
After each batch, verify no orphaned worktrees remain:
This cross-references git worktree list against epic status and flags any hierarchy-child/* worktree whose epic is already archived but was not cleaned up. Once a child’s branch has merged, remove its worktree and delete its branch immediately — never leave them dangling.