espennilsen/pi / skills/td
td
VerifiedManage tasks and issues with the td CLI. Use for creating, tracking, querying, and handing off work items. Covers task lifecycle, session management, structured handoffs, epics, dependencies, and boards.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 7.6 KB |
SKILL.md
View on GitHub---
name: td
description: Manage tasks and issues with the td CLI. Use for creating, tracking, querying, and handing off work items. Covers task lifecycle, session management, structured handoffs, epics, dependencies, and boards.
---
# 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:
```bash
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:
```bash
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:
```bash
td start <issue-id> # Sets focus + status to in_progress
```
4. **Log progress** — Track decisions, blockers, attempts:
```bash
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:
```bash
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:
```bash
td review <issue-id> # Submit for review (preferred)
```
7. **Review** — Different session approves or rejects:
```bash
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
```bash
# 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
```bash
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
```bash
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
```bash
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)
```bash
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
```bash
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
```bash
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
```bash
# 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
```bash
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
```bash
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
```bash
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
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack." | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |