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

# Task Workflow

> Understand the full lifecycle of a task - from creation to completion.

This guide explains how tasks move through the Coddo pipeline, from initial idea to completed work.

## The task lifecycle

```
Backlog > Todo > In Progress > Review > Done
```

Each stage represents a step in your development workflow:

### 1. Backlog

**Purpose:** Capture ideas and future work.

Add tasks here when you think of something that needs to be done, but you're not ready to work on it yet. Tasks in backlog are just placeholders - they don't need detailed instructions.

### 2. Todo

**Purpose:** Tasks queued for automatic execution.

When a task is moved to Todo, Coddo's **queue runner** automatically picks it up and starts executing it. Before moving a task here, make sure:

* The task has a clear **title**
* The **instruction** is detailed enough for the agent
* You've configured the **execution mode** (worktree, direct, or last used — the default is configurable in **Settings**)
* You've picked a **provider** (Claude Code or Codex) and a **model**

### 3. In Progress

**Purpose:** Tasks currently being executed.

When the queue runner picks up a task:

1. A **chat thread** is linked to the task (or created automatically)
2. If using **worktree mode**, a Git worktree is created
3. The agent (Claude Code or Codex) reads the task instruction and begins working
4. Progress is shown in real time (current tool, completed tools, todo items)

During execution you can:

* **Stop** the task to pause execution
* **Cancel** the task and move it back to backlog
* Watch the chat conversation in the detail panel

### 4. Review

**Purpose:** Verify completed work before marking as done.

After the agent finishes:

1. Review the changes in the **Chat** view (diffs, tool outputs)
2. For worktree tasks, validate and merge the branch
3. For direct mode tasks, commit and push changes
4. You can also send another message to ask for additional changes

### 5. Done

**Purpose:** Completed and reviewed tasks.

Move tasks here when you're satisfied with the result. Done tasks can be:

* **Archived** to clean up the board
* **Unarchived** if you need to revisit them

## Execution modes explained

### Worktree mode (default, recommended for parallel work)

```
main branch -----------------------------------
              |-- coddo/1-fix-login (worktree)
              |-- coddo/2-add-tests (worktree)
```

Each task gets its own Git worktree and branch. Up to **5 worktree tasks can execute in parallel**, configurable in Settings. Benefits:

* **Parallel execution** - Up to 5 tasks can run simultaneously
* **Isolation** - Changes don't interfere with each other
* **Clean merges** - Each task's changes are on a separate branch

### Direct mode (simpler workflow)

Tasks run on your current branch. Benefits:

* **Simpler** - No branch management needed
* **Faster** - No worktree creation overhead
* **Auto-commit** - Optionally commit changes automatically

<Warning>Only one task can run in direct mode at a time, since they share the same working directory.</Warning>

## Task + Chat relationship

Every in-progress task is linked to a chat thread. This means:

* Opening a task shows the full conversation in the detail panel
* The agent has the task instruction as context
* Duration from the chat is attributed to the task
* You can continue the conversation from the review state

## Best practices

1. **Break work into small tasks** - Smaller, focused tasks get better results than large, vague ones
2. **Write detailed instructions** - Include what you want, any constraints, and examples
3. **Use tags** - Categorize tasks (bug, feature, refactor) for better organization
4. **Review before marking done** - Always check the changes before completing a task
5. **Archive regularly** - Keep your board clean by archiving done tasks