td-tasks

name	td-tasks
description	Manage project tasks using the `td` CLI tool. Use when a `.td/` directory exists in the project (or needs to be created), when the user mentions tasks, todos, focus, or work items, or when starting a session and needing to understand what to work on. Also use when the user says "td" or references task states (focus, active, later, done).

td — Task State Manager

td is a local CLI tool for tracking task state and focus. Tasks are YAML files in .td/tasks/. States represent intent: focus (working now), active (taken on), later (parked), done (finished).

Starting a Session

Check current project state before doing anything:

td ls --json          # machine-readable task list (excludes done)
td status             # quick counts: focus: 2  active: 3  later: 1  done: 5  total: 11
td ls --state focus   # what matters right now

Commands

Create and manage tasks

td init                              # initialize .td/ in current directory
td add "Build login form"            # create task (state: active)
td add "Fix bug" --state focus       # create in specific state
td add "Login UI" --parent auth      # create as child task
td add "Thing" --id custom-id        # override auto-generated slug

Change state

td focus <id>       # → focus (working on it now)
td active <id>      # → active (taken on, not right now)
td later <id>       # → later (parked)
td done <id>        # → done (finished)

View tasks

td ls                    # all non-done tasks, human-readable table
td ls --all              # include done tasks
td ls --state focus      # filter by state
td ls --json             # JSON output for programmatic use
td tree                  # hierarchical view
td tree <id>             # subtree from specific node
td show <id>             # full detail on one task
td status                # summary counts by state

Modify and remove

td edit <id> --title "New title"
td edit <id> --notes "Updated info"
td edit <id> --parent other-task     # move under parent
td edit <id> --parent ""             # make root task
td mv <id> <parent-id>              # shorthand for edit --parent
td rm <id> --force                   # delete task (use --force to skip prompt)

Conventions

• Mark tasks done when finishing work, not just when asked to.
• When starting work on something, td focus <id> it.
• After completing a task, run td status to stay oriented.
• Use td ls --json when you need to reason about task data programmatically.
• IDs are slugs derived from titles. They are immutable after creation.
• Tasks can be nested via --parent for hierarchical structure.