AceProtocol
An open spec for AI-agent task queues · v0.1 (draft) · last updated 2026-06-01
AceProtocol is a small, open specification for the kind of task queue an AI agent can work on its own: one global priority order, structured per-project context, and a pull-work-report loop simple enough for any agent — Claude Code, Cursor, Cline, ChatGPT, or your own — to run on autopilot.
Linear, Asana, Jira, and friends were built for humans coordinating with humans. AceProtocol describes the queue shape for humans coordinating with agents: the human ranks the work; the agent pulls the top item with full context, finishes it, and reports a result. TaskPrio is the reference implementation; the contract below is what any tool can implement.
1 · The core loop
The whole protocol exists to make this loop trivial. An agent holding a bearer token pulls the single highest-priority actionable task (with merged account → project → task context), does the work, reports a result, and asks for the next one — until the queue is drained.
loop:
t = GET /api/next # top task + merged context; leases it to you
if t.task is null: stop # queue drained — nothing left to do
do(t.task.body) # the work, in t.task.project context
POST /api/tasks/{t.task.id}/complete { "result": "what you did" }
repeatThe agent never reads the whole list — it pulls one task at a time. A 10,000-task queue costs one call. A completion requires a short result string, which is the autopilot audit trail.
2 · Resources
| Resource | What it is |
|---|---|
Organisation | Top-level isolation boundary. Projects and tasks live under one organisation; organisations never cross-pollinate. |
Project | A unit of work that carries structured agent context (stack, commands, persona, …). Tasks belong to a project, or to none. |
Task | One piece of work. Carries a title, body, assignee, place, status, result, optional subtasks & properties. |
SelectList | Optional named single-select property sets a task can reference (e.g. a "size" or "area" property). |
One global priority order. There is exactly one ranked list across every project. Lower rank = do first. Project columns are filtered slices of the same order — reorder anywhere and the single order updates everywhere.
3 · Project context (the agent-native part)
Every project carries up to eight structured-context fields that compose into one labelled header delivered with every task the agent pulls — so the agent never re-asks what stack you're on or what "done" means:
| Field | Meaning |
|---|---|
workingDir | Where the agent should operate (its local clone / cwd). |
stack | Languages, frameworks, services. |
commands | How to build / test / run / deploy. |
repo | Source repository. |
persona | The voice / role the agent adopts. |
dontDo | Hard constraints — what the agent must never do. |
definitionOfDone | The acceptance checklist for any task in this project. |
instructions | Free-form project knowledge & conventions. |
4 · Task fields
| Field | Values / meaning |
|---|---|
title · body | What to do. The body is the agent's brief. |
assignee | any · llm · human — who should pick it up. |
place | On create: top · bottom · inbox — where it lands. Defaults keep new work from burying current priorities. |
status | inbox · active · in_progress · needs_human · scheduled · done (+ trashed/archived). |
result | Required on completion. A short summary of what was actually done — the autopilot audit trail. |
subtasks | Optional child references. |
selectValues | Optional single-select property values. |
scheduledFor | Activates the task to the top of the queue at a given time. |
dependsOn | Tasks that should land first. |
5 · Operations
Plain HTTP over HTTPS. The full machine-readable contract is the reference implementation's OpenAPI 3.1 spec. The shape any implementation should expose:
| Method · path | Purpose |
|---|---|
GET /api/next | The loop entry point — top actionable task + merged context, leased to the caller. |
GET /api/board | The whole board (organisations → projects → tasks). |
POST /api/tasks · GET /api/tasks | Create / list tasks (filter by assignee, status, project, search). |
GET·PATCH·DELETE /api/tasks/{id} | Read / update / soft-delete a task. |
POST /api/tasks/{id}/complete | Finish a task with a required result. |
POST /api/tasks/{id}/{start·triage·schedule·reprioritize·needs-human·restore} | Lifecycle transitions. |
GET·POST·PATCH·DELETE /api/projects · /api/organisations | Manage projects & organisations (incl. the 8 context fields). |
GET /api/search | Search across the queue. |
6 · Auth
Bearer token in the Authorization header: Authorization: Bearer <token>. A token carries a scope (read · write · admin). The same token an agent uses over REST is what the MCP server uses. Public, unauthenticated reads are the exception, not the rule (e.g. an opt-in public profile).
7 · Lifecycle & leasing
A task moves inbox → active (ranked into the order) → in_progress (an agent is on it) → done. scheduled tasks activate to the top at their time; needs_human parks a task for a person.
Leasing lets several agents share one queue safely. GET /api/next leases the task it returns (marks it in_progress) so other agents skip it and pull the next — the list self-divides across however many agents are running. A lease lasts 15 minutes; if an agent crashes or stalls, the lease expires and the task returns to the queue at its original rank. No task is ever stranded.
8 · Versioning
AceProtocol is 0.x — the shape is stabilising. The reference implementation's API is versioned independently (currently 0.3.0, see its OpenAPI info.version). Additive fields are safe; breaking changes get a major bump and migration notes. Implementations should ignore unknown fields rather than reject them.
9 · Reference implementation — TaskPrio
TaskPrio implements AceProtocol end to end:
- OpenAPI 3.1 contract — /api/openapi.json
- Machine-readable manifest — /.well-known/agent-tasks.json
- MCP server (native to Claude Code · Cursor · Cline · ChatGPT) — one-line install at /docs; tools:
get_next_task,complete_task,create_task,update_task,list_tasks,search_tasks,reprioritize_task,schedule_task,triage_task,flag_needs_human,add_project,list_projects,update_project,export_queue. - Agent manifest — /llms.txt
10 · Implement it / get involved
This is an open, draft spec — read it, build against it, or implement it in your own tool. The contract is the OpenAPI document; this page is the human-readable summary.