task-queue-mcp: Instructions file for Codex

task-queue-mcp

FastMCP server backed by YAML files on disk. Cross-agent task dispatch for the forge platform. Runs in a Docker container with the queue directory mounted.

What it does

Provides 10 tools for submitting, listing, retrieving, and mutating task files. Each task is a single YAML file (<timestamp>-<slug>.yml) in TASK_QUEUE_DIR.

Task status lifecycle:

submitted ──▶ approved ──────────▶ in-progress ──▶ completed
     │                                              └─▶ failed
     └──▶ pending-approval ──▶ approved            cancelled (terminal, any non-terminal state)
                                                    parked         (non-terminal, reversible)
                                                    routing-failed (non-terminal, dispatcher-written;
                                                                    operator can cancel/park/re-submit it,
                                                                    agents cannot reach it via update_task)

submitted ══▶ completed   (task_type=notify only — a creation path, not a transition;
                            written directly by submit_task, never via update_task.
                            VALID_TRANSITIONS["completed"] is still exactly {"in-progress"}.)

Terminal statuses: completed, failed, cancelled. Transitions are validated server-side; agents cannot claim (in-progress) a task that is not approved. The one exception is by construction, not transition: a notify task is written straight to completed at submit time and never passes through approved or in-progress at all.

Tools

• submit_task(source_agent, target_agent, task_type, summary, description, ...) — Write a YAML task file to TASK_QUEUE_DIR (initial status submitted, except task_type="notify", which is written straight to completed — see the lifecycle diagram above). Returns {ok, task_id, filename}.
• list_tasks(target_agent, source_agent, status, limit) — Filter tasks from the queue directory. include_archived and include_dead_letters are separate opt-ins, both off by default.
• get_task(task_id) — Retrieve a single task by ID. Searches the queue root, then archive/, then dead-letters/.
• update_task(task_id, status, ...) — Move a task to in-progress, completed, or failed (records actor/note/history).
• set_task_status(task_id, ...) — Operator-lane transitions (approved, cancelled, parked, audited overrides, out-of-vocabulary repair). routing-failed is a valid non-terminal source here, same as any other — an operator can cancel, park, or re-submit a task stuck in it.
• cancel_task(task_id, actor, note) — Cancel a non-terminal task.
• park_task(task_id, actor, note) — Pause a task in place. Status-only; the file never moves.
• unpark_task(task_id, actor, note, status) — Return a parked task to parked_from, or to an explicit status.
• amend_task(task_id, amendment, actor, reason) — Append a correction under payload.amendments. Never mutates payload.description.
• requeue_dead_letter(task_id, actor, note) — Operator-only. Move a record out of dead-letters/ back to the queue root at submitted. The only path in this server that walks a record out of a terminal status, and it is scoped to that one directory.