track-task-management

Track Task Management

Lightweight CLI tool for managing development tasks with integrated JJ workspace support.

Quick Start

Creating a Task

# Basic task
track new "Implement dark mode"

# With ticket integration
track new "Fix login bug" --ticket PROJ-123 --ticket-url https://jira.example.com/browse/PROJ-123

Adding TODOs

# Simple TODO
track todo add "Create dark mode CSS variables"

# TODO with isolated workspace
track todo add "Implement theme switcher" --worktree

Working in a Workspace

track sync
cd "$(track todo workspace 1)"

# Verify bookmark and describe changes
jj status
jj bookmark list -r @
jj describe -m "Implement theme switcher"

Checking Status

track status

Essential Commands

Workflows

For detailed step-by-step workflows, see:

• Creating Tasks - Complete guide for task creation and TODO setup
• Executing Tasks - Working through TODOs to completion
• Advanced Workflows - Multi-repo tasks, parallel work

Key Concepts

Ticket Integration

Link tasks to external tickets (Jira, GitHub, GitLab). Ticket IDs are automatically used in bookmark names.

track new "Feature" --ticket PROJ-123
# Creates bookmark: task/PROJ-123

JJ Workspaces

Automatically create isolated working directories for each TODO, enabling parallel development.

track todo add "Refactor auth" --worktree
track sync  # Creates workspace at: /repo/task/PROJ-123-todo-1
cd "$(track todo workspace 1)"
# ... work, jj describe ...
track todo done 1  # Automatically rebases and cleans up

Task-Scoped Indices

TODO, Link, and Repository indices (1, 2, 3...) are scoped to each task, not global. Each task maintains its own independent numbering for better organization.

Link Management

Add reference links to tasks for documentation, PRs, issues, or any relevant URLs.

track link add https://docs.example.com/api --title "API Documentation"
track link list

Template Feature

Create new tasks based on existing ones, copying all TODOs.

track new "Sprint 2" --template t:PROJ-100
# All TODOs copied with status reset to 'pending'

Alias Support

Set memorable aliases for tasks to make switching easier.

track alias set feature-x
track switch a:feature-x

Progress Notes (Scraps)

Record findings, decisions, and progress as you work. Supports Markdown formatting.

track scrap add "Decided to use bcrypt for password hashing"
track scrap add "## Performance Results\n- Query time: 50ms\n- Memory: 128MB"

Web UI

Visual interface with real-time updates, Markdown rendering, and inline editing.

track webui  # Access at http://localhost:3000

For LLM Agents

Standard Workflow Pattern

1. Sync first (MANDATORY): track sync
2. Verify bookmark: jj status (must be task bookmark, not main/master)
3. Check context: track status
4. Identify next action: Look at pending TODOs
5. Navigate to workspace: track todo workspace <index>
6. Implement changes and test
7. Describe changes: jj describe -m "..."
8. Record progress: track scrap add "..."
9. Complete: track todo done <index>
10. Repeat for next TODO

Important Notes

• ALWAYS run track sync before making code changes
• ALWAYS verify you are on task bookmark, not main/master/develop (jj status + jj bookmark list -r @)
• Always run track status first to understand current state
• TODO, Link, and Repository indices are task-scoped (not global)
• Describe all changes before track todo done
• Use scraps to document decisions and findings (supports Markdown)
• Ticket IDs appear in bookmark names when linked
• Use track webui for visual interface with real-time updates
• Template feature available for recurring workflows

Additional Resources

• Quick reference: Run track llm-help for comprehensive guide
• All commands: Run track --help
• Installation guide: See ../INSTALL.md