# Tasks

import Screenshot from "@docs/Screenshot.astro"
import Video from "@docs/Video.astro"
import SurfaceTabs from "@docs/SurfaceTabs.astro"
import AskRen from "@docs/AskRen.astro"

A task is a tracked piece of work. You or Ren can create one, including for follow-up work that comes up in a chat.

A task can span several [chats](/docs/concepts/chats/). Use a task to track work, hand it between projects, or resume it later. Ren can use the task's work and comment history when it resumes. Use a chat for a single request.

Every task belongs to a [space](/docs/concepts/spaces/). Everyone in the space can see it, and nobody else can. Put a task only you should see in your personal space.

In the API and CLI, a task is `task`.

## Views

Open **Tasks** in the sidebar. Use the **Display** button to switch the layout:

- **List** groups tasks by **Project** or by **Status**, ordered by creation date or priority.
- **Board** shows tasks as cards, grouped by project.

Use **Filter tasks** to narrow by status, priority, project, assignee, or label. By default, the list shows tasks that are **Todo** or **In progress**. Search finds tasks by text.

<Screenshot shot="tasks/list" alt="The Tasks list showing each task's labels and status" />

<Screenshot shot="tasks/kanban" alt="The Tasks page in Board layout with one column per project" />

## Create a task

A task needs a title and a space. Everything else is optional:

- **Description:** the details Ren and your teammates need.
- **Status:** **Todo**, **In progress**, **Done**, or **Dismissed**.
- **Priority:** **Low**, **Medium**, or **High**.
- **Assignee:** a person in the space who owns the task.
- **Project:** the project Ren uses to work on the task. Required before starting work.
- **Labels and due date:** to group and schedule the task.

<SurfaceTabs>
<Fragment slot="app">

1. Open **Tasks** and select **New task**, or press `C`. To add a task to a project directly, select the **+** next to the project's group.
2. Enter a title and an optional description.
3. Choose the space, then set any properties: status, priority, assignee, project, labels, and due date.
4. Select **Create task**. Turn on **Create more** to keep the dialog open for the next one.

<Video clip="tasks/create-task" title="Creating a task by filling in its title, space, and optional fields" />

</Fragment>
<Fragment slot="ask-ren">

<AskRen prompt="Create a high-priority task in the Engineering space: add retries to the supplier feed client. Assign it to the Build project." />

</Fragment>
<Fragment slot="cli">

```sh
ren tasks create --pod-id <space-id> --project-id <project-id> --title "Add retries to the supplier feed client" --priority high
```

</Fragment>
</SurfaceTabs>

## Labels

Labels group tasks across projects, like `billing` or `customer-request`, and they're shared across your organization. A task can have up to 16 labels, each up to 64 characters.

Ren uses two system labels: **fix** (`ren-fix`) for setup problems it can resolve, and **improvement** (`ren-improve`) for suggested improvements. You can filter by these labels but can't edit them, and Ren reserves the `ren-` prefix.

<SurfaceTabs>
<Fragment slot="app">

1. Open a task, or open **Labels** in the new task dialog.
2. Search for a label and select it.
3. To create one, type its name, pick a color, and select **Create label**.

</Fragment>
<Fragment slot="ask-ren">

<AskRen prompt="Add the billing label to the supplier feed task." />

</Fragment>
<Fragment slot="cli">

```sh
ren labels create --name billing
ren tasks update <task-id> --labels billing
```

</Fragment>
</SurfaceTabs>

## When Ren starts work

Ren doesn't start on a task when you create it, or when you change its project in the app. It starts when:

- Someone selects **Start** on the task. See [Start a task](#start-a-task).
- Someone hands the task to a project with the CLI or the API, or asks Ren to. See [Hand a task to another project](#hand-a-task-to-another-project).
- Someone messages Ren in a thread linked to the task, like the Slack thread or GitHub pull request the task came from. Ren continues the task in its project instead of starting a separate chat.

A task needs a project, and a status of **Todo**, **In progress**, or **In review**, before Ren can work on it.

## Task details

Open a task to see everything about it:

- **Properties:** status, priority, assignee, and due date.
- **Links:** the Slack threads, Linear issues, GitHub pull requests, and other URLs the task points to. Ren adds links as it works, and you can add them with the API or CLI. The app shows links but doesn't add them.
- **Labels and project:** how the task is grouped and where Ren works on it.
- **Activity:** every change to the task, who made it, comments, and the chats that worked on it. Open a chat from its card.

Only the author can edit or delete a comment.

<SurfaceTabs>
<Fragment slot="app">

Open the task, type in **Leave a comment...** at the bottom of the activity, and select **Comment**.

<Video clip="tasks/open-task" title="Opening a task from the list to its detail page" />

</Fragment>
<Fragment slot="ask-ren">

<AskRen prompt="Comment on the supplier feed task that the API sandbox is down until Friday." />

</Fragment>
</SurfaceTabs>

## Start a task

**Start** runs the assigned project's Ren on the task. Choose how:

- **Start new session** opens a new chat for the task.
- **Continue last session** resumes the assigned project's last chat for this task. If none exists, Ren creates a chat.

<SurfaceTabs>
<Fragment slot="app">

Open the task, select **Start**, then choose **Start new session** or **Continue last session**. The new chat appears in the task's activity.

<Screenshot
  shot="tasks/start"
  frame="detail"
  alt="A task's Start menu with Start new session and Continue last session"
/>

</Fragment>
<Fragment slot="ask-ren">

<AskRen prompt="Start the supplier feed task in a new session." />

</Fragment>
<Fragment slot="cli">

```sh
ren tasks start <task-id> --mode new
ren tasks start <task-id> --mode continue
```

</Fragment>
</SurfaceTabs>

Task chats can't ask clarifying questions. Permission requests wait in the chat until someone answers.

## Hand a task to another project

To hand work from one project to another, change the task's project and start it again. Each project's Ren keeps its own chat on the task. For example, hand it to **Plan**, then **Build**, then back to **Plan**: Plan picks up its own earlier chat.

If you use the CLI or the API, or ask Ren, you can pick a project in another space you belong to. The task moves to that space, and if its assignee isn't a member there, the task is unassigned. In the app, you can pick only projects in the task's space.

<SurfaceTabs>
<Fragment slot="app">

Open the task, change its **Project**, then select **Start** and choose **Continue last session**. Changing the project alone doesn't start anything.

</Fragment>
<Fragment slot="ask-ren">

<AskRen prompt="Hand the supplier feed task to the Build project. The plan is approved." />

</Fragment>
<Fragment slot="cli">

```sh
ren tasks assign <task-id> --project-id <project-id> --description "The plan is approved. Build it."
```

One command assigns the project, replaces the description with the instruction for the receiving project, and starts that project's Ren in its last chat on the task, or a new one. The reply's `message` says what changed and whether Ren started.

Add `--start new` to open a new chat instead, or `--start none` to assign the project without starting it. Don't run `ren tasks start` afterward: that starts Ren a second time.

</Fragment>
</SurfaceTabs>

## Archive a task

Archive a task you no longer need. It leaves the task list, can't be started, and messages in its linked threads no longer route to it. Its chats stay in the chat list.

<SurfaceTabs>
<Fragment slot="app">

Open the task's actions menu (the **⋯** button) and select **Archive task**. To archive several, select them in the list and choose **Archive** in the bar that appears.

</Fragment>
<Fragment slot="ask-ren">

<AskRen prompt="Archive the supplier feed task." />

</Fragment>
<Fragment slot="cli">

```sh
ren tasks archive <task-id>
```

</Fragment>
</SurfaceTabs>