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: 
.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: 
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. 
# 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: 
{"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: 
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: 
python3 .trellis/scripts/task.py list
Clear current task when done: 
python3 .trellis/scripts/task.py finish
Archive completed task: 
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: 
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.