---
title: "Tasks and priority"
description: "Why an agent needs an active task to change anything, how your requests become tasks, and how P0 to P3 priority decides what is worked next."
---

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

# Tasks and priority

In a connected project every change belongs to a task. The task manager is not optional: hooks in Claude Code and Codex enforce it, and your own requests are turned into tasks for you.

## An active task is required

A tool that edits files or runs a mutating shell command is refused while the working copy holds no task. The agent sees which commands to run:

```sh
overlane task next                  # what to work on, in priority order
overlane task start task-7          # claim an existing task
overlane task new "Fix login redirect"   # or create and claim one
```

Reading files, searching and every `overlane` command stay available. At the end of a session, uncommitted changes that no task accounts for block the stop once.

The task files `.overlane/state/task.json` and `.overlane/state/task-policy.json` are written only by `overlane` commands.

## Set the priority yourself

The explicit way is deterministic: you or the agent name the priority. This is always right, and nothing guesses.

```sh
overlane task new "Hotfix the build" --priority P0 --top
overlane task prioritise task-9 --priority P2
```

## Your requests become tasks

When you ask for work the prompt hook also creates a task before the agent starts. It reads the words you type with keyword rules, so it can guess wrong. Treat it as a convenience, and set the priority explicitly when it matters. The rules:

| You write | What happens |
| --- | --- |
| "Fix the login redirect" | New task, priority P0, claimed for this session |
| "Fix the login redirect asap" (also `urgent`, `now`, `first`) | P0 and placed first |
| "Add a CSV export when you can" (also `later`, `no rush`) | P2, queued behind current work |
| "Also make the button blue" | Added to the active task as an acceptance criterion |
| Questions, thanks, slash commands | Nothing |

Only what you type is read. Text inside tool output, files or web pages never creates or reprioritises a task.

## Priority and rank

Each task has a priority from `P0` (most urgent) to `P3`, and a rank inside its priority. Tasks with no rank are `P1`. The next task is the best ready or paused one by priority, then rank, then plan order, so milestones and dependencies still apply.

```sh
overlane task queue
overlane task prioritise task-9 --priority P0 --top --reason "customer is blocked"
```

Every change is a ledger event: `task.prioritised`, `task.preempted`, `task.policy_changed`.

## Preemption

A new task that outranks the one in progress preempts it. The active task is checkpointed and paused (reason `user`), the new task is claimed, and the agent is told to switch. When the new task is submitted, `overlane task next` returns the paused task and `overlane task resume task-7` continues it from its checkpoint. Nothing is committed or uploaded on the way.

## Relaxing the rule

The requirement is on by default. An agent can relax it for a project, for example a docs-only repository. Relaxing is the `task_policy` autonomy class: nothing waits under `autonomous`, another principal approves under `supervised`, and a person under `manual` (see [Autonomy](/autonomy/)):

```sh
overlane task policy set relaxed --reason "docs-only repository"
overlane task policy set required
```

A reason is mandatory. The change is a ledger event, and a relaxed project's context packet lists the policy `task_required`, so it is never silent.

## For agents

- The same operations are in the MCP tool `task_queue` (`next`, `list`, `prioritise`, `policy`, `set_policy`).
- Run `overlane search "task priority"` for commands, and see [For AI agents](/for-ai-agents/).
- Command reference: [task new](/cli/task-new/), [task next](/cli/task-next/), [task prioritise](/cli/task-prioritise/), [task policy](/cli/task-policy/).

Source: https://docs.overlane.app/task-priority/index.mdx