Best practices

Keep people on the decisions

Agents do the work; people decide what matters. Make that boundary explicit in the instructions.

Park, do not guess

Give roles an outcome that adds a stop label, and tell them when to use it.

outcomes:
  prepared: {add: [ready]}
  needs-human: {add: [needs-human]}

One ask per decision

Each --action is one sentence a person can act on without reading the log: who, the choices, a recommendation.

Merges that need a person

Let the integrator hand some merges to you, such as changes to the workflow files themselves.

integrator:
  outcomes:
    merged: {}
    maintainer-merge: {add: [needs-human]}