> ## Documentation Index
> Fetch the complete documentation index at: https://docs.collivo.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Task Folders for AI Agents

> Keep a task's files, guidance, and chats together so you can pick up where you left off.

## What this helps you do

A folder can give a task one place for its brief, progress journal, source material, drafts, and guidance. Starting or resuming a chat from that folder helps you and an agent pick up the work with its context close at hand.

Use this approach when work will take more than one chat, involves several files, or needs a handoff between people and agents. A regular folder works for this when you add the guidance and progress record the task needs. You can also create or mark a folder as a **task folder** so it has a distinct icon in the Files pane; it otherwise works like a regular folder.

## Before you start

* Choose the project and where the work should live. The <Icon icon="folder-kanban" color="#1F7A5A" /> **Task folder** button creates in your **Private** folder by default.
* Gather the source files the agent should use.
* Decide the intended outcome, deliverables, constraints, and success criteria.
* Make sure you have edit permission for the folder where the task folder will be created.

## Create a task folder

In the **Files** pane, select <Icon icon="folder-kanban" color="#1F7A5A" /> **Task folder** in the action bar. This sends an agent request to create a task folder in your **Private** folder. Tell the agent what the task is and what you want it to prepare. For example:

> Set up a task folder for the quarterly customer update. Use the approved messaging brief and the latest metrics table as source material. The deliverable is a draft update for review by the Customer Success lead.

You can also ask an agent directly to set up a task folder. If the goal, scope, or destination is unclear, clarify it before the agent creates anything.

Collivo may ask for approval before the agent creates the folder, creates files, applies an annotation, or uses source material outside the current working folder. See [Tool approvals](/ai-and-agents/tool-approvals).

## Use an existing folder

If your work is already in a folder, open its More options menu <Icon icon="ellipsis" color="#1F7A5A" /> and select <Icon icon="folder-kanban" color="#1F7A5A" /> **Convert to task folder**. This asks an agent to mark the same folder as a task folder. Its location and contents stay in place, its icon changes, and you can continue using it as before. Review its contents and add any missing guidance or progress notes; conversion does not replace that setup.

You can also keep using a regular folder for the task. [Attach it to a kanban card](/collaborate/kanban-boards#designate-a-working-folder-for-the-card) if you want to start or resume the folder's chat from that card.

## Give the folder useful context

A useful task folder usually contains:

| Item | Purpose |
| - | - |
| Folder annotation | Standing guidance that tells agents how to work in this folder |
| `requirements.md` | The task brief: goal, deliverables, constraints, success criteria, stakeholders, and open questions |
| `progress-journal.md` | The running status record: current state, session log, decisions, blockers, and deliverable status |
| Source files | The approved material the task should use |
| Drafts and deliverables | The outputs created while the work progresses |

Keep stable working guidance in the folder annotation. Keep changing details, decisions, and status updates in `progress-journal.md`.

## Set up the task context yourself

Whether the folder is new, converted, or regular:

1. In the **Files** pane, open the folder for the task. Create a regular folder first if you need one.
2. Add the source files the task needs, or keep them nearby and add them to chat context when needed.
3. Create `requirements.md` and describe the goal, deliverables, constraints, success criteria, stakeholders, and open questions.
4. Create `progress-journal.md` and record the current status, completed work, decisions, blockers, and next step.
5. Open the folder's More options menu <Icon icon="ellipsis" color="#1F7A5A" /> and select <Icon icon="sticky-note" color="#1F7A5A" /> **Annotate**.
6. Add folder guidance that tells agents what to read first, what decisions require your confirmation, where to save outputs, and when to update the journal.
7. Start a chat in the folder so it becomes the chat's current working folder.

## Start or resume work

Start each work session from the folder where the task lives.

1. Open the folder in the **Files** pane.
2. Select <Icon icon="message-square-plus" color="#1F7A5A" /> **Start chat in this folder**, <span style={{ display: "inline-flex", verticalAlign: "text-bottom" }}><svg aria-hidden="true" focusable="false" width="1em" height="1em" viewBox="0 0 24 24" fill="none" stroke="#1F7A5A" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round"><path d="M21 15a2 2 0 0 1-2 2H7l-4 4V5a2 2 0 0 1 2-2h14a2 2 0 0 1 2 2z" /><path d="m8.5 13 3-3-3-3" /><path d="m12.5 13 3-3-3-3" /></svg></span> **Resume previous chat**, or <Icon icon="message-square-plus" color="#1F7A5A" /> **New chat** from the folder's More options menu <Icon icon="ellipsis" color="#1F7A5A" />.
3. Ask the agent to review the folder guidance, journal, and relevant content before continuing the work.
4. Add any source files, comments, or outside documents the agent needs to the chat context.
5. Review proposed changes before approving actions that create, update, send, or access material outside the current folder.
6. At the end of the session, ask the agent to update `progress-journal.md` with completed work, decisions, blockers, and the next step.

If you attach the folder to a kanban card, you can start or resume work from that card. Find the card on the board, in card details, in **My Tasks**, or in the Files pane's **Tasks** tab. Select the card's <Icon icon="play" color="#1F7A5A" /> Play action:

* <Icon icon="play" color="#1F7A5A" /> **Start** creates a chat in the attached folder when it has no chats yet.
* <Icon icon="play" color="#1F7A5A" /> **Resume** opens the most recent chat in the attached folder.

See [Designate a working folder for the card](/collaborate/kanban-boards#designate-a-working-folder-for-the-card) to attach a folder.

## Keep the folder useful

* Update `requirements.md` when the goal, scope, or success criteria changes.
* Update `progress-journal.md` after meaningful progress, decisions, or blockers.
* Use clear filenames for drafts and final outputs.
* Move obsolete drafts into an archive folder or hide them from AI discovery when they should not guide future work.
* Check [Active instructions](/ai-and-agents/active-instructions) if the agent does not appear to be following the folder guidance.

<Warning>
  AI output can be incomplete or incorrect. Review important task-folder content, generated files, and journal updates before relying on them or sharing them with others.
</Warning>

## Expected result

The folder gives you a focused place to return to the work. Its brief, guidance, journal, and content help an agent understand what has been done and what remains. Review the agent's understanding when you resume, especially after the task changes.

## Troubleshooting

* **The agent starts from the wrong context:** confirm the chat is working in the task folder, then add the required source files to context.
* **The task brief is too vague:** add concrete deliverables, constraints, success criteria, and open questions to `requirements.md`.
* **The agent does not catch up on its own:** ask it to review the folder guidance, `progress-journal.md`, and relevant folder content, then summarize the current state and next open item.
* **Folder guidance is not being followed:** open [Active instructions](/ai-and-agents/active-instructions) and check whether the folder annotation is active or muted.
* **The folder guidance is not useful enough:** ask the agent to propose an update to the task folder's annotation, then review and save the revised guidance with <Icon icon="sticky-note" color="#1F7A5A" /> **Annotate**.
* **The agent needs a file outside the folder:** add the file to context deliberately, and review any approval request before allowing access.

## Related articles

* [Chat basics](/ai-and-agents/chat-basics)
* [Guide the AI with annotations](/ai-and-agents/annotations)
* [Active instructions](/ai-and-agents/active-instructions)
* [Tool approvals](/ai-and-agents/tool-approvals)
* [Generated files](/files-and-versioning/generated-files)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.