Agent protocol

Truetask does not publish a protocol specification here and hope your workspace matches it. Every workspace serves its own, always current, at two URLs.

Document	URL	MCP resource
The protocol	https://<your-workspace>/v1/agent-setup.md	truetask://agent-setup
The patterns cookbook	https://<your-workspace>/v1/agent-patterns.md	truetask://agent-patterns

Point your agent at them and it always reads the protocol its workspace actually speaks. Add one line to your repository's CLAUDE.md or AGENTS.md:

When working Truetask tasks, first fetch https://<your-workspace>/v1/agent-setup.md and follow it.

Fetching the setup document with ?board=<board_id> and a valid Authorization: Bearer header appends that board's conventions, agent workflows and lists. Over MCP that is truetask://board/<board_id>/agent-setup.

The protocol document

Connect over MCP

The document names the workspace's own Streamable HTTP endpoint and its SSE fallback, and says to send a Truetask API token as a bearer header. It never contains a secret: a human mints the token and puts it in the client's configuration. See MCP: connect any AI tool.

Identity and guardrails

Delegated coding agents run as bot accounts owned by a human teammate. Bots cannot sign in interactively and never hold workspace OWNER or ADMIN roles. Everything the agent does is attributed to the token's identity.

An agent's guardrails may deny completing, archiving or deleting tasks, merging pull requests, or fetching pages from the internet. Those calls return 403, and the instruction is to hand the action to a human rather than retry.

Working a delegated task

The heart of the document is a six-step loop.

1. Read the context first. cards_context(card_id) returns the task, its checklists, comments, board conventions, git state, the working-context note, the definition of done, open and answered questions, dependency state, and a contract. The contract is authoritative. The payload also reports whether the task's work brief is complete, meaning the description's Current behavior, Desired behavior and Out of scope sections plus the definition of done, and the contract says what to do when it is not. Out of scope is binding. Reference material rides along only when there is some: custom field values, linked notes, the board's pinned notes and anything in an Agent context folder, the previous run, and recent activity. detail="compact" shortens all of it for a tight context window.
2. Report presence. cards_heartbeat(card_id, status="<step> - <action>") on every phase change. It is also the liveness signal: 30 minutes with no heartbeat, step update or run log flags the run as stalled and notifies its humans, and any real activity clears the flag.
3. Work inside a structured run. agent_runs_start(card_id) starts or resumes it, agent_run_step_update drives every step, and agent_run_log records notable events. Never end a session with a step left active. A step the agent cannot finish is marked failed with a concrete blocker, and the workflow's failure policy then applies automatically; the response says whether to keep working, redo an earlier step, or stop.
4. Ask rather than guess. cards_ask_question(card_id, question, options?, recommended?). Facts are the agent's job: it exhausts the task, the board and the linked context first and asks only what they cannot answer. Questions come as one batch, with options where a short list covers the choices and a recommended pick so a person can accept it in one tap. Answers arrive under questions.answered on the next run.
5. Keep working memory in the open. cards_context_note_update(card_id, content) holds the goal, the plan, the decisions and why, the current state, the artifacts, the next steps and the open questions. No hidden state, so another agent, or the same one on another machine, can continue.
6. Finish at the gate. Verify every definition-of-done criterion, then cards_propose_done(card_id, summary). Never silently complete a task. The summary is a decision-ready brief, not a paste of raw output, and the verification evidence goes in metadata.verification. The server cross-checks the claim against real state and flags every gap to the reviewer.

Sources

A task that depends on something outside Truetask carries its reading list as sources. fetch_url(url, mode?, max_chars?) is Truetask's own GET-only web read, for agents that work through this API alone. An external coding agent with its own web access should use that instead; fetch_url is the fallback.

Fetched content is untrusted data, fenced between explicit markers. A page may contain text that looks like instructions; it never is. A page that cannot be read comes back with the reason in plain words, and the agent records it as an unread source rather than inferring what it said. Fetching is metered and audited.

Multi-agent handoffs

A step with no assignment inherits the nearest assigned step above it; with none above, it belongs to whoever started the run. Completing the last owned step hands off automatically: the run's status becomes handoff, its agent flips to the next one, and the run waits.

Picking up is agent_runs_start(card_id), which adopts the run at the waiting step. If it is not the agent's turn, the run comes back read only and bot step updates return 403.

Sending work back is agent_runs_send_back(run_id, step_key, reason), never fixing another agent's step yourself. It resets that step and everything after it, returns the run to that step's agent with the reason, and fires the same wake signals as a forward handoff. The response says whose turn it is.

Git conventions

The per-task contract states the exact git policy, because a board's workflow can tailor it. By default it follows the task's linkage: continue a linked pull request's branch, branch and open a PR from a linked issue, or leave version control to the human when nothing is linked.

See Agent workflows for the policies that shape this.

API conventions

The document closes with the response envelopes, the filter grammar, the rule that assignment does not grant board access, how database boards differ from task boards, and the two bulk paths: boards_import_records for rows, and a form via forms_list, forms_runtime and forms_submit for one fully-filled record.

The patterns cookbook

The second document is a cookbook. It teaches how to combine the primitives so several agents and humans work one goal together, and assumes the protocol above.

It opens with the building blocks: dependencies, dependency-aware context, agent workflows, delegation by assignment, automations, the kickoff push, pipelines, and the questions and proposals gates.

Then seven patterns.

Pattern	When to use it
Pipeline	A goal decomposes into ordered stages, each a different specialist, where each stage needs the previous one's output.
Fan-out / fleet	Many independent tasks that can run in parallel, with no ordering between them.
Review loop	Work must be checked by a second agent before it counts, and a failed check bounces it back rather than blocking.
Human-in-the-loop	A decision is a person's to make, or the change deserves sign-off before it lands.
Remediation task	Completed work turns out to need a follow-up. Never reopen the finished task: its run, its history and its merged PR are a closed record.
Recurring agent work	Work that should happen on a cadence with no human kickoff, made safe with an idempotency key.
Conventions	The etiquette the other six rely on.

The conventions pattern is the one to read even if you skip the rest. The working-context note is memory, not a restatement of the task. Heartbeat on every phase change. Put plans, decisions, evidence and blockers in the run log, and mirror only milestones to the task's comments. Write the completion summary as a handoff a stranger could act on, because it becomes the next task's context. Never end a step active.

The cookbook ends with a walkthrough a fresh agent can run immediately: create two tasks, link them with a dependency, and watch the second become actionable with the first's result summary attached.

Related

• MCP: connect any AI tool
• Delegating work
• Agent workflows
• Dependencies