Issue Tracking
First-class task tracking with acceptance criteria, lifecycle management, and branch integration.
Overview
Trellis has built-in issue tracking that integrates directly with the VCS. Issues have lifecycle states, acceptance criteria, automatic branch creation, and decision trace linkage.
Creating Issues
trellis issue create -t "Add Python parser" -P high -l parser \
--desc "Support Python AST parsing" \
--ac "test:bun test test/semantic/python" \
--ac "Handles decorators and async functions"
Issues default to backlog status. Use --status queue to create them as ready
for work.
Sub-tasks and epics
Link issues with a childOf graph edge. Set the parent at create time or
re-parent later:
# Create under an epic
trellis issue create -t "Import from Notion" --parent TRL-163
# Re-parent an existing issue
trellis issue update TRL-159 --parent TRL-163
# Remove parent link
trellis issue update TRL-159 --clear-parent
# List children of an epic
trellis issue list --parent TRL-163
Issue Lifecycle
backlog → queue → in_progress → paused → in_progress → closed
↑ |
└────────────────────────┘
# Triage: move from backlog → queue
trellis issue triage TRL-1
# Start working (auto-creates branch, auto-assigns)
trellis issue start TRL-1
# Pause and resume
trellis issue pause TRL-1 -n "Waiting on parser fixture review"
trellis issue resume TRL-1
# Run acceptance criteria
trellis issue check TRL-1
# Retract a criterion by index (tombstone — 3.4.0+)
trellis issue ac-rm TRL-1 2
# Close (requires tests pass + confirmation; auto-promotes lane by default)
trellis issue close TRL-1 --confirm
trellis issue close TRL-1 --confirm --push # git push after close
trellis issue close TRL-1 --confirm --no-promote # require manual lane promote first
Lanes and claims (3.2.5+)
issue start creates and enters an agent lane by default (--no-lane to
opt out). One active session can claim an in-progress issue; a second tab gets a
hard error. issue pause releases the claim for handoff.
Close auto-promotes unpromoted lane ops unless --no-promote. With
git.syncOnPromote (default on init), promote triggers trellis git sync.
Full workflow: Agent coordination.
trellis issue start TRL-1 --no-lane
trellis lane promote <lane-id>
trellis lane watch # live dashboard
Updating Issues
trellis issue update TRL-1 --title "New title" \
--desc "Updated description" \
--status queue -P high \
-l label1,label2 \
--assignee agent:cascade \
--parent TRL-5
trellis issue update TRL-1 --clear-parent
Listing & Filtering
trellis issue list
trellis issue list --status backlog
trellis issue list --status queue
trellis issue list --parent TRL-163
trellis issue active