Operator Control — Queue, Hold, and Continue

Type: Operational pattern
Related: kelly-handbook-ch7-multi-agent, auto-spawn-chain

Why Operator Control Exists

Full automation needs emergency brakes. The auto-spawn-chain lets pipelines run hands-free from step 1.1 through completion, but the operator must be able to:

  1. Pause a pipeline at a specific point without losing state
  2. Log blockers that require human input, not just mention them in chat
  3. Resume exactly where the pipeline stopped
  4. Inspect intermediate state before allowing the pipeline to continue

These two patterns — Operator Queue and Operator Hold — provide those capabilities.

Operator Queue (PIP-58)

Purpose

When the Router hits a blocker requiring human input, it logs the blocker to operator.md — not just chat. Chat messages get buried. A persistent queue file survives session boundaries.

Commands

# Add an item to the queue
operator-queue.sh add "Short title" "context link or description"

# List current queue items
operator-queue.sh list

# Clear an item when resolved (by title)
operator-queue.sh clear "Short title"

# Clear an item by index
operator-queue.sh clear 2

When to Add to Queue

The Router adds to operator.md when:
- The operator says "later", "ask me", or "queue this"
- The Router hits a blocker that needs human decision-making
- A step needs external input (API keys, credentials, account access)
- A gate failure needs operator judgment to resolve

When to Clear from Queue

The Router clears from operator.md when:
- The operator approves or provides the needed input
- The blocker resolves on its own (external dependency unblocks)
- The item becomes stale or irrelevant

Rules

  • Never load operator.md in shared/group contexts — it's private to the operator session. It may contain sensitive context about blockers, credentials, or business decisions.
  • Always confirm before queuing — tell the operator what's being queued, what success looks like, and any missing context. Never queue vague tasks.
  • Queue is not chat — the queue is a structured list. Chat messages disappear; queue items persist until explicitly cleared.

Queue vs Chat

Approach Problem
Chat only Messages get buried, lost across sessions, no tracking
Queue only No real-time dialogue for quick decisions
Queue + chat Queue for persistence, chat for real-time. Best of both.

The pattern: mention the blocker in chat for immediate awareness, then add it to the queue so it's not forgotten.

Operator Hold (PIP-17)

Purpose

Pause a pipeline at a specific subphase. The pipeline state is preserved — beads stay open, DONE markers stay as-is. The operator can inspect anything, then resume.

Commands

# Set a hold after a specific subphase
set-hold.sh <project> <subphase-id>
# e.g. set-hold.sh voice-ai 2.3

# Resume the pipeline
continue <project>
# e.g. continue voice-ai

How It Works

  1. Set hold: set-hold.sh writes a hold marker for the project at the specified subphase.
  2. Pipeline runs normally until it completes the held subphase.
  3. Auto-spawn stops — the auto-spawn-chain checks for holds before chaining the next step. If a hold is set, it stops.
  4. Operator inspects — check artifacts, review bead state, read logs.
  5. Resume: continue <project> clears the hold marker. The auto-spawn chain resumes from the next step.

When to Use Hold

  • Before a risky step — hold before DEPLOY to inspect BUILD and TEST results first
  • After a gate failure fix — hold after the fixed step to verify the fix before continuing
  • For spot-checks — hold at any point to inspect intermediate state
  • During debugging — hold to freeze the pipeline while investigating an issue

Hold vs Cancel

Action State Preserved? Can Resume?
Hold Yes — beads open, artifacts intact Yes — continue
Cancel Depends on implementation Manual restart required

Hold is always preferred over cancel. It's a pause button, not a stop button.

Interaction Between Queue and Hold

These two mechanisms serve different purposes and can be used together:

  • Queue is for items that need operator input — decisions, approvals, external data
  • Hold is for items that need operator inspection — reviewing state, checking artifacts

A common pattern:

  1. Pipeline runs to step 3.2
  2. Router detects an issue, adds to operator queue: "Step 3.2 output looks suspicious — review design artifacts"
  3. Router sets hold: set-hold.sh myproject 3.2
  4. Operator reviews artifacts, decides to proceed
  5. Operator clears queue item and runs continue myproject

Integration with Auto-Spawn

The auto-spawn-chain respects both mechanisms:

  • Queue: If the Router needs to add a queue item mid-chain, it does so. The chain doesn't advance until the blocker resolves.
  • Hold: If a hold is set, the chain stops at the held step. No step is spawned past the hold point.

The auto-spawn metadata (PIPELINE_DONE, NEXT_STEP) doesn't encode hold state — holds are checked separately by the Router before spawning the next step. This keeps the metadata simple and the hold mechanism independent.

Security Considerations

  • operator.md is private to the operator session. It should never be loaded in Discord, group chats, or shared contexts.
  • Queue items may contain sensitive context (API keys, credentials, business decisions). Treat the queue file as confidential.
  • Hold markers are project-scoped — they live in the project directory, not in shared state.

Summary

Mechanism Purpose Command Scope
Operator Queue Log blockers needing human input operator-queue.sh add/list/clear Persistent across sessions
Operator Hold Pause pipeline at specific point set-hold.sh / continue Project-scoped

Both exist because full automation without override capability is a liability, not a feature. The operator must always be able to pause, inspect, and resume without losing state.

PIP-17 (Operator Hold) and PIP-58 (Operator Queue) were implemented in early April 2026 after the first fully automated pipeline run — where the operator had no way to pause a misbehaving pipeline without killing it.

Concept Cross-References