Spec Agent Autonomy and Human-in-the-Loop Points

Workflow area: Agents & Responsible AI · Tier: Advanced · Hands-on time: ~45 minutes

The central product decision in any agentic feature is not which model or framework — it's how much rope. Autonomy is not a feature-level setting; it's a per-step decision. The same agent can safely draft an email (wrong draft costs nothing) and must never send one unsupervised on day one (wrong send costs a customer). Teams that spec autonomy at the feature level ship either a toothless demo or an unaccountable actor. The behavior spec makes rope a designed quantity: earned per step, bounded by undo, and revocable in one click.

When to use — and when not to

• Use it whenever an AI feature takes actionscalls tools, writes to systems, sends communications, spends money. Generation-only features need pb-40's bars, not this.
• Use it before the build startsautonomy retrofitted after an incident becomes a blunt "turn it off," destroying the value with the risk.
• Use it when stakeholders disagree on how autonomous "the agent" should bethe per-step decomposition dissolves most standoffs, because the disagreement is usually about two different steps.
• Skip the ceremony for read-only agentsan agent that only gathers and summarizes needs citation quality control, not an autonomy ladder.
• Skip agent framing entirely when the job is a fixed pipelineif the steps never vary, spec a workflow with AI inside steps; agents (dynamic step choice) add failure modes a deterministic pipeline doesn't have.

The recipe

1. 1.

   Decompose the job into steps and sort: workflow or agent. List every step from trigger to done. For each, ask: is the sequence fixed (workflow — the system decides nothing about what to do next) or does the system choose its next move based on intermediate results (agent)? Most "agent" features are 80% fixed pipeline with two genuinely dynamic steps. Only the dynamic steps need the autonomy treatment; the rest need ordinary engineering.

2. 2.

   Assign each acting step an autonomy tier. Use a four-tier scale: T0 suggest (output shown, human does the action) · T1 draft (action prepared, human approves each one) · T2 act-with-review (action executes from an allowlist, human reviews async, undo guaranteed) · T3 act (autonomous within bounds, sampled audit). Assign by two axes: reversibility and blast radius. The rule that survives review: nothing irreversible above T1, ever; T3 only for steps with proven T2 history.

3. 3.

   Draft the behavior spec with AI, then harden it. Paste your step table:

   Copy

   Write an agent-behavior spec from this step decomposition.
   Job: [WHAT THE AGENT ACCOMPLISHES END-TO-END]
   Steps: [LIST — each with workflow/agent, proposed tier T0-T3,
   the action taken, and what a wrong action costs]
   Tools available to the agent: [SYSTEMS IT CAN READ/WRITE]
   
   For each acting step produce:
   - PRECONDITIONS: what must be true before the agent may act
   - BOUNDS: allowlisted actions, rate limits, value limits (e.g.
     max refund amount, max emails/hour), scope limits (which
     accounts/records)
   - HITL POINT: exactly where the human enters — what they see,
     what they approve, their timeout behavior (act or halt on
     no-response?)
   - UNDO: the reversal procedure and its time window
   - ESCALATION: conditions that force a hand-off to a human
   Then: the global kill switch (who flips it, what state the
   system degrades to), and the promotion criteria to move any
   step up one tier.
   

   Sample output for one step:

   Copy

   STEP: issue refund (agent-chosen remedy) — T1
   Preconditions: verified purchase, amount ≤ $200, no fraud flag.
   Bounds: refund tool only; one refund per ticket; may not modify
   the order record.
   HITL: agent posts refund + one-line rationale to queue; support
   lead approves; timeout 4h → halt and notify (never auto-act).
   Undo: refund reversal within 30 days via finance tool.
   Escalation: amount > $200, repeat-refund customer, or agent
   confidence below threshold → route to human with full context.
   Promotion to T2: 200 consecutive approvals with ≥98% approval
   rate and zero fraud-flag misses, reviewed by PM + support lead.
   

4. 4.

   Design the HITL points as UX, not checkboxes. An approval queue that shows raw agent output gets rubber-stamped within a month. Spec what the approver sees: the proposed action, the evidence it's based on (quoted, linked), what changes if they decline, and batch affordances that don't collapse into approve-all. Measure approval-queue health (time-in-queue, decline rate) — a 0% decline rate means the human is decoration, and your T1 is a de facto T3.

5. 5.

   Map it visually and pressure-test the kill switch. One Miro board: steps left to right, tiers as swimlanes, HITL points as diamonds, undo annotations under each acting step — this is the artifact legal, support, and engineering can all read. Then run the tabletop: "the agent is misbehaving right now" — who notices (which alert), who flips the switch (name, not role), what do in-flight actions do (complete? abort? park?), what does the user see? Write the answers into the spec; pb-52's incident drill will test them.

Make it yours

• Notion spec template: turn the per-step block into a database (step, tier, bounds, HITL, undo, promotion criteria, current status) so tier promotions are recorded changes with dates and approvers, not tribal memory.
• Customer-controlled autonomy: for B2B, expose the tier as an admin setting per workspace — some customers want T2 speed, some require T1 review for compliance; your spec's bounds become the setting's options.
• Confidence-routed tiers: let the agent's own uncertainty demote a step — high-confidence actions flow at T2 while low-confidence ones drop to T1 — but only after you've validated the confidence signal against outcomes, or you've automated overconfidence.

Quality check

• Every acting step has all five fieldspreconditions, bounds, HITL, undo, escalation; a step missing undo is a step capped at T1.
• Nothing irreversible sits above T1sends, deletions, payments, and anything visible to customers requires per-action approval until undo exists.
• Promotion criteria are numeric and dual-signedtier upgrades name the evidence and require PM plus the operating team's owner.
• The kill switch has a name and a tested pathsomeone specific, a rehearsed procedure, and a defined degraded state (usually: fall back to T0 suggestions).
• Approval-queue health is instrumenteddecline rate and review time are on a dashboard; a permanently 0% decline rate triggers a spec review.