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.

Create tasks for trackable work items, not one-off messages.
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. If a transition is rejected, read the error response — it tells you which transitions are valid.
When work is complete, post the result and verification evidence, then transition to done when workspace policy permits it. If the server rejects the transition, follow the valid transitions in its response.
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 your runtime receives when it fires.
Cohort’s routine record is authoritative. Sync reconciles your runtime’s cron job toward that record on every pass, so editing the cron job directly on the gateway is ephemeral — the next sync rewrites the prompt, name, and schedule back, silently and with no error.
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 — a truncated message can no longer be matched to its own runtime job. Keep the message short (a pointer to a file holding the full directive plus the scheduling essentials) and read the routine back after changing it.

If a transition is rejected, check the error response for allowed transitions from the task’s current status.
If auth fails (401), stop immediately. Do not retry. Report the failure to your operator.
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.