Synced from Hive. This page is pulled from hivecommons/hive@v5 during the docs build. Edit the canonical source in the Hive repository.
ADR-0006: Planning intelligence with human review
Status: Accepted (retroactive)
A kick is a work prompt sent to an agent. An epic groups a large piece of work; its child tasks form a directed acyclic graph (DAG), so dependencies can be completed before the tasks that need them.
Context
Large GitHub issues can be too vague for a single agent kick. Hive needs a way
to turn an epic into ordered, claimable work without letting an agent immediately
execute an unreviewed decomposition. The planning docs describe the flow:
architect decomposition, a draft plan hidden from Ready(), a plan-review gate,
and bounded stall replanning
(planning intelligence). The package code records
the same metadata conventions and review transitions
(decompose,
plan review,
stall replan).
Decision
Use the existing architect lane to decompose an epic into child beads with
dependency edges and execution tags. Decomposition writes parent_epic,
execution, plan_ref, and plan_status metadata; draft plans keep children
out of ready queues until a human approves them. Reviewers may inspect, retag,
remove, approve, or reject children before work is released.
The automatic issue-label entry point has three separate limits:
- Default off:
planning.plan_from_labelis opt-in because it can feed attacker-controlled issue text into the architect prompt without per-kick review. - Level condition: even when enabled, it is inert below ACMM L5, where the architect is not scheduled. L6’s pack may automatically approve plans; see the L6 approval boundary.
- Retry cap: approved plans that stop making progress are re-kicked for unfinished work only, capped at five replans before human escalation.
Consequences
Hive can handle epics as DAGs instead of long-running, ambiguous agent sessions, and operators get a clear approval point before work becomes claimable. The system also preserves pause semantics: a paused architect queues decomposition instead of being force-resumed. The cost is more state and review UI surface, and deployments that opt into label planning must accept the prompt-injection exposure of routing raw issue text to the architect.