marcus/td/td-task-management

td - Task Management for AI Agents

Overview

td is a minimalist CLI for tracking tasks and maintaining agent memory across context windows. When your AI session ends, td captures what was done, what remains, and what decisions were made—so the next session picks up exactly where the last one left off.

Core capability: Run td usage and get everything needed for the next action—current focus, pending reviews, open issues, recent decisions.

Quick Start

Starting a New Agent Context

td usage --new-session -q  # Auto-rotate and show compact current state

Use td usage without -q when workflow guidance would be useful. Status output includes:

• Active work sessions and recent decisions
• What issues are pending review (you can review these)
• Highest priority open issues
• Recent handoffs from previous sessions

Single-Issue Workflow

For focused work on one issue:

td start <issue-id>                    # Begin work
td log "OAuth callback implemented"    # Track progress
td log --decision "Using JWT tokens"   # Log decisions
td handoff <id> --done "..." --remaining "..."  # Capture state
td review <id>                         # Submit for review

Multi-Issue Workflow

For agents handling related issues:

td ws start "Auth implementation"      # Start work session
td ws tag td-a1b2 td-c3d4             # Associate issues (auto-starts them)
td ws tag --no-start td-e5f6          # Associate without starting
td ws log "Shared token storage"       # Log to all tagged issues
td ws handoff                          # Capture state, end session

Key Workflows

Workflow 1: Starting New Work

# 1. Check what to work on
td usage          # See current state
td next           # Highest priority open issue
td critical-path  # What unblocks most work
 
# 2. Start work
td start <id>
 
# 3. Begin logging
td log "Started implementation"

Workflow 2: Handing Off Work

Use a structured handoff when work will continue in another context:

td handoff <id> \
  --done "OAuth flow, token storage" \
  --remaining "Refresh token rotation, error handling" \
  --decision "Using JWT for stateless auth" \
  --uncertain "Should tokens expire on password change?"

Keys:

• --done - What is complete
• --remaining - What remains
• --decision - Why you chose approach X
• --uncertain - What you're unsure about

Next session will see all this context with td usage or td context <id>.

Workflow 3: Reviewing Code

# 1. See reviewable issues
td reviewable
 
# 2. Check details
td show <id>
td context <id>
 
# 3. Approve or reject
# Independent review:
td approve <id> --reason "Reviewed diff, looks good"
# Or, in trusted mode, when you implemented it yourself:
#   a sub-agent reviewed it — name them (no --reason needed):
td approve <id> --reviewed-by "code-reviewer sub-agent"
#   you reviewed it yourself — say so:
td approve <id> --self-review --reason "Reviewed own diff, tests pass"
# Or:
td reject <id> --reason "Missing error handling"

Independent review is preferred when practical. The default trusted mode also lets an involved session approve by saying who reviewed the work: --reviewed-by "<who>" credits someone else, --self-review --reason owns it. Both are recorded and neither is verifiable by td, so never name a reviewer who did not review — that reads as independent in the audit trail, which is worse than an honest self-review. In delegated and strict an involved session cannot approve at all.

Workflow 4: Handling Blockers

# 1. Log the blocker
td log --blocker "Waiting on API spec from backend team"
 
# 2. Work on something else
td next              # Get another issue
td ws tag td-e5f6   # Add to work session
 
# 3. Come back to blocked issue later
td context td-a1b2  # Refresh context when blocker resolves

Commands by Category

Checking Status

• td usage - Current state, reviews, next steps
• td usage -q - Compact current state
• td current - What you're working on
• td ws current - Current work session state
• td next - Highest priority open
• td critical-path - What unblocks most work

Working on Issues

• td start <id> - Begin work
• td unstart <id> - Revert to open (undo accidental start)
• td log "msg" - Track progress
• td log --decision "..." - Log decision
• td log --blocker "..." - Log blocker
• td show <id> - View details
• td context <id> - Full context for resuming

Handing Off

• td handoff <id> --done "..." --remaining "..." - Single issue
• td ws handoff - Multi-issue work session

Reviews

• td review <id> - Submit for review
• td reviewable - Issues you can review
• td approve <id> --reason "..." - Approve an independent review
• td approve <id> --reviewed-by "<who>" - Record who reviewed it when that is not you (trusted mode)
• td approve <id> --self-review --reason "..." - Acknowledge and record a trusted-mode self-review
• td approve <id> --record-only --reason "..." - Attest without closing; any session closes after
• td reject <id> --reason "..." - Reject

Creating/Managing Issues

• td create "title" --type feature --priority P1 - Create
• td create "title" --description-file body.md --acceptance-file acceptance.md - Agent-safe rich text
• cat body.md | td update <id> --append --description-file - - Append rich text from stdin
• td list - List all
• td list --status in_progress - Filter by status
• td block <id> - Mark as blocked
• td delete <id> - Delete

File Tracking

• td link <id> <files...> - Track files with issue
• td files <id> - Show file changes

Other

• td monitor - Live dashboard
• td session --new "name" - Force new session
• td undo - Undo last action

See quick_reference.md for full command listing.

Resources

quick_reference.md

Complete command reference organized by task type.

ai_agent_workflows.md

Detailed workflows for common AI agent scenarios:

• Single-issue focus
• Multi-issue work sessions
• Handling blockers
• Resuming work
• Code review process
• Tips for AI agents

Issue Lifecycle

open → in_progress → in_review → closed
         |              |
         v              | (reject)
     blocked -----------+

Key Principles

Session Isolation: Every terminal/context gets a session ID for continuity and audit. Independent review is preferred; trusted mode also lets an involved session approve by recording who actually reviewed the work.

Structured Handoffs: Record done/remaining/decisions/uncertain when another context will need to continue the work.

Minimal: Does one thing. Single binary, SQLite local storage (.todos/), no server, works with any AI tool.

For AI Agents

At the start of a new agent context:

td usage --new-session -q

This auto-rotates sessions and gives you compact current state. Use judgment about how much tracking detail each task needs:

1. Single focused issue → Use single-issue workflow
2. Multiple related issues → Use td ws start for work sessions
3. Work will continue elsewhere → Use td handoff or td ws handoff
4. A decision aids continuity → Log it with --decision
5. An uncertainty matters → Record it with --uncertain
6. Track files → Use td link so future sessions know what changed

See ai_agent_workflows.md for detailed examples.