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

> ## Agent Instructions
> This handbook preview targets personal CLI 0.11.1. Check installed command help and the matching backend schema before using examples with another release. Examples with named people and placeholder IDs are fictional.

# Tasks and projects

> Keep actionable outcomes with a continuing session and group them by project.

A task records an outcome, its state, and one primary session where the work continues. A project groups related work toward a broader purpose. Keep the project's rationale and decisions in its own record; linked tasks own individual status. Mentioning a task in project prose does not create a structured assignment.

First look for existing work before creating a duplicate:

```sh theme={"theme":{"light":"github-light","dark":"vesper"}}
almanac list --type task --state open
almanac list --type project
almanac read TASK_ID
almanac tasks history TASK_ID
```

The task read gives its current revision, project reference, and primary session; history shows recorded state changes. If the relevant conversation already exists but is untracked, read its session revision and add task metadata to **that** session:

```sh theme={"theme":{"light":"github-light","dark":"vesper"}}
almanac sessions read SESSION_ID
almanac schema describe task
almanac sessions track SESSION_ID --expect 2 --input @task.json --request-key meridian-track-1
```

`@task.json` contains task fields such as fictional title and description, not an `initial_instruction`. Tracking does not copy or restart the conversation. If there is no session yet, `almanac create task --input @task.json --request-key meridian-task-1` creates the task with a new primary session. Without `initial_instruction` it saves work only. Including that field queues real model execution for the new task, so decide deliberately whether to start work. Reading or creating a bare session does not launch a run.

To change task state, read its **task** revision, then use a conditional edit such as `almanac set TASK_ID --expect 3 --input '{"state":"done"}' --request-key meridian-done-1`. This revision differs from the session revision used by `sessions track` or `sessions set`. On conflict, reread and reconsider the change. A project can be read and edited through the same root record verbs; inspect `schema describe project` for its exact fields. [Conversations](/work/conversations) explains how to inspect the primary session, and [review](/work/review) explains background change checkpoints.