espennilsen/td

td — Task & Session Management

td is a local-first task management CLI optimized for AI-assisted development workflows. It tracks issues, sessions, structured handoffs, and progress logs.

Session Workflow

Every session follows this pattern:

1. Start — Load context and begin a new session:

   td usage --new-session    # Full context dump (issues, logs, handoffs)
   td status                 # Quick dashboard: focus, reviews, blocked, ready
   

2. Pick work — Find what to work on:

   td next                   # Highest-priority open issue
   td ready                  # All open issues sorted by priority
   td list --mine            # Issues assigned to current session
   

3. Start an issue — Set focus and mark in-progress:

   td start <issue-id>       # Sets focus + status to in_progress
   

4. Log progress — Track decisions, blockers, attempts:

   td log "Implemented auth middleware"              # Progress (default)
   td log --blocker "Waiting on API key from team"   # Blocker
   td log --decision "Using JWT over session tokens"  # Decision
   td log --tried "Attempted Redis caching"           # Attempted approach
   td log --result "Redis too complex, using in-memory" # Result
   td log --hypothesis "Rate limiting might fix 429s"   # Hypothesis
   

5. Handoff — Capture structured state before ending session:

   td handoff <issue-id> \
     --done "Implemented login endpoint" \
     --done "Added JWT validation" \
     --remaining "Add refresh token flow" \
     --remaining "Write tests for auth middleware" \
     --decision "Using RS256 for JWT signing" \
     --uncertain "Should we support OAuth2 providers?"
   

6. Submit for review — When work is complete:

   td review <issue-id>      # Submit for review (preferred)
   

7. Review — Different session approves or rejects:

   td reviewable             # What can I review?
   td approve <issue-id>     # Ship it → closed
   td reject <issue-id> --reason "Need tests"  # Back to in_progress
   

Creating Issues

# Basic
td create "Fix login redirect bug"

# Full options
td create "Add OAuth2 support" \
  --type feature \
  --priority P1 \
  --description "Support Google and GitHub OAuth2 providers" \
  --labels "auth,backend" \
  --parent <epic-id>

# Types: task (default), bug, feature, epic, chore
# Priorities: P0 (critical) → P4 (minimal)
# Points: Fibonacci — 1, 2, 3, 5, 8, 13, 21

Querying Issues

Quick filters

td list                           # All open issues
td list --all                     # Include closed
td list --type bug                # Only bugs
td list --priority P0             # Only critical
td list --status in_progress      # In progress
td list --labels auth             # By label
td list --epic <epic-id>          # All tasks in an epic
td list --sort priority            # Sort by field
td list --long                    # Detailed output
td list --json                    # JSON output

TDQ query language

td query "status = open AND type = bug"
td query "priority <= P1"                    # P0 and P1
td query "created >= -7d"                    # Last 7 days
td query "title ~ auth OR description ~ auth"
td query "log.type = blocker"                # Issues with blockers
td query "implementer = @me AND is(in_progress)"
td query "descendant_of(<epic-id>)"          # All children of epic
td query "rework()"                          # Rejected issues

Saved boards

td board create "Active Bugs" "type = bug AND is(open)"
td board create "My Work" "implementer = @me AND NOT is(closed)"
td board list                                # Show all boards
td board show "Active Bugs"                  # Run saved query

Issue Lifecycle

open → in_progress → in_review → closed
  ↕        ↕            ↕
blocked  blocked      rejected → in_progress (rework)

Review workflow (preferred for non-trivial work)

td start <id>           # open → in_progress (sets focus)
# ... do work, log progress ...
td handoff <id> --done "..." --remaining "..."   # capture state
td review <id>          # in_progress → in_review (requires handoff)

# Different session reviews:
td reviewable           # what can I review?
td approve <id>         # in_review → closed (ship it)
td reject <id> --reason "Missing error handling"  # in_review → in_progress (back to work)

Other transitions

td block <id>           # → blocked
td unblock <id>         # → open
td close <id>           # → closed (skip review, for admin closes only)
td reopen <id>          # → open

Guidelines

• Always use review → approve/reject for non-trivial work — don't skip to close
• close is for admin purposes only: duplicates, won't-fix, trivial/minor tasks
• Session isolation: the session that implements can't approve its own work
• reject sends work back to in_progress for rework — always include a --reason

Dependencies

td dep add <id> <depends-on-id>     # A depends on B
td dep rm <id> <depends-on-id>      # Remove dependency
td depends-on <id>                  # What does this issue need?
td blocked-by <id>                  # What's waiting on this issue?
td critical-path <id>               # Longest dependency chain

Epics & Hierarchy

# Create an epic
td create "Auth System" --type epic --priority P1

# Add child tasks
td create "Login endpoint" --parent <epic-id>
td create "JWT validation" --parent <epic-id>

# View hierarchy
td tree <epic-id>                   # Visual tree
td list --epic <epic-id>            # All descendants
td epic list                        # List all epics with progress

Session Management

td session "working on auth"        # Name current session
td session --new                    # Start fresh session
td whoami                           # Show current session identity
td focus <id>                       # Set focus without starting
td unfocus                          # Clear focus
td resume <id>                      # Show context + set focus

Inspecting Issues

td show <id>                        # Full detail with logs, handoffs, comments
td show <id> --children             # Include child issues
td comments <id>                    # List comments
td comment <id> "Note about this"   # Add a comment

Useful Shortcuts

td status                # Dashboard: session, focus, reviews, blocked, ready
td next                  # Highest-priority open issue
td ready                 # Open issues sorted by priority
td blocked               # All blocked issues
td in-review             # Issues awaiting review
td reviewable            # Issues you can review
td deleted               # Soft-deleted issues
td restore <id>          # Restore deleted issue

Guidelines

• Always start sessions with td usage --new-session or td status
• Log as you go — decisions, blockers, and attempts are valuable for future sessions
• Handoff before stopping — structured handoffs make resumption seamless
• Use epics to group related work and track progress
• Use dependencies to make blocking relationships explicit
• Use boards to save frequently-used queries
• P0 = drop everything, P1 = do next, P2 = default, P3 = backlog, P4 = someday