Shared Task Queue Status Update Prompt

This prompt is for orchestration engineers who need a single, reliable instruction that forces an LLM to produce a structured, atomic status update for a shared task queue. It is designed for multi-agent systems where multiple workers consume from the same queue and must avoid duplicate processing, conflicting state transitions, and silent progress loss. The core job-to-be-done is to translate a high-level intent (like 'claim task X' or 'mark task Y as complete') into a machine-readable payload that an external queue controller or database transaction can validate and apply without ambiguity.

Use this prompt when your agents need to claim a task, report incremental progress, or signal completion in a way that an external queue controller or database transaction can validate. The prompt assumes you have a task identifier, a claim token or agent identifier, the current queue state, and the intended status transition available as input variables. It is particularly valuable in systems where the queue controller enforces a strict state machine (e.g., pending → claimed → in_progress → completed), and any deviation from valid transitions must be rejected before the update is committed. The prompt's output is designed to be parsed by a downstream validator that checks for duplicate claims, unauthorized transitions, and missing required fields before the queue state is mutated.

Do not use this prompt for simple single-agent to-do lists or workflows without concurrency. If there is no risk of two agents attempting to claim the same task, no shared state to corrupt, and no need for atomic status transitions, a simpler status update prompt will suffice. Similarly, avoid this prompt when the queue controller itself is the source of truth for task state and agents are only reading status—this prompt is for agents that need to write status updates back to the queue. For read-only task polling, use a lightweight retrieval prompt instead. The prompt is also inappropriate for workflows where task state transitions require human approval at each step; in those cases, pair this prompt with a human-in-the-loop escalation prompt that routes the proposed update for review before the queue is mutated.

This prompt template is the core instruction set you will paste into your orchestration layer. It is designed to be called by an agent immediately before and after it works on a task. The prompt forces the model to produce a structured status update that includes a claim token, a progress marker, and a completion signal. This atomic structure is the foundation for maintaining a consistent, conflict-free shared task queue across multiple concurrent agents.

codeCopy
You are an agent operating on a shared task queue. Your only job is to produce a valid, atomic status update for a single task. You must follow the schema exactly. Do not perform the task itself; only report its status.

## TASK CONTEXT
[INPUT: Current task details, including task ID, description, and current assigned status]

## QUEUE STATE
[CONTEXT: A snapshot of the relevant queue state, including the last known status of this task and any dependency statuses]

## OUTPUT SCHEMA
You must output a single JSON object conforming to this schema:
{
  "update_type": "claim" | "progress" | "complete" | "fail",
  "task_id": "string, the unique identifier of the task",
  "claim_token": "string, a unique, hard-to-guess token generated for 'claim' updates to establish ownership",
  "agent_id": "string, the identifier of the agent making this update",
  "timestamp": "string, ISO 8601 timestamp of the update",
  "progress_marker": "string, a concise, machine-readable status from a controlled vocabulary: QUEUED | CLAIMED | IN_PROGRESS | AWAITING_DEPENDENCY | COMPLETED | FAILED",
  "completion_signal": "boolean, true ONLY if progress_marker is COMPLETED or FAILED",
  "status_detail": "string, a brief, human-readable explanation of the current state",
  "dependency_checks": [
    {
      "dependency_id": "string, ID of a task this one depends on",
      "dependency_status": "string, the last known progress_marker of the dependency",
      "blocking": "boolean, true if this dependency is not yet COMPLETED"
    }
  ]
}

## CONSTRAINTS
- If update_type is 'claim', you MUST generate a unique claim_token and set progress_marker to 'CLAIMED'. The task must currently be 'QUEUED' or 'FAILED'.
- If update_type is 'progress', do not change the claim_token. progress_marker must be one of 'IN_PROGRESS' or 'AWAITING_DEPENDENCY'.
- If update_type is 'complete', set completion_signal to true and progress_marker to 'COMPLETED'.
- If update_type is 'fail', set completion_signal to true, progress_marker to 'FAILED', and provide a clear reason in status_detail.
- Always check [CONTEXT] for the task's current claim_token and progress_marker. Reject the update if it would represent an invalid state transition (e.g., completing a task not claimed by you).
- If a dependency is blocking, progress_marker MUST be 'AWAITING_DEPENDENCY'.

To adapt this template, replace the [INPUT] and [CONTEXT] placeholders with live data from your task queue and state store before each call. The [INPUT] should contain the specific task an agent intends to act on. The [CONTEXT] must be a fresh read of the task's current record from the shared state store to prevent acting on stale data. The constraints section encodes the state machine logic; modify it to match your exact workflow states. The claim_token mechanism is a lightweight concurrency control; for high-stakes systems, pair this prompt's output with a database-level compare-and-swap operation or a distributed lock. Always log the raw prompt and the model's output for debugging ordering violations.

The Shared Task Queue Status Update Prompt is designed to be called by an orchestration agent or a task worker agent whenever a task transitions between states (e.g., from PENDING to IN_PROGRESS, or IN_PROGRESS to COMPLETED). The prompt expects a structured input containing the task ID, the current state, the proposed new state, a claim token (to prevent concurrent modification), and any progress markers or output artifacts. The model's job is to produce a strictly validated, atomic status update payload that can be applied to the shared queue store. This prompt is not a general-purpose status reporter; it is specifically for systems where multiple agents may attempt to claim or modify the same task, and where duplicate processing or lost updates are unacceptable failure modes.

To wire this into an application, wrap the prompt call in a function that first assembles the input context from the task queue database. The function must fetch the current task record, verify that the supplied claim token matches the token stored in the database, and confirm that the proposed state transition is valid according to the queue's state machine (e.g., a task in COMPLETED state cannot transition back to IN_PROGRESS). If any pre-condition fails, the function should return a rejection response immediately without calling the model. On a successful model call, the output must be validated against a strict JSON schema that includes required fields: task_id, new_status, claim_token, timestamp, progress_percentage, completion_signal, and an optional status_message. If validation fails, retry the prompt once with the validation error message appended to the [CONSTRAINTS] field. If the retry also fails, log the failure and escalate to a human operator via the designated review queue. For high-risk task types (e.g., financial transactions or clinical data processing), always require a human approval step before applying the update, regardless of validation success. The approval step should present the original task state, the proposed update, and the model's confidence in the transition.

Model choice matters here. Use a model with strong structured output support and low latency, such as Claude 3.5 Sonnet or GPT-4o with response_format set to json_object and strict mode enabled. Avoid models that frequently drop required fields or hallucinate claim tokens. Implement idempotency by including a client-generated idempotency_key in the request to the queue store, so that retried updates do not create duplicate state entries. Log every prompt call, validation result, retry attempt, and human approval decision with the task ID and claim token for traceability. The most common production failure mode is a stale claim token: an agent holds a token, pauses, and another agent claims the task. The harness must detect this by comparing the token in the model's output with the current token in the database before applying the update. If they differ, discard the update and notify the calling agent that its claim has been invalidated.