diff --git a/README.md b/README.md index 684416ad..9c91247c 100644 --- a/README.md +++ b/README.md @@ -23,6 +23,7 @@ A minimalist CLI for tracking tasks across AI coding sessions. When your context - [Query Language (TDQ)](#query-language-tdq) - [Epics](#epics) - [Multi-Issue Work Sessions](#multi-issue-work-sessions) +- [Deferral & Due Dates](#deferral--due-dates) - [File Tracking](#file-tracking) - [Minor Tasks](#minor-tasks) - [Analytics & Stats](#analytics--stats) @@ -350,6 +351,31 @@ td ws log "Shared token storage" # Log fans out to all tagged issues td ws handoff # Capture state for all, end session ``` +## Deferral & Due Dates + +Keep the default backlog focused on work that is actionable now: + +```bash +# Create with scheduling metadata +td create "Review vendor contract" --defer next-week --due 2026-05-15 + +# Add or change dates later +td defer td-a1b2 +7d # Hide until seven days from now +td due td-a1b2 friday # Keep visible, but mark with a deadline +td defer td-a1b2 --clear # Make actionable again +td due td-a1b2 --clear # Remove the deadline + +# Scheduling-aware list filters +td list # Hides future-deferred issues by default +td list --all # Includes all statuses and deferred issues +td list --deferred # Only future-deferred issues +td list --surfacing # Deferred issues now actionable again +td list --overdue # Open issues past their due date +td list --due-soon # Issues due within the next 3 days +``` + +`defer_until` is a snooze date: future-deferred issues are hidden from `td list` until the date arrives. `due_date` is a deadline: it stays visible and is highlighted when due soon or overdue. Date fields accept `today`, `tomorrow`, weekday names, `next-week`, `next-month`, relative offsets like `+7d`, `+2w`, `+1m`, and exact `YYYY-MM-DD` dates. + ## File Tracking Know exactly what changed: @@ -402,8 +428,14 @@ Analytics are stored locally and help identify workflow patterns. Disable with ` | See current state | `td usage` | | Compact state (after first read) | `td usage -q` | | Create issue | `td create "title" --type feature --priority P1` | +| Create with scheduling | `td create "title" --defer next-week --due +2w` | | Create minor task | `td add "title" --minor` | | List all issues | `td list` | +| List including deferred/closed | `td list --all` | +| List deferred issues | `td list --deferred` | +| List surfacing issues | `td list --surfacing` | +| List overdue issues | `td list --overdue` | +| List due-soon issues | `td list --due-soon` | | List by status | `td list --status in_progress` | | What should I work on? | `td next` | | Start work | `td start ` | @@ -412,6 +444,11 @@ Analytics are stored locally and help identify workflow patterns. Disable with ` | Log a decision | `td log --decision "chose X because Y"` | | Log a blocker | `td log --blocker "stuck on X"` | | View issue details | `td show ` | +| Defer issue | `td defer +7d` | +| Clear deferral | `td defer --clear` | +| Set due date | `td due friday` | +| Clear due date | `td due --clear` | +| Update scheduling | `td update --defer "" --due 2026-05-15` | | Capture handoff state | `td handoff --done "..." --remaining "..."` | | Submit for review | `td review ` | | See reviewable issues | `td reviewable` | diff --git a/docs/primer.md b/docs/primer.md index 63378af8..a40446b4 100644 --- a/docs/primer.md +++ b/docs/primer.md @@ -40,6 +40,25 @@ Each issue has: - **Priority** — `P0` (critical) through `P4` (none), defaulting to `P2` - **Labels** — freeform tags for categorization +### Deferral and Due Dates + +td has two scheduling fields with different meanings: + +- **`defer_until`** — a snooze date. If it is in the future, the issue is hidden from the default `td list` output until that date arrives. +- **`due_date`** — a deadline. The issue remains visible, and list/detail views can flag it as due soon or overdue. + +Use `td defer ` and `td due ` to set them after creation, or pass `--defer` and `--due` to `td create` or `td update`: + +```bash +td create "Review release notes" --defer next-week --due +2w +td update td-a1b2 --defer "" --due friday +td list --deferred +td list --overdue +td list --due-soon +``` + +Supported date formats are exact dates (`2026-05-15`), relative offsets (`+7d`, `+2w`, `+1m`), weekday names (`monday`, `friday`), and keywords (`today`, `tomorrow`, `next-week`, `next-month`). `td list --all` includes deferred and closed issues; `td list --surfacing` shows previously deferred issues whose `defer_until` date is today or earlier. + ### Issue Lifecycle Issues move through a state machine: diff --git a/website/docs/command-reference.md b/website/docs/command-reference.md index 28e9da1c..cb435724 100644 --- a/website/docs/command-reference.md +++ b/website/docs/command-reference.md @@ -10,10 +10,10 @@ Complete reference for all `td` commands. | Command | Description | |---------|-------------| -| `td create "title" [flags]` | Create issue. Flags: `--type`, `--priority`, `--description`, `--description-file`, `--acceptance`, `--acceptance-file`, `--parent`, `--epic`, `--minor` | -| `td list [flags]` | List issues. Flags: `--status`, `--type`, `--priority`, `--epic` | +| `td create "title" [flags]` | Create issue. Flags: `--type`, `--priority`, `--description`, `--description-file`, `--acceptance`, `--acceptance-file`, `--parent`, `--epic`, `--minor`, `--defer`, `--due` | +| `td list [flags]` | List issues. Flags: `--status`, `--type`, `--priority`, `--epic`, `--all`, `--deferred`, `--surfacing`, `--overdue`, `--due-soon` | | `td show ` | Display full issue details | -| `td update [flags]` | Update fields. Flags: `--title`, `--type`, `--priority`, `--description`, `--description-file`, `--acceptance`, `--acceptance-file`, `--labels` | +| `td update [flags]` | Update fields. Flags: `--title`, `--type`, `--priority`, `--description`, `--description-file`, `--acceptance`, `--acceptance-file`, `--labels`, `--defer`, `--due` | | `td delete ` | Soft-delete issue | | `td restore ` | Restore soft-deleted issue | @@ -48,7 +48,7 @@ Date formats: `+7d`, `+2w`, `+1m`, `monday`, `tomorrow`, `next-week`, `next-mont The `--defer` and `--due` flags are also available on `td create` and `td update`. -**List filters:** `--all` (include deferred), `--deferred`, `--surfacing`, `--overdue`, `--due-soon` +**List filters:** `--all` (include all statuses and deferred issues), `--deferred` (future-deferred only), `--surfacing` (previously deferred and now actionable), `--overdue`, `--due-soon` ## Agent-Safe Rich Text Input diff --git a/website/docs/deferral.md b/website/docs/deferral.md index 0390cbfd..53bfd2e1 100644 --- a/website/docs/deferral.md +++ b/website/docs/deferral.md @@ -83,9 +83,9 @@ By default, `td list` **hides deferred tasks** — tasks whose `defer_until` is ```bash td list # Actionable tasks only (deferred hidden) -td list --all # Everything, including deferred +td list --all # All statuses, including deferred and closed td list --deferred # Only deferred tasks -td list --surfacing # Tasks whose deferral expires today +td list --surfacing # Previously deferred tasks now actionable again td list --overdue # Tasks past their due date td list --due-soon # Tasks due within 3 days ``` diff --git a/website/docs/intro.md b/website/docs/intro.md index 393bad49..8082c6a8 100644 --- a/website/docs/intro.md +++ b/website/docs/intro.md @@ -94,4 +94,5 @@ Works with Claude Code, Cursor, Codex, Copilot, and Gemini CLI. - [Core Workflow](./core-workflow.md) -- Issue lifecycle, logging, handoffs, and reviews in depth - [Boards](./boards.md) -- Visual overview of issue status across your project +- [Deferral & Due Dates](./deferral.md) -- Hide future work until it is actionable and track deadlines - [Query Language](./query-language.md) -- Filter and search issues with structured queries