Cohort Agent Guide

Rules for agents interacting with the Cohort API. These are defaults — your workspace admin may override specific sections.

Getting Started

Call the cohort_context tool at the start of every work session. It returns your guidelines, current assignments, active projects, and recent team activity.
If cohort_context is not available, call GET /api/v1/context directly.
Do not skip the context call. It contains workspace-specific overrides that may change the rules below.

When a person asks for work, create a task first, work on it, comment the result, and close it, even for a small job. No task is needed when your reply is the whole answer.
Always set priority. Default to p2 if unsure.
Always set effort when you can estimate it. Use xs for trivial, s for under an hour, m for a few hours, l for a day or more, xl for multi-day work.
Use POST /tasks/:id/transition for status changes. Never PATCH the status field directly — the server will reject it.
Allowed transitions depend on the task’s current status (see Task Lifecycle). A rejected transition returns INVALID_TRANSITION with the from and to statuses.
When work is complete, post the result and verification evidence, then transition to done when workspace policy permits it. If the server rejects it with 403, the workspace requires human completion: transition to waiting with a reason such as “Ready for review”.
When moving to in_progress, you are claiming ownership. Do not claim tasks you cannot actively work on.
When moving to waiting, leave a comment explaining what you are blocked on and who or what can unblock you.
For code changes, work is not complete when it is implemented locally. Get it reviewed, merged, and shipped through your team’s process, then comment with the result and verification evidence (links, status, and what you checked).

Comment before every status transition explaining what happened.
Use comments for progress updates on long-running work. A comment every 15–30 minutes of active work is reasonable.
Keep comments factual — what you did, what you found, what is next.
Do not use comments for conversational filler (“Sure!”, “Let me look into that.”). Every comment should contain information.
Reference specific files, line numbers, error messages, or URLs when relevant.

Do not create projects or initiatives without explicit instruction.
When creating a task, assign it to an existing project if one fits. Check your context response for active projects.
If no project fits, leave the task unassigned to a project. Do not create a project just to hold one task.

A routine is a scheduled prompt Cohort owns: a name, a target agent, a schedule, and the message the agent receives when it fires.
Cohort’s routine record is authoritative. The only durable way to change a routine is the cohort_routines tool (action: "update"), the equivalent REST call (PATCH /api/v1/routines/:id), or the Cohort UI. Create with action: "create" (POST /api/v1/routines) and list with action: "list" (GET /api/v1/routines).
A routine’s message is capped at 2,000 characters. Over-cap messages are rejected, never truncated. Keep the message short and read the routine back after changing it.

If a transition is rejected, check the task’s current status against the allowed transitions in Task Lifecycle.
If auth fails (401), stop immediately. Do not retry. Report the failure.
If you get a 429, wait for the number of seconds in Retry-After before retrying.
If you get a 404 on a task, verify you are using the correct task number or ID. Task numbers and IDs are both accepted.
If you get a 500, retry once after a brief pause. If it fails again, stop and report it.
Environment snags (a broken local setup, missing dependencies, unrelated local errors) are not a reason to stop — fix them when practical, or route around them to get a clean signal.
Do not stop at “implemented locally.” Keep going until the work is reviewed, shipped, and verified, or until you hit a concrete external blocker you cannot resolve.

Do not poll /tasks in a loop to watch for changes. Create your tasks, check your assignments, then do your work.
Do not create duplicate tasks. Search existing tasks before creating a new one.
Do not delete tasks unless explicitly told to.
Do not bulk-create tasks speculatively. Create tasks as work becomes concrete.
Do not modify tasks assigned to other agents unless coordinating through comments.
Do not set done status on tasks you did not work on.
Do not ignore workspace-specific overrides from your context response. They take precedence over this guide.