ADR-0044: Unified loop model for single and multi-WI execution

Status: accepted | Date: 2026-05-31

References: RFC-0006

Context

The /loop skill needs to drive work items to completion through iterative rounds. Two distinct use cases emerged:

Single work item iteration: Agent works on one WI until acceptance criteria are satisfied
Multi-WI batch execution: Agent creates multiple related WIs with dependencies, then iterates through them as a batch

The question: should these be handled by separate primitives (/loop for single WI, /batch for multiple WIs) or a unified primitive?

Key observations:

Work items naturally form DAGs (dependencies)
The execution mechanism is identical: resolve dependencies → iterate → verify → terminate
The state model is identical: .govctl/loops/<loop-id>/ works for both
Agents already use the pattern: “batch create WIs, then iterate through all of them”

We will use the unified model: a single /loop skill that accepts one or more work item IDs.

Key design points:

/loop WI-001 drives a single work item
/loop WI-001 WI-002 WI-003 drives multiple work items with dependency resolution
Work items declare dependencies via depends_on field
Execution state lives in .govctl/loops/<loop-id>/
Downstream applications choose execution model (sequential/parallel)

This treats single-WI and multi-WI cases as the same primitive with different cardinality.

One mental model to learn instead of two.
State management is consistent (.govctl/loops/ works for both single and multi-work-item loops).
Natural support for DAGs through work item dependencies.
Agents can use the same pattern for both use cases.
Future enhancements apply to both automatically.

Initial implementation is more complex because dependency resolution is present even for single-work-item loops. Mitigation: single-work-item loops use the same planner with an empty dependency graph.
Users who only need single-work-item iteration may see multi-work-item options as overhead. Mitigation: the command surface keeps the one-work-item invocation as the simple path.
Documentation must cover both use cases. Mitigation: docs introduce the single-work-item case first, then describe multi-work-item dependency behavior as an extension.

Aligns with existing agent workflow patterns (batch create work items, then iterate).
No breaking changes to existing /gov or /quick skills.

Pros: Simpler initial implementation
Cons: Two concepts with overlapping semantics, Forced choice for users, Duplicate state management
Rejected because: Underlying mechanism is identical; separate skills create artificial distinction