Writing tasks and project instructions for the agent

This page is addressed to an AI assistant that has been asked to help write, or to write, tasks for a Borago Board project. The authoritative description of the agent is What the agent can do. Read it once. This page is the writing advice that follows from it.

The two facts that shape every task

There is no session resume. Every run starts a fresh conversation. A run that fails or is stopped is re-run whole, and a task that grows past what one run can finish cannot be continued by the next run except through what the app hands over (the task text, comments, the previous run's summary and a note of the commands it ran). So a task is one self-contained piece of work with a visible end, and a big job is several tasks in a declared order.

The agent reads only what it is given. A run receives the project's AI instructions, the task title and description, the task's comments and answered questions, the previous attempt's output on a retry, the tasks it mentions, the notes and files it mentions, attachments, a short automatic selection of related finished tasks, and the project knowledge the agent has written down for itself in earlier runs. It does not receive other tasks' transcripts, the chat that produced it, or the user's other projects. If the agent needs to know something, it must be in the task, in the project instructions, or reachable in the repository.

What a good task contains

1. The outcome, in one or two sentences. What exists or works afterwards.
2. Where, when the repository is large. A file, a folder or a module. The agent can search, but a starting point saves a round.
3. The acceptance check. A command the agent can run, or an observable result. "The test suite passes." "Visiting the address returns 200." "The page renders the list below the header." When the post-run review is on for the project, it reads the diff against this, so the check is what makes a wrong verdict rare.
4. Constraints, only the ones that matter. The library to use or not use, the branch to commit on, whether to open a merge request.
5. Nothing else. No transcript of a conversation, no history of how the idea came about, no restating of the project instructions.

Put durable rules in the project's AI instructions instead of repeating them in every task: the language and framework, the test command, the commit style, what never to touch. The project also has separate review instructions that reach the two reviewers and never the agent, for things like "deployment happens once at the end, do not raise it per task".

Tokens the user can type

These are typed into a task's title, description or comments, and into chat. Each opens a picker in the app.

Task numbers are per project and stable across the user's devices. A plain #42 is ordinary text and refers to nothing.

Ordering and size

Tasks in To Do run in the order they sit on the board, top to bottom, one at a time per project. The only reordering is a prerequisite hold. A task mentioning an unfinished task waits. When the planning chat proposes tasks it writes those mentions for the user, so the dependencies are visible as chips on the cards and can be deleted in a keystroke.

Size follows the model. The chat proposes fewer, larger tasks for a strong hosted model and smaller ones for a small self-hosted model, and offers Fewer bigger and More smaller to re-cut a proposal. A per-task picker can send a small task to a cheaper model than the project's default.

What the agent can and cannot do inside a run

It can run shell commands in the project's container with a persistent shell (working directory and environment survive between commands), read and edit files, search the repository, use an investigation tool that reads the repository, and, on Claude, OpenAI and Gemini, search the web and fetch pages. Commands have an idle ceiling of 5 minutes and a hard ceiling of 15 minutes, and a command that outlives them is stopped. It cannot reach the user's filesystem outside the container and cannot start other containers unless container management is on for the project. It has the container's network, so it can download from and send to any address the container can reach, and it pushes to the git remote the project names. What leaves the machine from inside a run is decided by the task, not by the app.

It can end a run by asking a question (the task waits in place, the user answers in a comment, and a fresh run starts with the answer), by declaring steps a person must do (an action comment and a flag on the card), or by creating up to 8 follow-up tasks in Planning.

Do not say

• Do not tell the user to paste a long conversation into a task. The description is re-read on every turn of the run.
• Do not say the agent remembers earlier runs. It receives what is listed above under what the agent reads, and nothing else.
• Do not promise a run of any length. A run ends when the agent declares an outcome or when a hosted model is silent for 10 minutes. A single command that passes its ceiling is stopped and the run carries on. Long work is several tasks or a background wait.
• Do not tell the user to put secrets in the task text. Secrets go in the project's environment variables, which are encrypted and injected at run time. See Secrets and environment variables.
• Do not describe tools the app does not have: no MCP servers, no vendor command-line tool, no browser automation.

Related: What the agent can do, Writing tasks the agent can do, Chat to tasks, How a run works, The queue and its holds.

Copy this page for your AI Source as Markdown: /docs/for-ai/writing-tasks-for-the-agent.md · Updated 2026-10-07 · Was this right? Tell us