Loop mode: lead and worker

The lead assigns work, reviews each result and moves the task through its stages. A human accepts the final result and resolves stops requiring a decision.

How work proceeds

1. The lead reads the task and acceptance criteria, then assigns the next piece of work.
2. The worker carries it out and submits a result.
3. The lead reviews it, requests changes, starts the next stage or finishes.
4. A human receives the whole task for acceptance. Rejection returns to the lead.

Intermediate handoffs do not require individual human approval. The worker has a report per execution; the latest submitted report is available at acceptance and previous reports are retained.

Learning example

In the prepared product-filter story, the lead finds a problem, accepts the fix and starts verification. A limit of two handoffs stops the story before further work. Learning examples use prepared data; they do not run AI or execute feedback text.

LEAD ↔ WORKER

Product availability filter

The lead assigns work and reviews every worker result.

• LeadAssignments, feedback, stages
  Now
• WorkerChanges and reports
• YouAcceptance and decisions at stops

Lead ⇄ Worker
Lead → Human acceptance

Handoffs to worker 0 / 4

Task stage 1 / 2

LEAD

The lead prepares the first assignment

The task is a product availability filter for the selected warehouse. The lead splits work into implementation and verification.

• Stage 1: filter using the selected warehouse.
• Stage 2: checks and a result for acceptance.

Example round limit

2

4

6

Choose 2 to see a stop. The GrigDesk profile default is 20.

Example history · 1

1. The lead received the task. Handoffs to worker: 0.

A prepared example without running AI or commands. Buttons advance the story; in GrigDesk the pair works automatically until acceptance or a stop.

The lead prepares the first assignment. Handoffs to worker: 0 of 4.

When to choose a loop

Use a loop for work that can be split into verifiable pieces. Give the lead clear criteria, access to results and change boundaries. If a plan must be approved before implementation, configure a route with a separate gate.

Loops organize execution; they are not task kinds alongside feature, debug or perf.

Pair and transition configuration

The route loop field connects two different agent nodes:

"loop": {
  "lead": "review",
  "worker": "implement"
}

This is a definition fragment, not an importable route. A return arrow alone does not enable loop mode. Prepare a complete definition, import a draft, validate and publish it.

The pair must satisfy these constraints:

• Both nodes use type agent and phase main.
• In sequence.main the worker immediately precedes the lead, but the lead is the route entry.
• Worker outcomes done, skipped and failed use next to the lead. Rejections for build, tests, plan and human also return there; environment may have a separate action.
• Lead failed, build and tests outcomes return to the worker with rewind, resetting both pair nodes.
• Both nodes have retry.productFailure: 0.
• There are no other automatic returns, direct worker entries bypassing the lead or escalations to other routes. Human gates may return work to the pair.

Connect lead success to final acceptance and human rejection back to the lead. The loop field does not create nodes, instructions or gates.

Instructions and runners

The lead instruction defines review criteria, assignment rules, stage and task completion, and decisions requiring a human. The worker instruction defines change boundaries, checks and report content.

Moving to a new stage must close previous findings and rely on a new worker result. Renaming an assignment does not start a new progress series. The total round count persists between stages.

Runners and models are selected by runKey in launch policy. loop defines roles rather than providers.

Round limit

One round is one completed handoff from lead to worker, including the first. A worker reply does not add a round. A handoff stopped by the limit is not spent.

PROFILE_LOOP_MAX_ROUNDS=20

The allowed range is 1–100, with a default of 20. Empty values, zero and out-of-range values are rejected before model launch. The setting is read at start, continuation and gate decisions. Ordinary routes are unaffected.

This limits handoffs rather than tokens, cost or runtime. Stage changes, acceptance feedback and limit increases do not reset spent rounds.

Stops requiring a decision

Stop	Next action
no-progress	Investigate repeated findings, provide new information or resolve the decision, then return work to the appropriate node.
rewind-limit	Inspect the current stage's return history. Raising the overall limit does not resolve this stop.
loop-ceiling	Assess remaining work; increase the profile limit if needed, then Continue.
Environment unavailable	Restore the named preview, tool or dependency.
Decision outside agent authority	Answer the specific question. The lead cannot independently remove criteria or alter baseline measurements.

Without a higher limit, continuing after loop-ceiling leaves the task waiting and does not start a model. Raising the limit resumes the prepared handoff with results and counters preserved.

Progress checks and automatic return series limits still apply. Automatic rethink is not part of loop mode. The stall arbiter does not handle loop attempts, including manual analysis.

Before running

1. Validate the draft and both instructions.
2. Set the round limit in the editor's trial scenario. This does not change the profile.
3. Simulate handoff, feedback, acceptance, rejection and limit exhaustion.
4. Publish and run a small task with clear criteria.

Simulation checks transitions and the limit. It does not model stage-boundary recognition or progress failures requiring real node results. Running attempts retain their pinned routes.

Continue with execution and acceptance or workflow selection.