Skip to main content

​
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:
The directory name follows the pattern: MM-DD-slug-assignee.

​
Creating a task

Use the task script:
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.

​
Context files (JSONL)

These tell agents which files to read:
Different agents can have different context. Edit implement.jsonl, check.jsonl, etc. as needed.

​
Working on a task

Set the current task:
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:
Clear current task when done:
Archive completed task:

​
Multiple tasks

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

​
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.