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

# Managing tasks

> Track work with the task system

## What tasks are for

Tasks are work items with their own context. Each task knows:

* What you're building (PRD)
* Which files are relevant
* What branch to work on
* Current status

When you switch tasks, the AI switches context. No confusion about which feature you're working on.

## Task structure

Tasks live in `.trellis/tasks/`. Each task is a directory:

```
.trellis/tasks/01-31-user-auth-taosu/
├── task.json           # Metadata
├── prd.md              # Requirements
├── implement.jsonl     # Context for implement agent
├── check.jsonl         # Context for check agent
└── debug.jsonl         # Context for debug agent
```

The directory name follows the pattern: `MM-DD-slug-assignee`.

## Creating a task

Use the task script:

```bash theme={null}
python3 .trellis/scripts/task.py create "user-auth" --assignee taosu
```

This creates the task directory with default files. Then edit `prd.md` to define requirements.

### prd.md

Write what you're building. Be specific about requirements and acceptance criteria.

```markdown theme={null}
# User Authentication

## Goal

Users can sign up and log in with email/password.

## Requirements

- Sign up with email, password, display name
- Email verification required before login
- Login returns JWT token
- Token expires after 7 days
- Password reset via email

## API Endpoints

- POST /auth/signup
- POST /auth/login
- POST /auth/verify-email
- POST /auth/forgot-password
- POST /auth/reset-password

## Out of scope

- Social login (Google, GitHub)
- Two-factor authentication
```

### Context files (JSONL)

These tell agents which files to read:

```jsonl theme={null}
{"file": ".trellis/spec/backend/index.md", "reason": "Backend coding standards"}
{"file": ".trellis/spec/backend/api.md", "reason": "API design patterns"}
{"file": "src/routes/auth.ts", "reason": "Auth route implementation"}
{"file": "src/services/user.ts", "reason": "User service logic"}
```

Different agents can have different context. Edit `implement.jsonl`, `check.jsonl`, etc. as needed.

## Working on a task

Set the current task:

```bash theme={null}
python3 .trellis/scripts/task.py start 01-31-user-auth-taosu
```

Hooks use this to inject the right context. Now when you start a Claude Code session, it knows:

* Read the PRD from this task
* Load specs listed in the JSONL files
* Work on the task's branch

## Managing tasks

List all tasks:

```bash theme={null}
python3 .trellis/scripts/task.py list
```

Clear current task when done:

```bash theme={null}
python3 .trellis/scripts/task.py finish
```

Archive completed task:

```bash theme={null}
python3 .trellis/scripts/task.py archive 01-31-user-auth-taosu
```

## Multiple tasks

You can have multiple tasks in progress. Only one is "current" at a time. Switch with:

```bash theme={null}
python3 .trellis/scripts/task.py start other-task-id
```

## Task workflow

Typical flow:

1. Create task: `task.py create`
2. Edit `prd.md` with requirements
3. Set up context files (JSONL)
4. Set as current: `task.py start`
5. Work in Claude Code sessions
6. Archive when complete: `task.py archive <id>`

The task system keeps context organized so the AI knows what to focus on.